Add exploration tutorial for unions and closed hierarchies by BillWagner · Pull Request #54627 · dotnet/docs

BillWagner · 2026-07-02T18:45:16Z

Add two exploration tutorials for developers to learn about the union types and closed type hierarchies.

Internal previews

📄 File	🔗 Preview link
docs/csharp/toc.yml	Taken from https://github.com/dotnet/roslyn/wiki/Samples-and-Walkthroughs
docs/csharp/whats-new/tutorials/closed-hierarchies.md	Explore closed hierarchies in C#
docs/csharp/whats-new/tutorials/unions.md	Tutorial: Explore C# union types

Copilot

Pull request overview

This PR adds two new exploratory tutorials under the C# “What’s new” section to teach upcoming preview language features: union types and closed type hierarchies. It also introduces a shared “TelemetryMonitor / SmartHome” sample used by the tutorials via snippet-backed code files.

Changes:

Adds new tutorials: Explore union types and Explore closed hierarchies, and links them from docs/csharp/toc.yml.
Adds a multi-project sample (SmartHome.Core, SmartHome.App, and SmartHome.Extensions) with snippet regions referenced by both tutorials.
Introduces shim support types (UnionAttribute, IUnion, and IsClosedTypeAttribute) to allow the sample to compile when the SDK doesn’t yet ship the required runtime types.

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
docs/csharp/whats-new/tutorials/unions.md	New unions tutorial content, including referenced snippets and expected output.
docs/csharp/whats-new/tutorials/closed-hierarchies.md	New closed-hierarchies tutorial content, including referenced snippets and expected output.
docs/csharp/toc.yml	Adds both new tutorials to the “What’s new → Tutorials” section.
docs/csharp/whats-new/tutorials/snippets/telemetry-monitor/SmartHome.Core/SmartHome.Core.csproj	Adds Core sample project for snippets.
docs/csharp/whats-new/tutorials/snippets/telemetry-monitor/SmartHome.Core/Readings.cs	Adds `Reading` union sample and consumption switch.
docs/csharp/whats-new/tutorials/snippets/telemetry-monitor/SmartHome.Core/Result.cs	Adds “before” result type and `Result<T>` union sample + consumption.
docs/csharp/whats-new/tutorials/snippets/telemetry-monitor/SmartHome.Core/Sample.cs	Adds generic union (`Sample<T>`) and numeric normalization example.
docs/csharp/whats-new/tutorials/snippets/telemetry-monitor/SmartHome.Core/Quantity.cs	Adds custom union-like type example for non-boxing cases.
docs/csharp/whats-new/tutorials/snippets/telemetry-monitor/SmartHome.Core/Sensors.cs	Adds `closed` hierarchy sample and exhaustive switch.
docs/csharp/whats-new/tutorials/snippets/telemetry-monitor/SmartHome.Core/Report.cs	Adds generic `closed` hierarchy sample + fold/count example.
docs/csharp/whats-new/tutorials/snippets/telemetry-monitor/SmartHome.Core/UnionSupport.cs	Adds temporary shim types required for preview language features.
docs/csharp/whats-new/tutorials/snippets/telemetry-monitor/SmartHome.App/SmartHome.App.csproj	Adds console app that exercises the sample scenarios.
docs/csharp/whats-new/tutorials/snippets/telemetry-monitor/SmartHome.App/Program.cs	Demo program used by both tutorials via snippet regions.
docs/csharp/whats-new/tutorials/snippets/telemetry-monitor/SmartHome.Extensions/SmartHome.Extensions.csproj	Adds extensions project used to demonstrate the “escape hatch” case.
docs/csharp/whats-new/tutorials/snippets/telemetry-monitor/SmartHome.Extensions/DoorContact.cs	Adds cross-assembly subtype for the open `Contact` leaf case.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

You might need to add a polyfill

gewarren · 2026-07-06T17:44:45Z

