# What's new in C# 15: Union types

A payment goes through, gets declined, or is still waiting. C# 15's union types finally let you say "it's exactly one of these" in code, and the compiler holds you to it.

By Gregor Dzierzon · Published November 12, 2026

![Codey stands beside a card payment terminal whose screen has three lights, Paid, Declined and Pending, with only Paid lit](https://fsdtrainingmedia.blob.core.windows.net/public/images/2026/11/3d3d33c10dba493ebf64bb85f6dae539.webp)

> **What's new in C# 15**
>
> 1. [The release: .NET 11, LTS and STS](https://www.ask-codey.com/blog/whats-new-in-csharp-15)
> 2. **Union types**
> 3. Labeled `break` and `continue`
> 4. Closed hierarchies
> 5. Collection expression arguments
> 6. Extension indexers
> 7. For library authors: static interface members on older runtimes, and memory safety
>
> [All posts in this series](https://www.ask-codey.com/blog?tag=csharp-15)

## Union types

When you pay for something online, the page that comes back tells you one of three things:

- **Paid:** it went through, and here's the amount you were charged.
- **Declined:** your card was turned down, and here's the reason.
- **Pending:** the bank hasn't answered yet, so there's nothing more to say.

Two things are true about that result. Each kind carries **different information**: an amount, a reason, or nothing at all. And it's **always exactly one of the three.** A payment is never paid and declined at the same time, and it's never some fourth thing nobody planned for.

Now say you're writing the method that charges the card. What type does it return?

### Try 1: one class with every field

![Codey facepalms at a form labeled PaymentResult that says Status: Paid and also Reason: Card declined](https://fsdtrainingmedia.blob.core.windows.net/public/images/2026/11/e038809dbac44832a78a0f85fb3a09c0.webp)

The first idea most of us have is one class that can hold anything a result might need:

```csharp
public class PaymentResult
{
    public string Status { get; set; } = "";   // "Paid", "Declined" or "Pending"
    public decimal? Amount { get; set; }       // only when it's paid
    public string? Reason { get; set; }        // only when it's declined
}
```

It works, until it doesn't. There is nothing that stops a result with `Status = "Paid"` and a `Reason` but missing the `Amount`. Or maybe a typo like `Status = "Payed"`. The comments are helpful, but they don't  actually provide validation. Every piece of code that uses a result has to remember the rules.

### Try 2: a base class with one class per result

![Three cards, Paid, Declined and Pending, hang from a PaymentResult sign while a fourth card with a question mark walks in through an open door; Codey notes the compiler wants an anything else arm](https://fsdtrainingmedia.blob.core.windows.net/public/images/2026/11/d99a262ca10d4f82a82271d0ae7249b2.webp)

A better idea is a class for each kind of result, each with only its own data, sharing a base class:

```csharp
public abstract record class PaymentResult;
public record class Paid(decimal Amount) : PaymentResult;
public record class Declined(string Reason) : PaymentResult;
public record class Pending : PaymentResult;
```

Now a `Declined` can't have an amount. But look at what happens when you check which result you got:

```csharp
string message = result switch
{
    Paid paid => $"Thanks! We charged {paid.Amount:C}.",
    Declined declined => $"Your card was declined: {declined.Reason}",
    Pending => "We're still waiting to hear from the bank.",
    _ => throw new InvalidOperationException("Unknown result"),
};
```

That last line, the `_` "anything else" arm, is there because the compiler insists. Anyone can write another class that derives from `PaymentResult`, so the compiler can't be sure these three are all of them. And if *you* add a fourth result next month, the compiler stays quiet: the new result slips into the "anything else" arm, and you find out when the program throws an error.

What we want is a way to tell the compiler, "a payment result is one of these three types, and that's the whole list."

### The C# 15 answer: a union

That's what C# 15's **[union types](https://devblogs.microsoft.com/dotnet/csharp-15-union-types/)** do:

```csharp
public record class Paid(decimal Amount);
public record class Declined(string Reason);
public record class Pending;

public union PaymentResult(Paid, Declined, Pending);
```

Read the last line out loud as: **"A payment result is a Paid, a Declined or a Pending."** The name comes from math, where the *union* of several groups means everything in any of them, joined together.

Notice that the three records don't share a base class. They don't need anything in common at all. The union is what groups them.

You make one by handing it any of its three types:

```csharp
PaymentResult result = new Paid(49.99m);
```

And when you check which one you got, the "anything else" arm is gone:

```csharp
string message = result switch
{
    Paid paid => $"Thanks! We charged {paid.Amount:C}.",
    Declined declined => $"Your card was declined: {declined.Reason}",
    Pending => "We're still waiting to hear from the bank.",
};
```

The compiler knows the whole list, so three arms are enough.

![Codey points at a box labeled PaymentResult holding one card, Paid, beside the three cards it can hold: Paid, Declined or Pending](https://fsdtrainingmedia.blob.core.windows.net/public/images/2026/11/1d668011062540a6bed7e530e83d0bd8.webp)

### The real win: the compiler finds what you forgot

![Codey inspects a switch with tracks for Paid, Declined and Pending while a new Refunded card has no track and a warning tag says Refunded is not covered](https://fsdtrainingmedia.blob.core.windows.net/public/images/2026/11/9dd6dd3b7dfc49fdb0ba83882711129d.webp)

Next month, your store starts giving refunds. You add a fourth result to the list:

```csharp
public record class Refunded(decimal Amount);

public union PaymentResult(Paid, Declined, Pending, Refunded);
```

The moment you build, the compiler points at every `switch` that doesn't handle it yet:

```text
warning CS8509: The switch expression does not handle all possible values of its input type
(it is not exhaustive). For example, the pattern 'Refunded' is not covered.
```

In a big app, the payment result might be checked in a dozen places: the receipt page, the confirmation email, the order history, the support screen. With a union, you don't have to find them all yourself. **The compiler finds the place you forgot, before your customer does.**

### When to reach for a union

Any time a value is "one of a few different things", each with its own information:

- **Signing in:** signed in (with the user), wrong password (with the attempts left), or locked out (with the time it unlocks).
- **Delivery:** to a street address, or to a pickup locker, each with its own fields.
- **Reading a file:** the contents, or the reason it couldn't be read.

If you've used another language, you may know the idea already. [TypeScript](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#union-types) and [F#](https://learn.microsoft.com/en-us/dotnet/fsharp/language-reference/discriminated-unions) have had union types for years. C# 15 brings the same safety net to C#, built on the records and `switch` expressions you already know.

**On one page:** [the union types cheat sheet](https://www.ask-codey.com/cheat-sheets/csharp-15-union-types-cheat-sheet), to keep or to share.

## Sources

- Microsoft, [Explore union types in C# 15](https://devblogs.microsoft.com/dotnet/csharp-15-union-types/), .NET Blog: union types in depth.
- Microsoft, [What's new in C# 15](https://learn.microsoft.com/en-us/dotnet/csharp/whats-new/csharp-15), Microsoft Learn: every C# 15 feature, with examples.
- Microsoft, [TypeScript handbook: union types](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#union-types) and [F# discriminated unions](https://learn.microsoft.com/en-us/dotnet/fsharp/language-reference/discriminated-unions): the same idea in other languages.

Tags: [csharp](https://www.ask-codey.com/blog?tag=csharp), [csharp-15](https://www.ask-codey.com/blog?tag=csharp-15), [dotnet](https://www.ask-codey.com/blog?tag=dotnet), [whats-new](https://www.ask-codey.com/blog?tag=whats-new)

## Glossary subjects

- [C#](https://www.ask-codey.com/glossary/subjects/c-sharp)

## More posts

- Previous: [What's new in C# 15: .NET 11, LTS and STS](https://www.ask-codey.com/blog/whats-new-in-csharp-15)
- Next: [What's new in C# 15: Labeled break and continue](https://www.ask-codey.com/blog/whats-new-in-csharp-15-labeled-break-and-continue)

Source: https://www.ask-codey.com/blog/whats-new-in-csharp-15-union-types
