Discriminated Unions are a new feature potentially coming to C#, allowing developers to handle data types more safely and flexibly.

C# is constantly evolving, and one of the most exciting features that may be introduced is Discriminated Unions. This concept is already familiar to developers in other languages such as TypeScript and offers better type safety and flexibility in code. But what exactly are Discriminated Unions, and how could they be implemented in C#?

What are Discriminated Unions?

Discriminated Unions are a type of union type in which a shared property is used to distinguish between the different types within a union. A simple example of what this might look like in C# in the future:

// Union Class
union Shape
{
    Circle(int radius);
    Rectangle(int width, int height);    
}

// Usage
Shape shape = new Circle(10);

Discriminated Unions greatly improve type safety by ensuring that all possible cases of a variable must be covered — for example in a switch statement. This prevents unexpected runtime errors and promotes cleaner, safer code.

// Pattern Matching
var area = shape switch
{
    Circle c => Math.PI * c.Radius * c.Radius,
    Rectangle r => r.Width * r.Height,    
};

What are the benefits of Discriminated Unions?

Type safety: Discriminated Unions make code more robust by forcing developers to handle every possible type case.

Efficient handling of multiple types: Instead of using numerous base classes or interfaces, Discriminated Unions can define the various types within a single structure.

More readable code: Rather than relying on unsafe casting or type checks, it is immediately clear which types are allowed.

How could Discriminated Unions be implemented in C#?

C# plans to implement Discriminated Unions in several ways. The TypeUnions proposal describes five different forms:

Union Classes

These are intended for more complex type hierarchies in which classes with different properties but a common discriminator are used.

Union Structs

A similar idea to Union Classes, but with structs. This offers the advantage of better memory management, since structs are stored on the stack rather than the heap.

// Union Structs
union struct Shape
{
    Circle(int radius);
    Rectangle(int width, int height);    
}

Ad Hoc Unions

These allow types to be dynamically combined into a union without explicitly defining them beforehand. This is useful in scenarios where types need to be decided at runtime.

// Ad Hoc Unions
record Circle(int radius);
record Rectangle(int width, int height);   

(Circle or Rectangle) shape = new Circle(10);

Custom Unions

Developers are able to create their own specialised union types tailored to specific needs.

// Custom Unions
[Union]
public struct Shape
{
    public record Circle(int radius);
    public record Rectangle(int width, int height);

    public bool TryGetCircle(out Circle? circle) { ... }
    public bool TryGetRectangle(out Rectangle? rectangle) { ... }
}

Common Unions

This type of union could be defined in the C# standard library to support frequently used patterns such as Option or Result types.

// Common Unions
public union struct Option<T>
{
    Some(T value);
    None = default;
}

public union struct Result<T, TError>
{
    Success(T value);
    Error(TError error);
}

Conclusion

The introduction of Discriminated Unions in C# could fundamentally change the way types are handled. This feature would not only give developers more control and safety when working with different data types, but would also make code more readable and maintainable. It remains to be seen whether and when this long-awaited feature will find its way into C#.

The feature is still under discussion and may change before final implementation. Feel free to join the discussion and give feedback: Type Unions for C# Proposal

Discriminated Unions Are (Maybe) Coming to C#