{"id":59829,"date":"2026-04-02T10:05:00","date_gmt":"2026-04-02T17:05:00","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/dotnet\/?p=59829"},"modified":"2026-04-02T11:09:10","modified_gmt":"2026-04-02T18:09:10","slug":"csharp-15-union-types","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/dotnet\/csharp-15-union-types\/","title":{"rendered":"Explore union types in C# 15"},"content":{"rendered":"

Union types have been frequently requested for C#, and they’re here. Starting with .NET 11 Preview 2, C# 15 introduces the union<\/code> keyword. The union<\/code> 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.<\/p>\n

What are union types?<\/h2>\n

Before C# 15, when a method needs to return one of several possible types, you had imperfect options. Using object<\/code> placed no constraints on what types are actually stored \u2014 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” \u2014 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<\/code> and Exception<\/code>, or int<\/code> and IEnumerable<T><\/code>.<\/p>\n

Union types solve these problems. A union declares a closed set of case types \u2014 they don’t need to be related to each other, and no other types can be added. The compiler guarantees that switch<\/code> expressions handling the union are exhaustive, covering every case type without needing a discard _<\/code> 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.<\/p>\n

Here’s the simplest declaration:<\/p>\n

public record class Cat(string Name);\r\npublic record class Dog(string Name);\r\npublic record class Bird(string Name);\r\n\r\npublic union Pet(Cat, Dog, Bird);<\/code><\/pre>\n
This single line declares Pet<\/code> as a new type whose variables can hold a Cat<\/code>, a Dog<\/code>, or a Bird<\/code>. The compiler provides implicit conversions from each case type, so you can assign any of them directly:<\/p>\n
Pet pet = new Dog(\"Rex\");\r\nConsole.WriteLine(pet.Value); \/\/ Dog { Name = Rex }\r\n\r\nPet pet2 = new Cat(\"Whiskers\");\r\nConsole.WriteLine(pet2.Value); \/\/ Cat { Name = Whiskers }<\/code><\/pre>\n
The compiler issues an error if you assign an instance of a type that isn’t one of the case types to a Pet<\/code> object.<\/p>\n
The When you use an instance of a union<\/code> type known to be not null, the compiler knows the complete set of case types, so a switch<\/code> expression that covers all of them is exhaustive\u2014 no discard needed:<\/p>\n
string name = pet switch\r\n{\r\n    Dog d => d.Name,\r\n    Cat c => c.Name,\r\n    Bird b => b.Name,\r\n};<\/code><\/pre>\n
The types Dog<\/code>, Cat<\/code>, and Bird<\/code> are all non-nullable types. The pet<\/code> variable is known to be non-null, it was set in the earlier snippet. Therefore, this switch<\/code> expression isn’t required to check for null<\/code>. If any of the types are nullable, for example int?<\/code> or Bird?<\/code>, all switch<\/code> expressions for a Pet<\/code> instance would need a null<\/code> arm for exhaustiveness. If you later add a fourth case type to Pet<\/code>, every switch<\/code> 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.<\/p>\n
Patterns apply to the union’s Value<\/code> property, not the union struct itself. This “unwrapping” is automatic \u2014 you write Dog d<\/code> and the compiler checks Value<\/code> for you. The two exceptions are var<\/code> and _<\/code>, which apply to the union value itself so you can capture or ignore the whole union.<\/p>\n
For union<\/code> types, the null<\/code> pattern checks whether Value<\/code> is null. The default<\/code> value of a union struct has a null Value<\/code>:<\/p>\n
Pet pet = default;\r\n\r\nvar description = pet switch\r\n{\r\n    Dog d => d.Name,\r\n    Cat c => c.Name,\r\n    Bird b => b.Name,\r\n    null => \"no pet\",\r\n};\r\n\/\/ description is \"no pet\"<\/code><\/pre>\n
The Pet<\/code> example illustrates the syntax. Now, let’s explore real world scenarios for union types.<\/p>\n
OneOrMore<T> \u2014 single value or collection<\/h3>\n
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><\/code> declaration includes an AsEnumerable()<\/code> method directly in the union body \u2014 just like you’d add methods to any type declaration:<\/p>\n
public union OneOrMore<T>(T, IEnumerable<T>)\r\n{\r\n    public IEnumerable<T> AsEnumerable() => Value switch\r\n    {\r\n        T single => [single],\r\n        IEnumerable<T> multiple => multiple,\r\n        null => []\r\n    };\r\n}<\/code><\/pre>\n
Notice that the AsEnumerable<\/code> method must handle the case where Value<\/code> is null<\/code>. That’s because the default null-state of the Value<\/code> property is maybe-null<\/em>. This rule is necessary to provide proper warnings for arrays of a union type, or instances of the default value for the union<\/code> struct.<\/p>\n
Callers pass whichever form is convenient, and AsEnumerable()<\/code> normalizes it:<\/p>\n
OneOrMore<string> tags = \"dotnet\";\r\nOneOrMore<string> moreTags = new[] { \"csharp\", \"unions\", \"preview\" };\r\n\r\nforeach (var tag in tags.AsEnumerable())\r\n    Console.Write($\"[{tag}] \");\r\n\/\/ [dotnet]\r\n\r\nforeach (var tag in moreTags.AsEnumerable())\r\n    Console.Write($\"[{tag}] \");\r\n\/\/ [csharp] [unions] [preview]<\/code><\/pre>\n
Custom unions for existing libraries<\/h2>\n
The union<\/code> declaration is an opinionated shorthand. The compiler generates a struct with a constructor for each case type and a Value<\/code> property of type object?<\/code> 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?<\/code> reference and boxes value types. That covers the majority of use cases cleanly.<\/p>\n
But several community libraries already provide union-like types with their own storage strategies. Those libraries don’t need to switch to the union<\/code> syntax to benefit from C# 15. Any class or struct with a [System.Runtime.CompilerServices.Union]<\/code> 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<\/code> property.<\/p>\n
For performance-sensitive scenarios where case types include value types, libraries can also implement the non-boxing access pattern by adding a HasValue<\/code> property and TryGetValue<\/code> methods. This lets the compiler implement pattern matching without boxing.<\/p>\n
For full details on creating custom union types and the non-boxing access pattern, see the union types language reference<\/a>.<\/p>\n
Related proposals<\/h2>\n
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:<\/p>\n