Attribute (C#)Attributes (C#)

Attribute stellen eine effiziente Methode dar, Metadaten oder deklarative Informationen Code (Assemblys, Typen, Methoden, Eigenschaften usw.) zuzuordnen.Attributes provide a powerful method of associating metadata, or declarative information, with code (assemblies, types, methods, properties, and so forth). Nach dem Zuordnen eines Attributs zu einer Programmentität kann das Attribut zur Laufzeit mit einer Technik namens Reflektion abgefragt werden.After an attribute is associated with a program entity, the attribute can be queried at run time by using a technique called reflection. Weitere Informationen finden Sie unter Reflektion (C#).For more information, see Reflection (C#).

Attribute verfügen über die folgenden Eigenschaften:Attributes have the following properties:

  • Attribute fügen Metadaten zu Ihrem Programm hinzu.Attributes add metadata to your program. Metadaten sind Informationen zu den Typen, die in einem Programm definiert sind.Metadata is information about the types defined in a program. Alle .NET-Assemblys enthalten einen festgelegten Satz von Metadaten, der die Typen und Typmember beschreibt, die in der Assembly definiert sind.All .NET assemblies contain a specified set of metadata that describes the types and type members defined in the assembly. Sie können benutzerdefinierte Attribute hinzufügen, um zusätzliche erforderliche Informationen anzugeben.You can add custom attributes to specify any additional information that is required. Weitere Informationen finden Sie unter Erstellen benutzerdefinierter Attribute (C#).For more information, see, Creating Custom Attributes (C#).

  • Sie können eines oder mehrere Attribute auf ganze Assemblys, Module oder kleinere Programmelemente wie Klassen und Eigenschaften anwenden.You can apply one or more attributes to entire assemblies, modules, or smaller program elements such as classes and properties.

  • Attribute können Argumente auf die gleiche Art wie Methoden und Eigenschaften akzeptieren.Attributes can accept arguments in the same way as methods and properties.

  • Das Programm kann seine eigenen Metadaten oder die Metadaten in anderen Programmen mithilfe der Reflektion untersuchen.Your program can examine its own metadata or the metadata in other programs by using reflection. Weitere Informationen finden Sie unter Accessing Attributes by Using Reflection (C#) (Zugriff auf Attribute mit Reflektion (C#)).For more information, see Accessing Attributes by Using Reflection (C#).

Verwenden von AttributenUsing Attributes

Attribute können in nahezu jeder Deklaration platziert werden, auch wenn ein bestimmtes Attribut die Typen der Deklarationen einschränkt, für die es gültig ist.Attributes can be placed on most any declaration, though a specific attribute might restrict the types of declarations on which it is valid. In C# geben Sie ein Attribut durch Angabe des Namens des Attributs an, eingeschlossen in eckigen Klammern ([]), oberhalb der Deklaration der Entität, auf die es angewendet wird.In C#, you specify an attribute by placing the name of the attribute, enclosed in square brackets ([]), above the declaration of the entity to which it applies.

In diesem Beispiel wird das Attribut SerializableAttribute benutzt, um ein spezifisches Merkmal auf eine Klasse anzuwenden:In this example, the SerializableAttribute attribute is used to apply a specific characteristic to a class:

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

Eine Methode mit dem Attribut DllImportAttribute wird wie folgt deklariert:A method with the attribute DllImportAttribute is declared like this:

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

Mehrere Attribute können in einer Deklaration platziert werden:More than one attribute can be placed on a declaration:

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 für eine bestimmte Entität mehrmals angegeben werden.Some attributes can be specified more than once for a given entity. Ein Beispiel für ein solches mehrfach verwendbares Attribut ist ConditionalAttribute:An example of such a multiuse attribute is ConditionalAttribute:

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

Hinweis

Alle Attributnamen enden laut Konvention mit dem Wort „Attribute“, um sie von anderen Elementen in .NET Framework zu unterscheiden.By convention, all attribute names end with the word "Attribute" to distinguish them from other items in the .NET Framework. Sie müssen das Attributsuffix allerdings nicht angeben, wenn Sie Attribute im Code verwenden.However, you do not need to specify the attribute suffix when using attributes in code. Beispiel: [DllImport] entspricht [DllImportAttribute], aber DllImportAttribute ist der tatsächliche Name des Attributs in .NET Framework.For example, [DllImport] is equivalent to [DllImportAttribute], but DllImportAttribute is the attribute's actual name in the .NET Framework.

AttributparameterAttribute Parameters

Viele Attribute weisen Parameter auf, die positional, unbenannt der benannt sein können.Many attributes have parameters, which can be positional, unnamed, or named. Alle positionalen Parameter müssen in einer bestimmten Reihenfolge angegeben und können nicht ausgelassen werden. Benannte Parameter sind optional und können in beliebiger Reihenfolge angegeben werden.Any positional parameters must be specified in a certain order and cannot be omitted; named parameters are optional and can be specified in any order. Positionale Parameter werden zuerst angegeben.Positional parameters are specified first. Die folgenden drei Attribute sind beispielsweise äquivalent:For example, these three attributes are equivalent:

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

Der erste Parameter, der DLL-Name, ist positional und kommt immer an erster Stelle. Die anderen sind benannt.The first parameter, the DLL name, is positional and always comes first; the others are named. In diesem Fall werden beide benannten Parameter standardmäßig auf „false“ festgelegt und können daher ausgelassen werden.In this case, both named parameters default to false, so they can be omitted. In der Dokumentation des individuellen Attributs finden Sie Informationen zu Standardparameterwerten.Refer to the individual attribute's documentation for information on default parameter values.

AttributzieleAttribute Targets

Das Ziel eines Attributs ist die Entität, auf die das Attribut angewendet wird.The target of an attribute is the entity to which the attribute applies. Ein Attribut kann beispielsweise auf eine Klasse, eine bestimmte Methode oder eine ganze Assembly angewendet werden.For example, an attribute may apply to a class, a particular method, or an entire assembly. Standardmäßig wird ein Attribut auf das voranstehende Element angewendet.By default, an attribute applies to the element that it precedes. Sie können allerdings auch explizit festlegen, dass ein Attribut beispielsweise auf eine Methode, ihren Parameter oder ihren Rückgabewert angewendet wird.But you can also explicitly identify, for example, whether an attribute is applied to a method, or to its parameter, or to its return value.

Verwenden Sie die folgende Syntax, um ein Attributziel explizit zu kennzeichnen:To explicitly identify an attribute target, use the following syntax:

[target : attribute-list]  

Die Liste der möglichen target-Werte wird in der folgenden Tabelle gezeigt:The list of possible target values is shown in the following table.

ZielwertTarget value BetrifftApplies to
assembly Gesamte AssemblyEntire assembly
module Aktuelle AssemblymodulCurrent assembly module
field Feld in einer Klasse oder StrukturField in a class or a struct
event EreignisEvent
method Methode oder get- und set-EigenschaftenaccessorsMethod or get and set property accessors
param Methodenparameter oder set-Parameter des EigenschaftenaccessorsMethod parameters or set property accessor parameters
property EigenschaftProperty
return Rückgabewert einer Methode, Eigenschaftenindexer oder get-EigenschaftenaccessorReturn value of a method, property indexer, or get property accessor
type Struktur, Klasse, Schnittstelle, Enumeration oder DelegatStruct, class, interface, enum, or delegate

Im folgenden Beispiel wird veranschaulicht, wie Attribute auf Assemblys und Module angewendet werden.The following example shows how to apply attributes to assemblies and modules. Weitere Informationen finden Sie unter Allgemeine Attribute (C#).For more information, see Common Attributes (C#).

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

Im folgenden Beispiel wird gezeigt, wie Attribute auf Methoden, Methodenparameter und Methodenrückgabewerte in C# angewendet werden.The following example shows how to apply attributes to methods, method parameters, and method return values in C#.

// 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, auf denen SomeAttr definiert wird, um gültig zu sein, muss das Ziel return angegeben werden, selbst wenn SomeAttr nur für die Rückgabewerte definiert wurde.Regardless of the targets on which SomeAttr is defined to be valid, the return target has to be specified, even if SomeAttr were defined to apply only to return values. Das heißt, der Compiler verwendet keine AttributeUsage-Informationen zum Auflösen von mehrdeutigen Attributzielen.In other words, the compiler will not use AttributeUsage information to resolve ambiguous attribute targets. Weitere Informationen finden Sie unter AttributeUsage (C#).For more information, see AttributeUsage (C#).

Häufige Verwendungsmöglichkeiten für AttributeCommon Uses for Attributes

Die folgende Liste enthält einige häufige Verwendungsmöglichkeiten von Attributen im Code:The following list includes a few of the common uses of attributes in code:

  • Kennzeichnen von Methoden mit dem WebMethod-Attribut in Webdiensten, um anzugeben, dass die Methode über das SOAP-Protokoll aufrufbar sein sollte.Marking methods using the WebMethod attribute in Web services to indicate that the method should be callable over the SOAP protocol. Weitere Informationen finden Sie unter WebMethodAttribute.For more information, see WebMethodAttribute.

  • Beschreiben, wie Methodenparameter bei der Interaktion mit systemeigenem Code gemarshallt werden sollen.Describing how to marshal method parameters when interoperating with native code. Weitere Informationen finden Sie unter MarshalAsAttribute.For more information, see MarshalAsAttribute.

  • Beschreiben der COM-Eigenschaften für Klassen, Methoden und Schnittstellen.Describing the COM properties for classes, methods, and interfaces.

  • Aufrufen von nicht verwaltetem Code mithilfe der Klasse DllImportAttribute.Calling unmanaged code using the DllImportAttribute class.

  • Beschreiben der Assembly im Hinblick auf Titel, Version, Beschreibung oder Marke.Describing your assembly in terms of title, version, description, or trademark.

  • Beschreiben, welche Member einer Klasse zur Verbesserung der Dauerhaftigkeit serialisiert werden müssen.Describing which members of a class to serialize for persistence.

  • Beschreiben der Zuordnung zwischen Klassenmembern und XML-Knoten für die XML-Serialisierung.Describing how to map between class members and XML nodes for XML serialization.

  • Beschreiben der Sicherheitsanforderungen für Methoden.Describing the security requirements for methods.

  • Angeben von Eigenschaften zum Erzwingen der Sicherheit.Specifying characteristics used to enforce security.

  • Steuern der vom JIT-Compiler (Just-In-Time-Compiler) ausgeführten Optimierungen, damit der Code weiterhin problemlos debuggt werden kann.Controlling optimizations by the just-in-time (JIT) compiler so the code remains easy to debug.

  • Abrufen von Informationen zum Aufrufer einer Methode.Obtaining information about the caller to a method.

Weitere Informationen finden Sie unter:For more information, see:

Siehe auchSee Also

C#-ProgrammierhandbuchC# Programming Guide
Reflektion (C#)Reflection (C#)
AttributeAttributes