Attributi comuni (Visual Basic)

  • Articolo

Questo argomento descrive gli attributi usati più di frequente nei programmi Visual Basic.

Attributi globali

La maggior parte degli attributi viene applicata a elementi specifici del linguaggio quali classi o metodi. Alcuni attributi sono invece globali e vengono applicati a un intero assembly o a un intero modulo. Ad esempio, l'attributo AssemblyVersionAttribute può essere usato per incorporare informazioni sulla versione in un assembly, nel modo seguente:

<Assembly: AssemblyVersion("1.0.0.0")>

Gli attributi globali sono visibili nel codice sorgente dopo eventuali istruzioni Imports di primo livello e prima delle dichiarazioni di tipo, modulo o spazio dei nomi. Gli attributi globali possono apparire in più file di origine, ma i file devono essere compilati in un'unica operazione di compilazione. Per i progetti Visual Basic, gli attributi globali vengono in genere inseriti nel file AssemblyInfo.vb (il file è creato automaticamente alla creazione di un progetto in Visual Studio).

Gli attributi dell'assembly sono valori che forniscono informazioni relative a un assembly. Sono suddivisi nelle seguenti categorie:

  • Attributi relativi all'identità dell'assembly

  • Attributi informativi

  • Attributi relativi al manifesto dell'assembly

Attributi relativi all'identità dell'assembly

