Runnable C# Docs: Enums

Q: How do I convert an enum to a string in C#?

Call ToString(): OrderStatus.Shipped.ToString() returns "Shipped", and string interpolation does the same. ToString("D") gives the number instead. For a name known at compile time, nameof(OrderStatus.Shipped) is a constant. For user-facing text with spaces or translations, map values to strings yourself (a switch or a dictionary) rather than relying on the member name.

Q: How do I convert a string to an enum in C#?

Use Enum.TryParse (text, true, out var status), which returns false instead of throwing when the text matches no member (the true makes it case-insensitive). Enum.Parse(typeof(OrderStatus), text) throws ArgumentException on bad input. Both also accept numeric strings such as "42", so check the result with Enum.IsDefined when the input comes from users.

Q: How do I convert between an enum and an int in C#?

Cast in either direction: int code = (int)OrderStatus.Paid; and var status = (OrderStatus)2;. The cast from int never fails, even for numbers with no matching member; the result is an enum value that prints as the number. Validate with Enum.IsDefined(typeof(OrderStatus), value) when the number comes from outside.

An enum (enumeration) is a type whose values are a fixed set of named constants: order statuses, days of the week, log levels. Underneath, each name is an integer, but the type system keeps an OrderStatus from being mixed up with a plain int or with another enum.

Declaring and using an enum

List the member names in braces. By default the first is 0 and each next one is one higher:

using System;

enum OrderStatus
{
    Pending,     // 0
    Paid,        // 1
    Shipped,     // 2
    Delivered,   // 3
    Cancelled    // 4
}

class Program
{
    static void Main()
    {
        OrderStatus status = OrderStatus.Paid;
        Console.WriteLine(status);

        status = OrderStatus.Shipped;
        if (status == OrderStatus.Shipped)
            Console.WriteLine("On its way");

        Console.WriteLine(status > OrderStatus.Paid);   // compares the underlying numbers
        Console.WriteLine((int)status);
    }
}

Output:

Paid
On its way
True
2

The enum is a real type: a method that takes an OrderStatus cannot be called with 3 or with a LogLevel by mistake. Enums are value types, so they are never null and compare with == by value.

Explicit values and the underlying type

You can assign numbers yourself. That matters whenever the number leaves your program (a database column, an HTTP status, a file format), because then renumbering breaks stored data:

using System;

enum HttpStatus
{
    Ok = 200,
    Created = 201,
    BadRequest = 400,
    NotFound = 404,
    ServerError = 500
}

enum Priority : byte   // underlying type: byte instead of int
{
    Low = 1,
    Normal = 5,
    High = 10
}

class Program
{
    static void Main()
    {
        int code = (int)HttpStatus.NotFound;       // enum to int
        Console.WriteLine(code);

        var fromDb = (HttpStatus)201;              // int to enum
        Console.WriteLine(fromDb);

        var unknown = (HttpStatus)418;             // no member has 418: still allowed
        Console.WriteLine(unknown);

        Console.WriteLine(sizeof(Priority));
        Console.WriteLine(Enum.GetUnderlyingType(typeof(Priority)).Name);
    }
}

Output:

404
Created
418
1
Byte

Two things to notice. Casting an int to an enum never fails: (HttpStatus)418 is a valid value that just has no name, and it prints as the number. And the underlying type can be any integral type (byte, short, long, ...), which only matters for storage-sensitive code; int is the default and the right choice almost always.

When you add members later, add them at the end or give explicit values. Inserting Refunded between Paid and Shipped silently changes the number of every member after it.

Enum to string

ToString() returns the member name, which is also what Console.WriteLine and string interpolation use. Format strings change the output:

using System;

enum LogLevel { Debug, Info, Warning, Error }

class Program
{
    static string Label(LogLevel level)
    {
        switch (level)
        {
            case LogLevel.Warning: return "Needs attention";
            case LogLevel.Error: return "Action required";
            default: return "For information";
        }
    }

    static void Main()
    {
        var level = LogLevel.Warning;

        Console.WriteLine(level.ToString());         // name
        Console.WriteLine(level.ToString("D"));      // number
        Console.WriteLine(level.ToString("X"));      // hexadecimal, padded
        Console.WriteLine($"[{level}]");
        Console.WriteLine(nameof(LogLevel.Error));   // compile-time constant
        Console.WriteLine(Enum.GetName(typeof(LogLevel), 3));
        Console.WriteLine(Label(level));
    }
}

Output:

