Atributos (C# e Visual Basic)

Atributos fornecem um método eficiente de associar metadados ou informações declarativas, código (conjuntos de módulos, tipos, métodos, propriedades e assim por diante). Depois de um atributo estiver associado uma entidade de programa, o atributo pode ser consultado em tempo de execução usando uma técnica chamada reflexão. Para obter mais informações, consulte Reflexão (C# e Visual Basic).

Atributos têm as seguintes propriedades:

• Atributos adicionar metadados para o seu programa. Metadados informações sobre os tipos definidos em um programa. Todos os.NET assemblies contêm um conjunto de metadados que descrevem os tipos e membros de tipo definidos no assembly especificado. Você pode adicionar atributos personalizados para especificar qualquer informação adicional necessária. Para obter mais informações, consulte, Criando os atributos personalizados (C# e Visual Basic).

• Você pode aplicar um ou mais atributos para assemblies, módulos ou elementos pequenos programas como classes e propriedades.

• Atributos podem aceitar argumentos da mesma forma que métodos e propriedades.

• Seu programa pode examinar os metadados em outros programas ou seus próprios metadados por meio de reflexão. Para obter mais informações, consulte Acessar atributos usando reflexão (C# e Visual Basic).

Usando atributos

Atributos podem ser colocados na maioria das declaração, embora um atributo específico possa restringir os tipos de declarações no qual ele é válido. Para especificar um atributo colocando o nome do atributo, entre colchetes ([]), em C#, acima da declaração da entidade à qual ele se aplica. No Visual Basic, um atributo está entre colchetes angulares (< >). Ele deve aparecer imediatamente antes do elemento ao qual ele é aplicado, na mesma linha.

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

<System.Serializable()> Public Class SampleClass
    ' Objects of this type can be serialized.
End Class

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

Um método com o atributo DllImportAttribute é declarada como este:

Imports System.Runtime.InteropServices


...


<System.Runtime.InteropServices.DllImport("user32.dll")> 
Sub SampleMethod()
End Sub

using System.Runtime.InteropServices;


...


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

Mais de um atributo pode ser colocado em uma declaração:

Imports System.Runtime.InteropServices


...


Sub MethodA(<[In](), Out()> ByVal x As Double)
End Sub
Sub MethodB(<Out(), [In]()> ByVal x As Double)
End Sub

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 multiuse é ConditionalAttribute:

<Conditional("DEBUG"), Conditional("TEST1")> 
Sub TraceMethod()
End Sub

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

Observação
Por convenção, todos os nomes de atributo terminam com a palavra "Atributo" para diferenciá-los de outros itens na.NET Framework. No entanto, você não precisará especificar o sufixo de atributo ao usar os atributos no código. Por exemplo, [DllImport] é equivalente a [DllImportAttribute], mas DllImportAttribute é o nome do atributo real na.NET Framework.

Parâmetros do atributo

Muitos atributos têm parâmetros, o que podem ser nomeada, posicional ou sem nome. 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. Parâmetros de posição é especificada pela primeira vez. 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)]

<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 vem em primeiro lugar; outros são nomeados. Nesse caso, ambos chamados padrão de parâmetros como false, portanto, pode ser omitidos. Consulte a documentação do atributo individual para obter informações sobre valores de parâmetro padrão.

Destinos de atributo

O destino de um atributo é a entidade à qual o atributo se aplica. Por exemplo, um atributo podem ser aplicáveis a uma classe, um método específico ou um assembly inteiro. Por padrão, um atributo se aplica ao elemento que ela precede. Mas você pode também identificar explicitamente, por exemplo, se um atributo é aplicado a um método, ou seu parâmetro ou valor de retorno.

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

[target : attribute-list]

<target : attribute-list>

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

O exemplo a seguir mostra como aplicar atributos a módulos e assemblies. Para obter mais informações, consulte Atributos comuns (C# e Visual Basic).

Imports System.Reflection
<Assembly: AssemblyTitleAttribute("Production assembly 4"), 
Module: CLSCompliant(True)> 

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

O exemplo a seguir mostra como aplicar atributos para métodos, parâmetros de método, e valores de retorno de método em C#.

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

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

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

Observação
Independentemente dos destinos no qual SomeAttr é definido para ser válido, o return destino deve ser especificada, mesmo se SomeAttr foram definidos para aplicar apenas para retornar valores. Em outras palavras, o compilador não usará AttributeUsage informações para resolver o atributo ambíguo destinos. Para obter mais informações, consulte AttributeUsage (C# e Visual Basic).

Usos comuns para atributos

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

• A marcação de métodos usando a WebMethod atributo nos serviços da Web para indicar que o método deve ser acessível através do protocolo SOAP. Para obter mais informações, consulte WebMethodAttribute.

• Descrever como empacotar os parâmetros do método quando interoperar com código nativo. Para obter mais informações, consulte MarshalAsAttribute.

• Descrever as propriedades COM classes, métodos e interfaces.

• Chamada não gerenciado de código usando o DllImportAttribute classe.

• Descrever o seu assembly em termos de título, versão, descrição ou marca registrada.

• Descrever quais membros de uma classe para serializar para persistência.

• Descrever como mapear entre membros de classe e nós XML para serialização de XML.

• Descrever os requisitos de segurança para métodos.

• Especificando as características usado para reforçar a segurança.

• Controlando otimizações pelo compilador just-in-time (JIT) para que o código permanece fácil de depurar.

Seções relacionadas

Para obter mais informações, consulte:

• Criando os atributos personalizados (C# e Visual Basic)

• Acessar atributos usando reflexão (C# e Visual Basic)

• Como: Criar uma união C/C++ usando atributos (C# e Visual Basic)

• Atributos comuns (C# e Visual Basic)

Consulte também

Referência

Reflexão (C# e Visual Basic)

Conceitos

Guia de Programação C#

Estendendo metadados usando atributos

Outros recursos

Guia de programação Visual Basic