Common Attributes (Visual Basic) (Gemeinsame Attribute (Visual Basic))

  • Artikel

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

Globale Attribute

Die meisten Attribute werden auf spezifische Sprachelemente wie Klassen oder Methoden angewendet. Einige Attribute sind jedoch global – sie gelten für eine gesamte Assembly oder ein Modul. Zum Beispiel kann das AssemblyVersionAttribute-Attribut zum Einbetten von Versionsinformationen in eine Assembly verwendet werden. Diese sieht wie folgt aus:

<Assembly: AssemblyVersion("1.0.0.0")>

Globale Attribute werden im Quellcode nach Imports-Anweisungen der obersten Ebene und vor Typ-, Modul- oder Namespacedeklarationen angezeigt. Globale Attribute können in mehreren Quelldateien auftreten, jedoch müssen die Dateien in einem einzigen Kompilierungsdurchlauf kompiliert werden. Bei Visual Basic-Projekten werden globale Attribute im Allgemeinen in der Datei „AssemblyInfo.vb“ abgelegt (die Datei wird automatisch erstellt, wenn Sie ein Projekt in Visual Studio erstellen).

Assemblyattribute sind Werte, die Informationen zu einer Assembly bereitstellen. Sie werden in die folgenden Kategorien eingeteilt:

  • Attribute für Assemblyidentitäten

  • Informationsattribute

  • Attribute für Assemblymanifeste.

Attribute für Assemblyidentitäten

Drei Attribute bestimmen mit einem starken Namen (falls zutreffend) die Identität einer Assembly: „name“, „version“ und „culture“. Diese Attribute bilden den vollständigen Namen der Assembly und sind erforderlich, wenn im Code auf sie verwiesen wird. Mit Attributen können die Version und Kultur einer Assembly festgelegt werden. Allerdings wird der name-Wert vom Compiler, der Visual Studio-IDE im Dialogfeld „Assemblyinformationen“ oder dem Assemblylinker (Al.exe) festgelegt, wenn die Assembly erstellt wird. Die geschieht auf Grundlage der Datei, die das Assemblymanifest enthält. Das Attribut AssemblyFlagsAttribute gibt an, ob mehrere Kopien der Assembly parallel bestehen können.

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

Attribut Zweck
AssemblyName Beschreibt vollständig die Identität einer Assembly
AssemblyVersionAttribute Gibt die Version einer Assembly an
AssemblyCultureAttribute Gibt an, welche Kultur die Assembly unterstützt.
AssemblyFlagsAttribute Gibt an, ob eine Assembly die parallele Ausführung auf demselben Computer, im selben Prozess oder in derselben Anwendungsdomäne unterstützt

Informationsattribute

Mit Informationsattributen können Sie zusätzliche Firmen- oder Produktinformationen für eine Assembly bereitstellen. Die folgende Tabelle zeigt die Informationsattribute, die im Namespace System.Reflection definiert werden.

Attribut Zweck
AssemblyProductAttribute Definiert ein benutzerdefiniertes Attribut, das den Produktnamen für ein Assemblymanifest angibt
AssemblyTrademarkAttribute Definiert ein benutzerdefiniertes Attribut, das eine Marke für ein Assemblymanifest angibt
AssemblyInformationalVersionAttribute Definiert ein benutzerdefiniertes Attribut, das eine Informationsversion für ein Assemblymanifest angibt
AssemblyCompanyAttribute Definiert ein benutzerdefiniertes Attribut, das einen Firmennamen für ein Assemblymanifest angibt
AssemblyCopyrightAttribute Definiert ein benutzerdefiniertes Attribut, das ein Copyright für ein Assemblymanifest angibt
AssemblyFileVersionAttribute Weist den Compiler an, eine spezifische Versionsnummer für die Win32-Dateiversionsressource zu verwenden
CLSCompliantAttribute Gibt an, ob die Assembly mit der Common Language Specification (CLS) kompatibel ist

Attribute für Assemblymanifeste

