Explore union types in C# 15 - .NET Blog

Union types have been frequently requested for C#, and they’re here. Starting with .NET 11 Preview 2, C# 15 introduces the union keyword. The union keyword declares that a value is exactly one of a fixed set of types with compiler-enforced exhaustive pattern matching. If you’ve used discriminated unions in F# or similar features in other languages, you’ll feel right at home. But C# unions are designed for a C#-native experience: they’re type unions that compose existing types, integrate with the pattern matching you already know, and work seamlessly with the rest of the language.
Before C# 15, when a method needs to return one of several possible types, you had imperfect options. Using object placed no constraints on what types are actually stored — any type could end up there, and the caller had to write defensive logic for unexpected values. Marker interfaces and abstract base classes were better because they restrict the set of types, but they can’t be “closed” — anyone can implement the interface or derive from the base class, so the compiler can never consider the set complete. And both approaches require the types to share a common ancestor, which doesn’t work when you wanted a union of unrelated types like string and Exception, or int and IEnumerable<T>.
Union types solve these problems. A union declares a closed set of case types — they don’t need to be related to each other, and no other types can be added. The compiler guarantees that switch expressions handling the union are exhaustive, covering every case type without needing a discard _ or default branch. But it’s more than exhaustiveness: unions enable designs that traditional hierarchies can’t express, composing any combination of existing types into a single, compiler-verified contract.
Here’s the simplest declaration:
This single line declares Pet as a new type whose variables can hold a Cat, a Dog, or a Bird. The compiler provides implicit conversions from each case type, so you can assign any of them directly:
The compiler issues an error if you assign an instance of a type that isn’t one of the case types to a Pet object.
The When you use an instance of a union type known to be not null, the compiler knows the complete set of case types, so a switch expression that covers all of them is exhaustive— no discard needed:
The types Dog, Cat, and Bird are all non-nullable types. The pet variable is known to be non-null, it was set in the earlier snippet. Therefore, this switch expression isn’t required to check for null. If any of the types are nullable, for example int? or Bird?, all switch expressions for a Pet instance would need a null arm for exhaustiveness. If you later add a fourth case type to Pet, every switch expression that doesn’t handle it produces a compiler warning. That’s one core value: the compiler catches missing cases at build time, not at runtime.
Patterns apply to the union’s Value property, not the union struct itself. This “unwrapping” is automatic — you write Dog d and the compiler checks Value for you. The two exceptions are var and _, which apply to the union value itself so you can capture or ignore the whole union.
For union types, the null pattern checks whether Value is null. The default value of a union struct has a null Value:
The Pet example illustrates the syntax. Now, let’s explore real world scenarios for union types.
APIs sometimes accept either a single item or a collection. A union with a body lets you add helper members alongside the case types. The OneOrMore<T> declaration includes an AsEnumerable() method directly in the union body — just like you’d add methods to any type declaration:
Notice that the AsEnumerable method must handle the case where Value is null. That’s because the default null-state of the Value property is maybe-null. This rule is necessary to provide proper warnings for arrays of a union type, or instances of the default value for the union struct.
Callers pass whichever form is convenient, and AsEnumerable() normalizes it:
The union declaration is an opinionated shorthand. The compiler generates a struct with a constructor for each case type and a Value property of type object? that holds the underlying value. The constructors enable implicit conversions from any of the case types to the union type. The union instance always stores its contents as a single object? reference and boxes value types. That covers the majority of use cases cleanly.
But several community libraries already provide union-like types with their own storage strategies. Those libraries don’t need to switch to the union syntax to benefit from C# 15. Any class or struct with a [System.Runtime.CompilerServices.Union] attribute is recognized as a union type, as long as it follows the basic union pattern: one or more public single-parameter constructors (defining the case types) and a public Value property.
For performance-sensitive scenarios where case types include value types, libraries can also implement the non-boxing access pattern by adding a HasValue property and TryGetValue methods. This lets the compiler implement pattern matching without boxing.
For full details on creating custom union types and the non-boxing access pattern, see the union types language reference.
Union types give you a type that contains one of a closed set of types. Two proposed features provide related functionality for type hierarchies and enumerations. You can learn about both proposals and how they relate to unions by reading the feature specifications:
Together, these three features give C# a comprehensive exhaustiveness story:
Union types are available now in preview. When evaluating them, keep this broader roadmap in mind. These proposals are active, but aren’t yet committed to a release. Join the discussion as we continue the design and implementation of them.
Union types are available starting with .NET 11 Preview 2. To get started:
IDE support in Visual Studio will be available in the next Visual Studio I