Atributos comuns (Visual Basic)

  • Artigo

Este tópico descreve os atributos que são mais comumente usados nos programas em C#.

Atributos globais

A maioria dos atributos são aplicados aos elementos específicos de linguagem, como classes ou métodos. No entanto, alguns atributos são globais. Eles se aplicam a um assembly inteiro ou módulo. Por exemplo, o atributo AssemblyVersionAttribute pode ser usado para inserir informações de versão em um assembly, desta maneira:

<Assembly: AssemblyVersion("1.0.0.0")>

Os atributos globais aparecem no código-fonte depois de qualquer diretiva Imports de nível superior e antes de qualquer declaração de namespace, módulo ou tipo. Os atributos globais podem aparecer em vários arquivos de origem, mas os arquivos devem ser compilados em uma única passagem de compilação. Para projetos do Visual Basic, os atributos globais geralmente são colocados no arquivo AssemblyInfo.vb (o arquivo é criado automaticamente quando você cria um projeto no Visual Studio).

Os atributos de assembly são valores que fornecem informações sobre um assembly. Eles se enquadram nas seguintes categorias:

  • Atributos de identidade do assembly

  • Atributos informativos

  • Atributos de manifesto do assembly

Atributos de Identidade do Assembly

Três atributos (com um nome forte, se aplicável) determinam a identidade de um assembly: nome, versão e cultura. Esses atributos formam o nome completo do assembly e são necessários ao fazer referência a ele no código. Você pode definir a versão e a cultura de um assembly, usando atributos. No entanto, o valor do nome é definido pelo compilador, pelo IDE do Visual Studio na caixa de diálogo de Informações do Assembly ou pelo Assembly Linker (Al.exe) quando o assembly é criado, com base no arquivo que contém o manifesto do assembly. O atributo AssemblyFlagsAttribute especifica se várias cópias do assembly podem coexistir.

A tabela a seguir mostra os atributos de identidade.

Atributo Finalidade
AssemblyName Descreve completamente a identidade de um assembly.
AssemblyVersionAttribute Especifica a versão de um assembly.
AssemblyCultureAttribute Especifica a qual cultura o assembly dá suporte.
AssemblyFlagsAttribute Especifica se um assembly dá suporte à execução lado a lado no mesmo computador, no mesmo processo ou no mesmo domínio do aplicativo.

Atributos Informativos

Você pode usar atributos informativos para fornecer informações adicionais corporativas ou de produto para um assembly. A tabela a seguir mostra os atributos informativos definidos no namespace System.Reflection.

Atributo Finalidade
AssemblyProductAttribute Define um atributo personalizado que especifica um nome de produto para um manifesto do assembly.
AssemblyTrademarkAttribute Define um atributo personalizado que especifica uma marca registrada para um manifesto do assembly.
AssemblyInformationalVersionAttribute Define um atributo personalizado que especifica uma versão informativa para um manifesto do assembly.
AssemblyCompanyAttribute Define um atributo personalizado que especifica um nome de empresa para um manifesto do assembly.
AssemblyCopyrightAttribute Define um atributo personalizado que especifica os direitos autorais para um manifesto do assembly.
AssemblyFileVersionAttribute Instrui o compilador a usar um número de versão específico para o recurso de versão de arquivo do Win32.
CLSCompliantAttribute Indica se o assembly está em conformidade com a CLS (Common Language Specification).

Atributos de Manifesto do Assembly

Você pode usar atributos de manifesto do assembly para fornecer informações no manifesto do assembly. Isso inclui título, descrição, alias padrão e configuração. A tabela a seguir mostra os atributos de manifesto do assembly definidos no namespace System.Reflection.

Atributo Finalidade
AssemblyTitleAttribute Define um atributo personalizado que especifica um título de assembly para um manifesto do assembly.
AssemblyDescriptionAttribute Define um atributo personalizado que especifica uma descrição de assembly para um manifesto do assembly.
AssemblyConfigurationAttribute Define um atributo personalizado que especifica uma configuração de assembly (como comercial ou de depuração) para um manifesto do assembly. assembly.
AssemblyDefaultAliasAttribute Define um alias amigável padrão para um manifesto do assembly

