C#-Enumerationen

Ein Enumerationstyp (oder Enum) definiert einen Satz benannter Konstanten, die auf einem ganzzahligen Wert basieren. Verwenden Sie Enums, wenn für einen Wert eine Auswahl aus einer festen Gruppe von Optionen erforderlich ist, z. B. Wochentage, HTTP-Statuscodes, Protokollebene oder Richtungen. Enumerationen machen ihren Code besser lesbar und weniger fehleranfällig als unformatierte ganzzahlige Konstanten, da der Compiler die benannten Werte erzwingt.

Deklariere ein Enum

Definieren Sie ein Enum mit dem Schlüsselwort enum, gefolgt vom Typnamen und seinen Mitgliedern:

enum Season
{
    Spring,
    Summer,
    Autumn,
    Winter
}

Standardmäßig lautet intder zugrunde liegende Typ , und die Werte beginnen bei 0 und erhöhen sie um eins. Season.Spring ist 0, Season.Summer ist 1usw.

Angeben eines zugrunde liegenden Typs und expliziter Werte

Sie können einen anderen integralen Typ auswählen und explizite Werte zuweisen, um die numerische Darstellung zu steuern:

enum HttpStatus : ushort
{
    OK = 200,
    NotFound = 404,
    InternalServerError = 500
}

Verwenden Sie explizite Werte, wenn die Zahlen eine externe Bedeutung haben, z. B. HTTP-Statuscodes oder Protokollbezeichner. Der zugrunde liegende Typ kann ein beliebiger integraler Typ sein, außer char. Verwenden Sie byte, , short, ushort, int, uint, oder longulong.

Enumerationen in Switchausdrücken verwenden

Enums funktionieren natürlich mit switch Ausdrücken und Mustervergleichen. Der Compiler warnt Sie, wenn Sie nicht alle Member behandeln, wodurch Fehler verhindert werden, wenn Sie später einen neuen Wert hinzufügen:

static string DescribeSeason(Season season) => season switch
{
    Season.Spring => "Flowers bloom and temperatures rise.",
    Season.Summer => "Long days and warm weather.",
    Season.Autumn => "Leaves change color and fall.",
    Season.Winter => "Short days and cold temperatures.",
    _ => throw new ArgumentOutOfRangeException(nameof(season))
};

var today = Season.Autumn;
Console.WriteLine(DescribeSeason(today));

Das Verwurfsmuster (_) behandelt jeden Wert, der nicht explizit aufgeführt ist. Da der zugrunde liegende Typ eines Enums ein Integer ist, kann eine Variable einen Wert enthalten, der keinem benannten Element entspricht. Beispielsweise ist (Season)99 zur Laufzeit gültig. Das Discard-Muster stellt sicher, dass der Switch-Ausdruck diese unerwarteten Werte sicher behandelt. Der Musterabgleich ist ein C#-Feature, das einen Wert anhand einer Form oder Bedingung testet. In diesem Beispiel überprüft jeder case, ob das Enum mit einem bestimmten Element übereinstimmt. Switch-Ausdrücke sind eine von mehreren Musterabgleichsformen. Weitere Informationen zum Musterabgleich finden Sie unter Musterabgleich.

Bitkennzeichnungen

Wenn eine Aufzählung eine Kombination von Auswahlmöglichkeiten und nicht nur eine einzelne Auswahlmöglichkeit darstellt, definieren Sie jedes Mitglied als eine Zweierpotenz und wenden Sie FlagsAttribute an:

[Flags]
enum FileAccess
{
    None = 0,
    Read = 1,
    Write = 2,
    Execute = 4,
    ReadWrite = Read | Write,
    All = Read | Write | Execute
}

Kombinieren Sie Werte mithilfe des | Operators und testen Sie einzelne Flags mithilfe von HasFlag.

var permissions = FileAccess.Read | FileAccess.Write;

Console.WriteLine(permissions);                          // ReadWrite
Console.WriteLine(permissions.HasFlag(FileAccess.Read)); // True
Console.WriteLine(permissions.HasFlag(FileAccess.Execute)); // False

Das [Flags] Attribut wirkt sich auch auf ToString(). Es zeigt kombinierte Werte als durch Kommas getrennte Namen (wie Read, Write) anstelle einer Rohzahl an. Weitere Informationen finden Sie unter System.FlagsAttribute.

Konvertieren zwischen Enums und Ganzzahlen

Explizite Cast-Ausdrücke konvertieren zwischen einem Enum und seinem zugrunde liegenden Integer-Typ. Ein expliziter Cast verwendet die (Type)value-Syntax, um dem Compiler mitzuteilen, dass Sie die Konvertierung beabsichtigen:

var status = HttpStatus.NotFound;
ushort code = (ushort)status;
Console.WriteLine($"Status: {status} ({code})"); // Status: NotFound (404)

var fromCode = (HttpStatus)200;
Console.WriteLine(fromCode); // OK

Beachten Sie, dass bei der Umwandlung einer Ganzzahl in eine Aufzählung nicht überprüft wird, ob der Wert einem definierten Mitglied entspricht. Verwenden Sie Enum.IsDefined, um die Gültigkeit zu überprüfen, wenn Sie numerische Eingaben aus externen Quellen akzeptieren.

Parsen von Zeichenketten und Iterieren von Werten

Die Enum Basisklasse stellt Methoden zum Analysieren von Zeichenfolgen und Durchlaufen aller definierten Werte bereit:

// Parse a string to an enum value:
var parsed = Enum.Parse<Season>("Winter");
Console.WriteLine(parsed); // Winter

// Try to parse safely. It returns false only when the input can't be parsed. Call Enum.IsDefined to validate named members:
if (Enum.TryParse<Season>("Monsoon", out var unknown))
{
    Console.WriteLine(unknown);
}
else
{
    Console.WriteLine("'Monsoon' is not a valid Season"); // 'Monsoon' is not a valid Season
}

// Iterate over all values in an enum:
foreach (var season in Enum.GetValues<Season>())
{
    Console.WriteLine($"{season} = {(int)season}");
}
// Spring = 0
// Summer = 1
// Autumn = 2
// Winter = 3

Verwenden Sie Enum.TryParse<TEnum>(String, Boolean, TEnum) anstelle von Enum.Parse<TEnum>(String), wenn die Eingabe möglicherweise ungültig ist. Es gibt false zurück, anstatt eine Ausnahme auszulösen.

Siehe auch

• Übersicht über das Typsystem
• Enumerationstypen (C#-Referenz)
• Mustervergleich
• Richtlinien für Enum-Design