Attribute (C# und Visual Basic)

Attribute stellen eine effiziente Methode dar, um Metadaten oder Deklarationsinformationen mit Code (Assemblys, Typen, Methoden, Eigenschaften usw.) zu verknüpfen.Sobald das Attribut einer Programmentität zugeordnet ist, kann es zur Laufzeit mithilfe eines Verfahrens abgefragt werden, das als Reflektion bezeichnet wird.Weitere Informationen finden Sie unter Reflektion (C# und Visual Basic).

Attribute verfügen über folgende Eigenschaften:

• Attribute fügen dem Programm Metadaten hinzu.Metadaten sind Informationen zu den in Programmen definierten Typen.Alle .NET-Assemblys enthalten einen angegebenen Satz von Metadaten, der die in der Assembly definierten Typen und Typmember beschreibt.Sie können benutzerdefinierte Attribute hinzufügen, um bei Bedarf zusätzliche Informationen anzugeben.Weitere Informationen finden Sie unter Erstellen benutzerdefinierter Attribute (C# und Visual Basic).

• Sie können eines oder mehrere Attribute auf ganze Assemblys oder Module bzw. auf kleinere Programmelemente, wie Klassen und Eigenschaften, anwenden.

• Attribute können auf dieselbe Weise Argumente annehmen wie Methoden und Eigenschaften.

• Das Programm kann die eigenen Metadaten oder die Metadaten in anderen Programmen untersuchen, indem es Reflektion verwendet.Weitere Informationen finden Sie unter Zugreifen auf Attribute mithilfe der Reflektion (C# und Visual Basic).

Verwenden von Attributen

Attribute können in nahezu jede Deklaration eingefügt werden, obwohl spezifische Attribute u. U. nur für bestimmte Deklarationstypen zulässig sind.In C# geben Sie ein Attribut an, indem Sie den Namen des Attributs in eckigen Klammern ([]) über der Deklaration der Entität einfügen, auf die es sich bezieht.In Visual Basic werden Attribute in spitze Klammern (< >) eingeschlossen.Sie müssen unmittelbar auf derselben Zeile vor dem Element stehen, auf das sie angewendet werden.

In diesem Beispiel wird einer Klasse mithilfe des SerializableAttribute-Attributs ein bestimmtes Merkmal zugewiesen:

<System.Serializable()> Public Class SampleClass
    ' Objects of this type can be serialized.
End Class

[System.Serializable]
public class SampleClass
{
    // Objects of this type can be serialized.
}

Eine Methode für das DllImportAttribute-Attribut wird wie folgt deklariert:

Imports System.Runtime.InteropServices


...


<System.Runtime.InteropServices.DllImport("user32.dll")> 
Sub SampleMethod()
End Sub

using System.Runtime.InteropServices;


...


[System.Runtime.InteropServices.DllImport("user32.dll")]
extern static void SampleMethod();

In einer Deklaration können mehrere Attribute platziert werden:

Imports System.Runtime.InteropServices


...


Sub MethodA(<[In](), Out()> ByVal x As Double)
End Sub
Sub MethodB(<Out(), [In]()> ByVal x As Double)
End Sub

using System.Runtime.InteropServices;


...


void MethodA([In][Out] ref double x) { }
void MethodB([Out][In] ref double x) { }
void MethodC([In, Out] ref double x) { }

Einige Attribute können mehrfach für die jeweilige Entität angegeben werden.Beispielsweise kann ConditionalAttribute mehrfach verwendet werden:

<Conditional("DEBUG"), Conditional("TEST1")> 
Sub TraceMethod()
End Sub

[Conditional("DEBUG"), Conditional("TEST1")]
void TraceMethod()
{
    // ...
}

Hinweis
Alle Attributnamen enden vereinbarungsgemäß mit dem Wort "Attribute", um sie von anderen Elementen in .NET Framework zu unterscheiden.Bei Verwendung von Attributen im Code muss das Attributsuffix jedoch nicht angegeben werden.So ist [DllImport] beispielsweise äquivalent zu [DllImportAttribute], der tatsächliche Name des Attributs in .NET Framework lautet jedoch DllImportAttribute.

Attributparameter

Zahlreiche Attribute verfügen über Parameter, die positionell, unbenannt oder benannt sind.Positionelle Parameter müssen in einer bestimmten Reihenfolge angegeben und dürfen nicht weggelassen werden. Benannte Parameter sind optional und können in einer beliebigen Reihenfolge angegeben werden.Positionelle Parameter werden zuerst angegeben.Die folgenden drei Attribute sind beispielsweise äquivalent:

[DllImport("user32.dll")]
[DllImport("user32.dll", SetLastError=false, ExactSpelling=false)]
[DllImport("user32.dll", ExactSpelling=false, SetLastError=false)]

<DllImport("user32.dll")>
<DllImport("user32.dll", SetLastError:=False, ExactSpelling:=False)>
<DllImport("user32.dll", ExactSpelling:=False, SetLastError:=False)>

Der erste Parameter in Form des DLL-Namens ist positionell und muss stets zuerst angegeben werden. Die anderen Parameter sind benannte Parameter.In diesem Fall werden beide benannten Parameter standardmäßig auf false festgelegt, sodass sie weggelassen werden können.Informationen über Standardparameterwerte finden Sie in der Dokumentation des jeweiligen Attributs.

Attributziele

Das Ziel eines Attributs ist die Entität, auf die das Attribut angewendet wird.Ein Attribut kann z. B. auf eine Klasse, eine bestimmte Methode oder eine ganze Assembly angewendet werden.Standardmäßig wird ein Attribut auf das Element angewendet, dem es vorangestellt ist.Sie können jedoch beispielsweise auch explizit festlegen, ob ein Attribut auf eine Methode oder deren Parameter oder deren Rückgabewert angewendet wird.

Um explizit ein Attributziel zu bezeichnen, verwenden Sie die folgende Syntax:

[target : attribute-list]

<target : attribute-list>

Die Liste der möglichen target-Werte wird in der folgenden Tabelle gezeigt.

C#	Visual Basic	Betrifft
assembly	Assembly	Gesamte Assembly
module	Module	Aktuelles Assemblymodul (unterscheidet sich von einem Visual Basic-Modul)
field	Nicht unterstützt	Feld in einer Klasse oder einer Struktur
event	Nicht unterstützt	Ereignis
method	Nicht unterstützt	Methode oder get-Eigenschaftenaccessor und set-Eigenschaftenaccessor
param	Nicht unterstützt	Methodenparameter oder set-Eigenschaftenaccessorparameter
property	Nicht unterstützt	Eigenschaft
return	Nicht unterstützt	Rückgabewert einer Methode, eines Eigenschaftenindexers oder eines get-Eigenschaftenaccessors
type	Nicht unterstützt	Struktur, Klasse, Schnittstelle, Enumeration oder Delegat.

Im folgenden Beispiel wird gezeigt, wie Attribute auf Assemblys und Module angewendet werden.Weitere Informationen finden Sie unter Allgemeine Attribute (C# und Visual Basic).

Imports System.Reflection
<Assembly: AssemblyTitleAttribute("Production assembly 4"), 
Module: CLSCompliant(True)> 

using System;
using System.Reflection;
[assembly: AssemblyTitleAttribute("Production assembly 4")]
[module: CLSCompliant(true)]

Im folgenden Beispiel wird gezeigt, wie Attribute in C# auf Methoden, Methodenparameter und Methodenrückgabewerte angewendet werden.

// default: applies to method
[SomeAttr]
int Method1() { return 0; }

// applies to method
[method: SomeAttr]
int Method2() { return 0; }

// applies to return value
[return: SomeAttr]
int Method3() { return 0; }

Hinweis

Unabhängig von den Zielen, für die SomeAttr als gültig definiert wurde, muss das return-Ziel auch dann angegeben werden, wenn SomeAttr so definiert wurde, dass es nur auf Rückgabewerte angewendet wird.Dies bedeutet auch, dass der Compiler keine AttributeUsage-Informationen verwendet, um mehrdeutige Attributziele aufzulösen.Weitere Informationen finden Sie unter AttributeUsage (C# und Visual Basic).

Allgemeine Verwendungszwecke für Attribute

In der folgenden Liste sind einige der allgemeinen Situationen für die Verwendung von Attributen im Code aufgeführt:

• Kennzeichnen von Methoden in Webdiensten mit dem WebMethod-Attribut, um darauf hinzuweisen, dass die Methode Aufrufe über das SOAP-Protokoll unterstützt.Weitere Informationen finden Sie unter WebMethodAttribute.

• Beschreiben des Marshallingverfahrens für Methodenparameter, wenn systemeigener Code kombiniert wird.Weitere Informationen finden Sie unter MarshalAsAttribute.

• Beschreiben der COM-Eigenschaften von Klassen, Methoden und Schnittstellen.

• Aufrufen von nicht verwaltetem Code mit der DllImportAttribute-Klasse.

• Beschreiben der Assembly im Hinblick auf Titel, Version, Inhalt oder Marke.

• Festlegen, welche Member einer Klasse aus Gründen der Dauerhaftigkeit serialisiert werden müssen.

• Beschreiben, auf welche Weise Klassenmember und XML-Knoten einander für die XML-Serialisierung zugeordnet werden.

• Beschreiben der Sicherheitsanforderungen für Methoden.

• Angeben der Features, die zur Einhaltung der Sicherheit erforderlich sind.

• Steuern der vom Just-In-Time (JIT)-Compiler ausgeführten Optimierungen, damit der Code weiterhin problemlos gedebuggt werden kann.

• Abrufen von Informationen über den Aufrufer zu einer Methode.

Verwandte Abschnitte

Weitere Informationen finden Sie unter:

• Erstellen benutzerdefinierter Attribute (C# und Visual Basic)

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

• Gewusst wie: Erstellen einer Union in C/C++ mit Attributen (C# und Visual Basic)

• Allgemeine Attribute (C# und Visual Basic)

• Aufruferinformationen (C# und Visual Basic)

Siehe auch

Referenz

Reflektion (C# und Visual Basic)

Konzepte

C#-Programmierhandbuch

Weitere Ressourcen

Visual Basic-Programmierhandbuch

Erweitern von Metadaten mithilfe von Attributen