Attributi comuni (C# e Visual Basic)

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

• Attributi globali

• Attributo Obsolete

• Attributo Conditional

• 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à.

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.

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.

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:

• AssemblyKeyFileAttribute

• AssemblyKeyNameAttribute

• AssemblyDelaySignAttribute

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. Di seguito è riportato un esempio di utilizzo di questo attributo.

    <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());
    }
}

Attributi di Visual Basic

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

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

Riferimenti

Reflection (C# e Visual Basic)

Accesso agli attributi tramite reflection (C# e Visual Basic)

System.Reflection

Attribute

Concetti

C# Programming Guide

Estensione di metadati mediante attributi

Altre risorse

Visual Basic Programming Guide