Attributi comuni (C# e Visual Basic)

Articolo
06/10/2015

In questo argomento vengono illustrati gli attributi utilizzati più di frequente nei programmi C# e Visual Basic.

Attributi globali
Attributo Obsolete
Attributo Conditional
Chiamante di attributi informativi
Attributi di Visual Basic

Attributi globali

La maggior parte degli attributi viene applicata a elementi specifici del linguaggio, ad esempio classi o metodi. Esistono tuttavia alcuni attributi globali che vengono applicati a un intero assembly o modulo. Ad esempio, l'attributo AssemblyVersionAttribute può essere utilizzato per incorporare le informazioni sulla versione in un assembly, come indicato di seguito:

[assembly: AssemblyVersion("1.0.0.0")]

<Assembly: AssemblyVersion("1.0.0.0")>

Gli attributi globali vengono visualizzati nel codice sorgente dopo qualsiasi direttiva using (Imports in Visual Basic) di primo livello e prima di qualsiasi dichiarazione di tipo, modulo o spazio dei nomi. Gli attributi globali possono essere utilizzati in più file di origine ma i file devono essere compilati in un singolo passaggio. Per i progetti Visual Basic gli attributi globali vengono generalmente inseriti nel file AssemblyInfo.vb creato automaticamente con i progetti Visual Basic. Nei progetti C# vengono inseriti nel file AssemblyInfo.cs.

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

Attributi relativi all'identità dell'assembly
Attributi informativi
Attributi relativi al manifesto dell'assembly
Attributi relativi al nome sicuro

Attributi relativi all'identità dell'assembly

L'identità di un assembly è determinata da tre attributi e, se disponibile, da un nome sicuro. Questi attributi, ovvero nome, versione e impostazioni cultura, Il nome completo dell'assembly è costituito da questi attributi che sono necessari quando si creano riferimenti all'assembly nel codice. Tramite gli attributi è possibile impostare la versione e le impostazioni cultura di un assembly. Il valore relativo al nome viene tuttavia impostato dal compilatore, dall'ambiente di sviluppo integrato di Visual Studio nella Finestra di dialogo Informazioni assembly o da Assembly Linker (Al.exe) durante la creazione dell'assembly, in base al file che contiene il manifesto dell'assembly. L'attributo AssemblyFlagsAttribute specifica se è possibile la coesistenza di più copie dell'assembly.

Nella tabella che segue sono riportati gli attributi relativi all'identità.

Attributo	Scopo
AssemblyName	Descrive in modo completo l'identità di un assembly.
AssemblyVersionAttribute	Specifica la versione dell'assembly.
AssemblyCultureAttribute	Specifica le impostazioni cultura supportate dall'assembly.
AssemblyFlagsAttribute	Specifica se l'assembly supporta l'esecuzione side-by-side sullo 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. Nella tabella che segue sono riportati gli attributi informativi definiti nello spazio dei nomi System.Reflection.

Attributo	Scopo
AssemblyProductAttribute	Definisce un attributo personalizzato che specifica il nome del prodotto per un manifesto dell'assembly.
AssemblyTrademarkAttribute	Definisce un attributo personalizzato che specifica il marchio per un manifesto dell'assembly.
AssemblyInformationalVersionAttribute	Definisce un attributo personalizzato che specifica la versione informativa per un manifesto dell'assembly.
AssemblyCompanyAttribute	Definisce un attributo personalizzato che specifica il nome della società per un manifesto dell'assembly.
AssemblyCopyrightAttribute	Definisce un attributo personalizzato che specifica il copyright per un manifesto dell'assembly.
AssemblyFileVersionAttribute	Indica al compilatore di utilizzare un numero di versione specifico per la risorsa di versione del file Win32.
CLSCompliantAttribute	Indica se l'assembly è conforme con le specifiche CLS.

Attributi relativi al manifesto dell'assembly

È possibile utilizzare gli attributi del manifesto dell'assembly per fornire le informazioni nel manifesto dell'assembly, inclusi titolo, descrizione, alias predefinito e configurazione. Nella tabella che segue sono riportati gli attributi relativi al manifesto dell'assembly definiti nello spazio dei nomi System.Reflection.

Attributo	Scopo
AssemblyTitleAttribute	Definisce un attributo personalizzato che specifica il titolo dell'assembly per un manifesto dell'assembly.
AssemblyDescriptionAttribute	Definisce un attributo personalizzato che specifica la descrizione dell'assembly per un manifesto dell'assembly.
AssemblyConfigurationAttribute	Definisce un attributo personalizzato che specifica la configurazione dell'assembly, ad esempio finale o debug, per un manifesto dell'assembly.
AssemblyDefaultAliasAttribute	Viene definito un alias predefinito descrittivo per un manifesto dell'assembly.

Attributi relativi al nome sicuro

Nelle versioni precedenti di Visual Studio la firma degli assembly con nome sicuro veniva eseguita con gli attributi a livello di assembly seguenti:

Sebbene questa tecnica sia ancora supportata, il metodo migliore per la firma degli assembly consiste nell'utilizzo della pagina Firma in Progettazione progetti. Per ulteriori informazioni, vedere Pagina Firma, Progettazione progetti e Procedura: firmare un assembly (Visual Studio).

Attributo Obsolete

L'attributo Obsolete viene utilizzato per contrassegnare un'entità del programma il cui uso non è più consigliato. Ogni volta che si utilizza un'entità contrassegnata con questo attributo verrà generato automaticamente un avviso o un errore, a seconda del modo in cui è configurato l'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

[System.Obsolete("use class B")]
class A
{
    public void Method() { }
}
class B
{
    [System.Obsolete("use NewMethod", true)]
    public void OldMethod() { }
    public void NewMethod() { }
}

In questo esempio l'attributo Obsolete viene applicato alla classe A e al metodo B.OldMethod. Poiché il secondo argomento del costruttore di attributo applicato a B.OldMethod è impostato su true, questo metodo causerà un errore del compilatore, mentre l'utilizzo della classe A produrrà semplicemente un avviso. La chiamata a B.NewMethod, tuttavia, non causerà né un avviso né un errore.

La stringa fornita come primo argomento del costruttore di attributo verrà visualizzata nel testo dell'avviso o dell'errore. Se ad esempio si utilizzano le definizioni precedenti, il codice riportato di seguito 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()

// Generates 2 warnings: 
// A a = new A(); 

// Generate no errors or warnings:
B b = 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 della classe e uno per il costruttore di classe.

L'attributo Obsolete può essere utilizzato senza argomenti. In questo caso, tuttavia, si consiglia di indicare il motivo che rende obsoleto l'elemento e di fornire un elemento da utilizzare in alternativa.

Obsolete è un attributo di utilizzo singolo 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 disabilitare la visualizzazione di informazioni diagnostiche specifiche di un programma:

#Const TRACE_ON = True 
Imports System
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

#define TRACE_ON
using System;
using System.Diagnostics;

public class Trace
{
    [Conditional("TRACE_ON")]
    public static void Msg(string msg)
    {
        Console.WriteLine(msg);
    }
}

public class ProgramClass
{
    static void Main()
    {
        Trace.Msg("Now in Main...");
        Console.WriteLine("Done.");
    }
}

Se l'identificatore TRACE_ON non è definito, non verrà visualizzato alcun output di traccia.

L'attributo Conditional viene spesso utilizzato con l'identificatore DEBUG per attivare le funzionalità di traccia e registrazione per le build di debug ma non nelle build di rilascio, come indicato nell'esempio riportato di seguito:

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

End Sub

[Conditional("DEBUG")]
static void DebugMethod()
{
}

Quando viene chiamato un metodo contrassegnato con l'attributo Conditional, la presenza o l'assenza del simbolo di pre-elaborazione specificato determina se la chiamata deve essere inclusa o omessa. Se il simbolo è definito, la chiamata viene inclusa. In caso contrario, viene omessa. L'utilizzo di Conditional rappresenta un'alternativa più semplice, più elegante e meno soggetta a errori rispetto all'inclusione di metodi all'interno di blocchi #if…#endif, come illustrato di seguito:

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

#if DEBUG
    void ConditionalMethod()
    {
    }
#endif

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

Utilizzo di più identificatori

Se un metodo ha più attributi Conditional, viene inclusa una chiamata al metodo nel caso in cui almeno uno dei simboli condizionali sia definito (in altre parole, nel caso in cui i simboli siano collegati dall'operatore OR). In questo esempio la presenza di A o B determinerà una chiamata al metodo:

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

End Sub

[Conditional("A"), Conditional("B")]
static void DoIfAorB()
{
    // ...
}

Per ottenere l'effetto di collegamento logico di simboli mediante l'operatore AND, è possibile definire metodi condizionali seriali. Ad esempio, il secondo metodo riportato più avanti verrà eseguito solo se sono definiti sia A che 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

[Conditional("A")]
static void DoIfA()
{
    DoIfAandB();
}

[Conditional("B")]
static void DoIfAandB()
{
    // Code to execute when both A and B are defined...
}

Utilizzo di Conditional con le classi Attribute

L'attributo Conditional può essere applicato anche a una definizione di classe Attribute. In questo esempio l'attributo personalizzato Documentation aggiungerà le informazioni ai metadati solo se è definito l'identificatore 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

[Conditional("DEBUG")]
public class Documentation : System.Attribute
{
    string text;

    public Documentation(string text)
    {
        this.text = text;
    }
}

class SampleClass
{
    // This attribute will only be included if DEBUG is defined.
    [Documentation("This method displays an integer.")]
    static void DoWork(int i)
    {
        System.Console.WriteLine(i.ToString());
    }
}

Chiamante di attributi informativi

Mediante il Chiamante di attributi informativi è possibile 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 di un metodo.

Per ottenere informazioni sul chiamante del membro, utilizzare gli attributi applicati ai parametri facoltativi. Ongi parametro facoltativo è impostato con un valore predefinito. Nella tabella seguente sono elencati gli attributi delle informazioni del chiamante definiti nello spazio dei nomi System.Runtime.CompilerServices :

Attributo	Descrizione	Type
CallerFilePathAttribute	Percorso completo del file di origine contenente il chiamante. Si tratta del percorso durante la fase di compilazione.	String
CallerLineNumberAttribute	Numero di riga nel file di origine da cui viene chiamato il metodo.	Integer
CallerMemberNameAttribute	Nome del metodo o della proprietà di un chiamante. Per ulteriori informazioni, vedere Informazioni sul chiamante (C# e Visual Basic).	String

Per ulteriori informazioni sulle informazioni del chiamante, vedere Informazioni sul chiamante (C# e Visual Basic).

Attributi di Visual Basic

Nella tabella seguente sono elencati gli attributi specifici di Visual Basic.

Attributo	Scopo
ComClassAttribute	Consente di indicare al compilatore che la classe deve essere esposta come oggetto COM.
HideModuleNameAttribute	Consente l'accesso ai membri del modulo utilizzando solo la qualifica necessaria per il modulo.
VBFixedStringAttribute	Consente di specificare la dimensione di una stringa di lunghezza fissa in una struttura da utilizzare con funzionalità di input e output di file.
VBFixedArrayAttribute	Consente di specificare la dimensione di una matrice fissa in una struttura da utilizzare con funzionalità di input e output di file.

COMClassAttribute

Utilizzare COMClassAttribute per semplificare il processo di creazione di componenti COM da Visual Basic. Poiché gli oggetti COM sono notevolmente diversi dagli assembly .NET Framework e non utilizzano COMClassAttribute, è necessario eseguire numerosi passaggi per generare un oggetto COM da Visual Basic. Per le classi contrassegnate con COMClassAttribute, il compilatore esegue automaticamente molti dei passaggi necessari.

HideModuleNameAttribute

Utilizzare HideModuleNameAttribute per consentire l'accesso ai membri del modulo utilizzando solo la qualificazione necessaria per il modulo.

VBFixedStringAttribute

Utilizzare VBFixedStringAttribute per imporre la creazione di una stringa a lunghezza fissa da parte di Visual Basic. Per impostazione predefinita, la lunghezza delle stringhe è variabile e questo attributo risulta utile per la memorizzazione delle stringhe nei file. Il metodo è illustrato nel codice seguente:

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

È possibile utilizzare VBFixedArrayAttribute per dichiarare matrici di dimensione fissa. Per impostazione predefinita le matrici hanno lunghezza variabile, come le stringhe di Visual Basic. È possibile utilizzare questo attributo per serializzare o scrivere dati nei file.

Vedere anche

Condividi tramite