Méthodes d’extension (Guide de programmation C#)Extension Methods (C# Programming Guide)

Les méthodes d'extension vous permettent d'« ajouter » des méthodes à des types existants sans créer un type dérivé, ni recompiler ou modifier le type d'origine.Extension methods enable you to "add" methods to existing types without creating a new derived type, recompiling, or otherwise modifying the original type. Les méthodes d'extension sont un type particulier de méthode statique appelées comme s'il s'agissait de méthodes d'instance sur le type étendu.Extension methods are a special kind of static method, but they are called as if they were instance methods on the extended type. Pour le code client écrit en C#, F# et Visual Basic, il n’y a aucune différence apparente lors de l’appel entre une méthode d’extension et les méthodes qui sont réellement définies dans un type.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.

Les méthodes d’extension les plus courantes sont les opérateurs de requête standard LINQLINQ qui ajoutent des fonctionnalités de requête aux types System.Collections.IEnumerable et System.Collections.Generic.IEnumerable<T> existants.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. Pour utiliser les opérateurs de requête standard, introduisez-les d'abord dans la portée avec une directive using System.Linq.To use the standard query operators, first bring them into scope with a using System.Linq directive. Puis, tout type qui implémente IEnumerable<T> semble avoir des méthodes d'instance telles que GroupBy, OrderBy, Average, etc.Then any type that implements IEnumerable<T> appears to have instance methods such as GroupBy, OrderBy, Average, and so on. Vous pouvez consulter ces méthodes supplémentaires dans la saisie semi-automatique des instructions IntelliSense quand vous tapez un « point » après une instance d’un type IEnumerable<T> tel que List<T> ou 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.

L'exemple suivant indique comment appeler la méthode OrderBy d'opérateur de requête standard sur un tableau d'entiers.The following example shows how to call the standard query operator OrderBy method on an array of integers. L'expression entre parenthèses est une expression lambda.The expression in parentheses is a lambda expression. De nombreux opérateurs de requête standard prennent des expressions lambda comme paramètres, mais ce n’est pas requis pour les méthodes d’extension.Many standard query operators take lambda expressions as parameters, but this is not a requirement for extension methods. Pour plus d’informations, consultez Expressions 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

Les méthodes d’extension sont définies comme méthodes statiques mais sont appelées en utilisant la syntaxe de méthode d’instance.Extension methods are defined as static methods but are called by using instance method syntax. Leur premier paramètre spécifie les types sur lesquels la méthode s’applique et le paramètre est précédé du modificateur this.Their first parameter specifies which type the method operates on, and the parameter is preceded by the this modifier. Les méthodes d'extension sont uniquement dans la portée lorsque vous importez explicitement l'espace de noms dans votre code source avec une directive using.Extension methods are only in scope when you explicitly import the namespace into your source code with a using directive.

L'exemple suivant présente une méthode d'extension définie pour la classe System.String.The following example shows an extension method defined for the System.String class. Notez qu'elle est définie à l'intérieur d'une classe statique, non imbriquée et non générique :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;
        }
    }   
}

La méthode d'extension WordCount peut être mise à portée avec cette directive using :The WordCount extension method can be brought into scope with this using directive:

using ExtensionMethods;  

Elle peut être appelée à partir d'une application à l'aide de cette syntaxe :And it can be called from an application by using this syntax:

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

Dans votre code, vous appelez la méthode d'extension avec la syntaxe de méthode d'instance.In your code you invoke the extension method with instance method syntax. Toutefois, le langage intermédiaire (IL) généré par le compilateur traduit votre code dans un appel sur la méthode statique.However, the intermediate language (IL) generated by the compiler translates your code into a call on the static method. Par conséquent, le principe d'encapsulation n'est pas réellement violé.Therefore, the principle of encapsulation is not really being violated. En fait, les méthodes d’extension ne peuvent pas accéder aux variables privées dans le type qu’elles étendent.In fact, extension methods cannot access private variables in the type they are extending.

Pour plus d’informations, consultez Guide pratique pour implémenter et appeler une méthode d’extension personnalisée.For more information, see How to: Implement and Call a Custom Extension Method.

En général, vous appellerez probablement les méthodes d’extension beaucoup plus souvent que vous n’implémenterez vos propres méthodes.In general, you will probably be calling extension methods far more often than implementing your own. Comme les méthodes d'extension sont appelées à l'aide de la syntaxe de méthode d'instance, aucune connaissance particulière n'est requise pour les utiliser depuis le code client.Because extension methods are called by using instance method syntax, no special knowledge is required to use them from client code. Pour activer des méthodes d'extension pour un type particulier, ajoutez simplement une directive using pour l'espace de noms dans lequel les méthodes sont définies.To enable extension methods for a particular type, just add a using directive for the namespace in which the methods are defined. Par exemple, pour utiliser les opérateurs de requête standard, ajoutez la directive using à votre code :For example, to use the standard query operators, add this using directive to your code:

using System.Linq;  

