{"id":3777,"date":"2026-04-02T17:50:18","date_gmt":"2026-04-02T17:50:18","guid":{"rendered":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/2026\/04\/02\/explore-union-types-in-c-15\/"},"modified":"2026-04-02T17:50:18","modified_gmt":"2026-04-02T17:50:18","slug":"explore-union-types-in-c-15","status":"publish","type":"post","link":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/2026\/04\/02\/explore-union-types-in-c-15\/","title":{"rendered":"Explore union types in C# 15"},"content":{"rendered":"

Union types have been frequently requested for C#, and they\u2019re 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\u2019ve used discriminated unions in F# or similar features in other languages, you\u2019ll feel right at home. But C# unions are designed for a C#-native experience: they\u2019re 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\u2019t be \u201cclosed\u201d \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\u2019t 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\u2019t 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\u2019s more than exhaustiveness: unions enable designs that traditional hierarchies can\u2019t express, composing any combination of existing types into a single, compiler-verified contract.<\/p>\n

Here\u2019s the simplest declaration:<\/p>\n

public record class Cat(string Name);\npublic record class Dog(string Name);\npublic record class Bird(string Name);\n\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\");\nConsole.WriteLine(pet.Value); \/\/ Dog { Name = Rex }\n\nPet pet2 = new Cat(\"Whiskers\");\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\u2019t one of the case types to a Pet<\/code> object.<\/p>\n
When you use an instance of a union<\/code> type, 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\n{\n    Dog d => d.Name,\n    Cat c => c.Name,\n    Bird b => b.Name,\n};<\/code><\/pre>\n
The types Dog<\/code>, Cat<\/code>, and Bird<\/code> are all non-nullable types, the switch<\/code> expression isn\u2019t required to check for null<\/code>. If any of the types are nullable, for example int?<\/code> or Bird?<\/code>, the switch<\/code> expression 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\u2019t handle it produces a compiler warning. That\u2019s one core value: the compiler catches missing cases at build time, not at runtime.<\/p>\n
Patterns apply to the union\u2019s Value<\/code> property, not the union struct itself. This \u201cunwrapping\u201d 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;\n\nvar description = pet switch\n{\n    Dog d => d.Name,\n    Cat c => c.Name,\n    Bird b => b.Name,\n    null => \"no pet\",\n};\n\/\/ description is \"no pet\"<\/code><\/pre>\n
The Pet<\/code> example illustrates the syntax. Now, let\u2019s 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\u2019d add methods to any type declaration:<\/p>\n
public union OneOrMore<T>(T, IEnumerable<T>)\n{\n    public IEnumerable<T> AsEnumerable() => Value switch\n    {\n        T single => [single],\n        IEnumerable<T> multiple => multiple,\n        null => []\n    };\n}<\/code><\/pre>\n
Notice that the AsEnumerable<\/code> method must handle the case where Value<\/code> is null<\/code>. That\u2019s 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\";\nOneOrMore<string> moreTags = new[] { \"csharp\", \"unions\", \"preview\" };\n\nforeach (var tag in tags.AsEnumerable())\n    Console.Write($\"[{tag}] \");\n\/\/ [dotnet]\n\nforeach (var tag in moreTags.AsEnumerable())\n    Console.Write($\"[{tag}] \");\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\u2019t 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