Metodi di estensione (Guida per programmatori C#)Extension Methods (C# Programming Guide)

I metodi di estensione consentono di "aggiungere" metodi ai tipi esistenti senza creare un nuovo tipo derivato, ricompilare o modificare in altro modo il tipo originale.Extension methods enable you to "add" methods to existing types without creating a new derived type, recompiling, or otherwise modifying the original type. I metodi di estensione sono metodi statici, ma vengono chiamati come se fossero metodi di istanza sul tipo esteso.Extension methods are static methods, but they're called as if they were instance methods on the extended type. Per il codice client scritto in C#, F # e Visual Basic, non esiste alcuna differenza evidente tra la chiamata di un metodo di estensione e i metodi definiti in un tipo.For client code written in C#, F# and Visual Basic, there's no apparent difference between calling an extension method and the methods defined in a type.

I metodi di estensione più comuni sono gli operatori di query standard LINQ che aggiungono la funzionalità di query ai System.Collections.IEnumerable tipi e esistenti System.Collections.Generic.IEnumerable<T> .The most common extension methods are the LINQ standard query operators that add query functionality to the existing System.Collections.IEnumerable and System.Collections.Generic.IEnumerable<T> types. Per utilizzare gli operatori query standard, inserirli innanzitutto nell'ambito con una direttiva using System.Linq.To use the standard query operators, first bring them into scope with a using System.Linq directive. In questo modo qualsiasi tipo che implementa IEnumerable<T> avrà apparentemente metodi di istanza quali GroupBy, OrderBy, Averagee così via.Then any type that implements IEnumerable<T> appears to have instance methods such as GroupBy, OrderBy, Average, and so on. È possibile visualizzare questi metodi aggiuntivi con la funzionalità di completamento istruzioni di IntelliSense quando si digita "punto" dopo un'istanza di un tipo IEnumerable<T>, ad esempio List<T> o 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.

Esempio di OrderByOrderBy Example

Nell'esempio seguente viene illustrato come chiamare il metodo OrderBy dell'operatore query standard su una matrice di Integer.The following example shows how to call the standard query operator OrderBy method on an array of integers. L'espressione tra parentesi è un'espressione lambda.The expression in parentheses is a lambda expression. Molti operatori di query standard accettano espressioni lambda come parametri, ma questo non è un requisito per i metodi di estensione.Many standard query operators take lambda expressions as parameters, but this isn't a requirement for extension methods. Per altre informazioni, vedere espressioni 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

I metodi di estensione sono definiti come metodi statici, ma vengono chiamati utilizzando la sintassi del metodo di istanza.Extension methods are defined as static methods but are called by using instance method syntax. Il primo parametro specifica il tipo su cui opera il metodo.Their first parameter specifies which type the method operates on. Il parametro è preceduto dal modificatore this .The parameter is preceded by the this modifier. I metodi di estensione si trovano nell'ambito solo quando si importa in modo esplicito lo spazio dei nomi nel codice sorgente con una direttiva using.Extension methods are only in scope when you explicitly import the namespace into your source code with a using directive.

Nell'esempio riportato di seguito viene illustrato un metodo di estensione definito per la classe System.String.The following example shows an extension method defined for the System.String class. Viene definito all'interno di una classe statica non annidata e non generica:It's 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;
        }
    }
}

Il metodo di estensione WordCount può essere inserito nell'ambito con questa direttiva using:The WordCount extension method can be brought into scope with this using directive:

using ExtensionMethods;

Può inoltre essere chiamato da un'applicazione utilizzando questa sintassi:And it can be called from an application by using this syntax:

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

Il metodo di estensione viene richiamato nel codice con la sintassi del metodo di istanza.You invoke the extension method in your code with instance method syntax. Il linguaggio intermedio (IL) generato dal compilatore converte il codice in una chiamata sul metodo statico.The intermediate language (IL) generated by the compiler translates your code into a call on the static method. Il principio di incapsulamento non viene effettivamente violato.The principle of encapsulation is not really being violated. I metodi di estensione non possono accedere a variabili private nel tipo che stanno estendendo.Extension methods cannot access private variables in the type they are extending.

