Visão geral de atributos (Visual Basic)Attributes overview (Visual Basic)

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 (Visual Basic).For more information, see Reflection (Visual Basic).

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 (Visual Basic).For more information, see, Creating Custom Attributes (Visual Basic).

  • 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 (Visual Basic).For more information, see Accessing Attributes by Using Reflection (Visual Basic).

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 Visual Basic, um atributo é colocado entre colchetes angulares ( < > ).In Visual Basic, an attribute is enclosed in angle brackets (< >). Ele deverá aparecer imediatamente antes do elemento ao qual ele é aplicado, na mesma linha.It must appear immediately before the element to which it is applied, on the same line.

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:

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

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

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

Mais de um atributo pode ser colocado em uma declaração:More than one attribute can be placed on a declaration:

Imports System.Runtime.InteropServices
Sub MethodA(<[In](), Out()> ByVal x As Double)
End Sub
Sub MethodB(<Out(), [In]()> ByVal x As Double)
End Sub

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")>
Sub TraceMethod()
End Sub

Observação

Por convenção, todos os nomes de atributo terminam com a palavra "Atributo" para distingui-los de outros itens no .NET Framework.By convention, all attribute names end with the word "Attribute" to distinguish them from other items in the .NET Framework. 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 do atributo real no .NET Framework.For example, [DllImport] is equivalent to [DllImportAttribute], but DllImportAttribute is the attribute's actual name in the .NET Framework.

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 posicionais devem ser especificados em uma determinada ordem e não podem ser omitidos. Os parâmetros nomeados são opcionais e podem ser especificados em qualquer ordem.Any positional parameters must be specified in a certain order and cannot be omitted; 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. 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 de AtributosAttribute 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 de assembly atual (que é diferente de um módulo do Visual Basic)Current assembly module (which is different from a Visual Basic Module)

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 (Visual Basic).For more information, see Common Attributes (Visual Basic).

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

Usos comuns para os 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