Metody rozszerzeń (Przewodnik programowania w języku C#)Extension Methods (C# Programming Guide)

Metody rozszerzenia umożliwiają „dodawanie” metod do istniejących typów bez konieczności tworzenia nowego typu pochodnego, ponownej kompilacji lub modyfikowania oryginalnego typu w inny sposób.Extension methods enable you to "add" methods to existing types without creating a new derived type, recompiling, or otherwise modifying the original type. Metody rozszerzenia stanowią specjalny rodzaj metod statycznych, ale są wywoływane tak, jakby były metodami wystąpień w typie rozszerzonym.Extension methods are a special kind of static method, but they are called as if they were instance methods on the extended type. W przypadku kodu klienta pisanego C#w F# i Visual Basic nie ma żadnej widocznej różnicy między wywołaniem metody rozszerzającej a metodami, które są faktycznie zdefiniowane w typie.For client code written in C#, F# and Visual Basic, there is no apparent difference between calling an extension method and the methods that are actually defined in a type.

Najbardziej typowymi metodami rozszerzenia są LINQLINQ standardowe operatory zapytań, które dodają funkcję zapytania do System.Collections.IEnumerable istniejących System.Collections.Generic.IEnumerable<T> i typów.The most common extension methods are the LINQLINQ standard query operators that add query functionality to the existing System.Collections.IEnumerable and System.Collections.Generic.IEnumerable<T> types. Aby użyć standardowych operatorów zapytań, najpierw Przenieś je do zakresu za pomocą using System.Linq dyrektywy.To use the standard query operators, first bring them into scope with a using System.Linq directive. Następnie dowolny typ, który IEnumerable<T> implementuje wydaje się mieć metody instancji, GroupBytakie OrderByjak Average,,, i tak dalej.Then any type that implements IEnumerable<T> appears to have instance methods such as GroupBy, OrderBy, Average, and so on. Te dodatkowe metody można zobaczyć w uzupełnianiu instrukcji IntelliSense po wpisaniu "kropki" po wystąpieniu IEnumerable<T> typu, takim jak List<T> lub Array.You can see these additional methods in IntelliSense statement completion when you type "dot" after an instance of an IEnumerable<T> type such as List<T> or Array.

Poniższy przykład pokazuje, jak wywołać metodę standardowego operatora OrderBy zapytania w tablicy liczb całkowitych.The following example shows how to call the standard query operator OrderBy method on an array of integers. Wyrażenie w nawiasach to wyrażenie lambda.The expression in parentheses is a lambda expression. Wiele standardowych operatorów zapytań przyjmuje wyrażenia lambda jako parametry, ale nie jest to wymagane dla metod rozszerzenia.Many standard query operators take lambda expressions as parameters, but this is not a requirement for extension methods. Aby uzyskać więcej informacji, zobacz wyrażenia lambda.For more information, see Lambda Expressions.

class ExtensionMethods2    
{
    
    static void Main()
    {            
        int[] ints = { 10, 45, 15, 39, 21, 26 };
        var result = ints.OrderBy(g => g);
        foreach (var i in result)
        {
            System.Console.Write(i + " ");
        }           
    }        
}
//Output: 10 15 21 26 39 45

Metody rozszerzenia są zdefiniowane jako metody statyczne, ale są wywoływane przy użyciu składni metod wystąpienia.Extension methods are defined as static methods but are called by using instance method syntax. Pierwszy parametr określa, który typ metody operuje, a parametr jest poprzedzony przez ten modyfikator.Their first parameter specifies which type the method operates on, and the parameter is preceded by the this modifier. Metody rozszerzające są tylko w zakresie, gdy jawnie zaimportowano przestrzeń nazw do kodu źródłowego using za pomocą dyrektywy.Extension methods are only in scope when you explicitly import the namespace into your source code with a using directive.

Poniższy przykład przedstawia metodę rozszerzenia zdefiniowaną dla System.String klasy.The following example shows an extension method defined for the System.String class. Należy zauważyć, że zdefiniowano ją wewnątrz niezagnieżdżonej nieogólnej klasy statycznej:Note that it is defined inside a non-nested, non-generic static class:

namespace ExtensionMethods
{
    public static class MyExtensions
    {
        public static int WordCount(this String str)
        {
            return str.Split(new char[] { ' ', '.', '?' }, 
                             StringSplitOptions.RemoveEmptyEntries).Length;
        }
    }   
}

Metodę rozszerzenia można wprowadzić do zakresu przy użyciu tej using dyrektywy: WordCountThe WordCount extension method can be brought into scope with this using directive:

using ExtensionMethods;  

A za pomocą poniższej składni można ją wywołać z aplikacji:And it can be called from an application by using this syntax:

string s = "Hello Extension Methods";  
int i = s.WordCount();  

W kodzie metoda rozszerzenia jest wywoływana za pomocą składni metody wystąpienia.In your code you invoke the extension method with instance method syntax. Jednak język pośredni (IL) generowany przez kompilator dokonuje translacji kodu na wywołanie metody statycznej.However, the intermediate language (IL) generated by the compiler translates your code into a call on the static method. W związku z tym zasada hermetyzacji tak naprawdę nie jest naruszana.Therefore, the principle of encapsulation is not really being violated. W rzeczywistości metody rozszerzenia nie mają dostępu do zmiennych prywatnych w typie, który rozszerzają.In fact, extension methods cannot access private variables in the type they are extending.

Aby uzyskać więcej informacji, zobacz jak: Implementowanie i wywoływanie niestandardowej metodyrozszerzenia.For more information, see How to: Implement and Call a Custom Extension Method.

Ogólnie rzecz biorąc, liczba wywołań metod rozszerzenia zazwyczaj jest o wiele większa niż liczba implementacji własnych metod.In general, you will probably be calling extension methods far more often than implementing your own. Metody rozszerzenia są wywoływane przy użyciu składni metody wystąpienia, więc nie jest potrzebna specjalistyczna wiedza, aby móc używać ich z poziomu kodu klienta.Because extension methods are called by using instance method syntax, no special knowledge is required to use them from client code. Aby włączyć metody rozszerzające dla określonego typu, po prostu Dodaj using dyrektywę dla przestrzeni nazw, w której są zdefiniowane metody.To enable extension methods for a particular type, just add a using directive for the namespace in which the methods are defined. Na przykład aby użyć standardowych operatorów zapytań, należy dodać tę using dyrektywę do kodu:For example, to use the standard query operators, add this using directive to your code:

using System.Linq;  

(Może być też koniecznie dodanie odwołania do biblioteki System.Core.dll). Można zauważyć, że standardowe operatory zapytań są teraz wyświetlane w technologii IntelliSense jako dodatkowe metody dostępne dla IEnumerable<T> większości typów.(You may also have to add a reference to System.Core.dll.) You will notice that the standard query operators now appear in IntelliSense as additional methods available for most IEnumerable<T> types.

Metody rozszerzające w czasie kompilacjiBinding Extension Methods at Compile Time

Można stosować metody rozszerzenia, aby rozszerzyć klasę lub interfejs, ale nie w celu pominięcia go.You can use extension methods to extend a class or interface, but not to override them. Metoda rozszerzenia mająca taką samą nazwę i podpis jak interfejs lub metoda klasy nigdy nie zostanie wywołana.An extension method with the same name and signature as an interface or class method will never be called. W czasie kompilacji metody rozszerzenia zawsze mają niższy priorytet niż zdefiniowane w typie metody wystąpienia.At compile time, extension methods always have lower priority than instance methods defined in the type itself. Innymi słowy, jeśli typ ma metodę o nazwie Process(int i)i istnieje metoda rozszerzająca o tym samym podpisie, kompilator zawsze utworzy powiązanie z metodą wystąpienia.In other words, if a type has a method named Process(int i), and you have an extension method with the same signature, the compiler will always bind to the instance method. Gdy kompilator napotyka wywołanie metody, najpierw szuka dopasowania w metodach wystąpienia danego typu.When the compiler encounters a method invocation, it first looks for a match in the type's instance methods. Jeżeli nie znajdzie dopasowania, wyszuka metody rozszerzenia, które są zdefiniowane dla danego typu, i utworzy powiązanie z pierwszą metodą rozszerzenia, którą znajdzie.If no match is found, it will search for any extension methods that are defined for the type, and bind to the first extension method that it finds. W poniższym przykładzie pokazano, w jaki sposób kompilator określa metodę rozszerzenia lub metodę wystąpienia, z którą ma utworzyć powiązanie.The following example demonstrates how the compiler determines which extension method or instance method to bind to.

PrzykładExample

W poniższym przykładzie przedstawiono reguły, zgodnie z którymi kompilator języka C# określa, czy należy powiązać wywołanie metody z metodą wystąpienia typu, czy z metodą rozszerzenia.The following example demonstrates the rules that the C# compiler follows in determining whether to bind a method call to an instance method on the type, or to an extension method. Klasa Extensions statyczna zawiera metody rozszerzenia zdefiniowane dla dowolnego typu, który IMyInterfaceimplementuje.The static class Extensions contains extension methods defined for any type that implements IMyInterface. Klasy A, B iC wszystkie implementują interfejs.Classes A, B, and C all implement the interface.

Metoda MethodB rozszerzenia nigdy nie jest wywoływana, ponieważ jej nazwa i podpis są dokładnie zgodne z metodami już zaimplementowanymi przez klasy.The MethodB extension method is never called because its name and signature exactly match methods already implemented by the classes.

Gdy kompilator nie może odnaleźć metody wystąpienia mającej pasujący podpis, tworzy powiązanie z pasującą metodą rozszerzenia, jeśli taka istnieje.When the compiler cannot find an instance method with a matching signature, it will bind to a matching extension method if one exists.

// Define an interface named IMyInterface.
namespace DefineIMyInterface
{
    using System;

    public interface IMyInterface
    {
        // Any class that implements IMyInterface must define a method
        // that matches the following signature.
        void MethodB();
    }
}


// Define extension methods for IMyInterface.
namespace Extensions
{
    using System;
    using DefineIMyInterface;

    // The following extension methods can be accessed by instances of any 
    // class that implements IMyInterface.
    public static class Extension
    {
        public static void MethodA(this IMyInterface myInterface, int i)
        {
            Console.WriteLine
                ("Extension.MethodA(this IMyInterface myInterface, int i)");
        }

        public static void MethodA(this IMyInterface myInterface, string s)
        {
            Console.WriteLine
                ("Extension.MethodA(this IMyInterface myInterface, string s)");
        }

        // This method is never called in ExtensionMethodsDemo1, because each 
        // of the three classes A, B, and C implements a method named MethodB
        // that has a matching signature.
        public static void MethodB(this IMyInterface myInterface)
        {
            Console.WriteLine
                ("Extension.MethodB(this IMyInterface myInterface)");
        }
    }
}


// Define three classes that implement IMyInterface, and then use them to test
// the extension methods.
namespace ExtensionMethodsDemo1
{
    using System;
    using Extensions;
    using DefineIMyInterface;

    class A : IMyInterface
    {
        public void MethodB() { Console.WriteLine("A.MethodB()"); }
    }

    class B : IMyInterface
    {
        public void MethodB() { Console.WriteLine("B.MethodB()"); }
        public void MethodA(int i) { Console.WriteLine("B.MethodA(int i)"); }
    }

    class C : IMyInterface
    {
        public void MethodB() { Console.WriteLine("C.MethodB()"); }
        public void MethodA(object obj)
        {
            Console.WriteLine("C.MethodA(object obj)");
        }
    }

    class ExtMethodDemo
    {
        static void Main(string[] args)
        {
            // Declare an instance of class A, class B, and class C.
            A a = new A();
            B b = new B();
            C c = new C();

            // For a, b, and c, call the following methods:
            //      -- MethodA with an int argument
            //      -- MethodA with a string argument
            //      -- MethodB with no argument.

            // A contains no MethodA, so each call to MethodA resolves to 
            // the extension method that has a matching signature.
            a.MethodA(1);           // Extension.MethodA(IMyInterface, int)
            a.MethodA("hello");     // Extension.MethodA(IMyInterface, string)

            // A has a method that matches the signature of the following call
            // to MethodB.
            a.MethodB();            // A.MethodB()

            // B has methods that match the signatures of the following
            // method calls.
            b.MethodA(1);           // B.MethodA(int)
            b.MethodB();            // B.MethodB()

            // B has no matching method for the following call, but 
            // class Extension does.
            b.MethodA("hello");     // Extension.MethodA(IMyInterface, string)

            // C contains an instance method that matches each of the following
            // method calls.
            c.MethodA(1);           // C.MethodA(object)
            c.MethodA("hello");     // C.MethodA(object)
            c.MethodB();            // C.MethodB()
        }
    }
}
/* Output:
    Extension.MethodA(this IMyInterface myInterface, int i)
    Extension.MethodA(this IMyInterface myInterface, string s)
    A.MethodB()
    B.MethodA(int i)
    B.MethodB()
    Extension.MethodA(this IMyInterface myInterface, string s)
    C.MethodA(object obj)
    C.MethodA(object obj)
    C.MethodB()
 */

Ogólne wskazówkiGeneral Guidelines

Ogólnie zalecane jest, aby implementować metody rozszerzenia oszczędnie i tylko wtedy, gdy jest to konieczne.In general, we recommend that you implement extension methods sparingly and only when you have to. Jeśli to możliwe, kod klienta, który musi rozszerzyć istniejący typ, powinien to zrobić przez utworzenie nowego typu, który będzie typem pochodnym istniejącego typu.Whenever possible, client code that must extend an existing type should do so by creating a new type derived from the existing type. Aby uzyskać więcej informacji, zobacz dziedziczenie.For more information, see Inheritance.

W przypadku korzystania z metody rozszerzenia w celu rozszerzania typu, którego kodu źródłowego nie można zmienić, istnieje ryzyko, że zmiana w implementacji typu spowoduje przerwanie działania metody rozszerzenia.When using an extension method to extend a type whose source code you cannot change, you run the risk that a change in the implementation of the type will cause your extension method to break.

W przypadku implementowania metod rozszerzających dla danego typu należy pamiętać o następujących kwestiach:If you do implement extension methods for a given type, remember the following points:

  • Metoda rozszerzenia nigdy nie zostanie wywołana, jeśli ma taki sam podpis, jak metoda zdefiniowana w typie.An extension method will never be called if it has the same signature as a method defined in the type.

  • Metody rozszerzenia są włączane do zakresu na poziomie przestrzeni nazw.Extension methods are brought into scope at the namespace level. Na przykład jeśli masz wiele klas statycznych, które zawierają metody rozszerzające w pojedynczej przestrzeni nazw Extensionso nazwie, wszystkie te elementy zostaną wprowadzone do zakresu using Extensions; przez dyrektywę.For example, if you have multiple static classes that contain extension methods in a single namespace named Extensions, they will all be brought into scope by the using Extensions; directive.

Dla zaimplementowanej biblioteki klas nie należy używać metod rozszerzenia, aby uniknąć zwiększenia numeru wersji zestawu.For a class library that you implemented, you shouldn't use extension methods to avoid incrementing the version number of an assembly. W przypadku dodawania znaczącej funkcjonalności do biblioteki, której kod źródłowy jest własnością użytkownika, należy przestrzegać standardowych wytycznych programu .NET Framework dotyczących wersji zestawów.If you want to add significant functionality to a library for which you own the source code, you should follow the standard .NET Framework guidelines for assembly versioning. Aby uzyskać więcej informacji, zobacz przechowywanie wersji zestawu.For more information, see Assembly Versioning.

Zobacz takżeSee also