Allgemeine Attribute (C# und Visual Basic)

In diesem Thema werden die Attribute beschrieben, die in C#- und Visual Basic-Programmen am häufigsten verwendet werden.

• Globale Attribute

• Veraltetes Attribut

• Bedingtes Attribut

• Visual Basic-Attribute

Globale Attribute

Die meisten Attribute werden auf spezifische Sprachelemente wie Klassen oder Methoden angewendet. Einige Attribute sind jedoch global, d. h., sie werden auf vollständige Assemblys oder Module angewendet. Zum Beispiel kann das AssemblyVersionAttribute-Attribut verwendet werden, um Versionsinformationen in eine Assembly wie folgt einzubetten:

[assembly: AssemblyVersion("1.0.0.0")]

<Assembly: AssemblyVersion("1.0.0.0")>

Globale Attribute befinden sich im Quellcode hinter jeder using-Direktive der obersten Ebene (Imports in Visual Basic) sowie vor jeder Typ-, Modul- oder Namespacedeklaration. Globale Attribute können in mehreren Quelldateien auftreten, jedoch müssen die Dateien in einem einzigen Kompilierungsdurchgang kompiliert werden. In Visual Basic-Projekten werden globale Attribute im Allgemeinen in der Datei AssemblyInfo.vb eingefügt, die automatisch zusammen mit Visual Basic-Projekten erstellt wird. In C#-Projekten werden sie in der Datei AssemblyInfo.cs eingefügt.

Assemblyattribute sind Werte, die Informationen über eine Assembly liefern. Sie werden in die folgenden Kategorien eingeteilt:

• Attribute für die Assemblyidentität

• Informationsattribute

• Attribute für Assemblymanifeste

• Attribute für starke Namen

Attribute für die Assemblyidentität

Die Identität einer Assembly wird (ggf. mit einem starken Namen) durch drei Attribute bestimmt, nämlich die Attribute für Namen, Version und Kulturkreis. Diese Attribute bilden den vollständigen Namen der Assembly und werden benötigt, wenn im Code auf die Assembly verwiesen wird. Version und Kulturkreis einer Assembly können mithilfe von Attributen festgelegt werden. Der Namenswert wird jedoch durch den Compiler, über die IDE von Visual Studio im Dialogfeld "Assemblyinformationen" oder durch den Assemblylinker (Al.exe) festgelegt, wenn die Assembly erstellt wird. Dies erfolgt anhand der Datei, die das Assemblymanifest enthält. Das AssemblyFlagsAttribute-Attribut gibt an, ob gleichzeitig mehrere Kopien der Assembly vorhanden sein können.

In der folgenden Tabelle sind die Identitätsattribute aufgeführt.

Informationsattribute

Mit Informationsattributen können Sie zusätzliche Firmen- oder Produktinformationen für eine Assembly bereitstellen. In der folgenden Tabelle sind die im System.Reflection-Namespace definierten Informationsattribute aufgeführt.

Attribute für Assemblymanifeste

Mithilfe von Assemblymanifestattributen können Sie die Informationen im Assemblymanifest bereitstellen. Dies schließt Titel, Beschreibung, Standardalias und Konfiguration ein. In der folgenden Tabelle sind die im System.Reflection-Namespace definierten Attribute für Assemblymanifeste aufgeführt.

Attribute für starke Namen

In vorherigen Versionen von Visual Studio wurde das Signieren von Assemblys mit starken Namen mithilfe der folgenden Attribute auf Assemblyebene ausgeführt:

• AssemblyKeyFileAttribute

• AssemblyKeyNameAttribute

• AssemblyDelaySignAttribute

Dies wird immer noch unterstützt, allerdings ist der bevorzugte Weg, Assemblys zu signieren, die Verwendung der Seite Signierung im Projekt-Designer. Weitere Informationen finden Sie unter Seite "Signierung", Projekt-Designer und Gewusst wie: Signieren von Assemblys (Visual Studio).

Veraltetes Attribut

Das Obsolete-Attribut kennzeichnet eine Programmentität, die nicht mehr zur Verwendung empfohlen wird. Jedes Mal, wenn eine als veraltet gekennzeichnete Entität verwendet wird, wird daraufhin je nach Konfiguration des Attributs eine Warnung oder ein Fehler generiert. Beispiel:

    <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 diesem Beispiel wird das Obsolete-Attribut auf Klasse A und Methode B.OldMethod angewendet. Da das zweite Argument des Attributkonstruktors, das auf B.OldMethod angewendet wird, auf true festgelegt ist, führt die Verwendung dieser Methode zu einem Compilerfehler. Die Verwendung der Klasse A erzeugt jedoch lediglich eine Warnung. Durch den Aufruf von B.NewMethod wird jedoch keine Warnung bzw. kein Fehler erzeugt.

Die Zeichenfolge, die dem Attributkonstruktor als erstes Argument zur Verfügung steht, wird als Teil der Warnung bzw. des Fehlers angezeigt. Zum Beispiel generiert der folgende Code zwei Warnungen und einen Fehler, wenn er mit den vorherigen Definitionen verwendet wird:

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

Es werden zwei Warnungen für die Klasse A generiert: eine für die Deklaration des Klassenverweises und eine für den Klassenkonstruktor.

Das Obsolete-Attribut kann ohne Argumente verwendet werden. Es ist jedoch empfehlenswert, eine Erklärung einzubinden, warum das Element veraltet ist und was alternativ dazu verwendet werden kann.

Das Obsolete-Attribut ist ein einmal verwendbares Attribut und kann auf jede Entität angewendet werden, die Attribute zulässt. Obsolete ist ein Alias für ObsoleteAttribute.

Bedingtes Attribut

Das Conditional-Attribut macht die Ausführung einer Methode von einem Vorverarbeitungsbezeichner abhängig. Das Conditional-Attribut ist ein Alias für ConditionalAttribute und kann auf eine Methode oder eine Attributklasse angewendet werden.

In diesem Beispiel wird Conditional auf eine Methode angewendet, um die Anzeige von programmspezifischen Diagnoseinformationen zu aktivieren bzw. zu deaktivieren:

#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.");
    }
}

