Atributos (C#)Attributes (C#)

Os atributos fornecem um método eficiente de associação de metadados, ou informações declarativas, ao código (assemblies, tipos, métodos, propriedades e etc.).Attributes provide a powerful method of associating metadata, or declarative information, with code (assemblies, types, methods, properties, and so forth). Após um atributo ser associado a uma entidade de programa, o atributo poderá ser consultado no tempo de execução usando uma técnica chamada reflexão.After an attribute is associated with a program entity, the attribute can be queried at run time by using a technique called reflection. Para obter mais informações, consulte Reflexão (C#).For more information, see Reflection (C#).

Os atributos têm as seguintes propriedades:Attributes have the following properties:

  • Os atributos adicionam metadados ao seu programa.Attributes add metadata to your program. Os metadados são informações sobre os tipos definidos em um programa.Metadata is information about the types defined in a program. Todos os assemblies .NET contêm um conjunto de metadados especificado que descreve os tipos e os membros de tipo definidos no assembly.All .NET assemblies contain a specified set of metadata that describes the types and type members defined in the assembly. Você pode adicionar atributos personalizados para especificar qualquer informação adicional necessária.You can add custom attributes to specify any additional information that is required. Para obter mais informações, consulte Criando atributos personalizados (C#).For more information, see, Creating Custom Attributes (C#).
  • Você pode aplicar um ou mais atributos a assemblies completos, módulos ou elementos de programas menores, como classes e propriedades.You can apply one or more attributes to entire assemblies, modules, or smaller program elements such as classes and properties.
  • Os atributos podem aceitar argumentos da mesma forma que métodos e propriedades.Attributes can accept arguments in the same way as methods and properties.
  • Seu programa pode examinar seus próprios metadados ou os metadados em outros programas usando reflexão.Your program can examine its own metadata or the metadata in other programs by using reflection. Para obter mais informações, consulte Acessando atributos usando reflexão (C#).For more information, see Accessing Attributes by Using Reflection (C#).

Usando atributosUsing attributes

Os atributos podem ser colocados em quase qualquer declaração, embora um atributo específico possa restringir os tipos de declarações nas quais ele é válido.Attributes can be placed on most any declaration, though a specific attribute might restrict the types of declarations on which it is valid. No C#, você especifica um atributo colocando o nome do atributo entre colchetes ([]) acima da declaração da entidade à qual ele se aplica.In C#, you specify an attribute by placing the name of the attribute enclosed in square brackets ([]) above the declaration of the entity to which it applies.

Neste exemplo, o atributo SerializableAttribute é usado para aplicar uma característica específica a uma classe:In this example, the SerializableAttribute attribute is used to apply a specific characteristic to a class:

[Serializable]
public class SampleClass
{
    // Objects of this type can be serialized.
}

Um método com o atributo DllImportAttribute é declarado como este exemplo:A method with the attribute DllImportAttribute is declared like the following example:

[System.Runtime.InteropServices.DllImport("user32.dll")]
extern static void SampleMethod();

Mais de um atributo pode ser colocado em uma declaração como o seguinte exemplo mostra:More than one attribute can be placed on a declaration as the following example shows:

using System.Runtime.InteropServices;
void MethodA([In][Out] ref double x) { }
void MethodB([Out][In] ref double x) { }
void MethodC([In, Out] ref double x) { }

Alguns atributos podem ser especificados mais de uma vez para uma determinada entidade.Some attributes can be specified more than once for a given entity. Um exemplo de um atributo multiuso é ConditionalAttribute:An example of such a multiuse attribute is ConditionalAttribute:

[Conditional("DEBUG"), Conditional("TEST1")]
void TraceMethod()
{
    // ...
}

Observação

Por convenção, todos os nomes de atributo terminam com a palavra "Atributo" para distingui-los de outros itens nas bibliotecas do .NET.By convention, all attribute names end with the word "Attribute" to distinguish them from other items in the .NET libraries. No entanto, você não precisa especificar o sufixo de atributo ao usar atributos no código.However, you do not need to specify the attribute suffix when using attributes in code. Por exemplo, [DllImport] é equivalente a [DllImportAttribute], mas DllImportAttribute é o nome real do atributo na Biblioteca de Classes .NET Framework.For example, [DllImport] is equivalent to [DllImportAttribute], but DllImportAttribute is the attribute's actual name in the .NET Framework Class Library.

Parâmetros de atributoAttribute parameters

Muitos atributos têm parâmetros, que podem ser nomeados, sem nome ou posicionais.Many attributes have parameters, which can be positional, unnamed, or named. Quaisquer parâmetros de posição devem ser especificados em uma determinada ordem e não podem ser omitidos.Any positional parameters must be specified in a certain order and cannot be omitted. Parâmetros nomeados são opcionais e podem ser especificados em qualquer ordem.Named parameters are optional and can be specified in any order. Os parâmetros posicionais são especificados primeiro.Positional parameters are specified first. Por exemplo, esses três atributos são equivalentes:For example, these three attributes are equivalent:

[DllImport("user32.dll")]
[DllImport("user32.dll", SetLastError=false, ExactSpelling=false)]
[DllImport("user32.dll", ExactSpelling=false, SetLastError=false)]

O primeiro parâmetro, o nome da DLL, é posicional e sempre vir em primeiro lugar; os outros são nomeados.The first parameter, the DLL name, is positional and always comes first; the others are named. Nesse caso, ambos os parâmetros nomeados são padronizados como false e, portanto, podem ser omitidos.In this case, both named parameters default to false, so they can be omitted. Parâmetros de posição correspondem aos parâmetros do construtor de atributo.Positional parameters correspond to the parameters of the attribute constructor. Parâmetros nomeados ou opcionais correspondem a propriedades ou a campos do atributo.Named or optional parameters correspond to either properties or fields of the attribute. Consulte a documentação do atributo individual para obter informações sobre valores de parâmetro padrão.Refer to the individual attribute's documentation for information on default parameter values.

Destinos do atributoAttribute targets

O destino de um atributo é a entidade à qual o atributo se aplica.The target of an attribute is the entity to which the attribute applies. Por exemplo, um atributo pode ser aplicado a uma classe, um método específico ou um assembly inteiro.For example, an attribute may apply to a class, a particular method, or an entire assembly. Por padrão, um atributo aplica-se ao elemento que ele precede.By default, an attribute applies to the element that it precedes. Mas você pode identificar explicitamente, por exemplo, se um atributo é aplicado a um método, ou a seu parâmetro ou a seu valor retornado.But you can also explicitly identify, for example, whether an attribute is applied to a method, or to its parameter, or to its return value.

Para identificar explicitamente um atributo de destino, use a seguinte sintaxe:To explicitly identify an attribute target, use the following syntax:

[target : attribute-list]

A lista de possíveis valores target é mostrada na tabela a seguir.The list of possible target values is shown in the following table.

Valor de destinoTarget value Aplica-se aApplies to
assembly Assembly inteiroEntire assembly
module Módulo do assembly atualCurrent assembly module
field Campo em uma classe ou um structField in a class or a struct
event eventoEvent
method Método ou acessadores de propriedade get e setMethod or get and set property accessors
param Parâmetros de método ou parâmetros de acessador de propriedade setMethod parameters or set property accessor parameters
property PropriedadeProperty
return Valor retornado de um método, indexador de propriedade ou acessador de propriedade getReturn value of a method, property indexer, or get property accessor
type Struct, classe, interface, enum ou delegadoStruct, class, interface, enum, or delegate

Especifique o valor de destino field para aplicar um atributo ao campo de suporte criado para uma propriedade autoimplementada.You would specify the field target value to apply an attribute to the backing field created for an auto-implemented property.

O exemplo a seguir mostra como aplicar atributos a módulos e assemblies.The following example shows how to apply attributes to assemblies and modules. Para obter mais informações, consulte Atributos comuns (C#).For more information, see Common Attributes (C#).

using System;
using System.Reflection;
[assembly: AssemblyTitleAttribute("Production assembly 4")]
[module: CLSCompliant(true)]

O exemplo a seguir mostra como aplicar atributos a métodos, parâmetros de método e valores de retorno de método em C#.The following example shows how to apply attributes to methods, method parameters, and method return values in C#.

// default: applies to method
[ValidatedContract]
int Method1() { return 0; }

// applies to method
[method: ValidatedContract]
int Method2() { return 0; }

// applies to return value
[return: ValidatedContract]
int Method3() { return 0; }

Observação

Independentemente dos destinos nos quais ValidatedContract é definido como válido, o destino return deve ser especificado, mesmo se ValidatedContract forem definidos para serem aplicados somente a valores de retorno.Regardless of the targets on which ValidatedContract is defined to be valid, the return target has to be specified, even if ValidatedContract were defined to apply only to return values. Em outras palavras, o compilador não usará as informações de AttributeUsage para resolver os destinos de atributos ambíguos.In other words, the compiler will not use AttributeUsage information to resolve ambiguous attribute targets. Para obter mais informações, consulte AttributeUsage (C#).For more information, see AttributeUsage (C#).

Usos comuns para atributosCommon uses for attributes

A lista a seguir inclui alguns dos usos comuns de atributos no código:The following list includes a few of the common uses of attributes in code:

  • Marcar métodos usando o atributo WebMethod nos serviços Web para indicar que o método deve ser chamado por meio do protocolo SOAP.Marking methods using the WebMethod attribute in Web services to indicate that the method should be callable over the SOAP protocol. Para obter mais informações, consulte WebMethodAttribute.For more information, see WebMethodAttribute.
  • Descrever como realizar marshaling de parâmetros de método ao interoperar com código nativo.Describing how to marshal method parameters when interoperating with native code. Para obter mais informações, consulte MarshalAsAttribute.For more information, see MarshalAsAttribute.
  • Descrever as propriedades COM para classes, métodos e interfaces.Describing the COM properties for classes, methods, and interfaces.
  • Chamar o código não gerenciado usando a classe DllImportAttribute.Calling unmanaged code using the DllImportAttribute class.
  • Descrever o assembly em termos de versão, título, descrição ou marca.Describing your assembly in terms of title, version, description, or trademark.
  • Descrever quais membros de uma classe serializar para persistência.Describing which members of a class to serialize for persistence.
  • Descrever como fazer mapeamento entre nós XML e membros de classe para serialização de XML.Describing how to map between class members and XML nodes for XML serialization.
  • Descrever os requisitos de segurança para métodos.Describing the security requirements for methods.
  • Especificar as características usadas para impor a segurança.Specifying characteristics used to enforce security.
  • Controlar otimizações pelo compilador JIT (Just-In-Time) para que o código permaneça fácil de depurar.Controlling optimizations by the just-in-time (JIT) compiler so the code remains easy to debug.
  • Obter informações sobre o chamador de um método.Obtaining information about the caller to a method.

Para obter mais informações, consulte:For more information, see:

Consulte tambémSee Also