Allgemeine Attribute (C#)Common Attributes (C#)

Dieses Thema beschreibt die Attribute, die am häufigsten in C#-Programmen verwendet werden.This topic describes the attributes that are most commonly used in C# programs.

Globale AttributeGlobal Attributes

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.Most attributes are applied to specific language elements such as classes or methods; however, some attributes are global—they apply to an entire assembly or module. Zum Beispiel kann das AssemblyVersionAttribute-Attribut zum Einbetten von Versionsinformationen in eine Assembly verwendet werden. Diese sieht wie folgt aus:For example, the AssemblyVersionAttribute attribute can be used to embed version information into an assembly, like this:

[assembly: AssemblyVersion("1.0.0.0")]  

Globale Attribute befinden sich im Quellcode nach allen obersten using-Direktiven und vor jeden Typ-, Modul- oder Namespacedeklarationen.Global attributes appear in the source code after any top-level using directives and before any type, module, or namespace declarations. Globale Attribute können in mehreren Quelldateien auftreten, jedoch müssen die Dateien in einem einzigen Kompilierungsdurchlauf kompiliert werden.Global attributes can appear in multiple source files, but the files must be compiled in a single compilation pass. In C#-Projekten werden globale Attribute in die Datei „AssemblyInfo.cs“ eingefügt.In C# projects, global attributes are put in the AssemblyInfo.cs file.

Assemblyattribute sind Werte, die Informationen zu einer Assembly bereitstellen.Assembly attributes are values that provide information about an assembly. Sie werden in die folgenden Kategorien eingeteilt:They fall into the following categories:

  • Attribute für AssemblyidentitätenAssembly identity attributes

  • InformationsattributeInformational attributes

  • Attribute für Assemblymanifeste.Assembly manifest attributes

Attribute für AssemblyidentitätenAssembly Identity Attributes

Drei Attribute bestimmen mit einem starken Namen (falls zutreffend) die Identität einer Assembly: „name“, „version“ und „culture“.Three attributes (with a strong name, if applicable) determine the identity of an assembly: name, version, and culture. Diese Attribute bilden den vollständigen Namen der Assembly und sind erforderlich, wenn im Code auf sie verwiesen wird.These attributes form the full name of the assembly and are required when you reference it in code. Mit Attributen können die Version und Kultur einer Assembly festgelegt werden.You can set an assembly's version and culture using attributes. 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.However, the name value is set by the compiler, the Visual Studio IDE in the Assembly Information Dialog Box, or the Assembly Linker (Al.exe) when the assembly is created, based on the file that contains the assembly manifest. Das Attribut AssemblyFlagsAttribute gibt an, ob mehrere Kopien der Assembly parallel bestehen können.The AssemblyFlagsAttribute attribute specifies whether multiple copies of the assembly can coexist.

In der folgenden Tabelle werden die Identitätsattribute aufgeführt.The following table shows the identity attributes.

AttributAttribute ZweckPurpose
AssemblyName Beschreibt vollständig die Identität einer AssemblyFully describes the identity of an assembly.
AssemblyVersionAttribute Gibt die Version einer Assembly anSpecifies the version of an assembly.
AssemblyCultureAttribute Gibt an, welche Kultur die Assembly unterstützt.Specifies which culture the assembly supports.
AssemblyFlagsAttribute Gibt an, ob eine Assembly die parallele Ausführung auf demselben Computer, im selben Prozess oder in derselben Anwendungsdomäne unterstütztSpecifies whether an assembly supports side-by-side execution on the same computer, in the same process, or in the same application domain.

InformationsattributeInformational Attributes

Mit Informationsattributen können Sie zusätzliche Firmen- oder Produktinformationen für eine Assembly bereitstellen.You can use informational attributes to provide additional company or product information for an assembly. Die folgende Tabelle zeigt die Informationsattribute, die im Namespace System.Reflection definiert werden.The following table shows the informational attributes defined in the System.Reflection namespace.

AttributAttribute ZweckPurpose
AssemblyProductAttribute Definiert ein benutzerdefiniertes Attribut, das den Produktnamen für ein Assemblymanifest angibtDefines a custom attribute that specifies a product name for an assembly manifest.
AssemblyTrademarkAttribute Definiert ein benutzerdefiniertes Attribut, das eine Marke für ein Assemblymanifest angibtDefines a custom attribute that specifies a trademark for an assembly manifest.
AssemblyInformationalVersionAttribute Definiert ein benutzerdefiniertes Attribut, das eine Informationsversion für ein Assemblymanifest angibtDefines a custom attribute that specifies an informational version for an assembly manifest.
AssemblyCompanyAttribute Definiert ein benutzerdefiniertes Attribut, das einen Firmennamen für ein Assemblymanifest angibtDefines a custom attribute that specifies a company name for an assembly manifest.
AssemblyCopyrightAttribute Definiert ein benutzerdefiniertes Attribut, das ein Copyright für ein Assemblymanifest angibtDefines a custom attribute that specifies a copyright for an assembly manifest.
AssemblyFileVersionAttribute Weist den Compiler an, eine spezifische Versionsnummer für die Win32-Dateiversionsressource zu verwendenInstructs the compiler to use a specific version number for the Win32 file version resource.
CLSCompliantAttribute Gibt an, ob die Assembly mit der Common Language Specification (CLS) kompatibel istIndicates whether the assembly is compliant with the Common Language Specification (CLS).

Attribute für AssemblymanifesteAssembly Manifest Attributes

Sie können Attribute für Assemblymanifeste verwenden, um Informationen im Assemblymanifest bereitzustellen.You can use assembly manifest attributes to provide information in the assembly manifest. Dies schließt Titel, Beschreibung, Standardalias und Konfiguration ein.This includes title, description, default alias, and configuration. Die folgende Tabelle zeigt die Attribute für Assemblymanifeste, die im Namespace System.Reflection definiert werden.The following table shows the assembly manifest attributes defined in the System.Reflection namespace.

AttributAttribute ZweckPurpose
AssemblyTitleAttribute Definiert ein benutzerdefiniertes Attribut, das einen Assemblytitel für ein Assemblymanifest angibtDefines a custom attribute that specifies an assembly title for an assembly manifest.
AssemblyDescriptionAttribute Definiert ein benutzerdefiniertes Attribut, das eine Assemblybeschreibung für ein Assemblymanifest angibtDefines a custom attribute that specifies an assembly description for an assembly manifest.
AssemblyConfigurationAttribute Definiert ein benutzerdefiniertes Attribut, das eine Assemblykonfiguration (z.B. Retail oder Debug) für ein Assemblymanifest angibtDefines a custom attribute that specifies an assembly configuration (such as retail or debug) for an assembly manifest.
AssemblyDefaultAliasAttribute Definiert einen benutzerfreundlichen Standardalias für ein AssemblymanifestDefines a friendly default alias for an assembly manifest

Obsolete-AttributObsolete Attribute

Das Obsolete-Attribut markiert eine Programmentität als eine, die nicht mehr zur Verwendung empfohlen wird.The Obsolete attribute marks a program entity as one that is no longer recommended for use. 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.Each use of an entity marked obsolete will subsequently generate a warning or an error, depending on how the attribute is configured. Zum Beispiel:For example:

[System.Obsolete("use class B")]  
class A  
{  
    public void Method() { }  
}  
class B  
{  
    [System.Obsolete("use NewMethod", true)]  
    public void OldMethod() { }  
    public void NewMethod() { }  
}  

Dieses Beispiel zeigt, wie das Obsolete-Attribut auf die A-Klasse und die B.OldMethod-Methode angewendet wird.In this example the Obsolete attribute is applied to class A and to method B.OldMethod. 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.Because the second argument of the attribute constructor applied to B.OldMethod is set to true, this method will cause a compiler error, whereas using class A will just produce a warning. Wenn Sie B.NewMethod aufrufen, werden weder Warnungen noch Fehler erzeugt.Calling B.NewMethod, however, produces no warning or error.

Die Zeichenfolge, die als erstes Argument für den Attributkonstruktor bereitgestellt wurde, wird als Teil der Warnung oder des Fehlers angezeigt.The string provided as the first argument to attribute constructor will be displayed as part of the warning or error. Wenn Sie es mit den vorherigen Definitionen verwenden, generiert der folgende Code zwei Warnungen und einen Fehler:For example, when you use it with the previous definitions, the following code generates two warnings and one error:

// 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.Two warnings for class A are generated: one for the declaration of the class reference, and one for the class constructor.

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.The Obsolete attribute can be used without arguments, but including an explanation of why the item is obsolete and what to use instead is recommended.

Das Obsolete-Attribut ist ein Attribut zur einmaligen Nutzung und kann auf jede Entität angewendet werden, die Attribute zulässt.The Obsolete attribute is a single-use attribute and can be applied to any entity that allows attributes. Obsolete ist ein Alias für ObsoleteAttribute.Obsolete is an alias for ObsoleteAttribute.

Conditional-AttributConditional Attribute

Das Conditional-Attribut macht die Ausführung einer Methode abhängig von einem Vorverarbeitungsbezeichner.The Conditional attribute makes the execution of a method dependent on a preprocessing identifier. Das Conditional-Attribut ist ein Alias für ConditionalAttribute und kann auf eine Methode oder Attributklasse angewendet werden.The Conditional attribute is an alias for ConditionalAttribute, and can be applied to a method or an attribute class.

In diesem Beispiel wird Conditional auf eine Methode angewendet, um die Anzeige programmspezifischer Diagnoseinformationen zu aktivieren oder zu deaktivieren.In this example, Conditional is applied to a method to enable or disable the display of program-specific diagnostic information:

#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.If the TRACE_ON identifier is not defined, no trace output will be displayed.

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:The Conditional attribute is often used with the DEBUG identifier to enable trace and logging features for debug builds but not in release builds, like this:

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

Wenn eine als bedingt gekennzeichnete Methode aufgerufen wird, bestimmt das Vorhandensein oder Fehlen des angegebenen Vorverarbeitungssymbols, ob der Aufruf eingeschlossen oder ausgelassen wird.When a method marked as conditional is called, the presence or absence of the specified preprocessing symbol determines whether the call is included or omitted. Wenn das Symbol definiert ist, wird der Aufruf einbezogen; andernfalls wird der Aufruf ausgelassen.If the symbol is defined, the call is included; otherwise, the call is omitted. 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.:Using Conditional is a cleaner, more elegant, and less error-prone alternative to enclosing methods inside #if…#endif blocks, like this:

#if DEBUG  
    void ConditionalMethod()  
    {  
    }  
#endif  

Eine bedingte Methode muss eine Methode in einer Klassen- oder Stukturdeklaration sein und darf keinen Rückgabewert besitzen.A conditional method must be a method in a class or struct declaration and must not have a return value.

Verwenden mehrerer BezeichnerUsing Multiple Identifiers

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).If a method has multiple Conditional attributes, a call to the method is included if at least one of the conditional symbols is defined (in other words, the symbols are logically linked together by using the OR operator). In diesem Beispiel führt das Vorhandensein von A oder B zu einem Methodenaufruf:In this example, the presence of either A or B will result in a method call:

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

