[Proposal]: Unions

[MadsTorgersen]

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/unions.md
• Discussion: [Discussion]: Unions #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