Atributo obsoleto

O atributo Obsolete marca uma entidade programa como não recomendada para uso. Cada uso de uma entidade marcada como obsoleta gerará subsequentemente um aviso ou erro, dependendo de como o atributo é configurado. Por exemplo:

<System.Obsolete("use class B")>
Class A
    Sub Method()
    End Sub
End Class

Class B
    <System.Obsolete("use NewMethod", True)>
    Sub OldMethod()
    End Sub

    Sub NewMethod()
    End Sub
End Class

Neste exemplo o atributo Obsolete é aplicado à classe A e ao método B.OldMethod. Como o segundo argumento do construtor de atributo aplicado a B.OldMethod está definido como true, esse método causará um erro do compilador, enquanto que ao usar a classe A, produzirá apenas um aviso. Chamar B.NewMethod, no entanto, não produz aviso nem erro.

A cadeia de caracteres fornecida como o primeiro argumento para o construtor de atributo será exibida como parte do aviso ou erro. Por exemplo, ao usá-lo com as definições anteriores, o código a seguir gera um erro e dois avisos:

' Generates 2 warnings:
' Dim a As New A
' Generate no errors or warnings:

Dim b As New B
b.NewMethod()

' Generates an error, terminating compilation:
' b.OldMethod()

São gerados dois avisos para a classe A: um para a declaração da referência de classe e outro para o construtor de classe.

O atributo Obsolete pode ser usado sem argumentos, mas é recomendável incluir uma explicação de por que o item está obsoleto e o que deve ser usado no lugar dele.

O atributo Obsolete é um atributo de uso único e pode ser aplicado a qualquer entidade que permite atributos. Obsolete é um alias para ObsoleteAttribute.

Atributo condicional

O atributo Conditional torna a execução de um método dependente de um identificador de pré-processamento. O atributo Conditional é um alias para ConditionalAttribute e pode ser aplicado a um método ou uma classe de atributo.

Neste exemplo, Conditional é aplicado a um método para habilitar ou desabilitar a exibição de informações de diagnóstico específicas do programa:

#Const TRACE_ON = True
Imports System.Diagnostics

Module TestConditionalAttribute
    Public Class Trace
        <Conditional("TRACE_ON")>
        Public Shared Sub Msg(ByVal msg As String)
            Console.WriteLine(msg)
        End Sub

    End Class

    Sub Main()
        Trace.Msg("Now in Main...")
        Console.WriteLine("Done.")
    End Sub
End Module

Se o identificador TRACE_ON não estiver definido, nenhuma saída de rastreamento será exibida.

O atributo Conditional é frequentemente usado com o identificador DEBUG para habilitar recursos de rastreamento e de registro em log para builds de depuração, mas não em builds de versão, dessa maneira:

<Conditional("DEBUG")>
Shared Sub DebugMethod()

End Sub

Quando um método marcado como condicional é chamado, a presença ou ausência do símbolo de pré-processamento especificado determina se a chamada será incluída ou omitida. Se o símbolo estiver definido, a chamada será incluída, caso contrário, a chamada será omitida. O uso de Conditional é uma alternativa mais limpa, mais elegante e menos propensa a erros para incluir métodos dentro de blocos #if…#endif, dessa maneira:

#If DEBUG Then
    Sub ConditionalMethod()
    End Sub
#End If

Um método condicional deve ser um método em uma declaração de classe ou de struct e não deve ter um valor retornado.

Usando vários identificadores

Se um método tem vários atributos Conditional, uma chamada para o método será incluída se pelo menos um dos símbolos condicionais for definido (em outras palavras, os símbolos são logicamente vinculados através do uso do operador OR). Neste exemplo, a presença de A ou B resultará em uma chamada de método:

<Conditional("A"), Conditional("B")>
Shared Sub DoIfAorB()

End Sub

Para alcançar o efeito da vinculação lógica de símbolos usando o operador AND, você pode definir métodos condicionais em série. Por exemplo, o segundo método abaixo será executado somente se A e B estiverem definidos:

<Conditional("A")>
Shared Sub DoIfA()
    DoIfAandB()
End Sub

<Conditional("B")>
Shared Sub DoIfAandB()
    ' Code to execute when both A and B are defined...
End Sub

Usando condicional com classes de atributos

O atributo Conditional também pode ser aplicado a uma definição de classe de atributos. Neste exemplo, o atributo personalizado Documentation só adicionará informações aos metadados se DEBUG estiver definido.

<Conditional("DEBUG")>
Public Class Documentation
    Inherits System.Attribute
    Private text As String
    Sub New(ByVal doc_text As String)
        text = doc_text
    End Sub
End Class

Class SampleClass
    ' This attribute will only be included if DEBUG is defined.
    <Documentation("This method displays an integer.")>
    Shared Sub DoWork(ByVal i As Integer)
        System.Console.WriteLine(i)
    End Sub
End Class

Atributos de informações do chamador

Ao usar atributos de informações do chamador, você pode obter informações sobre o chamador de um método. Você pode obter o caminho do arquivo do código-fonte, o número de linha no código-fonte e o nome do membro do chamador.

Para obter informações do chamador do membro, você usa os atributos que são aplicados aos parâmetros opcionais. Cada parâmetro opcional especifica um valor padrão. A tabela a seguir lista os atributos de informações do chamador que são definidos no namespace de System.Runtime.CompilerServices:

Atributo Descrição Type
CallerFilePathAttribute O caminho completo do arquivo de origem que contém o chamador. Esse é o caminho em tempo de compilação. String
CallerLineNumberAttribute Número de linha no arquivo de origem do qual o método é chamado. Integer
CallerMemberNameAttribute Nome do método ou nome da propriedade do chamador. Para obter mais informações, consulte Informações do chamador (C#). String
CallerArgumentExpressionAttribute Expressão usada pelo chamador para um argumento. Para obter mais informações, consulte Informações do chamador (C#). String

Para obter mais informações sobre os atributos de informações do chamador, consulte Informações do chamador (C#).

Atributos do Visual Basic

A tabela a seguir lista os atributos específicos do Visual Basic.

Atributo Finalidade
ComClassAttribute Indica ao compilador que a classe deve ser exposta como um objeto COM.
HideModuleNameAttribute Permite que os membros de módulo sejam acessados usando somente a qualificação necessária para o módulo.
VBFixedStringAttribute Especifica o tamanho de uma cadeia de caracteres de comprimento fixo em uma estrutura para uso com funções de entrada e saída de arquivo.
VBFixedArrayAttribute Especifica o tamanho de uma matriz fixa em uma estrutura para uso com funções de entrada e saída de arquivo.

COMClassAttribute

Use COMClassAttribute para simplificar o processo de criação de componentes COM do Visual Basic. Os objetos COM são consideravelmente diferentes de .NET Framework assemblies e, semCOMClassAttribute, você precisa seguir várias etapas para gerar um objeto COM do Visual Basic. Para classes marcadas com COMClassAttribute, o compilador executa muitas dessas etapas automaticamente.

HideModuleNameAttribute

Use HideModuleNameAttribute para permitir que os membros de módulo sejam acessados usando somente a qualificação necessária para o módulo.

VBFixedStringAttribute

Use VBFixedStringAttribute para forçar o Visual Basic a criar uma cadeia de caracteres de comprimento fixo. As cadeias de caracteres têm comprimento variável por padrão e esse atributo é útil ao armazenar cadeias de caracteres em arquivos. O código a seguir demonstra isso:

Structure Worker
    ' The runtime uses VBFixedString to determine
    ' if the field should be written out as a fixed size.
    <VBFixedString(10)> Public LastName As String
    <VBFixedString(7)> Public Title As String
    <VBFixedString(2)> Public Rank As String
End Structure

VBFixedArrayAttribute

Use VBFixedArrayAttribute para declarar matrizes fixas em tamanho. Assim como as cadeias de caracteres do Visual Basic, as matrizes têm comprimento variável por padrão. Esse atributo é útil ao serializar ou gravar dados em arquivos.

Confira também