Um den Effekt der logischen Verknüpfung von Symbolen durch den AND-Operator zu erzielen, können Sie serielle bedingte Methoden definieren.To achieve the effect of logically linking symbols by using the AND operator, you can define serial conditional methods. Zum Beispiel wird die zweite Methode unten nur ausgeführt, wenn jeweils A und B definiert sind:For example, the second method below will execute only if both A and B are defined:

[Conditional("A")]  
static void DoIfA()  
{  
    DoIfAandB();  
}  

[Conditional("B")]  
static void DoIfAandB()  
{  
    // Code to execute when both A and B are defined...  
}  

Verwenden von Conditional mit AttributklassenUsing Conditional with Attribute Classes

Das Conditional-Attribut kann auch auf die Definition einer Attributklasse angewendet werden.The Conditional attribute can also be applied to an attribute class definition. In diesem Beispiel wird das benutzerdefinierte Attribut Documentation den Metadaten nur dann Informationen hinzufügen, wenn DEBUG definiert ist.In this example, the custom attribute Documentation will only add information to the metadata if DEBUG is defined.

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

AufufrerinfoattributeCaller Info Attributes

Mithilfe der Aufrufer-Informationsattribute können Sie Informationen zum Aufrufer einer Methode abrufen.By using Caller Info attributes, you can obtain information about the caller to a method. Sie können den Dateipfad des Quellcodes, die Zeilennummer im Quellcode und den Membernamen des Aufrufers abrufen.You can obtain the file path of the source code, the line number in the source code, and the member name of the caller.

