C#-opsommingen

Een opsommingstype (of enum) definieert een set benoemde constanten die worden ondersteund door een geheel getal. Gebruik opsommingen wanneer een waarde een van een vaste set opties moet zijn, zoals dagen van de week, HTTP-statuscodes, logboekniveaus of routebeschrijvingen. Enums maken uw code beter leesbaar en minder foutgevoelig dan onbewerkte gehele getallen, omdat de compiler de benoemde waarden afdwingt.

Een opsomming declareren

Definieer een opsomming met het enum trefwoord gevolgd door de typenaam en de bijbehorende leden:

enum Season
{
    Spring,
    Summer,
    Autumn,
    Winter
}

Standaard is het onderliggende type int, en beginnen de waarden bij 0 en nemen ze met één toe. Season.Spring is 0, Season.Summer is 1, enzovoort.

Een onderliggend type en expliciete waarden opgeven

U kunt een ander integraal type kiezen en expliciete waarden toewijzen om de numerieke weergave te beheren:

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

Gebruik expliciete waarden wanneer de getallen externe betekenis hebben, zoals HTTP-statuscodes of protocol-id's. Het onderliggende type kan elk integraal type zijn, behalve char. Gebruik byte, short, , ushort, int, , uint, of longulong.

Gebruik opsommingen in de switchexpressies

Opsommingen werken natuurlijk met switch expressies en patroonkoppeling. De compiler waarschuwt u als u niet alle leden afhandelt, waardoor fouten worden voorkomen wanneer u later een nieuwe waarde toevoegt:

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));

Met het verwijderingspatroon (_) wordt een waarde verwerkt die niet expliciet wordt vermeld. Omdat het onderliggende type van een enum een geheel getal is, kan een variabele een waarde bevatten die niet overeenkomt met een benoemd lid. Bijvoorbeeld, (Season)99 is geldig tijdens de uitvoering. Het verwijderingspatroon zorgt ervoor dat de switchexpressie deze onverwachte waarden veilig verwerkt. Patroonkoppeling is een C#-functie waarmee een waarde wordt getest op basis van een shape of voorwaarde. In dit voorbeeld controleert elke case of de enum overeenkomt met een specifiek lid. Schakelexpressies zijn een van de verschillende patroonkoppelingsformulieren. Zie Patroonkoppeling voor meer informatie over patroonkoppeling.

Bitvlagken

Wanneer een enum een combinatie van keuzes vertegenwoordigt in plaats van één keuze, definieert u elk lid als een macht van twee en past u het FlagsAttributevolgende toe:

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

Waarden combineren met behulp van de | operator en testen op afzonderlijke vlaggen met behulp van 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

Het [Flags] kenmerk is ook van invloed op ToString(). Er worden gecombineerde waarden weergegeven als door komma's gescheiden namen (zoals Read, Write) in plaats van een onbewerkt getal. Zie System.FlagsAttribute voor meer informatie.

Converteren tussen opsommingen en gehele getallen

Expliciete cast-expressies converteren tussen een enum en het bijbehorende onderliggende gehele getaltype. Een expliciete cast gebruikt de (Type)value syntaxisnotatie om de compiler aan te geven dat u de conversie wilt uitvoeren.

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

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

Houd er rekening mee dat het casten van een geheel getal naar een enum niet controleert of de waarde overeenkomt met een gedefinieerd lid. Gebruik Enum.IsDefined dit om de geldigheid te controleren wanneer u numerieke invoer van externe bronnen accepteert.

Tekenreeksen parseren en waarden herhalen

De Enum basisklasse biedt methoden voor het parseren van tekenreeksen en het herhalen van alle gedefinieerde waarden:

// 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

Gebruik Enum.TryParse<TEnum>(String, Boolean, TEnum) in plaats van Enum.Parse<TEnum>(String) wanneer de invoer mogelijk ongeldig is. Het retourneert false in plaats van een uitzondering te genereren.

Zie ook

• Typesysteemoverzicht
• Opsommingstypen (C#-verwijzing)
• Patroonherkenning
• Richtlijnen voor enum-ontwerp