Comparteix a través de


Métodos de extensión (Guía de programación de C#)

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. 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. 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.

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. Para usar los operadores de consulta estándar, inclúyalos primero en el ámbito con una directiva using System.Linq. A partir de ese momento, cualquier tipo que implemente IEnumerable<T> parecerá tener métodos de instancia como GroupBy, OrderBy, Average, etc. 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.

Ejemplo de OrderBy

En el ejemplo siguiente se muestra cómo llamar al método OrderBy de operador de consulta estándar en una matriz de enteros. La expresión entre paréntesis es una expresión lambda. Muchos operadores de consulta estándar toman expresiones lambda como parámetros, pero no es un requisito para los métodos de extensión. Para obtener más información, vea Expresiones 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

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. Su primer parámetro especifica en qué tipo funciona el método. El parámetro sigue este modificador. 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.

En el ejemplo siguiente se muestra un método de extensión definido para la clase System.String. Se define dentro de una clase estática no anidada y no genérica:

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:

using ExtensionMethods;

También se le puede llamar desde una aplicación con esta sintaxis:

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. El lenguaje intermedio (IL) generado por el compilador convierte el código en una llamada en el método estático. El principio de encapsulación no se infringe realmente. Los métodos de extensión no pueden tener acceso a las variables privadas en el tipo que extienden.

Tanto la clase MyExtensions como el método WordCount son static, y se puede acceder a ellos como a todos los demás miembros static. El método WordCount se puede invocar como otros métodos static, como se muestra a continuación:

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

El código de C# anterior:

  • Declara y asigna un nuevo objeto string denominado s con un valor de "Hello Extension Methods".
  • Llama a MyExtensions.WordCount dado el argumento s.

Para más información, consulte Implementación e invocación de un método de extensión personalizado.

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. 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. 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. Por ejemplo, para usar los operadores de consulta estándar, agregue esta directiva using al código:

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>.

Enlazar métodos de extensión en tiempo de compilación

Se pueden usar métodos de extensión para ampliar una clase o interfaz, pero no para invalidarlas. Nunca se llamará a un método de extensión con el mismo nombre y signatura que un método de interfaz o clase. 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. 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. Cuando el compilador encuentra una invocación de método, primero busca una coincidencia en los métodos de instancia del tipo. Si no se encuentra una coincidencia, buscará cualquier método de extensión definido para el tipo y se enlazará al primer método de extensión que encuentre.

Ejemplo

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. La clase estática Extensions contiene métodos de extensión definidos para cualquier tipo que implemente IMyInterface. Las clases A, B y C implementan la interfaz.

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.

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.

// 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()
 */

Patrones de uso común

Funcionalidad de colección

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. 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>. 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. Encontrará un ejemplo de esto mediante una matriz de Int32 anteriormente en este artículo.

Funcionalidad específica de la capa

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. 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. 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.

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 predefinidos

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. 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. 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. 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 del objeto System.IO.Stream, y los objetos System.Exception para una funcionalidad de control de errores específica. Solo su imaginación y sentido común limitan estos tipos de casos de uso.

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. Eso significa que los cambios en la estructura se realizan en una copia de la misma. Esos cambios dejarán de verse una vez que se salga del método de extensión. Puede agregar el modificador ref al primer argumento, lo que lo convierte en un método de extensión ref. La palabra clave ref puede aparecer antes o después de la palabra clave this sin ninguna diferencia semántica. Agregar el modificador ref indica que el primer argumento se pasa por referencia. Esto le permite escribir métodos de extensión que cambian el estado de la estructura que se extiende (tenga en cuenta que los miembros privados no son accesibles). Solo se permiten los tipos de valor o los tipos genéricos restringidos a la estructura (consulte struct la restricción para obtener más información) como primer parámetro de un método de extensiónref. En el ejemplo siguiente se muestra cómo usar un método de extensión ref para modificar directamente un tipo integrado sin necesidad de reasignar el resultado o pasarlo a través de una función con la palabra clave 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
    }
}

En este ejemplo siguiente se muestran los métodos de extensión ref para los tipos de estructura definidos por el usuario:

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

Instrucciones generales

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. 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.

Para obtener más información sobre los tipos derivados, consulte Herencia.

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.

Si se implementan métodos de extensión para un tipo determinado, recuerde los puntos siguientes:

  • No se llama a un método de extensión si tiene la misma signatura que un método definido en el tipo.
  • Los métodos de extensión se incluyen en el ámbito en el nivel de espacio de nombres. 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.

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. 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. Para obtener más información, vea Versiones de los ensamblados.

Consulte también