Métodos de extensão (Guia de Programação em C#)Extension Methods (C# Programming Guide)

Os métodos de extensão permitem que você "adicione" tipos existentes sem criar um novo tipo derivado, recompilar ou, caso contrário, modificar o tipo original.Extension methods enable you to "add" methods to existing types without creating a new derived type, recompiling, or otherwise modifying the original type. Os métodos de extensão são métodos estáticos, mas são chamados como se fossem métodos de instância no tipo estendido.Extension methods are static methods, but they're called as if they were instance methods on the extended type. Para o código de cliente escrito em C#, F # e Visual Basic, não há nenhuma diferença aparente entre chamar um método de extensão e os métodos definidos em um 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.

Os métodos de extensão mais comuns são os operadores de consulta padrão do LINQ que adicionam a System.Collections.IEnumerable funcionalidade System.Collections.Generic.IEnumerable<T> de consulta aos tipos existentes e.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. Para usar os operadores de consulta padrão, traga-os primeiro ao escopo com uma diretiva using System.Linq.To use the standard query operators, first bring them into scope with a using System.Linq directive. Em seguida, qualquer tipo que implemente IEnumerable<T> parece ter métodos de instância como GroupBy, OrderBy, Average e assim por diante.Then any type that implements IEnumerable<T> appears to have instance methods such as GroupBy, OrderBy, Average, and so on. Você pode exibir esses métodos adicionais no preenchimento de declaração do IntelliSense ao digitar "ponto" após uma instância de um tipo IEnumerable<T> como 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.

Exemplo de OrderByOrderBy Example

O exemplo a seguir mostra como chamar o método de consulta padrão OrderBy em qualquer matriz de inteiros.The following example shows how to call the standard query operator OrderBy method on an array of integers. A expressão entre parênteses é uma expressão lambda.The expression in parentheses is a lambda expression. Muitos operadores de consulta padrão usam expressões lambda como parâmetros, mas isso não é um requisito para métodos de extensão.Many standard query operators take lambda expressions as parameters, but this isn't a requirement for extension methods. Para obter mais informações, consulte Expressões 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

Os métodos de extensão são definidos como estáticos, mas são chamados usando a sintaxe do método de instância.Extension methods are defined as static methods but are called by using instance method syntax. Seu primeiro parâmetro especifica em qual tipo o método opera.Their first parameter specifies which type the method operates on. O parâmetro é precedido por este modificador.The parameter is preceded by the this modifier. Os métodos de extensão só estarão no escopo quando você importar explicitamente o namespace para seu código-fonte com uma diretiva using.Extension methods are only in scope when you explicitly import the namespace into your source code with a using directive.

O exemplo a seguir mostra um método de extensão definido para a classe System.String.The following example shows an extension method defined for the System.String class. Ele é definido dentro de uma classe estática não aninhada não genérica: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;
        }
    }
}

O método de extensão WordCount pode ser colocado no escopo com esta diretiva using:The WordCount extension method can be brought into scope with this using directive:

using ExtensionMethods;

E pode ser chamado a partir de um aplicativo usando esta sintaxe:And it can be called from an application by using this syntax:

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

Você invoca o método de extensão em seu código com a sintaxe do método de instância.You invoke the extension method in your code with instance method syntax. A IL (linguagem intermediária) gerada pelo compilador converte seu código em uma chamada no método estático.The intermediate language (IL) generated by the compiler translates your code into a call on the static method. O princípio do encapsulamento não está realmente violado.The principle of encapsulation is not really being violated. Os métodos de extensão não podem acessar variáveis privadas no tipo que estão sendo estendidas.Extension methods cannot access private variables in the type they are extending.

Para obter mais informações, consulte como implementar e chamar um método de extensão personalizado.For more information, see How to implement and call a custom extension method.

