Atributos (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.). 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. Para obter mais informações, consulte Reflexão (C#).

Os atributos têm as seguintes propriedades:

  • Os atributos adicionam metadados ao seu programa. Os metadados são informações sobre os tipos definidos em um programa. Todos os assemblies .NET contêm um conjunto de metadados especificado que descreve os tipos e os membros de tipo definidos no assembly. Você pode adicionar atributos personalizados para especificar qualquer informação adicional necessária. Para obter mais informações, consulte Criando atributos personalizados (C#).
  • Você pode aplicar um ou mais atributos a assemblies completos, módulos ou elementos de programas menores, como classes e propriedades.
  • Os atributos podem aceitar argumentos da mesma forma que métodos e propriedades.
  • Seu programa pode examinar seus próprios metadados ou os metadados em outros programas usando reflexão. Para obter mais informações, consulte Acessando atributos usando reflexão (C#).

Usando atributos

Os atributos podem ser colocados em praticamente qualquer declaração, embora um atributo específico possa restringir os tipos de declarações nas quais ele é válido. No C#, você especifica um atributo colocando o nome do atributo entre colchetes ([]) acima da declaração da entidade à qual ele se aplica.

Neste exemplo, o atributo SerializableAttribute é usado para aplicar uma característica específica a uma classe:

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

Um método com o atributo DllImportAttribute é declarado como este exemplo:

[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:

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. Um exemplo de um atributo multiuso é 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. No entanto, você não precisa especificar o sufixo de atributo ao usar atributos no código. Por exemplo, [DllImport] é equivalente a [DllImportAttribute], mas DllImportAttribute é o nome real do atributo na Biblioteca de Classes .NET Framework.

Parâmetros de atributo

Muitos atributos têm parâmetros, que podem ser nomeados, sem nome ou posicionais. Quaisquer parâmetros de posição devem ser especificados em uma determinada ordem e não podem ser omitidos. Parâmetros nomeados são opcionais e podem ser especificados em qualquer ordem. Os parâmetros posicionais são especificados primeiro. Por exemplo, esses três atributos são equivalentes:

[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. Nesse caso, ambos os parâmetros nomeados são padronizados como false e, portanto, podem ser omitidos. Parâmetros de posição correspondem aos parâmetros do construtor de atributo. Parâmetros nomeados ou opcionais correspondem a propriedades ou a campos do atributo. Consulte a documentação do atributo individual para obter informações sobre valores de parâmetro padrão.

Para obter mais informações sobre os tipos de parâmetro permitidos, consulte a seção Atributos da especificação da linguagem C#

Destinos do atributo

O destino de um atributo é a entidade à qual o atributo se aplica. Por exemplo, um atributo pode ser aplicado a uma classe, um método específico ou um assembly inteiro. Por padrão, um atributo aplica-se ao elemento que o segue. 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.

Para identificar explicitamente um atributo de destino, use a seguinte sintaxe:

[target : attribute-list]

A lista de possíveis valores target é mostrada na tabela a seguir.

Valor de destino Aplica-se a
assembly Assembly inteiro
module Módulo do assembly atual
field Campo em uma classe ou um struct
event Evento
method Método ou acessadores de propriedade get e set
param Parâmetros de método ou parâmetros de acessador de propriedade set
property Propriedade
return Valor retornado de um método, indexador de propriedade ou acessador de propriedade get
type Struct, classe, interface, enum ou delegado

Especifique o valor de destino field para aplicar um atributo ao campo de suporte criado para uma propriedade autoimplementada.

O exemplo a seguir mostra como aplicar atributos a módulos e assemblies. Para obter mais informações, consulte Atributos comuns (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#.

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

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

// applies to parameter
int Method3([ValidatedContract] string contract) { return 0; }

// applies to return value
[return: ValidatedContract]
int Method4() { 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. Em outras palavras, o compilador não usará as informações de AttributeUsage para resolver os destinos de atributos ambíguos. Para obter mais informações, consulte AttributeUsage (C#).

Usos comuns para atributos

A lista a seguir inclui alguns dos usos comuns de atributos no código:

  • 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. Para obter mais informações, consulte WebMethodAttribute.
  • Descrever como realizar marshaling de parâmetros de método ao interoperar com código nativo. Para obter mais informações, consulte MarshalAsAttribute.
  • Descrever as propriedades COM para classes, métodos e interfaces.
  • Chamar o código não gerenciado usando a classe DllImportAttribute.
  • Descrever o assembly em termos de versão, título, descrição ou marca.
  • Descrever quais membros de uma classe serializar para persistência.
  • Descrever como fazer mapeamento entre nós XML e membros de classe para serialização de XML.
  • Descrever os requisitos de segurança para métodos.
  • Especificar as características usadas para impor a segurança.
  • Controlar otimizações pelo compilador JIT (Just-In-Time) para que o código permaneça fácil de depurar.
  • Obter informações sobre o chamador de um método.

Para obter mais informações, consulte:

Confira também