Dokumentacja C# z przykładami: Metody rozszerzające

Q: Czy w C# można wywołać metodę rozszerzającą na null?

Tak. Wywołanie kompiluje się do wywołania metody static z null jako pierwszym argumentem, więc samo wywołanie nie rzuca NullReferenceException. O tym, co zrobić, decyduje metoda: potraktować null jako poprawne wejście (jak pomocnik w stylu IsNullOrEmpty) albo rzucić ArgumentNullException, tak jak robią to metody LINQ.

Metoda rozszerzająca dodaje metodę do istniejącego typu bez modyfikowania go, dziedziczenia po nim czy opakowywania go. Piszesz zwykłą metodę static, oznaczasz jej pierwszy parametr słowem this, a kod wywołujący używa jej przez kropkę, jakby typ miał ją od zawsze:

using System;

static class StringExtensions
{
    public static string Truncate(this string text, int maxLength)
    {
        if (text.Length <= maxLength) return text;
        return text.Substring(0, maxLength) + "...";
    }

    public static int WordCount(this string text) =>
        text.Split(new[] { ' ' }, StringSplitOptions.RemoveEmptyEntries).Length;
}

class Program
{
    static void Main()
    {
        string title = "Extension methods let you add behavior to types you do not own";

        Console.WriteLine(title.Truncate(24));
        Console.WriteLine(title.WordCount());
        Console.WriteLine("short".Truncate(24));

        Console.WriteLine(StringExtensions.Truncate(title, 9));   // the same method, called directly
    }
}

Wynik:

Extension methods let yo...
12
short
Extension...

title.Truncate(24) kompiluje się dokładnie do StringExtensions.Truncate(title, 24). Składnia z kropką to tylko wygoda: metoda nadal jest static, nadal mieszka w StringExtensions i może używać wyłącznie publicznych składowych typu string.

Zasady deklarowania

Metoda musi być static i znajdować się w klasie, która jest static, niegeneryczna i niezagnieżdżona w innej klasie. Klasa niestatyczna lub generyczna daje CS1106, Extension method must be defined in a non-generic static class; zagnieżdżona daje CS1109, Extension methods must be defined in a top level static class.
this stawia się tylko przy pierwszym parametrze, a typ tego parametru to typ, który rozszerzasz. Kolejne parametry są zwykłe.
Sama metoda może być generyczna (this IEnumerable<T> source), choć klasa nie może.
Widzi tylko to, co widzi każdy kod z zewnątrz: składowe publiczne (a w obrębie tego samego assembly także internal). Pola prywatne pozostają prywatne.

Zgodnie z konwencją klasę nazywa się od tego, co rozszerza (StringExtensions, EnumerableExtensions), i grupuje w namespace takim jak MyApp.Extensions.

Rozszerzanie interfejsów i IEnumerable<T>

Rozszerzenie interfejsu dodaje metodę do każdego typu, który go implementuje. Rozszerzenie IEnumerable<T> daje więc metodę naraz tablicom, listom, zbiorom, kolekcjom kluczy słowników i wynikom zapytań LINQ:

using System;
using System.Collections.Generic;
using System.Linq;

static class EnumerableExtensions
{
    public static decimal Median(this IEnumerable<decimal> source)
    {
        var sorted = source.OrderBy(x => x).ToList();
        if (sorted.Count == 0) throw new InvalidOperationException("sequence is empty");
        int mid = sorted.Count / 2;
        return sorted.Count % 2 == 1 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
    }

    public static IEnumerable<T> EveryNth<T>(this IEnumerable<T> source, int n)
    {
        int i = 0;
        foreach (T item in source)
        {
            if (i % n == 0) yield return item;
            i++;
        }
    }
}

class Program
{
    static void Main()
    {
        decimal[] prices = { 12m, 3m, 45m, 7m };
        var orderTotals = new List<decimal> { 20m, 80m, 50m };

        Console.WriteLine(prices.Median());
        Console.WriteLine(orderTotals.Median());
        Console.WriteLine(orderTotals.Where(t => t > 25m).Median());

        string[] frames = { "f0", "f1", "f2", "f3", "f4", "f5", "f6" };
        Console.WriteLine(string.Join(" ", frames.EveryNth(3)));
    }
}

Wynik:

9.5
50
65
f0 f3 f6

EveryNth jest generyczna: T jest wnioskowany z odbiorcy, więc działa tu dla stringów i dla każdego innego typu elementów. Ponieważ używa yield return, jest leniwa jak wbudowane operatory LINQ i można ją z nimi łączyć w łańcuch.