Tre attributi (con un nome sicuro, se disponibile), consentono di determinare l'identità di un assembly: il nome, la versione e le impostazioni cultura. Questi attributi formano il nome completo dell'assembly e sono necessari per creare riferimenti all'assembly nel codice. È possibile usare gli attributi per impostare la versione e le impostazioni cultura di un assembly. Tuttavia il valore del nome viene impostato alla creazione dell'assembly dal compilatore (l'IDE di Visual Studio nella finestra di dialogo informazioni Assembly oppure Assembly Linker, Al.exe), in base al file che contiene il manifesto dell'assembly. L'attributo AssemblyFlagsAttribute specifica se è supportata la coesistenza di più copie dell'assembly.

La tabella seguente visualizza gli attributi relativi all'identità.

Attributo Scopo
AssemblyName Descrive in modo completo l'identità di un assembly.
AssemblyVersionAttribute Specifica la versione di un assembly.
AssemblyCultureAttribute Specifica le impostazioni cultura supportate dall'assembly.
AssemblyFlagsAttribute Specifica se un assembly supporta l'esecuzione side-by-side nello stesso computer, nello stesso processo o nello stesso dominio dell'applicazione.

Attributi informativi

Gli attributi informativi consentono di fornire informazioni aggiuntive relative alla società o al prodotto per un assembly. La tabella seguente mostra gli attributi informativi definiti nello spazio dei nomi System.Reflection.

Attributo Scopo
AssemblyProductAttribute Definisce un attributo personalizzato che specifica un nome prodotto per un manifesto dell'assembly.
AssemblyTrademarkAttribute Definisce un attributo personalizzato che specifica un marchio registrato per un manifesto dell'assembly.
AssemblyInformationalVersionAttribute Definisce un attributo personalizzato che specifica una versione informativa per un manifesto dell'assembly.
AssemblyCompanyAttribute Definisce un attributo personalizzato che specifica un nome società per un manifesto dell'assembly.
AssemblyCopyrightAttribute Definisce un attributo personalizzato che specifica un copyright per un manifesto dell'assembly.
AssemblyFileVersionAttribute Indica al compilatore di usare un numero di versione specifico per la risorsa della versione del file Win32.
CLSCompliantAttribute Indica se l'assembly è conforme a CLS (Common Language Specification).

Attributi relativi al manifesto dell'assembly

È possibile usare gli attributi relativi al manifesto dell'assembly per includere informazioni nel manifesto dell'assembly. Queste informazioni includono il titolo, la descrizione, l'alias predefinito e la configurazione. La tabella seguente visualizza gli attributi del manifesto dell'assembly definiti nello spazio dei nomi System.Reflection.

Attributo Scopo
AssemblyTitleAttribute Definisce un attributo personalizzato che specifica un titolo assembly per un manifesto dell'assembly.
AssemblyDescriptionAttribute Definisce un attributo personalizzato che specifica una descrizione assembly per un manifesto dell'assembly.
AssemblyConfigurationAttribute Definisce un attributo personalizzato che specifica una configurazione assembly per un manifesto dell'assembly.
AssemblyDefaultAliasAttribute Definisce un alias predefinito descrittivo per un manifesto dell'assembly.

Attributo Obsolete

L'attributo Obsolete contrassegna un'entità del programma il cui uso non è più consigliato. Ogni uso di un'entità contrassegnata con Obsolete genererà in seguito un avviso o errore, a seconda della configurazione dell'attributo. Ad esempio:

<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

Nel seguente esempio l'attributo Obsolete viene applicato alla classe A e al metodo B.OldMethod. Poiché il secondo argomento del costruttore dell'attributo applicato a B.OldMethod è impostato su true questo metodo genererà un errore del compilatore, mentre l'uso della classe A produrrà semplicemente un avviso. Tuttavia la chiamata di B.NewMethod non produrrà né un avviso né un errore.

La stringa specificata come primo argomento al costruttore dell'attributo viene inclusa nell'avviso o nell'errore visualizzato. Ad esempio, se viene usato con le definizioni precedenti, il codice che segue genera due avvisi e un errore:

' 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()

Vengono generati due avvisi per la classe A: uno per la dichiarazione del riferimento alla classe e uno per il costruttore della classe.

L'attributo Obsolete può essere usato senza argomenti, ma è consigliabile includere la spiegazione del motivo per cui l'elemento è obsoleto e l'indicazione degli elementi di codice da usare come alternativa.

Obsolete è un attributo monouso e può essere applicato a qualsiasi entità che supporta gli attributi. Obsolete è un alias per ObsoleteAttribute.

Attributo Conditional

L'attributo Conditional rende l'esecuzione di un metodo dipendente da un identificatore di pre-elaborazione. L'attributo Conditional è un alias per ConditionalAttribute e può essere applicato a un metodo o a una classe Attribute.

In questo esempio, Conditional viene applicato a un metodo per attivare o disattivare la visualizzazione di informazioni di diagnostica specifiche del programma:

#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 l'identificatore TRACE_ON non è definito, non viene visualizzato nessun output di traccia.

L'attributo Conditional viene usato spesso con l'identificatore DEBUG per abilitare funzioni di traccia e registrazione nelle compilazioni di debug ma non nelle build di rilascio, come segue:

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

End Sub

Quando viene chiamato un metodo contrassegnato come condizionale, la presenza o l'assenza del simbolo di pre-elaborazione specificato determina se la chiamata viene inclusa o omessa. Se il simbolo è definito la chiamata viene inclusa, in caso contrario viene omessa. L'uso di Conditional rappresenta un'alternativa più efficiente, elegante e meno soggetta a errori rispetto all'inclusione di metodi nei blocchi #if…#endif come segue:

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

Un metodo condizionale deve essere un metodo in una dichiarazione di classe o struct e non deve avere un valore restituito.

Usare più identificatori

Se un metodo ha più attributi Conditional, una chiamata al metodo è inclusa se è definito almeno uno dei simboli condizionali (in altre parole, se i simboli sono collegati tra loro a livello logico mediante l'operatore OR). In questo esempio la presenza di A o B determina una chiamata al metodo:

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

End Sub

Per ottenere il collegamento logico di simboli tramite l'operatore AND è possibile definire metodi condizionali seriali. Ad esempio, il secondo metodo riportato di seguito viene eseguito solo se sono definiti sia A sia B:

<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

Usare Conditional con le classi di attributi

L'attributo Conditional può essere applicato anche a una definizione di classe Attribute. In questo esempio l'attributo personalizzato Documentation aggiunge le informazioni ai metadati solo se è definito l'elemento DEBUG.

<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

Attributi informativi sul chiamante

Gli attributi di informazioni sul chiamante consentono di ottenere informazioni sul chiamante di un metodo. È possibile ottenere il percorso del file del codice sorgente, il numero di riga nel codice sorgente e il nome del chiamante.

È possibile ottenere informazioni sul chiamante usando gli attributi applicati ai parametri facoltativi. Ogni parametro facoltativo specifica un valore predefinito. Nella tabella seguente sono elencati gli attributi di informazioni sul chiamante definiti nello spazio dei nomi System.Runtime.CompilerServices:

Attributo Descrizione Tipo
CallerFilePathAttribute Percorso completo del file di origine contenente il chiamante. È il percorso al momento della compilazione. String
CallerLineNumberAttribute Numero di riga nel file di origine da cui viene chiamato il metodo. Integer
CallerMemberNameAttribute Nome di una proprietà o di un metodo del chiamante. Per altre informazioni, vedere Informazioni sul chiamante (Visual Basic). String
CallerArgumentExpressionAttribute Espressione utilizzata dal chiamante per un argomento. Per altre informazioni, vedere Informazioni sul chiamante (Visual Basic). String

Per altre informazioni sugli attributi di informazioni sul chiamante, vedere Informazioni sul chiamante (Visual Basic).

Attributi di Visual Basic

La tabella seguente elenca gli attributi specifici di Visual Basic.

Attributo Scopo
ComClassAttribute Indica al compilatore che la classe deve essere esposta come oggetto COM.
HideModuleNameAttribute Consente l'accesso ai membri del modulo usando solo la qualifica necessaria per il modulo.
VBFixedStringAttribute Specifica le dimensioni di una stringa a lunghezza fissa in una struttura da usare con le funzioni di input e output dei file.
VBFixedArrayAttribute Specifica le dimensioni di una matrice fissa in una struttura da usare con le funzioni di input e output dei file.

COMClassAttribute

Usare COMClassAttribute per semplificare il processo di creazione di componenti COM da Visual Basic. Gli oggetti COM sono notevolmente diversi dagli assembly .NET Framework e senza COMClassAttribute, è necessario seguire una serie di passaggi per generare un oggetto COM da Visual Basic. Per le classi contrassegnate con COMClassAttribute, il compilatore esegue automaticamente molti di questi passaggi.

HideModuleNameAttribute

Usare HideModuleNameAttribute per consentire l'accesso ai membri del modulo usando solo la qualifica necessaria per il modulo.

VBFixedStringAttribute

Utilizzare VBFixedStringAttribute per forzare Visual Basic a creare una stringa a lunghezza fissa. Le stringhe sono di lunghezza variabile per impostazione predefinita e questo attributo è utile quando si archiviano stringhe nei file. Questo concetto è illustrato nel codice riportato di seguito:

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

Usare VBFixedArrayAttribute per dichiarare matrici di dimensioni fisse. Analogamente alle stringhe di Visual Basic, le matrici sono di lunghezza variabile per impostazione predefinita. Questo attributo è utile per la serializzazione o la scrittura di dati nei file.

Vedi anche