Métodos de extensión (Guía de programación de C#)Extension Methods (C# Programming Guide)

Los métodos de extensión permiten "agregar" métodos a los tipos existentes sin crear un nuevo tipo derivado, recompilar o modificar de otra manera el 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. Los métodos de extensión son métodos estáticos, pero se les llama como si fueran métodos de instancia en el tipo extendido.Extension methods are static methods, but they're called as if they were instance methods on the extended type. En el caso del código de cliente escrito en C#, F# y Visual Basic, no existe ninguna diferencia aparente entre llamar a un método de extensión y llamar a los métodos definidos en 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.

Los métodos de extensión más comunes son los operadores de consulta LINQ estándar, que agregan funciones de consulta a los tipos System.Collections.IEnumerable y System.Collections.Generic.IEnumerable<T> existentes.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 los operadores de consulta estándar, inclúyalos primero en el ámbito con una directiva using System.Linq.To use the standard query operators, first bring them into scope with a using System.Linq directive. A partir de ese momento, cualquier tipo que implemente IEnumerable<T> parecerá tener métodos de instancia como GroupBy, OrderBy, Average, etc.Then any type that implements IEnumerable<T> appears to have instance methods such as GroupBy, OrderBy, Average, and so on. Puede ver estos métodos adicionales en la finalización de instrucciones de IntelliSense al escribir "punto" después de una instancia de un tipo IEnumerable<T>, como 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.

Ejemplo de OrderByOrderBy Example

En el ejemplo siguiente se muestra cómo llamar al método OrderBy de operador de consulta estándar en una matriz de enteros.The following example shows how to call the standard query operator OrderBy method on an array of integers. La expresión entre paréntesis es una expresión lambda.The expression in parentheses is a lambda expression. Muchos operadores de consulta estándar toman expresiones lambda como parámetros, pero no es un requisito para los métodos de extensión.Many standard query operators take lambda expressions as parameters, but this isn't a requirement for extension methods. Para obtener más información, vea Expresiones 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

Los métodos de extensión se definen como métodos estáticos, pero se les llama usando la sintaxis de método de instancia.Extension methods are defined as static methods but are called by using instance method syntax. Su primer parámetro especifica en qué tipo funciona el método.Their first parameter specifies which type the method operates on. El parámetro va precedido del modificador this.The parameter is preceded by the this modifier. Los métodos de extensión únicamente se encuentran dentro del ámbito cuando el espacio de nombres se importa explícitamente en el código fuente con una directiva using.Extension methods are only in scope when you explicitly import the namespace into your source code with a using directive.

En el ejemplo siguiente se muestra un método de extensión definido para la clase System.String.The following example shows an extension method defined for the System.String class. Se define dentro de una clase estática no anidada y no 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;
        }
    }
}

El método de extensión WordCount se puede incluir en el ámbito con esta directiva using:The WordCount extension method can be brought into scope with this using directive:

using ExtensionMethods;

También se le puede llamar desde una aplicación con esta sintaxis:And it can be called from an application by using this syntax:

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

El método de extensión se invoca en el código con la sintaxis de método de instancia.You invoke the extension method in your code with instance method syntax. El lenguaje intermedio (IL) generado por el compilador convierte el código en una llamada en el método estático.The intermediate language (IL) generated by the compiler translates your code into a call on the static method. El principio de encapsulación no se infringe realmente.The principle of encapsulation is not really being violated. Los métodos de extensión no pueden tener acceso a las variables privadas en el tipo que extienden.Extension methods cannot access private variables in the type they are extending.

Para obtener más información, vea Procedimiento para implementar e invocar un método de extensión personalizado.For more information, see How to implement and call a custom extension method.

En general, probablemente se llamará a métodos de extensión con mucha más frecuencia de la que se implementarán métodos propios.In general, you'll probably be calling extension methods far more often than implementing your own. Dado que los métodos de extensión se llaman con la sintaxis de método de instancia, no se requieren conocimientos especiales para usarlos desde el código de cliente.Because extension methods are called by using instance method syntax, no special knowledge is required to use them from client code. Para habilitar los métodos de extensión para un tipo determinado, basta con agregar una directiva using para el espacio de nombres en el que se definen los métodos.To enable extension methods for a particular type, just add a using directive for the namespace in which the methods are defined. Por ejemplo, para usar los operadores de consulta estándar, agregue esta directiva using al código:For example, to use the standard query operators, add this using directive to your code:

using System.Linq;

(Puede que haya que agregar también una referencia a System.Core.dll). Observará que los operadores de consulta estándar aparecen ahora en IntelliSense como métodos adicionales disponibles para la mayoría de los tipos IEnumerable<T>.(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.

Enlazar métodos de extensión en tiempo de compilaciónBinding Extension Methods at Compile Time

Se pueden usar métodos de extensión para ampliar una clase o interfaz, pero no para invalidarlas.You can use extension methods to extend a class or interface, but not to override them. Nunca se llamará a un método de extensión con el mismo nombre y signatura que un método de interfaz o clase.An extension method with the same name and signature as an interface or class method will never be called. En tiempo de compilación, los métodos de extensión siempre tienen menos prioridad que los métodos de instancia definidos en el propio tipo.At compile time, extension methods always have lower priority than instance methods defined in the type itself. En otras palabras, si un tipo tiene un método denominado Process(int i) y hay un método de extensión con la misma signatura, el compilador siempre se enlazará al método de instancia.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. Cuando el compilador encuentra una invocación de método, primero busca una coincidencia en los métodos de instancia del tipo.When the compiler encounters a method invocation, it first looks for a match in the type's instance methods. Si no la hay, buscará cualquier método de extensión definido para el tipo y se enlazará al primer método de extensión que encuentre.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. En el ejemplo siguiente se muestra cómo determina el compilador a qué método de extensión o de instancia enlazarse.The following example demonstrates how the compiler determines which extension method or instance method to bind to.

EjemploExample

En el ejemplo siguiente se muestran las reglas que el compilador de C# sigue para determinar si se va a enlazar una llamada a método a un método de instancia del tipo o a un método de extensión.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 clase estática Extensions contiene métodos de extensión definidos para cualquier tipo que implemente IMyInterface.The static class Extensions contains extension methods defined for any type that implements IMyInterface. Las clases A, B y C implementan la interfaz.Classes A, B, and C all implement the interface.

Nunca se llama al método de extensión MethodB, porque su nombre y signatura coinciden exactamente con los métodos ya implementados por las clases.The MethodB extension method is never called because its name and signature exactly match methods already implemented by the classes.

Si el compilador no encuentra un método de instancia con una signatura coincidente, se enlazará a un método de extensión coincidente, si existe.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()
 */

Patrones de uso comúnCommon Usage Patterns

Funcionalidad de colecciónCollection Functionality

En el pasado, era habitual crear "Clases de colección" que implementaban la interfaz System.Collections.Generic.IEnumerable<T> para un tipo especificado e incluían una funcionalidad que actuaba en colecciones de ese 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. Aunque no hay ningún problema con la creación de este tipo de objeto de colección, se puede lograr la misma funcionalidad mediante una extensión en 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>. Las extensiones tienen la ventaja de permitir que se llame a la funcionalidad desde cualquier colección como System.Array o System.Collections.Generic.List<T> que implementa System.Collections.Generic.IEnumerable<T> en ese 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. Encontrará un ejemplo de esto mediante una matriz de Int32 anteriormente en este artículo.An example of this using an Array of Int32 can be found earlier in this article.

Funcionalidad específica de la capaLayer-Specific Functionality

Al usar Onion Architecture (Arquitectura cebolla) u otro diseño de la aplicación por niveles, es habitual tener un conjunto de entidades de dominio u objetos de transferencia de datos que se pueden usar para la comunicación entre los límites de la aplicación.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. Por regla general, estos objetos no contienen ninguna funcionalidad o contienen únicamente una funcionalidad mínima que se aplica a todas las capas de la aplicación.These objects generally contain no functionality, or only minimal functionality that applies to all layers of the application. Los métodos de extensión se pueden usar para agregar una funcionalidad específica de cada capa de la aplicación sin cargar el objeto con métodos no necesarios o deseados en otras capas.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}";
}