LINQ jest zbudowany na metodach rozszerzających

Where, Select, OrderBy, Sum, First i reszta LINQ to metody rozszerzające dla IEnumerable<T>, zdefiniowane w klasie static System.Linq.Enumerable. Dlatego using System.Linq; musi stać na początku pliku, zanim list.Where(...) się skompiluje, i dlatego LINQ działa z każdym typem kolekcji, choć żaden z nich nie implementuje metody Where:

using System;
using System.Linq;

class Program
{
    static void Main()
    {
        int[] scores = { 72, 95, 58, 88 };

        var passed1 = scores.Where(s => s >= 60).OrderBy(s => s);
        var passed2 = Enumerable.OrderBy(Enumerable.Where(scores, s => s >= 60), s => s);

        Console.WriteLine(string.Join(", ", passed1));
        Console.WriteLine(string.Join(", ", passed2));
    }
}

Wynik:

72, 88, 95
72, 88, 95

Obie linie to ten sam kod. Składnia rozszerzeń zamienia zagnieżdżone wywołania, które czyta się od środka, w łańcuch czytany w kolejności wykonywania kroków. To główny powód istnienia metod rozszerzających: dodano je w C# 3 razem z LINQ. Operatory omawia strona o LINQ.

Namespace musi być zaimportowany

Metoda rozszerzająca jest w zasięgu tylko wtedy, gdy namespace jej klasy static zaimportowano przez using. Bez tego wywołanie kończy się błędem, jakby metoda nie istniała:

error CS1061: 'string' does not contain a definition for 'Truncate' and no accessible extension method 'Truncate' accepting a first argument of type 'string' could be found (are you missing a using directive or an assembly reference?)