Sie können Attribute für Assemblymanifeste verwenden, um Informationen im Assemblymanifest bereitzustellen. Dies schließt Titel, Beschreibung, Standardalias und Konfiguration ein. Die folgende Tabelle zeigt die Attribute für Assemblymanifeste, die im Namespace System.Reflection definiert werden.

Attribut Zweck
AssemblyTitleAttribute Definiert ein benutzerdefiniertes Attribut, das einen Assemblytitel für ein Assemblymanifest angibt
AssemblyDescriptionAttribute Definiert ein benutzerdefiniertes Attribut, das eine Assemblybeschreibung für ein Assemblymanifest angibt
AssemblyConfigurationAttribute Definiert ein benutzerdefiniertes Attribut, das eine Assemblykonfiguration (z.B. Retail oder Debug) für ein Assemblymanifest angibt
AssemblyDefaultAliasAttribute Definiert einen benutzerfreundlichen Standardalias für ein Assemblymanifest

Obsolete-Attribut

Das Obsolete-Attribut markiert eine Programmentität als eine, die nicht mehr zur Verwendung empfohlen wird. Jede Verwendung einer Entität, die als veraltet markiert ist, generiert anschließend eine Warnung oder einen Fehler, je nachdem, wie das Attribut konfiguriert ist. 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

Dieses Beispiel zeigt, wie das Obsolete-Attribut auf die A-Klasse und die B.OldMethod-Methode angewendet wird. Da das zweite Argument des Attributkonstruktors, das auf B.OldMethod angewendet wurde, auf true festgelegt wird, verursacht diese Methode einen Compilerfehler. Die Verwendung der A-Klasse erzeugt hingegen nur eine Warnung. Wenn Sie B.NewMethod aufrufen, werden weder Warnungen noch Fehler erzeugt.

Die Zeichenfolge, die als erstes Argument für den Attributkonstruktor bereitgestellt wurde, wird als Teil der Warnung oder des Fehlers angezeigt. Wenn Sie es mit den vorherigen Definitionen verwenden, generiert der folgende Code zwei Warnungen und einen Fehler:

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

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, jedoch ist das Einschließen einer Erklärung, warum das Element veraltet ist und was demnach verwendet werden soll, empfohlen.

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

Conditional-Attribut

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

In diesem Beispiel wird Conditional auf eine Methode angewendet, um die Anzeige programmspezifischer Diagnoseinformationen zu aktivieren oder zu deaktivieren.

#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

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

Das Conditional-Attribut wird oft zusammen mit dem DEBUG-Bezeichner verwendet, um die Ablaufverfolgung und Protokollierung von Features zum Debuggen von Builds, jedoch nicht in Releasebuilds, wie folgt zu aktivieren:

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

End Sub

Wenn eine als bedingt gekennzeichnete Methode aufgerufen wird, bestimmt das Vorhandensein oder Fehlen des angegebenen Vorverarbeitungssymbols, ob der Aufruf eingeschlossen oder ausgelassen wird. Wenn das Symbol definiert ist, wird der Aufruf einbezogen; andernfalls wird der Aufruf ausgelassen. Die Verwendung von Conditional ist eine sauberere, elegantere und auch weniger fehleranfällige Alternative zum Einschließen von Methoden innerhalb von #if…#endif-Blöcken, z.B.:

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

Eine bedingte Methode muss eine Methode in einer Klassen- oder Stukturdeklaration sein und darf keinen Rückgabewert besitzen.

Verwenden mehrerer Bezeichner

Wenn eine Methode mehrere Conditional-Attribute besitzt, wird ein Aufruf an die Methode eingeschlossen, wenn mindestens eines der bedingten Symbole definiert ist (anders gesagt, sind die Symbole durch Verwendung des OR-Operators logisch miteinander verknüpft). In diesem Beispiel führt das Vorhandensein von A oder B zu einem Methodenaufruf:

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

End Sub