Em geral, você provavelmente estará chamando métodos de extensão muito mais frequentemente do que implementar seus próprios.In general, you'll probably be calling extension methods far more often than implementing your own. Como os métodos de extensão são chamados com a sintaxe do método de instância, nenhum conhecimento especial é necessário para usá-los no código do cliente.Because extension methods are called by using instance method syntax, no special knowledge is required to use them from client code. Para habilitar métodos de extensão para um tipo específico, apenas adicione uma diretiva using para o namespace no qual os métodos estão definidos.To enable extension methods for a particular type, just add a using directive for the namespace in which the methods are defined. Por exemplo, para usar os operadores de consulta padrão, adicione esta diretiva using ao seu código:For example, to use the standard query operators, add this using directive to your code:

using System.Linq;

(Você também pode precisar adicionar uma referência a System. Core. dll.) Você observará que os operadores de consulta padrão agora aparecem no IntelliSense como métodos adicionais disponíveis para IEnumerable<T> a maioria dos tipos.(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.

Associando Métodos de Extensão no Momento da CompilaçãoBinding Extension Methods at Compile Time

Você pode usar métodos de extensão para estender uma classe ou interface, mas não os substituir.You can use extension methods to extend a class or interface, but not to override them. Um método de extensão com o mesmo nome e assinatura que um método de interface ou classe nunca será chamado.An extension method with the same name and signature as an interface or class method will never be called. No tempo de compilação, os métodos de extensão sempre têm menos prioridade que os métodos de instância definidos no próprio tipo.At compile time, extension methods always have lower priority than instance methods defined in the type itself. Em outras palavras, se um tipo possuir um método chamado Process(int i) e se você tiver um método de extensão com a mesma assinatura, o compilador sempre se associará ao método de instância.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 o compilador encontra uma invocação de método, primeiro ele procura uma correspondência nos métodos de instância do tipo.When the compiler encounters a method invocation, it first looks for a match in the type's instance methods. Se nenhuma correspondência for encontrada, ele irá procurar todos os métodos de extensão definidos para o tipo e associará o primeiro método de extensão que encontrar.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. O exemplo a seguir demonstra como o compilador determina a qual método de extensão ou método de instância associar.The following example demonstrates how the compiler determines which extension method or instance method to bind to.

ExemploExample

O exemplo a seguir demonstra as regras que o compilador C# segue ao determinar se deve associar uma chamada de método a um método de instância no tipo ou a um método de extensão.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. A classe estática Extensions contém métodos de extensão definidos para qualquer tipo que implementa IMyInterface.The static class Extensions contains extension methods defined for any type that implements IMyInterface. As classes A, B e C implementam a interface.Classes A, B, and C all implement the interface.

O método de extensão MethodB nunca é chamado porque seu nome e assinatura são exatamente iguais aos métodos já implementados pelas classes.The MethodB extension method is never called because its name and signature exactly match methods already implemented by the classes.

Quando o compilador não consegue localizar um método de instância com uma assinatura correspondente, ele se associará a um método de extensão correspondente, se houver.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()
 */

Padrões de uso comunsCommon Usage Patterns

Funcionalidade de coleçãoCollection Functionality

No passado, era comum criar "classes de coleção" que implementavam a System.Collections.Generic.IEnumerable<T> interface para um determinado tipo e uma funcionalidade contida que atuava em coleções desse 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. Embora não haja nada de errado ao criar esse tipo de objeto de coleção, a mesma funcionalidade pode ser obtida usando uma extensão no 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>. As extensões têm a vantagem de permitir que a funcionalidade seja chamada de qualquer coleção, como System.Array uma System.Collections.Generic.List<T> ou implementada System.Collections.Generic.IEnumerable<T> nesse 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. Um exemplo disso é usar uma matriz de Int32, que pode ser encontrada anteriormente neste artigo.An example of this using an Array of Int32 can be found earlier in this article.

Funcionalidade específica de camadaLayer-Specific Functionality

Ao usar uma arquitetura de cebola ou outro design de aplicativo em camadas, é comum ter um conjunto de entidades de domínio ou Transferência de Dados objetos que podem ser usados para se comunicar entre os limites do aplicativo.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. Esses objetos geralmente não contêm nenhuma funcionalidade ou apenas funcionalidade mínima que se aplica a todas as camadas do aplicativo.These objects generally contain no functionality, or only minimal functionality that applies to all layers of the application. Os métodos de extensão podem ser usados para adicionar funcionalidade específica a cada camada de aplicativo sem carregar o objeto com métodos não necessários ou desejados em outras camadas.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}";
}