Per ulteriori informazioni, vedere come implementare e chiamare un metodo di estensione personalizzato.For more information, see How to implement and call a custom extension method.

In generale, probabilmente si chiamerà metodi di estensione molto più spesso rispetto all'implementazione di un proprio.In general, you'll probably be calling extension methods far more often than implementing your own. Perché i metodi di estensione vengono chiamati utilizzando la sintassi del metodo di istanza, non è necessaria alcuna particolare conoscenza per utilizzarli dal codice client.Because extension methods are called by using instance method syntax, no special knowledge is required to use them from client code. Per abilitare i metodi di estensione per un particolare tipo, aggiungere una direttiva using per lo spazio dei nomi nel quale sono definiti i metodi.To enable extension methods for a particular type, just add a using directive for the namespace in which the methods are defined. Per utilizzare ad esempio gli operatori query standard, aggiungere questa direttiva using al codice:For example, to use the standard query operators, add this using directive to your code:

using System.Linq;

Potrebbe anche essere necessario aggiungere un riferimento a System.Core.dll. Si noterà che gli operatori di query standard vengono ora visualizzati in IntelliSense come metodi aggiuntivi disponibili per la maggior parte dei IEnumerable<T> tipi.(You may also have to add a reference to System.Core.dll.) You'll notice that the standard query operators now appear in IntelliSense as additional methods available for most IEnumerable<T> types.

Associazione di metodi di estensione in fase di compilazioneBinding Extension Methods at Compile Time

È possibile utilizzare metodi di estensione per estendere una classe o un'interfaccia, ma non per eseguirne l'override.You can use extension methods to extend a class or interface, but not to override them. Un metodo di estensione con lo stesso nome e la stessa firma di un metodo di interfaccia o di classe non verrà mai chiamato.An extension method with the same name and signature as an interface or class method will never be called. In fase di compilazione, i metodi di estensione hanno sempre una priorità più bassa dei metodi di istanza definiti nel tipo stesso.At compile time, extension methods always have lower priority than instance methods defined in the type itself. In altre parole, se un tipo dispone di un metodo denominato Process(int i) e si dispone di un metodo di estensione con la stessa firma, il compilatore eseguirà sempre l'associazione al metodo di istanza.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. Quando il compilatore rileva una chiamata al metodo, cerca innanzitutto una corrispondenza nei metodi di istanza del tipo.When the compiler encounters a method invocation, it first looks for a match in the type's instance methods. Se non viene trovata alcuna corrispondenza, cercherà eventuali metodi di estensione definiti per il tipo ed eseguirà l'associazione al primo metodo di estensione trovato.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. Nell'esempio seguente viene dimostrato come il compilatore determina a quale metodo di estensione o metodo di istanza eseguire l'associazione.The following example demonstrates how the compiler determines which extension method or instance method to bind to.

EsempioExample

Nell'esempio seguente vengono illustrate le regole che il compilatore C# segue nel determinare se associare una chiamata al metodo a un metodo di istanza sul tipo o a un metodo di estensione.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. La classe Extensions statica contiene metodi di estensione definiti per qualsiasi tipo che implementa IMyInterface.The static class Extensions contains extension methods defined for any type that implements IMyInterface. Le classi A, B e C implementano tutte l'interfaccia.Classes A, B, and C all implement the interface.

Il metodo di estensione MethodB non viene mai chiamato perché il nome e la firma corrispondono esattamente a metodi già implementati dalle classi.The MethodB extension method is never called because its name and signature exactly match methods already implemented by the classes.

Quando il compilatore non riesce a trovare un metodo di istanza con una firma corrispondente, eseguirà l'associazione a un metodo di estensione corrispondente se ne esiste uno.When the compiler can't 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()
 */

