What's new in C# 15: Closed hierarchies

A package is packed, shipped or delivered, and nothing else. C# 15 lets a base class say "this family is complete", so the compiler can check every switch for you.

By Gregor Dzierzon ·

Codey stands at a shipping counter beside three parcels stamped Packed, Shipped and Delivered

What's new in C# 15

  1. The release: .NET 11, LTS and STS
  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

Closed hierarchies

Think about tracking a package you ordered. At any moment it's in one of a few states: packed and waiting for the truck, shipped with a tracking number, or delivered on a certain day. Every state is a kind of shipment, and each one has its own details.

That's a natural fit for inheritance: a base class for "a shipment", and a class for each state that derives from it.

public abstract record class Shipment;
public record class Packed : Shipment;
public record class Shipped(string TrackingNumber) : Shipment;
public record class Delivered(DateOnly On) : Shipment;

The problem: the family is never finished

A Shipment family tree with Packed, Shipped and Delivered under it, and an open gate with a parcel marked ? walking in; Codey says the compiler can't know these are all of them

Now the order page shows a line for each state:

string status = shipment switch
{
    Packed => "Packed and waiting for the truck",
    Shipped shipped => quot;On its way: {shipped.TrackingNumber}",
    Delivered delivered => quot;Delivered on {delivered.On:MMM d}",
    _ => "Unknown",
};

You know there are three states. The compiler doesn't. Any code, anywhere, could write a fourth class that derives from Shipment, so the compiler warns you until you add the _ "anything else" arm. And once that arm is there, it hides your own mistakes: add a Returned state next month, forget to update this switch, and the page quietly shows "Unknown" to a customer whose package is coming back.

If you read the union types post, this is the same problem. Unions solve it for types that have nothing in common. Closed hierarchies solve it for a family that really does share a base class.

The C# 15 answer: closed

Mark the base class closed:

public closed record class Shipment;
public record class Packed : Shipment;
public record class Shipped(string TrackingNumber) : Shipment;
public record class Delivered(DateOnly On) : Shipment;

closed means: every class that derives directly from this one must be in the same project. Code in other projects can use a Shipment, but can't add a new kind of it. So the compiler can see the whole family, and the "anything else" arm goes away:

string status = shipment switch
{
    Packed => "Packed and waiting for the truck",
    Shipped shipped => quot;On its way: {shipped.TrackingNumber}",
    Delivered delivered => quot;Delivered on {delivered.On:MMM d}",
};

Now add that Returned state:

public record class Returned(string Reason) : Shipment;

and the compiler points at every switch that needs it:

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

No customer sees "Unknown". You see the warning first.

The Shipment family stands inside a fenced yard with a gate sign reading closed: new kinds only in this project; a new parcel, Returned, inside the fence has a tag reading Not handled yet, and Codey points at it

Good to know

  • "Same project" is the plain version. Microsoft's wording is the same assembly, the .dll file one project builds.
  • A closed class is automatically abstract. You can't create a plain Shipment, only one of its kinds, which is what you wanted anyway.
  • Only the first level is closed. A class that derives from Shipped can live anywhere, unless you seal Shipped.
  • It works for classes and record classes, not for structs or interfaces.

Union or closed hierarchy?

On the left, a family tree, Shipment with Packed, Shipped and Delivered, labeled One family: closed hierarchy; on the right, three separate cards, Paid, Declined and Pending, in a ring labeled Separate types: union; Codey stands between them

Both give you a switch the compiler can check. The difference is whether the cases belong together:

  • Closed hierarchy: the cases are one family that shares a base class, and maybe shared data or methods. Packed, shipped and delivered are all shipments.
  • Union: the cases are separate types that only meet in one place. A payment result can be a Paid, a Declined or a Pending, and those records are useful on their own.

On one page: the closed hierarchies cheat sheet, to keep or to share.

Sources

Tags: csharp, csharp-15, dotnet, whats-new

Glossary subjects