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.
What are union types?
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:
public record class Cat(string Name);
public record class Dog(string Name);
public record class Bird(string Name);
public union Pet(Cat, Dog, Bird);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:
Pet pet = new Dog("Rex");
Console.WriteLine(pet.Value); // Dog { Name = Rex }
Pet pet2 = new Cat("Whiskers");
Console.WriteLine(pet2.Value); // Cat { Name = Whiskers }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:
string name = pet switch
{
Dog d => d.Name,
Cat c => c.Name,
Bird b => b.Name,
};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:
Pet pet = default;
var description = pet switch
{
Dog d => d.Name,
Cat c => c.Name,
Bird b => b.Name,
null => "no pet",
};
// description is "no pet"The Pet example illustrates the syntax. Now, let’s explore real world scenarios for union types.
OneOrMore<T> — single value or collection
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:
public union OneOrMore<T>(T, IEnumerable<T>)
{
public IEnumerable<T> AsEnumerable() => Value switch
{
T single => [single],
IEnumerable<T> multiple => multiple,
null => []
};
}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:
OneOrMore<string> tags = "dotnet";
OneOrMore<string> moreTags = new[] { "csharp", "unions", "preview" };
foreach (var tag in tags.AsEnumerable())
Console.Write($"[{tag}] ");
// [dotnet]
foreach (var tag in moreTags.AsEnumerable())
Console.Write($"[{tag}] ");
// [csharp] [unions] [preview]Custom unions for existing libraries
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.
Related proposals
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:
- Closed hierarchies: The
closedmodifier on a class prevents derived classes from being declared outside the defining assembly. - Closed enums: A
closedenum prevents creation of values other than the declared members.
Together, these three features give C# a comprehensive exhaustiveness story:
- Union types — exhaustive matching over a closed set of types
- Closed hierarchies — exhaustive matching over a sealed class hierarchy
- Closed enums — exhaustive matching over a fixed set of enum values
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.
Try it yourself
Union types are available starting with .NET 11 Preview 2. To get started:
- Install the .NET 11 Preview SDK.
- Create or update a project targeting
net11.0. - Set
<LangVersion>preview</LangVersion>in your project file.
IDE support in Visual Studio will be available in the next Visual Studio Insiders build. It is included in the latest C# DevKit Insiders build.
Early preview: declare runtime types yourself
In .NET 11 Preview 2, theUnionAttribute and IUnion interface aren’t included in the runtime yet. You must declare them in your project. Later preview versions will include these types in the runtime.
Add the following to your project (or grab RuntimePolyfill.cs from the docs repo):
namespace System.Runtime.CompilerServices
{
[AttributeUsage(AttributeTargets.Class | AttributeTargets.Struct,
AllowMultiple = false)]
public sealed class UnionAttribute : Attribute;
public interface IUnion
{
object? Value { get; }
}
}Once those are in place, you can declare and use union types:
public record class Cat(string Name);
public record class Dog(string Name);
public union Pet(Cat, Dog);
Pet pet = new Cat("Whiskers");
Console.WriteLine(pet switch
{
Cat c => $"Cat: {c.Name}",
Dog d => $"Dog: {d.Name}",
});Some features from the full proposal specification aren’t yet implemented, including union member providers. Those are coming in future previews.
Share your feedback
Union types are in preview, and your feedback directly shapes the final design. Try them in your projects, explore edge cases, and tell us what works and what doesn’t.
To learn more:
Compiler needs to know the exact type to bind the call. Without interface it’s impossible 🙁
I wish CLR supported structural interface implementation.
The null handling in the default switch example highlights why union member providers are so important. If all case types share a common member like Name, we should just be able to write pet.Name directly — no switch needed at all. TypeScript and F# already do this. The current workaround of switching just to get a shared property, plus having to handle a null arm, feels like a lot of ceremony for something the compiler clearly has enough information to solve. Really looking forward to member providers landing in a future preview.
One of the key features of how rust feels better to code in is the syntax level support through the use of std lib union types like Result and Option.
I apologise if there is information about this already and I simply need to dig further but I am both unable to contain my excitement nor dedicate the time to properly look into this at this current time (and had to find out either way!) but is there any reason why this version of C# 15 couldn’t come with atleast those two as built in unions?
There are two primary benifits: A)...
yeah I think I need to re-dig back into this topic, I have always had a hard time processing the difference between a regular union type and a tagged/discriminating union but I figured it out before I guess I need to re-figure it out again, tagged/discriminating coming in a later time: https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/proposals/unions#motivation
Nice! I especially like that it allows to generate custom classes that support switching over!
Some thoughts:
1. Required object? Value
When writing a custom union with type safe TryGetValue methods, I'd like to not expose the general object Value.
It would be nice if this was either not required (as it is unused with the TryGetValue flow) or there was support for explicit implementation on the IUnion interface (I would even throw an error there).
Example for when this would be useful would be if all union types implement an interface that is more useful then a general object type.
I also don't...
The first two questions should be handled by the Union member providers. It’s in the proposal, but didn’t make preview 2. It should make an upcoming preview for C# 15.
As for 3, that’s been requested.
love it, worked a couple of years with f# and going back to c# this was one of the features i really was missing.
Would it be allowed?
If you accept Pet as parameter you never know.
That will only be needed if you assigned default to Pet
How is F# compatiblity?
well…
public class Foo(); public class Bar() : Foo(); public union U(Foo, Bar); var u = new U(new Bar()); u switch { Bar bar => throw new Exception(), Foo foo => foo }; u switch { Foo foo => foo, Bar bar => throw new Exception(), };