Modelli di utilizzo comuniCommon Usage Patterns

Funzionalità di raccoltaCollection Functionality

In passato, era comune creare "classi di raccolta" che implementavano l' System.Collections.Generic.IEnumerable<T> interfaccia per un determinato tipo e conteneva la funzionalità che agiva sulle raccolte di quel tipo.In the past, it was common to create "Collection Classes" that implemented the System.Collections.Generic.IEnumerable<T> interface for a given type and contained functionality that acted on collections of that type. Anche se non c'è niente di sbagliato nella creazione di questo tipo di oggetto Collection, è possibile ottenere la stessa funzionalità usando un'estensione in System.Collections.Generic.IEnumerable<T> .While there's nothing wrong with creating this type of collection object, the same functionality can be achieved by using an extension on the System.Collections.Generic.IEnumerable<T>. Le estensioni offrono il vantaggio di consentire la chiamata della funzionalità da qualsiasi raccolta, ad esempio System.Array o System.Collections.Generic.List<T> che implementi System.Collections.Generic.IEnumerable<T> in tale tipo.Extensions have the advantage of allowing the functionality to be called from any collection such as an System.Array or System.Collections.Generic.List<T> that implements System.Collections.Generic.IEnumerable<T> on that type. Un esempio di questo esempio di utilizzo di una matrice di Int32 è disponibile in precedenza in questo articolo.An example of this using an Array of Int32 can be found earlier in this article.

Funzionalità specifiche del livelloLayer-Specific Functionality

Quando si usa un'architettura a cipolla o un'altra progettazione di applicazioni a più livelli, è comune avere un set di entità di dominio o oggetti Trasferimento dati che possono essere usati per comunicare tra i limiti dell'applicazione.When using an Onion Architecture or other layered application design, it's common to have a set of Domain Entities or Data Transfer Objects that can be used to communicate across application boundaries. Questi oggetti in genere non contengono funzionalità o solo funzionalità minime che si applicano a tutti i livelli dell'applicazione.These objects generally contain no functionality, or only minimal functionality that applies to all layers of the application. I metodi di estensione possono essere usati per aggiungere funzionalità specifiche per ogni livello dell'applicazione senza caricare l'oggetto con metodi non necessari o desiderati in altri livelli.Extension methods can be used to add functionality that is specific to each application layer without loading the object down with methods not needed or wanted in other layers.

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}";
}

Estensione di tipi predefinitiExtending Predefined Types

Anziché creare nuovi oggetti quando è necessario creare funzionalità riutilizzabili, è spesso possibile estendere un tipo esistente, ad esempio un tipo .NET o CLR.Rather than creating new objects when reusable functionality needs to be created, we can often extend an existing type, such as a .NET or CLR type. Ad esempio, se non si usano i metodi di estensione, è possibile creare Engine una Query classe o per eseguire il lavoro di esecuzione di una query su un SQL Server che può essere chiamato da più posizioni nel codice.As an example, if we don't use extension methods, we might create an Engine or Query class to do the work of executing a query on a SQL Server that may be called from multiple places in our code. Tuttavia, è possibile estendere la System.Data.SqlClient.SqlConnection classe usando i metodi di estensione per eseguire la query da qualsiasi luogo in cui è presente una connessione a una SQL Server.However we can instead extend the System.Data.SqlClient.SqlConnection class using extension methods to perform that query from anywhere we have a connection to a SQL Server. Altri esempi potrebbero consistere nell'aggiungere funzionalità comuni alla System.String classe, estendere le funzionalità di elaborazione dei dati System.IO.File degli System.IO.Stream oggetti e e System.Exception gli oggetti per una specifica funzionalità di gestione degli errori.Other examples might be to add common functionality to the System.String class, extend the data processing capabilities of the System.IO.File and System.IO.Stream objects, and System.Exception objects for specific error handling functionality. Questi tipi di casi d'uso sono limitati solo dalla propria immaginazione e dal buon senso.These types of use-cases are limited only by your imagination and good sense.