Warning
2
00000002
[Warning]
Error
Error
Needs attention

Member names are identifiers, so they cannot contain spaces and they are not translated. For text shown to users, map the values yourself, as Label does, or with a Dictionary<LogLevel, string>. Some codebases put a [Description("Needs attention")] attribute on each member and read it with reflection; the reflection and attributes page shows how that lookup works.

String to enum: Parse and TryParse

Enum.Parse converts a name back into a value and throws ArgumentException if nothing matches. Enum.TryParse returns false instead, which is what you want for any input you do not control:

using System;

enum Size { Small, Medium, Large }

class Program
{
    static void Main()
    {
        var a = (Size)Enum.Parse(typeof(Size), "Large");
        Console.WriteLine(a);

        var b = (Size)Enum.Parse(typeof(Size), "medium", true);   // ignoreCase
        Console.WriteLine(b);

        try
        {
            Enum.Parse(typeof(Size), "Huge");
        }
        catch (ArgumentException)
        {
            Console.WriteLine("Parse threw ArgumentException for Huge");
        }

        foreach (var input in new[] { "small", "XL", "2", "7" })
        {
            Size s;
            bool ok = Enum.TryParse(input, true, out s);
            Console.WriteLine($"{input,-6} parsed={ok,-5} value={s,-6} defined={Enum.IsDefined(typeof(Size), s)}");
        }
    }
}

Output:

Large
Medium
Parse threw ArgumentException for Huge
small  parsed=True  value=Small  defined=True
XL     parsed=False value=Small  defined=True
2      parsed=True  value=Large  defined=True
7      parsed=True  value=7      defined=False

The last two rows are the trap. Both methods accept numeric strings, so "7" parses successfully into a Size that has no name. And a failed TryParse sets the result to 0, which here is the valid-looking Small. When the text comes from a query string, a config file or a form, always check both the return value and Enum.IsDefined:

if (Enum.TryParse(input, true, out Size size) && Enum.IsDefined(typeof(Size), size))
{
    // safe to use size
}

.NET Core 2.0 and later add a generic Enum.Parse<Size>("Large") that needs no cast.

Listing all values

Enum.GetValues returns every member, sorted by numeric value (compared as unsigned, so negative members come last); Enum.GetNames returns their names. This is how you fill a dropdown or validate against every option:

using System;
using System.Linq;

enum Plan { Free = 0, Starter = 9, Pro = 29, Team = 99 }

class Program
{
    static void Main()
    {
        foreach (Plan p in Enum.GetValues(typeof(Plan)))
            Console.WriteLine($"{p,-8} {(int)p,3} EUR/month");

        Console.WriteLine(string.Join(" | ", Enum.GetNames(typeof(Plan))));

        int paidPlans = Enum.GetValues(typeof(Plan)).Cast<Plan>().Count(p => p != Plan.Free);
        Console.WriteLine($"{paidPlans} paid plans");
    }
}

Output:

Free       0 EUR/month
Starter    9 EUR/month
Pro       29 EUR/month
Team      99 EUR/month
Free | Starter | Pro | Team
3 paid plans

Enum.GetValues(typeof(Plan)) returns a plain Array, hence the Cast<Plan>() before LINQ. On .NET 5 and later, Enum.GetValues<Plan>() returns a typed Plan[] directly.

Flags: combining values

Some enums describe a set of options rather than one choice: file permissions, days a shop is open, notification channels. Give each member its own bit (1, 2, 4, 8, ...), add None = 0, and mark the enum [Flags]. Values then combine with |:

using System;

[Flags]
enum Permissions
{
    None = 0,
    Read = 1,
    Write = 2,
    Delete = 4,
    Share = 8,
    Editor = Read | Write            // named combination
}

class Program
{
    static void Main()
    {
        Permissions user = Permissions.Read | Permissions.Share;
        Console.WriteLine(user);

        user |= Permissions.Write;                  // add
        Console.WriteLine(user);
        Console.WriteLine(user.HasFlag(Permissions.Write));
        Console.WriteLine((user & Permissions.Delete) != 0);

        user &= ~Permissions.Share;                 // remove
        Console.WriteLine(user);
        Console.WriteLine((int)user);

        var parsed = (Permissions)Enum.Parse(typeof(Permissions), "Read, Delete");
        Console.WriteLine(parsed);
        Console.WriteLine(parsed.HasFlag(Permissions.None));   // always true
    }
}

Output:

Read, Share
Editor, Share
True
False
Editor
3
Read, Delete
True

