AtributosAttributes

Los tipos, los miembros y otras entidades en un programa de C # admiten modificadores que controlan ciertos aspectos de su comportamiento.Types, members, and other entities in a C# program support modifiers that control certain aspects of their behavior. Por ejemplo, la accesibilidad de un método se controla mediante los modificadores public, protected, internal y private.For example, the accessibility of a method is controlled using the public, protected, internal, and private modifiers. C # generaliza esta funcionalidad de manera que los tipos de información declarativa definidos por el usuario se puedan adjuntar a las entidades del programa y recuperarse en tiempo de ejecución.C# generalizes this capability such that user-defined types of declarative information can be attached to program entities and retrieved at run-time. Los programas especifican esta información declarativa adicional mediante la definición y el uso de atributos.Programs specify this additional declarative information by defining and using attributes.

En el ejemplo siguiente se declara un atributo HelpAttribute que se puede colocar en entidades de programa para proporcionar vínculos a la documentación asociada.The following example declares a HelpAttribute attribute that can be placed on program entities to provide links to their associated documentation.

using System;

public class HelpAttribute: Attribute
{
    string url;
    string topic;
    public HelpAttribute(string url) 
    {
        this.url = url;
    }

    public string Url => url;

    public string Topic {
        get { return topic; }
        set { topic = value; }
    }
}

Todas las clases de atributos se derivan de la clase base Attribute proporcionada por la biblioteca estándar.All attribute classes derive from the Attribute base class provided by the standard library. Los atributos se pueden aplicar proporcionando su nombre, junto con cualquier argumento, entre corchetes, justo antes de la declaración asociada.Attributes can be applied by giving their name, along with any arguments, inside square brackets just before the associated declaration. Si el nombre de un atributo termina en Attribute, esa parte del nombre se puede omitir cuando se hace referencia al atributo.If an attribute’s name ends in Attribute, that part of the name can be omitted when the attribute is referenced. Por ejemplo, HelpAttribute se puede usar de la manera siguiente.For example, the HelpAttribute can be used as follows.

[Help("https://docs.microsoft.com/dotnet/csharp/tour-of-csharp/attributes")]
public class Widget
{
    [Help("https://docs.microsoft.com/dotnet/csharp/tour-of-csharp/attributes", 
    Topic = "Display")]
    public void Display(string text) {}
}

En este ejemplo se adjunta un atributo HelpAttribute a la clase Widget.This example attaches a HelpAttribute to the Widget class. También se agrega otro atributo HelpAttribute al método Display en la clase.It adds another HelpAttribute to the Display method in the class. Los constructores públicos de una clase de atributos controlan la información que se debe proporcionar cuando el atributo se adjunta a una entidad de programa.The public constructors of an attribute class control the information that must be provided when the attribute is attached to a program entity. Se puede proporcionar información adicional haciendo referencia a las propiedades públicas de lectura y escritura de la clase de atributos (como la referencia a la propiedad Topic usada anteriormente).Additional information can be provided by referencing public read-write properties of the attribute class (such as the reference to the Topic property previously).

Los metadatos definidos por atributos pueden leerse y manipularse en tiempo de ejecución mediante reflexión.The metadata defined by attributes can be read and manipulated at runtime using reflection. Cuando se solicita un atributo determinado mediante esta técnica, se invoca al constructor de la clase de atributos con la información proporcionada en el origen del programa y se devuelve la instancia de atributo resultante.When a particular attribute is requested using this technique, the constructor for the attribute class is invoked with the information provided in the program source, and the resulting attribute instance is returned. Si se proporciona información adicional mediante propiedades, dichas propiedades se establecen en los valores dados antes de devolver la instancia del atributo.If additional information was provided through properties, those properties are set to the given values before the attribute instance is returned.

El siguiente ejemplo de código demuestra cómo obtener las HelpAttributeinstancias asociadas a la clase Widget y su método Display.The following code sample demonstrates how to get the HelpAttribute instances associated to the Widget class and its Display method.

Type widgetType = typeof(Widget);

//Gets every HelpAttribute defined for the Widget type
object[] widgetClassAttributes = widgetType.GetCustomAttributes(typeof(HelpAttribute), false);

if (widgetClassAttributes.Length > 0)
{
    HelpAttribute attr = (HelpAttribute)widgetClassAttributes[0];
    Console.WriteLine($"Widget class help URL : {attr.Url} - Related topic : {attr.Topic}");
}

System.Reflection.MethodInfo displayMethod = widgetType.GetMethod(nameof(Widget.Display));

//Gets every HelpAttribute defined for the Widget.Display method
object[] displayMethodAttributes = displayMethod.GetCustomAttributes(typeof(HelpAttribute), false);

if (displayMethodAttributes.Length > 0)
{
    HelpAttribute attr = (HelpAttribute)displayMethodAttributes[0];
    Console.WriteLine($"Display method help URL : {attr.Url} - Related topic : {attr.Topic}");
}

Console.ReadLine();