Um diese Memberaufruferinformationen zu erhalten, verwenden Sie die Attribute, die auf optionale Parameter angewendet werden.To obtain member caller information, you use attributes that are applied to optional parameters. Jeder optionale Parameter gibt einen Standardwert an.Each optional parameter specifies a default value. In der folgenden Tabelle sind die Aufrufer-Informationsattribute angegeben, die im System.Runtime.CompilerServices-Namespace definiert sind:The following table lists the Caller Info attributes that are defined in the System.Runtime.CompilerServices namespace:

AttributAttribute descriptionDescription TypType
CallerFilePathAttribute Vollständiger Pfad der Quelldatei, die den Aufrufer enthält.Full path of the source file that contains the caller. Dies ist der Pfad zum Zeitpunkt der Kompilierung.This is the path at compile time. String
CallerLineNumberAttribute Zeilennummer in der Quelldatei, in der die Methode aufgerufen wirdLine number in the source file from which the method is called. Integer
CallerMemberNameAttribute Der Methoden- oder Eigenschaftenname des AufrufersMethod name or property name of the caller. Weitere Informationen finden Sie unter Caller Information (C#) (Aufruferinformationen (C#)).For more information, see Caller Information (C#). String

Weitere Informationen zu den Aufruferinformationsattributen finden Sie unter Caller Information (C#) (Aufruferinformationen (C#)).For more information about the Caller Info attributes, see Caller Information (C#).

Siehe auchSee Also

System.Reflection
Attribute
C#-ProgrammierhandbuchC# Programming Guide
AttributeAttributes
Reflektion (C#)Reflection (C#)
Accessing Attributes by Using Reflection (C#) (Zugriff auf Attribute mit Reflektion (C#))Accessing Attributes by Using Reflection (C#)