Um den Effekt der logischen Verknüpfung von Symbolen durch den AND-Operator zu erzielen, können Sie serielle bedingte Methoden definieren. Zum Beispiel wird die zweite Methode unten nur ausgeführt, wenn jeweils A und 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

Verwenden von Conditional mit Attributklassen

Das Conditional-Attribut kann auch auf die Definition einer Attributklasse angewendet werden. In diesem Beispiel wird das benutzerdefinierte Attribut Documentation den Metadaten nur dann Informationen hinzufügen, 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

Aufruferinfoattribute

Mithilfe der Aufrufer-Informationsattribute können Sie Informationen zum Aufrufer einer Methode abrufen. Sie können den Dateipfad des Quellcodes, die Zeilennummer im Quellcode und den Membernamen des Aufrufers abrufen.

Um diese Memberaufruferinformationen zu erhalten, verwenden Sie die Attribute, die auf optionale Parameter angewendet werden. Jeder optionale Parameter gibt einen Standardwert an. In der folgenden Tabelle sind die Aufrufer-Informationsattribute angegeben, die im System.Runtime.CompilerServices-Namespace definiert sind:

Attribut BESCHREIBUNG Typ
CallerFilePathAttribute Vollständiger Pfad der Quelldatei, die den Aufrufer enthält. Dies ist der Pfad zum Zeitpunkt der Kompilierung. String
CallerLineNumberAttribute Zeilennummer in der Quelldatei, in der die Methode aufgerufen wird Integer
CallerMemberNameAttribute Der Methoden- oder Eigenschaftenname des Aufrufers Weitere Informationen finden Sie unter Aufruferinformationen (Visual Basic). String
CallerArgumentExpressionAttribute Ausdruck, der vom Aufrufer für ein Argument verwendet wird. Weitere Informationen finden Sie unter Aufruferinformationen (Visual Basic). String

Weitere Informationen zu den Aufruferinfoattributen finden Sie unter Aufruferinformationen (Visual Basic).

Visual Basic-Attribute

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

attribute Zweck
ComClassAttribute Weist den Compiler an, dass die Klasse als COM-Objekt verfügbar gemacht werden soll.
HideModuleNameAttribute Erlaubt den Zugriff auf Modulmember nur mithilfe des Merkmals, das für das Modul erforderlich ist.
VBFixedStringAttribute Gibt die Größe einer Zeichenfolge mit fester Länge in einer Struktur für die Verwendung mit Dateieingabe- und -ausgabefunktionen an.
VBFixedArrayAttribute Gibt die Größe eines Arrays mit fester Größe in einer Struktur für die Verwendung mit Dateieingabe- und -ausgabefunktionen an.

COMClassAttribute

Verwenden Sie COMClassAttribute, um das Erstellen von COM-Komponenten aus Visual Basic zu vereinfachen. COM-Objekte unterscheiden sich erheblich von .NET Framework-Assemblys, und ohne COMClassAttribute müssen Sie eine Vielzahl von Schritten ausführen, um ein COM-Objekt aus Visual Basic zu generieren. Bei Klassen, die mit COMClassAttribute gekennzeichnet sind, führt der Compiler viele dieser Schritte automatisch aus.

HideModuleNameAttribute

Verwenden Sie HideModuleNameAttribute, um den Zugriff auf Modulmember nur mithilfe des Merkmals zu erlauben, das für das Modul erforderlich ist.

VBFixedStringAttribute

Verwenden Sie VBFixedStringAttribute, um zu erzwingen, dass Visual Basic eine Zeichenfolge mit fester Länge erstellt. Zeichenfolgen weisen standardmäßig eine variable Länge auf, und dieses Attribut ist hilfreich, wenn Sie Zeichenfolgen in Dateien speichern möchten. Dies veranschaulicht der folgende Code:

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 zu deklarieren, deren Größe festgelegt sind. Genau wie Visual Basic-Zeichenfolgen haben Arrays standardmäßig eine variable Länge. Dieses Attribut ist hilfreich, wenn Sie Daten serialisieren oder in Dateien schreiben.

Siehe auch