Dodaj using dla namespace z rozszerzeniami (albo, od C# 10, jeden global using dla całego projektu):

using System;
using Shop.Extensions;

namespace Shop.Extensions
{
    public static class PriceExtensions
    {
        public static string ToPriceTag(this decimal amount) => $"EUR {amount:F2}";
    }
}

class Program
{
    static void Main()
    {
        decimal total = 49.9m;
        Console.WriteLine(total.ToPriceTag());
    }
}

Wynik:

EUR 49.90

Ma to też dobrą stronę: metoda rozszerzająca, której nie chcesz mieć wszędzie, może żyć w namespace importowanym tylko przez niektóre pliki.

Metody instancji wygrywają

Gdy typ ma już pasującą metodę instancji, kompilator jej używa i w ogóle nie bierze pod uwagę rozszerzenia. Rozszerzenie o tej samej sygnaturze jest martwym kodem w każdym miejscu wywołania ze składnią z kropką:

using System;

class Invoice
{
    public decimal Amount = 120m;
    public string Describe() => $"Invoice (instance method): {Amount}";
}

static class InvoiceExtensions
{
    public static string Describe(this Invoice invoice) => "extension: only reachable as a static call";
    public static string Describe(this Invoice invoice, string currency) =>
        $"Invoice (extension): {invoice.Amount} {currency}";
}

class Program
{
    static void Main()
    {
        var invoice = new Invoice();
        Console.WriteLine(invoice.Describe());
        Console.WriteLine(invoice.Describe("USD"));
        Console.WriteLine(InvoiceExtensions.Describe(invoice));
    }
}

Wynik:

Invoice (instance method): 120
Invoice (extension): 120 USD
extension: only reachable as a static call

Rozszerzenie z jednym argumentem przegrało z metodą instancji; to z dwoma argumentami zostało użyte, bo żadna metoda instancji nie przyjmuje stringa. Oznacza to również, że aktualizacja biblioteki, która doda metodę instancji o nazwie twojego rozszerzenia, po cichu przełączy twoje wywołania na wersję z biblioteki. Wybieraj nazwy rozszerzeń, które raczej nie będą kolidować.

Wywołanie na null

Ponieważ to w rzeczywistości wywołanie static, odbiorca null nie powoduje wyjątku w miejscu wywołania. Metoda dostaje null jako pierwszy argument i sama decyduje, co to znaczy:

using System;

static class TextExtensions
{
    public static bool IsBlank(this string s) => string.IsNullOrWhiteSpace(s);

    public static string Initials(this string fullName)
    {
        if (fullName == null) throw new ArgumentNullException(nameof(fullName));
        string result = "";
        foreach (string part in fullName.Split(' '))
            if (part.Length > 0) result += char.ToUpper(part[0]);
        return result;
    }
}

class Program
{
    static void Main()
    {
        string missing = null;

        Console.WriteLine(missing.IsBlank());
        Console.WriteLine("ada lovelace".Initials());

        try
        {
            missing.Initials();
        }
        catch (ArgumentNullException e)
        {
            Console.WriteLine($"{e.GetType().Name}: {e.ParamName}");
        }
    }
}

Wynik:

True
AL
ArgumentNullException: fullName

To, że missing.IsBlank() zwraca true, jest wygodne, ale może zaskoczyć czytelników, którzy oczekują, że wywołanie składowej na null rzuci wyjątek. Akceptuj null tylko w metodach, których nazwa to jasno sugeruje (IsBlank, OrEmpty); w pozostałych rzucaj ArgumentNullException, tak jak LINQ.

Rozszerzanie enumów

Enumy nie mogą mieć własnych metod, dlatego są naturalnym celem rozszerzeń:

enum OrderStatus { Pending, Paid, Shipped, Delivered, Cancelled }

static class OrderStatusExtensions
{
    public static bool IsFinal(this OrderStatus s) =>
        s == OrderStatus.Delivered || s == OrderStatus.Cancelled;
}

// usage: if (order.Status.IsFinal()) { ... }

Składowe rozszerzające w C# 14

Do C# 14 rozszerzeniami mogły być tylko metody. C# 14 dodał bloki extension, które grupują składowe dla jednego odbiorcy i pozwalają też na właściwości rozszerzające i składowe static:

// C# 14 and later
public static class StringExtensions
{
    extension(string s)
    {
        public bool IsBlank => string.IsNullOrWhiteSpace(s);   // extension property
        public string Truncate(int max) => s.Length <= max ? s : s[..max] + "...";
    }
}

Klasyczne metody rozszerzające z parametrem this pozostają poprawne i to ich używa niemal cały istniejący kod i biblioteki.

Kiedy ją napisać

Metody rozszerzające pasują, gdy typ nie należy do ciebie (string, DateTime, interfejsy frameworka), gdy chcesz mieć tego samego pomocnika w każdej implementacji interfejsu albo gdy łańcuch czyta się lepiej niż zagnieżdżone wywołania. Jeśli klasa jest twoja, dodaj zamiast tego prawdziwą metodę instancji: może korzystać z prywatnego stanu i jest tam, gdzie czytelnicy jej szukają. Unikaj też rozszerzania object, bo wtedy twoja metoda pojawia się na liście podpowiedzi dla każdej wartości w programie.

Najczęściej zadawane pytania

Czym jest metoda rozszerzająca w C#?

To metoda static, którą można wywołać tak, jakby była metodą instancji innego typu. Piszesz ją w klasie static i stawiasz this przed pierwszym parametrem: public static bool IsBlank(this string s) => string.IsNullOrWhiteSpace(s);. Wtedy name.IsBlank() działa dla każdego stringa, bez zmieniania typu string i bez dziedziczenia po nim.

Dlaczego kompilator nie widzi mojej metody rozszerzającej?

Metody rozszerzające są widoczne tylko wtedy, gdy zaimportowano ich namespace. Jeśli klasa static jest w MyApp.Extensions, dodaj using MyApp.Extensions; do pliku, który ją wywołuje; w przeciwnym razie kompilator zgłasza CS1061, czyli że typ nie zawiera definicji ani dostępnej metody rozszerzającej o tej nazwie. Sprawdź też, czy klasa jest static, niegeneryczna i nie jest zagnieżdżona.

Czy metoda rozszerzająca może zastąpić metodę instancji?

Nie. Kompilator najpierw szuka pasującej metody instancji, a metody rozszerzające bierze pod uwagę dopiero wtedy, gdy takiej nie ma. Rozszerzenie o tej samej nazwie i tych samych parametrach co metoda instancji jest po cichu ignorowane w każdym miejscu wywołania, które używa składni instancji.

Czy w C# można wywołać metodę rozszerzającą na null?

Tak. Wywołanie kompiluje się do wywołania metody static z null jako pierwszym argumentem, więc samo wywołanie nie rzuca NullReferenceException. O tym, co zrobić, decyduje metoda: potraktować null jako poprawne wejście (jak pomocnik w stylu IsNullOrEmpty) albo rzucić ArgumentNullException, tak jak robią to metody LINQ.

Czy w C# istnieją właściwości rozszerzające?

Nie przed C# 14. Do tego czasu rozszerzeniami mogą być tylko metody, więc to, co byłoby właściwością, zapisuje się jako metodę (GetFullName()). C# 14 dodał bloki rozszerzeń, które oprócz metod mogą deklarować właściwości rozszerzające i składowe static.

Powiązane zagadnienia