L'estensione dei tipi predefiniti può essere difficile con i struct tipi perché vengono passati per valore ai metodi.Extending predefined types can be difficult with struct types because they're passed by value to methods. Ciò significa che vengono apportate modifiche allo struct a una copia dello struct.That means any changes to the struct are made to a copy of the struct. Queste modifiche non sono visibili quando il metodo di estensione viene chiuso.Those changes aren't visible once the extension method exits. A partire da C# 7,2, è possibile aggiungere il ref modificatore al primo argomento di un metodo di estensione.Beginning with C# 7.2, you can add the ref modifier to the first argument of an extension method. L'aggiunta del ref modificatore indica che il primo argomento viene passato per riferimento.Adding the ref modifier means the first argument is passed by reference. In questo modo è possibile scrivere metodi di estensione che modificano lo stato dello struct esteso.This enables you to write extension methods that change the state of the struct being extended.

Linee guida generaliGeneral Guidelines

Sebbene sia ancora considerato preferibile aggiungere funzionalità modificando il codice di un oggetto o derivando un nuovo tipo ogni volta che è ragionevole ed è possibile farlo, i metodi di estensione sono diventati un'opzione cruciale per la creazione di funzionalità riutilizzabili nell'ecosistema .NET.While it's still considered preferable to add functionality by modifying an object's code or deriving a new type whenever it's reasonable and possible to do so, extension methods have become a crucial option for creating reusable functionality throughout the .NET ecosystem. Per le situazioni in cui l'origine originale non è sotto il controllo, quando un oggetto derivato è inappropriato o impossibile oppure quando la funzionalità non deve essere esposta oltre l'ambito applicabile, i metodi di estensione rappresentano una scelta ottimale.For those occasions when the original source isn't under your control, when a derived object is inappropriate or impossible, or when the functionality shouldn't be exposed beyond its applicable scope, Extension methods are an excellent choice.

Per ulteriori informazioni sui tipi derivati, vedere ereditarietà.For more information on derived types, see Inheritance.

Quando si usa un metodo di estensione per estendere un tipo il cui codice sorgente non è in grado di controllare, si corre il rischio che una modifica nell'implementazione del tipo provochi l'interruzione del metodo di estensione.When using an extension method to extend a type whose source code you aren't in control of, you run the risk that a change in the implementation of the type will cause your extension method to break.

Se si implementano metodi di estensione per un determinato tipo, è importante tenere presente quanto segue:If you do implement extension methods for a given type, remember the following points:

  • Un metodo di estensione non verrà mai chiamato se dispone della stessa firma di un metodo definito nel tipo.An extension method will never be called if it has the same signature as a method defined in the type.
  • I metodi di estensione vengono inseriti nell'ambito al livello dello spazio dei nomi.Extension methods are brought into scope at the namespace level. Se, ad esempio, sono presenti più classi statiche che contengono metodi di estensione in un singolo spazio dei nomi denominato Extensions , verranno tutti inseriti nell'ambito using Extensions; dalla direttiva.For example, if you have multiple static classes that contain extension methods in a single namespace named Extensions, they'll all be brought into scope by the using Extensions; directive.

Per una libreria di classi implementata, non è necessario utilizzare i metodi di estensione per evitare l'incremento del numero di versione di un assembly.For a class library that you implemented, you shouldn't use extension methods to avoid incrementing the version number of an assembly. Se si desidera aggiungere funzionalità significative a una libreria per la quale si è proprietari del codice sorgente, attenersi alle linee guida di .NET per il controllo delle versioni degli assembly.If you want to add significant functionality to a library for which you own the source code, follow the .NET guidelines for assembly versioning. Per altre informazioni, vedere Controllo delle versioni degli assembly.For more information, see Assembly Versioning.

Vedere ancheSee also