Méthodes d’extension (Guide de programmation C#)
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. Les méthodes d'extension sont des méthodes statiques appelées comme s'il s'agissait de méthodes d'instance sur le type étendu. 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 définies dans un type.
Les méthodes d’extension les plus courantes sont les opérateurs de requête standard LINQ qui ajoutent des fonctionnalités de requête aux types System.Collections.IEnumerable et System.Collections.Generic.IEnumerable<T> existants. Pour utiliser les opérateurs de requête standard, introduisez-les d'abord dans la portée avec une directive using System.Linq. Puis, tout type qui implémente IEnumerable<T> semble avoir des méthodes d'instance telles que GroupBy, OrderBy, Average, etc. 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.
Exemple OrderBy
L'exemple suivant indique comment appeler la méthode OrderBy d'opérateur de requête standard sur un tableau d'entiers. L'expression entre parenthèses est une expression lambda. 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. Pour plus d’informations, consultez Expressions lambda.
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. Leur premier paramètre spécifie le type sur lequel la méthode opère. Le paramètre suit ce modificateur. 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.
L'exemple suivant présente une méthode d'extension définie pour la classe System.String. Elle est définie à l'intérieur d'une classe statique, non imbriquée et non générique :
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 :
using ExtensionMethods;
Elle peut être appelée à partir d'une application à l'aide de cette syntaxe :
string s = "Hello Extension Methods";
int i = s.WordCount();
Vous appelez la méthode d'extension dans votre code avec la syntaxe de méthode d'instance. Le langage intermédiaire (IL) généré par le compilateur traduit votre code dans un appel sur la méthode statique. Le principe d’encapsulation n’est pas réellement violé. Les méthodes d’extension ne peuvent pas accéder aux variables privées dans le type qu’elles étendent.
La classe MyExtensions et la méthode WordCount sont static et elles sont accessibles comme tous les autres membres static. La méthode WordCount peut être appelée comme d’autres méthodes static comme suit :
string s = "Hello Extension Methods";
int i = MyExtensions.WordCount(s);
Le code C# précédent :
- Déclare et affecte un nouveau
stringnommésavec la valeur"Hello Extension Methods". - Appelle l’argument
MyExtensions.WordCountdonnés.
Pour plus d’informations, consultez Comment implémenter et appeler une méthode d’extension personnalisée.
En général, vous appellerez probablement les méthodes d’extension beaucoup plus souvent que vous n’implémenterez les vôtres. 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. 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. Par exemple, pour utiliser les opérateurs de requête standard, ajoutez la directive using à votre code :
using System.Linq;
(Vous devrez peut-être également ajouter une référence à System.Core.dll.) Vous remarquerez que les opérateurs de requête standard apparaissent désormais dans IntelliSense en tant que méthodes supplémentaires disponibles pour la plupart des types IEnumerable<T>.
Liaison de méthodes d’extension à la compilation
Vous pouvez utiliser des méthodes d'extension pour étendre une classe ou une interface, mais pas pour les remplacer. 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. 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. 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. Lorsque le compilateur rencontre un appel de méthode, il recherche d'abord une correspondance dans les méthodes d'instance du type. 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.
Exemple
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. Le classe statique Extensions contient des méthodes d'extension définies pour tout type qui implémente IMyInterface. Les classes A, B et C implémentent toutes l'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.
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.
// Define an interface named IMyInterface.
namespace DefineIMyInterface
{
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()
*/
Modes d’utilisation courants
Fonctionnalités des collections
Dans le passé, il était courant de créer des « classes de collection » qui implémentaient l’interface System.Collections.Generic.IEnumerable<T> pour un type donné et contenaient des fonctionnalités qui agissaient sur des collections de ce type. Bien qu’il n’y ait rien de mal à créer ce type d’objet de collection, la même fonctionnalité peut être obtenue à l’aide d’une extension sur System.Collections.Generic.IEnumerable<T>. Les extensions ont l’avantage de permettre à la fonctionnalité d’être appelée à partir de n’importe quelle collection, telle que System.Array ou System.Collections.Generic.List<T> qui implémente System.Collections.Generic.IEnumerable<T> sur ce type. Vous trouverez un exemple de ceci à l’aide d’un tableau d’Int32 plus haut dans cet article.
Fonctionnalité Layer-Specific
Lors de l’utilisation d’une architecture Onion ou d’une autre conception d’application en couches, il est commun d’avoir un ensemble d’entités de domaine ou d’objets de transfert de données qui peuvent être utilisés pour communiquer entre les limites de l’application. Ces objets ne contiennent généralement aucune fonctionnalité, ou seulement des fonctionnalités minimales qui s’appliquent à toutes les couches de l’application. Les méthodes d’extension peuvent être utilisées pour ajouter des fonctionnalités spécifiques à chaque couche d’application sans charger l’objet avec des méthodes non nécessaires ou non souhaitées dans d’autres couches.
public class DomainEntity
{
public int Id { get; set; }
public string FirstName { get; set; }
public string LastName { get; set; }
}
static class DomainEntityExtensions
{
static string FullName(this DomainEntity value)
=> $"{value.FirstName} {value.LastName}";
}
Extension des types prédéfinis
Plutôt que de créer des objets lorsque des fonctionnalités réutilisables doivent être créées, nous pouvons souvent étendre un type existant, tel qu’un type .NET ou CLR. Par exemple, si nous n’utilisons pas de méthodes d’extension, nous pouvons créer une classe Engine ou Query pour exécuter une requête sur SQL Server qui peut être appelé à plusieurs emplacements dans notre code. Toutefois, nous pouvons à la place étendre la classe System.Data.SqlClient.SqlConnection à l’aide de méthodes d’extension pour exécuter cette requête à partir de n’importe où nous avons une connexion à SQL Server. D’autres exemples consistent à ajouter des fonctionnalités courantes à la classe System.String, à étendre les fonctionnalités de traitement des données de l’objet System.IO.Stream et des objets System.Exception pour des fonctionnalités de gestion des erreurs spécifiques. Ces types de cas d’usage ne sont limités que par votre imagination et votre bon sens.
L’extension de types prédéfinis peut être difficile avec les types struct, car ils sont transmis par valeur aux méthodes. Cela signifie que toutes les modifications apportées au struct sont apportées à une copie du struct. Ces modifications ne sont pas visibles une fois la méthode d’extension terminée. Vous pouvez ajouter le modificateur ref au premier argument pour en faire une méthode d’extension ref. Le mot clé ref peut apparaître avant ou après le mot clé this sans aucune différence sémantique. L’ajout du modificateur ref signifie que le premier argument est passé par référence. Cette opération vous permet d’écrire des méthodes d’extension qui modifient l’état du type struct en cours d’extension (notez que les membres privés ne sont pas accessibles). Seuls les types valeur ou les types génériques contraints à struct (voir contrainte struct pour plus d’informations) sont autorisés en tant que premier paramètre d’une méthode d’extension ref. L’exemple suivant montre comment utiliser une méthode d’extension ref pour modifier directement un type intégré sans avoir à réaffecter le résultat ou à le transmettre à une fonction avec le mot clé ref :
public static class IntExtensions
{
public static void Increment(this int number)
=> number++;
// Take note of the extra ref keyword here
public static void RefIncrement(this ref int number)
=> number++;
}
public static class IntProgram
{
public static void Test()
{
int x = 1;
// Takes x by value leading to the extension method
// Increment modifying its own copy, leaving x unchanged
x.Increment();
Console.WriteLine($"x is now {x}"); // x is now 1
// Takes x by reference leading to the extension method
// RefIncrement changing the value of x directly
x.RefIncrement();
Console.WriteLine($"x is now {x}"); // x is now 2
}
}
L’exemple suivant illustre les méthodes d’extension ref pour les types de structs définis par l’utilisateur :
public struct Account
{
public uint id;
public float balance;
private int secret;
}
public static class AccountExtensions
{
// ref keyword can also appear before the this keyword
public static void Deposit(ref this Account account, float amount)
{
account.balance += amount;
// The following line results in an error as an extension
// method is not allowed to access private members
// account.secret = 1; // CS0122
}
}
public static class AccountProgram
{
public static void Test()
{
Account account = new()
{
id = 1,
balance = 100f
};
Console.WriteLine($"I have ${account.balance}"); // I have $100
account.Deposit(50f);
Console.WriteLine($"I have ${account.balance}"); // I have $150
}
}
Instructions générales
Bien qu’il soit toujours préférable d’ajouter des fonctionnalités en modifiant le code d’un objet ou en dérivant un nouveau type chaque fois qu’il est possible et raisonnable de le faire, les méthodes d’extension sont devenues une option essentielle pour créer des fonctionnalités réutilisables dans l’écosystème .NET. Dans les cas où la source d’origine n’est pas sous votre contrôle, lorsqu’un objet dérivé est inapproprié ou impossible, ou lorsque la fonctionnalité ne doit pas être exposée au-delà de son étendue applicable, les méthodes d’extension sont un excellent choix.
Pour plus d’informations sur les types dérivés, consultez Héritage.
Lors de l’utilisation d’une méthode d’extension pour étendre un type dont vous ne contrôlez pas le code source, vous risquez d’interrompre votre méthode d’extension en cas de modification dans l’implémentation du type.
Si vous implémentez des méthodes d’extension pour un type donné, prenez en compte les points suivants :
- Une méthode d’extension n’est pas appelée si elle a la même signature qu’une méthode définie dans le type.
- Les méthodes d'extension sont mises en portée au niveau de l'espace de noms. 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 directiveusing Extensions;.
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. Si vous souhaitez ajouter une fonctionnalité importante à une bibliothèque dont le code source vous appartient, vous devez suivre les directives .NET relatives à la gestion de version des assemblys. Pour plus d’informations, consultez Versioning des assemblys.
Voir aussi
- Exemples de programmation parallèle (il s’agit de nombreux exemples de méthodes d’extension)
- Expressions lambda
- Vue d'ensemble des opérateurs de requête standard
- Règles de conversion pour les paramètres Instance et leur impact
- Interopérabilité des méthodes d’extension entre les langages
- Méthodes d’extension et délégués curryfiés
- Extension method Binding and Error reporting
