AtributosAttributes

Tipos, membros e outras entidades em um programa C# dão suporte a modificadores que controlam determinados aspectos de seu comportamento.Types, members, and other entities in a C# program support modifiers that control certain aspects of their behavior. Por exemplo, a acessibilidade de um método é controlada usando os modificadores public, protected, internal e private.For example, the accessibility of a method is controlled using the public, protected, internal, and private modifiers. O C# generaliza essa funcionalidade, de modo que os tipos definidos pelo usuário de informações declarativas podem ser anexados a entidades de programa e recuperados no tempo de execução.C# generalizes this capability such that user-defined types of declarative information can be attached to program entities and retrieved at run-time. Os programas especificam essas informações declarativas adicionais, definindo e usando os atributos.Programs specify this additional declarative information by defining and using attributes.

O exemplo a seguir declara um atributo HelpAttribute que pode ser colocado em entidades de programa para fornecem links para a documentação associada.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 as classes de atributo derivam da classe base Attribute fornecida pela biblioteca padrão.All attribute classes derive from the Attribute base class provided by the standard library. Os atributos podem ser aplicados, fornecendo seu nome, junto com quaisquer argumentos, dentro dos colchetes pouco antes da declaração associada.Attributes can be applied by giving their name, along with any arguments, inside square brackets just before the associated declaration. Se o nome de um atributo termina em Attribute, essa parte do nome pode ser omitida quando o atributo é referenciado.If an attribute’s name ends in Attribute, that part of the name can be omitted when the attribute is referenced. Por exemplo, o atributo HelpAttribute pode ser usado da seguinte maneira.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) {}
}

Este exemplo anexa um HelpAttribute à classe Widget.This example attaches a HelpAttribute to the Widget class. Ele adiciona outro HelpAttribute ao método Display na classe.It adds another HelpAttribute to the Display method in the class. Os construtores públicos de uma classe de atributo controlam as informações que devem ser fornecidas quando o atributo é anexado a uma entidade 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. As informações adicionais podem ser fornecidas ao referenciar propriedades públicas de leitura-gravação da classe de atributo (como a referência anterior à propriedade Topic).Additional information can be provided by referencing public read-write properties of the attribute class (such as the reference to the Topic property previously).

Os metadados definidos por atributos podem ser lidos e manipulados em tempo de execução usando reflexão.The metadata defined by attributes can be read and manipulated at runtime using reflection. Quando um atributo específico for solicitado usando esta técnica, o construtor para a classe de atributo será invocado com as informações fornecidas na origem do programa e a instância do atributo resultante será retornada.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. Se forem fornecidas informações adicionais por meio de propriedades, essas propriedades serão definidas para os valores fornecidos antes que a instância do atributo seja retornada.If additional information was provided through properties, those properties are set to the given values before the attribute instance is returned.

O exemplo de código a seguir demonstra como obter as instâncias HelpAttribute associadas à classe Widget e seu 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();