(Il peut également être nécessaire d'ajouter une référence à System.Core.dll.) Vous pouvez remarquer que les opérateurs de requête standard apparaissent dorénavant dans IntelliSense comme des méthodes supplémentaires disponibles pour la plupart des types IEnumerable<T>.(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.

Note

Bien que les opérateurs de requête standard n'apparaissent pas dans IntelliSense pour String, ils sont encore disponibles.Although standard query operators do not appear in IntelliSense for String, they are still available.

Liaison de méthodes d'extension à la compilationBinding Extension Methods at Compile Time

Vous pouvez utiliser des méthodes d'extension pour étendre une classe ou une interface, mais pas pour les remplacer.You can use extension methods to extend a class or interface, but not to override them. Une méthode d'extension avec le même nom et la même signature qu'une méthode d'interface ou de classe ne sera jamais appelée.An extension method with the same name and signature as an interface or class method will never be called. Au moment de la compilation, les méthodes d'extension ont toujours la priorité la plus faible par rapport aux méthodes d'instance définies dans le type lui-même.At compile time, extension methods always have lower priority than instance methods defined in the type itself. En d'autres termes, si un type a une méthode nommée Process(int i) et que vous avez une méthode d'extension avec la même signature, le compilateur créera toujours une liaison avec la méthode d'instance.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. Lorsque le compilateur rencontre un appel de méthode, il recherche d'abord une correspondance dans les méthodes d'instance du type.When the compiler encounters a method invocation, it first looks for a match in the type's instance methods. Si aucune correspondance n'est trouvée, il recherche toutes les méthodes d'extension définies pour le type et crée une liaison avec la première méthode d'extension qu'il trouve.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. L’exemple suivant montre comment le compilateur détermine quelle méthode d’extension ou méthode d’instance est choisie pour créer une liaison.The following example demonstrates how the compiler determines which extension method or instance method to bind to.

ExempleExample

L’exemple suivant montre les règles que le compilateur C# suit pour déterminer s’il faut lier un appel de méthode à une méthode d’instance sur le type, ou à une méthode d’extension.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. Le classe statique Extensions contient des méthodes d'extension définies pour tout type qui implémente IMyInterface.The static class Extensions contains extension methods defined for any type that implements IMyInterface. Les classes A, B et C implémentent toutes l'interface.Classes A, B, and C all implement the interface.

La méthode d'extension MethodB n'est jamais appelée car son nom et sa signature correspondent exactement aux méthodes déjà implémentées par les classes.The MethodB extension method is never called because its name and signature exactly match methods already implemented by the classes.

Lorsque le compilateur ne trouve pas de méthode d’instance avec une signature correspondante, il crée une liaison avec une méthode d’extension correspondante, s’il en existe une.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(object, int)
            a.MethodA("hello");     // Extension.MethodA(object, 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(object, 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()
 */

Indications généralesGeneral Guidelines

En général, nous vous recommandons d'implémenter des méthodes d'extension modérément et uniquement lorsque cela est nécessaire.In general, we recommend that you implement extension methods sparingly and only when you have to. Dès que cela est possible, le code client qui doit étendre un type existant doit le faire en créant un type dérivé du type existant.Whenever possible, client code that must extend an existing type should do so by creating a new type derived from the existing type. Pour plus d’informations, consultez Héritage.For more information, see Inheritance.

Lors de l’utilisation d’une méthode d’extension pour étendre un type dont le code source ne peut pas être modifié, vous risquez d’interrompre votre méthode d’extension en cas de modification dans l’implémentation du type.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.

Si vous implémentez des méthodes d’extension pour un type donné, prenez en compte les points suivants :If you do implement extension methods for a given type, remember the following points:

  • Une méthode d'extension ne sera jamais appelée si elle a la même signature qu'une méthode définie dans le type.An extension method will never be called if it has the same signature as a method defined in the type.

  • Les méthodes d'extension sont mises en portée au niveau de l'espace de noms.Extension methods are brought into scope at the namespace level. Par exemple, si vous avez plusieurs classes statiques qui contiennent des méthodes d'extension dans un espace de noms unique nommé Extensions, elles seront toutes mises en portée par la directive using Extensions;.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.

Pour une bibliothèque de classes que vous avez implémentée, vous ne devez pas utiliser de méthodes d'extension pour éviter d'incrémenter le numéro de version d'un assembly.For a class library that you implemented, you shouldn't use extension methods to avoid incrementing the version number of an assembly. Si vous souhaitez ajouter une fonctionnalité importante à une bibliothèque dont le code source vous appartient, vous devez suivre les directives .NET Framework standard relatives à la gestion de version des assemblys.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. Pour plus d’informations, consultez Versioning des assemblys.For more information, see Assembly Versioning.

Voir aussiSee Also

Guide de programmation C#C# Programming Guide
Exemples de programmation parallèle (il s’agit de nombreux exemples de méthodes d’extension)Parallel Programming Samples (these include many example extension methods)
Expressions lambdaLambda Expressions
Vue d’ensemble des opérateurs de requête standardStandard Query Operators Overview
Règles de conversion pour les paramètres Instance et leur impactConversion rules for Instance parameters and their impact
Interopérabilité des méthodes d’extension entre les langagesExtension methods Interoperability between languages
Méthodes d’extension et délégués curryfiésExtension methods and Curried Delegates
Liaison de méthode d’extension et rapport d’erreursExtension method Binding and Error reporting