Atributos comuns (Visual Basic)
Este tópico descreve os atributos que são mais comumente usados em programas do Visual Basic.
Atributos globais
A maioria dos atributos é aplicada a elementos específicos da linguagem, como classes ou métodos; No entanto, alguns atributos são globais — eles se aplicam a um assembly ou módulo inteiro. Por exemplo, o AssemblyVersionAttribute atributo pode ser usado para incorporar informações de versão em um assembly, da seguinte forma:
<Assembly: AssemblyVersion("1.0.0.0")>
Os atributos globais aparecem no código-fonte após qualquer instrução de nível Imports
superior e antes de qualquer tipo, módulo ou declaração de namespace. Os atributos globais podem aparecer em vários arquivos de origem, mas os arquivos devem ser compilados em um único passo 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).
Atributos de assembly são valores que fornecem informações sobre um assembly. Enquadram-se nas seguintes categorias:
Atributos de identidade do assembly
Atributos informativos
Atributos do 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 quando você faz 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 de nome é definido pelo compilador, o IDE do Visual Studio na caixa de diálogo Informações do assembly ou o vinculador de assembly (Al.exe) quando o assembly é criado, com base no arquivo que contém o manifesto do assembly. O AssemblyFlagsAttribute atributo especifica se várias cópias do assembly podem coexistir.
A tabela a seguir mostra os atributos de identidade.
Atributo | Propósito |
---|---|
AssemblyName | Descreve completamente a identidade de um assembly. |
AssemblyVersionAttribute | Especifica a versão de um assembly. |
AssemblyCultureAttribute | Especifica qual cultura o assembly suporta. |
AssemblyFlagsAttribute | Especifica se um assembly oferece suporte à execução lado a lado no mesmo computador, no mesmo processo ou no mesmo domínio de aplicativo. |
Atributos informativos
Você pode usar atributos informativos para fornecer informações adicionais sobre a empresa ou o produto para uma montagem. A tabela a seguir mostra os atributos informativos definidos no System.Reflection namespace.
Atributo | Propósito |
---|---|
AssemblyProductAttribute | Define um atributo personalizado que especifica um nome de produto para um manifesto de assembly. |
AssemblyTrademarkAttribute | Define um atributo personalizado que especifica uma marca comercial para um manifesto de assembly. |
AssemblyInformationalVersionAttribute | Define um atributo personalizado que especifica uma versão informativa para um manifesto de assembly. |
AssemblyCompanyAttribute | Define um atributo personalizado que especifica um nome de empresa para um manifesto de assembly. |
AssemblyCopyrightAttribute | Define um atributo personalizado que especifica um copyright para um manifesto de assembly. |
AssemblyFileVersionAttribute | Instrui o compilador a usar um número de versão específico para o recurso de versão do arquivo Win32. |
CLSCompliantAttribute | Indica se o assembly é compatível com a Common Language Specification (CLS). |
Atributos do manifesto do assembly
Você pode usar atributos de manifesto de assembly para fornecer informações no manifesto de assembly. Isso inclui título, descrição, alias padrão e configuração. A tabela a seguir mostra os atributos de manifesto System.Reflection de assembly definidos no namespace.
Atributo | Propósito |
---|---|
AssemblyTitleAttribute | Define um atributo personalizado que especifica um título de assembly para um manifesto de assembly. |
AssemblyDescriptionAttribute | Define um atributo personalizado que especifica uma descrição de assembly para um manifesto de assembly. |
AssemblyConfigurationAttribute | Define um atributo personalizado que especifica uma configuração de assembly (como varejo ou depuração) para um manifesto de assembly. |
AssemblyDefaultAliasAttribute | Define um alias padrão amigável para um manifesto de assembly |
Atributo obsoleto
O Obsolete
atributo marca uma entidade de programa como uma que não é mais recomendada para uso. Cada uso de uma entidade marcada como obsoleta gerará posteriormente um aviso ou um erro, dependendo de como o atributo está 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 Obsolete
atributo é aplicado à classe A
e ao método B.OldMethod
. Como o segundo argumento do construtor de atributo aplicado a B.OldMethod
é definido como true
, esse método causará um erro de compilador, enquanto o uso da classe A
produzirá apenas um aviso. Ligar B.NewMethod
, no entanto, não produz nenhum aviso ou erro.
A cadeia de caracteres fornecida como o primeiro argumento para o construtor de atributos será exibida como parte do aviso ou erro. Por exemplo, quando você usá-lo com as definições anteriores, o código a seguir gera dois avisos e um erro:
' 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()
Dois avisos para classe A
são gerados: um para a declaração da referência de classe e outro para o construtor de classe.
O Obsolete
atributo pode ser usado sem argumentos, mas recomenda-se incluir uma explicação do motivo pelo qual o item está obsoleto e o que usar em vez disso.
O Obsolete
atributo é um atributo de uso único e pode ser aplicado a qualquer entidade que permita atributos. Obsolete
é um alias para ObsoleteAttribute.
Atributo condicional
O Conditional
atributo torna a execução de um método dependente de um identificador de pré-processamento. O Conditional
atributo é um alias para ConditionalAttribute, e pode ser aplicado a um método ou a 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 TRACE_ON
identificador não estiver definido, nenhuma saída de rastreamento será exibida.
O Conditional
atributo é frequentemente usado com o DEBUG
identificador para habilitar recursos de rastreamento e registro em log para compilações de depuração, mas não em compilações de versão, como esta:
<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 é incluída ou omitida. Se o símbolo estiver definido, a chamada é incluída; caso contrário, a chamada será omitida. Usar Conditional
é uma alternativa mais limpa, elegante e menos propensa a erros para fechar métodos dentro #if…#endif
de blocos, como este:
#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 struct e não deve ter um valor de retorno.
Usando vários identificadores
Se um método tiver vários Conditional
atributos, 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 estão logicamente ligados entre si usando o operador OR). Neste exemplo, a presença de um ou A
B
resultará em uma chamada de método:
<Conditional("A"), Conditional("B")>
Shared Sub DoIfAorB()
End Sub
Para obter o efeito de vincular logicamente símbolos usando o operador AND, você pode definir métodos condicionais seriais. Por exemplo, o segundo método abaixo será executado somente se ambos A
e B
forem 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 atributo
O Conditional
atributo também pode ser aplicado a uma definição de classe de atributo. Neste exemplo, o atributo Documentation
custom só adicionará informações aos metadados se DEBUG for 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
Usando os atributos Caller Info, você pode obter informações sobre o chamador para um método. Você pode obter o caminho do arquivo do código-fonte, o número da linha no código-fonte e o nome do membro do chamador.
Para obter informações sobre o chamador de membro, use atributos que são aplicados a parâmetros opcionais. Cada parâmetro opcional especifica um valor padrão. A tabela a seguir lista os atributos Caller Info definidos no System.Runtime.CompilerServices namespace:
Atributo | Description | Type |
---|---|---|
CallerFilePathAttribute | Caminho completo do arquivo de origem que contém o chamador. Este é o caminho em tempo de compilação. | String |
CallerLineNumberAttribute | Número da 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 sobre chamadores (Visual Basic). | String |
CallerArgumentExpressionAttribute | Expressão usada pelo chamador para um argumento. Para obter mais informações, consulte Informações sobre chamadores (Visual Basic). | String |
Para obter mais informações sobre os atributos Caller Info, consulte Caller Information (Visual Basic).
Atributos do Visual Basic
A tabela a seguir lista os atributos que são específicos para Visual Basic.
Atributo | Propósito |
---|---|
ComClassAttribute | Indica ao compilador que a classe deve ser exposta como um objeto COM. |
HideModuleNameAttribute | Permite que os membros do módulo sejam acessados usando apenas 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 dos assemblies do .NET Framework e, sem COMClassAttribute
o , 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 do módulo sejam acessados usando apenas a qualificação necessária para o módulo.
VBFixedStringAttribute
Use VBFixedStringAttribute
para forçar o Visual Basic para criar uma cadeia de caracteres de comprimento fixo. As cadeias de caracteres são de 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 que são fixas em tamanho. Como as cadeias de caracteres do Visual Basic, as matrizes são de comprimento variável por padrão. Esse atributo é útil ao serializar ou gravar dados em arquivos.