Wenn der TRACE_ON-Bezeichner nicht definiert ist, wird keine Ablaufverfolgungsausgabe angezeigt.

Das Conditional-Attribut wird oft mit dem DEBUG-Bezeichner verwendet, um Features zur Ablaufverfolgung und Protokollierung für Debugbuilds (nicht für Releasebuilds) zu aktivieren. Beispiel:

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

End Sub

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

Wenn eine als bedingt gekennzeichnete Methode aufgerufen wird, bestimmt das Vorhandensein oder Nichtvorhandensein des angegebenen Präprozessorsymbols, ob der Aufruf einbezogen oder weggelassen wird. Ist das Symbol definiert, wird der Aufruf einbezogen; andernfalls wird er nicht berücksichtigt. Die Verwendung von Conditional stellt eine klarer definierte, elegantere und weniger fehleranfällige Alternative zum Einschließen von Methoden in #if…#endif-Blöcke dar:

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

#if DEBUG
    void ConditionalMethod()
    {
    }
#endif

Eine bedingte Methode muss eine Methode in einer Klassendeklaration oder Strukturdeklaration sein und darf keinen Rückgabewert aufweisen.

Verwenden mehrerer Bezeichner

Wenn eine Methode über mehrere Conditional-Attribute verfügt, wird der Aufruf der Methode einbezogen, sofern mindestens ein bedingtes Symbol definiert ist. Dies bedeutet, dass die Symbole durch den OR-Operator logisch verbunden sind. In diesem Beispiel führt das Vorhandensein von A oder B zu einem Methodenaufruf:

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

End Sub

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

Um Symbole mit einem AND-Operator logisch zu verbinden, können Sie serielle bedingte Methoden definieren. Zum Beispiel wird die nachfolgende zweite Methode nur ausgeführt, wenn sowohl A als auch B definiert sind:

<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...
}

Verwenden von Conditional für Attributklassen

Das Conditional-Attribut kann auch auf die Definition einer Attributklasse angewendet werden. In diesem Beispiel fügt das benutzerdefinierte Documentation-Attribut den Metadaten nur Informationen zu, wenn DEBUG definiert ist.

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

Visual Basic-Attribute

In der folgenden Tabelle sind die für Visual Basic spezifischen Attribute aufgeführt.

COMClassAttribute

Mit COMClassAttribute können Sie das Erstellen von COM-Komponenten in Visual Basic vereinfachen. Zwischen COM-Objekten und .NET Framework-Assemblys bestehen erhebliche Unterschiede. Ohne das COMClassAttribute müssen Sie eine Reihe von Schritten ausführen, um in Visual Basic ein COM-Objekt zu generieren. Bei mit COMClassAttribute gekennzeichneten Klassen werden vom Compiler viele dieser Schritte automatisch ausgeführt.

HideModuleNameAttribute

Verwenden Sie HideModuleNameAttribute, damit nur unter Verwendung der Qualifizierung, die für das Modul benötigt wird, auf Modulmember zugegriffen werden kann.

VBFixedStringAttribute

Verwenden Sie VBFixedStringAttribute, um Visual Basic zu zwingen, eine Zeichenfolge mit fester Länge zu erstellen. Zeichenfolgen haben standardmäßig eine variable Länge. Außerdem eignet sich dieses Attribut zum Speichern von Zeichenfolgen in Dateien. Der folgende Code zeigt dies:

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

Verwenden Sie VBFixedArrayAttribute, um Arrays mit fester Größe zu deklarieren. Ähnlich wie Zeichenfolgen in Visual Basic weisen Arrays standardmäßig eine variable Länge auf. Dieses Attribut ist beim Serialisieren oder Schreiben von Daten in Dateien hilfreich.

Siehe auch

Referenz

Reflektion (C# und Visual Basic)

Zugreifen auf Attribute mithilfe der Reflektion (C# und Visual Basic)

System.Reflection

Attribute

Konzepte

C#-Programmierhandbuch

Erweitern von Metadaten mithilfe von Attributen

Weitere Ressourcen

Visual Basic-Programmierhandbuch