Estendendo tipos predefinidosExtending Predefined Types

Em vez de criar novos objetos quando a funcionalidade reutilizável precisa ser criada, muitas vezes podemos estender um tipo existente, como um .NET Framework ou um tipo CLR.Rather than creating new objects when reusable functionality needs to be created, we can often extend an existing type such as a .NET Framework or CLR type. Por exemplo, se não usarmos métodos de extensão, podemos criar uma Engine classe or Query para fazer o trabalho de executar uma consulta em um SQL Server que pode ser chamado de vários locais em nosso código.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. No entanto, podemos estender System.Data.SqlClient.SqlConnection a classe usando métodos de extensão para executar essa consulta em qualquer lugar em que tenhamos uma conexão com um 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. Outros exemplos System.String podem ser adicionar funcionalidade comum à classe, estender os recursos de processamento de dados dos objetos System.IO.File e System.IO.Stream e System.Exception objetos para a funcionalidade de tratamento de erros específica.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. Esses tipos de casos de uso são limitados apenas por sua imaginação e bom sentido.These types of use-cases are limited only by your imagination and good sense.

A extensão de tipos predefinidos struct pode ser difícil com tipos porque eles são passados por valor para métodos.Extending predefined types can be difficult with struct types because they're passed by value to methods. Isso significa que qualquer alteração na estrutura é feita em uma cópia da estrutura.That means any changes to the struct are made to a copy of the struct. Essas alterações não serão visíveis depois que o método de extensão sair.Those changes aren't visible once the extension method exits. A partir do C# 7,2, você pode adicionar ref o modificador ao primeiro argumento de um método de extensão.Beginning with C# 7.2, you can add the ref modifier to the first argument of an extension method. Adicionar o ref modificador significa que o primeiro argumento é passado por referência.Adding the ref modifier means the first argument is passed by reference. Isso permite que você escreva métodos de extensão que alteram o estado da estrutura que está sendo estendida.This enables you to write extension methods that change the state of the struct being extended.

Diretrizes geraisGeneral Guidelines

Embora ainda seja considerado preferível adicionar funcionalidade modificando o código de um objeto ou derivando um novo tipo sempre que for razoável e possível fazer isso, os métodos de extensão se tornaram uma opção crucial para a criação de funcionalidade reutilizável em todo o ecossistema do .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. Para as ocasiões em que a fonte original não está sob seu controle, quando um objeto derivado é inadequado ou impossível, ou quando a funcionalidade não deve ser exposta além do escopo aplicável, os métodos de extensão são uma opção excelente.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.

Para obter mais informações sobre tipos derivados, consulte herança.For more information on derived types, see Inheritance.

Ao usar um método de extensão para estender um tipo cujo código-fonte você não está controlando, você corre o risco de que uma alteração na implementação do tipo cause a interrupção do método de extensão.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 você implementar métodos de extensão para um determinado tipo, lembre-se das seguintes considerações:If you do implement extension methods for a given type, remember the following points:

  • Um método de extensão nunca será chamado se possuir a mesma assinatura que um método definido no tipo.An extension method will never be called if it has the same signature as a method defined in the type.
  • Os métodos de extensão são trazidos para o escopo no nível do namespace.Extension methods are brought into scope at the namespace level. Por exemplo, se você tiver várias classes estáticas que contêm métodos de extensão em um único Extensionsnamespace chamado, elas serão colocadas no escopo pela using Extensions; diretiva.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.

Para uma biblioteca de classes que você implemente, não use métodos de extensão para evitar incrementar o número de versão de um assembly.For a class library that you implemented, you shouldn't use extension methods to avoid incrementing the version number of an assembly. Se desejar adicionar funcionalidade significativa a uma biblioteca da qual você possua o código-fonte, siga as diretrizes padrão do .NET Framework para controle de versão do assembly.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. Para obter mais informações, consulte Controle de versão do assembly.For more information, see Assembly Versioning.

Confira tambémSee also