What each operator does: | sets bits, & ~X clears them, ^ toggles them, and (value & X) != 0 or value.HasFlag(X) tests them. HasFlag(X) means "all of X's bits are set", so HasFlag(None) is true for every value, and HasFlag(Editor) requires both Read and Write.

Notice the second line: when a named combination covers some of the set bits, ToString uses it, so Read | Write | Share prints as Editor, Share. Keep that in mind before parsing the output of ToString with anything other than Enum.Parse.

The attribute does not change the arithmetic. It changes formatting: without [Flags], Read | Share prints as 9, because no single member has that value. With it, ToString and Parse both work with the comma-separated form. Members must still be powers of two; writing Read, Write, Delete with default numbering (0, 1, 2) makes Write | Delete equal 3, a meaningless value.

Switching on an enum

switch is the natural way to act on an enum. Include a default branch, because an enum variable can hold values with no name:

switch (status)
{
    case OrderStatus.Pending:
    case OrderStatus.Paid:
        return "Preparing";
    case OrderStatus.Shipped:
        return "On the way";
    case OrderStatus.Delivered:
        return "Delivered";
    default:
        return "Unknown";
}

Since C# 8 a switch expression is shorter. Without a _ arm the compiler warns: CS8509 when a named member is missing, and CS8524 when every name is handled but unnamed values such as (OrderStatus)7 are not:

string text = status switch
{
    OrderStatus.Pending or OrderStatus.Paid => "Preparing",   // 'or' pattern: C# 9
    OrderStatus.Shipped => "On the way",
    OrderStatus.Delivered => "Delivered",
    OrderStatus.Cancelled => "Cancelled",
    _ => throw new ArgumentOutOfRangeException(nameof(status)),
};

Default and undefined values

The default value of any enum is 0, whether or not a member has that value. Fields, array elements and a failed TryParse all produce it. Design for this:

Make 0 a meaningful "not set" member (None, Unknown) rather than a real choice. Otherwise an uninitialized field silently reads as the first real option.
Validate numbers from outside with Enum.IsDefined. For [Flags] enums, IsDefined returns false for combinations that have no name (Read | Share), so check the bits instead: (value & ~Permissions.All) == 0 with an All member covering every bit.

Common mistakes

Trusting TryParse alone. Numeric strings parse, and a failed parse yields 0. Add Enum.IsDefined.
Relying on implicit numbering for stored values. Inserting a member renumbers the ones after it. Assign explicit values to any enum that is persisted.
Flags without powers of two. Default numbering (0, 1, 2, 3) overlaps bits. Use 1, 2, 4, 8, or 1 << n.
Showing ToString() to users. Member names are code identifiers. Map values to display text.
No default in a switch. An enum can hold values outside its named members.

Frequently Asked Questions

How do I convert an enum to a string in C#?

Call ToString(): OrderStatus.Shipped.ToString() returns "Shipped", and string interpolation does the same. ToString("D") gives the number instead. For a name known at compile time, nameof(OrderStatus.Shipped) is a constant. For user-facing text with spaces or translations, map values to strings yourself (a switch or a dictionary) rather than relying on the member name.

How do I convert a string to an enum in C#?

Use Enum.TryParse<OrderStatus>(text, true, out var status), which returns false instead of throwing when the text matches no member (the true makes it case-insensitive). Enum.Parse(typeof(OrderStatus), text) throws ArgumentException on bad input. Both also accept numeric strings such as "42", so check the result with Enum.IsDefined when the input comes from users.

How do I convert between an enum and an int in C#?

Cast in either direction: int code = (int)OrderStatus.Paid; and var status = (OrderStatus)2;. The cast from int never fails, even for numbers with no matching member; the result is an enum value that prints as the number. Validate with Enum.IsDefined(typeof(OrderStatus), value) when the number comes from outside.

How do I loop through all values of an enum in C#?

foreach (OrderStatus s in Enum.GetValues(typeof(OrderStatus))) visits every member in order of their numeric values. Since .NET 5 there is a generic version, Enum.GetValues<OrderStatus>(), that needs no cast. Enum.GetNames(typeof(OrderStatus)) returns the names as strings.

What does [Flags] do on a C# enum?

It marks an enum whose values are bits meant to be combined with |, such as Read | Write. Give each member a power of two (1, 2, 4, 8) and a None = 0. The attribute makes ToString() print combinations as "Read, Write" and lets Enum.Parse read that format back. Test a bit with HasFlag or (value & Permissions.Write) != 0.

Related concepts