Ampliación de tipos predefinidosExtending Predefined Types

En lugar de crear objetos cuando es necesario crear una funcionalidad reutilizable, a menudo podemos ampliar un tipo existente como un tipo CLR o de .NET.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. Como ejemplo, si no usamos métodos de extensión, podemos crear una clase Engine o Query para ejecutar una consulta en un servidor SQL Server al que se puede llamar desde varias ubicaciones en nuestro 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. Sin embargo, en su lugar, podemos ampliar la clase System.Data.SqlClient.SqlConnection mediante métodos de extensión para realizar esa consulta desde cualquier lugar en el que tengamos una conexión a un servidor 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. Otros ejemplos podrían ser la adición de una funcionalidad común a la clase System.String, la ampliación de las funcionalidades de procesamiento de datos de los objetos System.IO.File y System.IO.Stream, y los objetos System.Exception para una funcionalidad de control de errores 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. Solo su imaginación y sentido común limitan estos tipos de casos de uso.These types of use-cases are limited only by your imagination and good sense.

La ampliación de tipos predefinidos puede ser difícil con los tipos struct, ya que se pasan en función del valor a los métodos.Extending predefined types can be difficult with struct types because they're passed by value to methods. Eso significa que los cambios en la estructura se realizan en una copia de la misma.That means any changes to the struct are made to a copy of the struct. Esos cambios dejarán de verse una vez que se salga del método de extensión.Those changes aren't visible once the extension method exits. A partir de C# 7.2, puede agregar el modificador ref al primer argumento de un método de extensión.Beginning with C# 7.2, you can add the ref modifier to the first argument of an extension method. La adición del modificador ref significa que el primer argumento se pasa por referencia.Adding the ref modifier means the first argument is passed by reference. Esto le permite escribir métodos de extensión que cambian el estado de la estructura que se amplía.This enables you to write extension methods that change the state of the struct being extended.

Instrucciones generalesGeneral Guidelines

Aunque sigue considerándose preferible agregar la funcionalidad modificando un código del objeto o derivando un nuevo tipo siempre que sea razonable y posible hacerlo, los métodos de extensión se han convertido en una opción fundamental para crear una funcionalidad reutilizable en todo el 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. Para esas ocasiones en las que no cuente con el control del origen original, si un objeto derivado es inadecuado o imposible, o la funcionalidad no se debe exponer más allá de su ámbito aplicable, los métodos de extensión son una opción 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 obtener más información sobre los tipos derivados, consulte Herencia.For more information on derived types, see Inheritance.

Al usar un método de extensión para ampliar un tipo cuyo código fuente no está bajo su control, se corre el riesgo de que un cambio en la implementación del tipo interrumpa el método de extensión.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.

Si se implementan métodos de extensión para un tipo determinado, recuerde los puntos siguientes:If you do implement extension methods for a given type, remember the following points:

  • Nunca se llamará a un método de extensión si tiene la misma signatura que un método definido en el tipo.An extension method will never be called if it has the same signature as a method defined in the type.
  • Los métodos de extensión se incluyen en el ámbito en el nivel de espacio de nombres.Extension methods are brought into scope at the namespace level. Por ejemplo, si se tienen varias clases estáticas que contienen métodos de extensión en un único espacio de nombres denominado Extensions, la directiva using Extensions; los incluirá a todos en el ámbito.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 una biblioteca de clases ya implementada, no deben usarse métodos de extensión para evitar incrementar el número de versión de un ensamblado.For a class library that you implemented, you shouldn't use extension methods to avoid incrementing the version number of an assembly. Si quiere agregar una funcionalidad significativa a una biblioteca de cuyo código fuente es propietario, siga las instrucciones de .NET estándar para el control de versiones de ensamblado.If you want to add significant functionality to a library for which you own the source code, follow the .NET guidelines for assembly versioning. Para obtener más información, vea Versiones de los ensamblados.For more information, see Assembly Versioning.

Vea tambiénSee also