[Proposal]: Unions (VS 18.8, .NET 11)

Unions

Note: This consolidates several previous proposals into one. Recent design meeting history for all of them is included below.

• Specification: https://github.com/dotnet/csharplang/blob/main/proposals/csharp-15.0/unions.md
• Discussion: #9663

Summary

A set of interlinked features that combine to provide C# support for union types, including a declaration syntax and several useful behaviors.

public union Pet(Cat, Dog); // Declaration syntax

Pet pet = dog;              // Implicit conversion

_ = pet switch
{
    Cat cat => ...,         // Implicit matching
    Dog dog => ...,
}                           // Exhaustive switching

Design meetings

• https://github.com/dotnet/csharplang/blob/main/meetings/2025/LDM-2025-05-28.md#nominal-type-unions
• https://github.com/dotnet/csharplang/blob/main/meetings/2025/LDM-2025-06-25.md#unions
• https://github.com/dotnet/csharplang/blob/main/meetings/2025/LDM-2025-07-30.md#union-interfaces
• https://github.com/dotnet/csharplang/blob/main/meetings/2025/LDM-2025-07-30.md#custom-unions
• https://github.com/dotnet/csharplang/blob/main/meetings/2025/LDM-2025-07-30.md#non-boxing-access-pattern
• https://github.com/dotnet/csharplang/blob/main/meetings/2025/LDM-2025-08-13.md#unions
• https://github.com/dotnet/csharplang/blob/main/meetings/2025/LDM-2025-08-18.md#unions
• https://github.com/dotnet/csharplang/blob/main/meetings/2025/LDM-2025-08-27.md#union-syntax
• https://github.com/dotnet/csharplang/blob/main/meetings/2025/LDM-2025-09-10.md#unions-overview
• https://github.com/dotnet/csharplang/blob/main/meetings/2025/LDM-2025-09-24.md#union-syntax-thunderdome-part-1
• https://github.com/dotnet/csharplang/blob/main/meetings/2025/LDM-2025-09-29.md
• https://github.com/dotnet/csharplang/blob/main/meetings/2026/LDM-2026-02-04.md#discriminated-unions-patterns
• https://github.com/dotnet/csharplang/blob/main/meetings/2026/LDM-2026-02-11.md#union-patterns-update
• https://github.com/dotnet/csharplang/blob/main/meetings/2026/LDM-2026-05-20.md#unions
• https://github.com/dotnet/csharplang/blob/main/meetings/2026/LDM-2026-06-08.md#unions
• https://github.com/dotnet/csharplang/blob/main/meetings/2026/LDM-2026-08-12.md#union-pattern-matching-targets