+- The .NET SDK that includes the closed hierarchies preview feature. Download it from the [.NET download site](https://dotnet.microsoft.com/download/dotnet).
+- An editor such as Visual Studio or Visual Studio Code with the C# Dev Kit.


These bullets seem to be lacking an intro statement.

gewarren · 2026-07-06T17:45:56Z

+
+   :::code language="csharp" source="snippets/telemetry-monitor/SmartHome.Core/Sensors.cs" id="SensorExhaustive":::
+
+1. Build the project. In earlier previews, you need to add a polyfill for the `Closed` attribute:


Is "earlier previews" clear to readers?

gewarren · 2026-07-06T17:49:12Z

+
+This tutorial uses preview language features. You need an SDK that supports union types and a language version set to `preview`.
+
+- The .NET 11 SDK that includes the union types preview feature. Download it from the [.NET download site](https://dotnet.microsoft.com/download/dotnet).


Needs intro?

Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com>

adegeo

Here's feedback on closed. I'll follow up with union soon.

adegeo · 2026-07-06T15:27:33Z

@@ -0,0 +1,63 @@
+using SmartHome.Core;


This folder structure is violating the snippet design we have. If it's shared by multiple articles, it should be in a shared folder. For example, move the entire telementry-monitor folder:

‎docs/csharp/whats-new/tutorials/snippets/shared/telemetry-monitor/

adegeo · 2026-07-06T15:30:59Z

+
+This tutorial uses preview language features. You need an SDK that supports closed hierarchies and a language version set to `preview`.
+
+- The .NET SDK that includes the closed hierarchies preview feature. Download it from the [.NET download site](https://dotnet.microsoft.com/download/dotnet).


Should this be .NET 11 Preview X? The user doesn't really know what to download from this statement.

adegeo · 2026-07-06T15:32:11Z

+
+You build a class library, `SmartHome.Core`, that holds the closed hierarchy, a second library, `SmartHome.Extensions`, that extends an open case, and a console app, `SmartHome.App`, that drives them.
+
+1. Create the solution and projects:


Tutorials should be explicit in steps. Here the first step should be to open a terminal and run the following dotnet commands from a folder previously created to store the code of the tutorial.

adegeo · 2026-07-06T15:34:30Z

+1. In each project file, set the language version to `preview`:
+
+   ```xml
+   <PropertyGroup>
+     <LangVersion>preview</LangVersion>
+   </PropertyGroup>
+   ```


They could probably use --langVersion preview on all of the dotnet new commands in the previous step. If so, I would keep this here for reference, as an optional step. Someone may follow the tutorial but hate creating the new projects via terminal and prefer to use an IDE. If so, they'll need to know how to set the preview version.

adegeo · 2026-07-06T15:56:22Z

+---
+# Tutorial: Explore C# closed hierarchies
+
+A *closed hierarchy* restricts the direct subtypes of a base type to the assembly that declares it. Because the compiler knows the full set of subtypes, it can verify that a switch handles every one without a default arm. Closed hierarchies suit domains where the set of cases is stable and you want the compiler to flag every place that needs to change when you add a case.


...it can verify that a switch handles every one without a default arm...

Should it be explicit with switch expression or switch expression pattern?

adegeo · 2026-07-06T15:58:56Z

+
+   :::code language="csharp" source="snippets/telemetry-monitor/SmartHome.Core/Sensors.cs" id="ClosedSensor":::
+
+1. In the same file, add a method that matches every sensor with a switch:


Suggested change

1. In the same file, add a method that matches every sensor with a switch:

1. In the same file, add a method that matches every sensor with a switch expression:

adegeo · 2026-07-06T16:01:04Z

+
+   :::code language="csharp" source="snippets/telemetry-monitor/SmartHome.Core/Sensors.cs" id="SensorExhaustive":::
+
+1. Build the project. In earlier previews, you need to add a polyfill for the `Closed` attribute:


I'm not sure what the reader is supposed to do. Are they supposed to add this? Only the latest preview is supported, so we should code directly for that and not include information that can confuse the reader.

adegeo · 2026-07-06T18:58:21Z

+
+## Run the sample
+
+The console app builds each sensor and report, then prints them through the exhaustive switches:


I think this can be more expressive. It should tell the reader what file to open, to paste in the code, then to run it.

adegeo · 2026-07-06T18:58:55Z

+
+You built the sensor model of a smart-home telemetry monitor and, in the process, worked through closed-hierarchy scenarios. You:
+
+- Declared a `closed` `Sensor` base type and matched its subtypes with an exhaustive switch that needs no default arm.


nit: is this better?

Suggested change

- Declared a `closed` `Sensor` base type and matched its subtypes with an exhaustive switch that needs no default arm.

- Declared a `closed Sensor` base type and matched its subtypes with an exhaustive switch that needs no default arm.

BillWagner added 3 commits July 1, 2026 12:58

First draft of these tutorials

2340b32

Use a better generic sample

d79e6e2

Review articles.

c6dc1e0

Copilot AI review requested due to automatic review settings July 2, 2026 18:45

dotnetrepoman Bot added this to the July 2026 milestone Jul 2, 2026

Copilot started reviewing on behalf of BillWagner July 2, 2026 18:47 View session

Copilot AI reviewed Jul 2, 2026

View reviewed changes

BillWagner and others added 4 commits July 2, 2026 15:42

Potential fix for pull request finding

731394d

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Update sample and code.

aa05421

Fix preview build errors

e61e598

You might need to add a polyfill

Fix snippet name

63b5898

BillWagner marked this pull request as ready for review July 2, 2026 20:16

BillWagner requested a review from a team as a code owner July 2, 2026 20:16

gewarren approved these changes Jul 6, 2026

View reviewed changes

Apply suggestions from code review

7eb77af

Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com>

adegeo reviewed Jul 6, 2026

View reviewed changes

		- The .NET SDK that includes the closed hierarchies preview feature. Download it from the [.NET download site](https://dotnet.microsoft.com/download/dotnet).
		- An editor such as Visual Studio or Visual Studio Code with the C# Dev Kit.


		:::code language="csharp" source="snippets/telemetry-monitor/SmartHome.Core/Sensors.cs" id="SensorExhaustive":::

		1. Build the project. In earlier previews, you need to add a polyfill for the `Closed` attribute:


		This tutorial uses preview language features. You need an SDK that supports union types and a language version set to `preview`.

		- The .NET 11 SDK that includes the union types preview feature. Download it from the [.NET download site](https://dotnet.microsoft.com/download/dotnet).


		You build a class library, `SmartHome.Core`, that holds the closed hierarchy, a second library, `SmartHome.Extensions`, that extends an open case, and a console app, `SmartHome.App`, that drives them.

		1. Create the solution and projects:


		:::code language="csharp" source="snippets/telemetry-monitor/SmartHome.Core/Sensors.cs" id="ClosedSensor":::

		1. In the same file, add a method that matches every sensor with a switch:


		## Run the sample

		The console app builds each sensor and report, then prints them through the exhaustive switches:


		You built the sensor model of a smart-home telemetry monitor and, in the process, worked through closed-hierarchy scenarios. You:

		- Declared a `closed` `Sensor` base type and matched its subtypes with an exhaustive switch that needs no default arm.

	- Declared a `closed` `Sensor` base type and matched its subtypes with an exhaustive switch that needs no default arm.
	- Declared a `closed Sensor` base type and matched its subtypes with an exhaustive switch that needs no default arm.

Uh oh!

Conversation

BillWagner commented Jul 2, 2026 • edited by github-actions Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Internal previews

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adegeo left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

BillWagner commented Jul 2, 2026 •

edited by github-actions Bot

Loading