{"id":5049,"date":"2026-09-10T17:35:28","date_gmt":"2026-09-10T17:35:28","guid":{"rendered":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/2026\/09\/10\/use-c-unions-and-closed-hierarchies-in-asp-net-core\/"},"modified":"2026-09-10T17:35:28","modified_gmt":"2026-09-10T17:35:28","slug":"use-c-unions-and-closed-hierarchies-in-asp-net-core","status":"publish","type":"post","link":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/2026\/09\/10\/use-c-unions-and-closed-hierarchies-in-asp-net-core\/","title":{"rendered":"Use C# unions and closed hierarchies in ASP.NET Core"},"content":{"rendered":"

Sometimes an API contract says that a value can have more than one JSON type. Kubernetes has a practical example: maxUnavailable<\/code><\/a> can be an absolute number, such as 2<\/code>, or a percentage, such as \"25%\"<\/code>. Imagine an ASP.NET Core endpoint that exposes the same contract:<\/p>\n

public union IntOrString(int, string);\n\napp.MapGet(\"\/deployments\/{name}\/max-unavailable\", IntOrString (string name) => Deployments.GetMaxUnavailable(name));<\/code><\/pre>\n
Depending on the deployment, the response is either 2<\/code> or \"25%\"<\/code>.<\/p>\n
IntOrString<\/code> uses the native union<\/code> declaration introduced in C# 15 and .NET 11. A union is one named type that represents a value from a fixed list of case types. This union accepts an int<\/code> or a string<\/code>, but not a bool<\/code>, a DateTime<\/code>, or anything else. Union cases aren\u2019t limited to classes in one hierarchy; they can include primitives, classes, interfaces, and nullable types.<\/p>\n
Each case converts to the union directly without any casting:<\/p>\n
IntOrString absolute = 2;\nIntOrString percentage = \"25%\";<\/code><\/pre>\n
It is also quite natural to use a switch<\/code> statement or expression to handle the active case. Normal C# pattern matching works:<\/p>\n
static string Describe(IntOrString value) => value switch\n{\n    int count => $\"{count} pods\",\n    string percentage => percentage,\n};<\/code><\/pre>\n
Notice that there is no fallback arm such as _ => ...<\/code>. The compiler knows every permitted case, so it checks that the switch<\/code> handles them all. If another case is added to IntOrString<\/code>, existing switches that don\u2019t handle it produce a warning.<\/p>\n
For example, suppose a string<\/code> case is added to a union that previously contained only bool<\/code> and decimal<\/code>, but its formatter isn\u2019t updated:<\/p>\n
public union SettingValue(bool, decimal, string);\n\nstatic string Describe(SettingValue value) => value switch\n{\n    bool enabled => enabled ? \"enabled\" : \"disabled\",\n    decimal number => number.ToString(),\n    \/\/ missing string case\n};<\/code><\/pre>\n
The compiler identifies the missing case:<\/p>\n
warning CS8509: The switch expression does not handle all possible values of its input type (it is not exhaustive). For example, the pattern 'string' is not covered.<\/code><\/pre>\n
This feedback appears wherever the union is handled, so adding a case can\u2019t silently leave an existing switch incomplete. That\u2019s one of the main benefits of using a union instead of object<\/code> or an open hierarchy.<\/p>\n
Before native unions, developers usually reached for object<\/code>, a shared base type, or a custom wrapper. object<\/code> accepts too much, and a base type can\u2019t group unrelated existing types such as int<\/code> and string<\/code>. A custom wrapper can enforce the set, but it also needs its own construction and matching APIs. A native union keeps the contract in the method signature, works with regular C# patterns, and has built-in support in System.Text.Json<\/code><\/a> (STJ).<\/p>\n
Other ways to model alternatives<\/h2>\n
Before choosing a union, it helps to separate it from two related features.<\/p>\n
Polymorphism<\/h3>\n
Regular C# polymorphism models related types through inheritance. For example, Circle<\/code> and Square<\/code> can derive from a common Shape<\/code> base class and share its members and behavior.<\/p>\n
STJ has been able to serialize such a hierarchy with a discriminator. Mark the base type with [JsonPolymorphic]<\/code><\/a> and register each supported derived type with [JsonDerivedType]<\/code>. The resulting JSON identifies the active type explicitly (see $type<\/code> entry in the JSON):<\/p>\n
{\"$type\":\"circle\",\"radius\":5}<\/code><\/pre>\n
STJ always works from that explicitly registered set; it doesn\u2019t automatically include every type that might derive from the base in the future. If the C# base class remains open, the language doesn\u2019t enforce the same set and a switch<\/code> over it needs a fallback case.<\/p>\n
Closed hierarchies<\/h3>\n
C# 15 adds support for closed class hierarchies<\/strong>. Adding the closed<\/code> keyword to a base class prevents other assemblies from deriving directly from it. The compiler can then treat its known derived types as a complete list and check a switch<\/code> for exhaustiveness:<\/p>\n
public closed record class PaymentEvent(string PaymentId);\n\npublic sealed record class PaymentInitiated(string PaymentId) : PaymentEvent(PaymentId);\npublic sealed record class PaymentAuthorized(string PaymentId, decimal Amount) : PaymentEvent(PaymentId);\npublic sealed record class PaymentFailed(string PaymentId, string Reason) : PaymentEvent(PaymentId);<\/code><\/pre>\n
A closed hierarchy is union-like because it represents a known set of alternatives. In C#, however, it is still an inheritance hierarchy: its cases derive from a base class and can share members and behavior. When you control the hierarchy, closed<\/code> enforces the fixed set in the language and lets STJ infer the derived types instead of registering each one explicitly.<\/p>\n
The closed<\/code> modifier affects the C# type relationship; it doesn\u2019t change JSON by itself. The serialization section below<\/a> shows the default behavior first, followed by the opt-in polymorphic behavior.<\/p>\n
Choosing a model for your API<\/h2>\n
A union isn\u2019t always the best choice whenever an API has several possible shapes. Start with whether you control the case types and the JSON contract.<\/p>\n
When you are designing a new API and all alternatives are classes you control, prefer a closed hierarchy with a JSON discriminator. For example, PaymentInitiated<\/code>, PaymentAuthorized<\/code>, and PaymentFailed<\/code> can derive from PaymentEvent<\/code>. The discriminator makes the JSON self-describing, while closed<\/code> lets the compiler check that every known event is handled.<\/p>\n
Keep the base class open only when the model must remain extensible, such as an existing hierarchy designed for other assemblies to extend. STJ still requires every supported derived type to be registered explicitly, and callers need a fallback because the compiler can\u2019t consider an open hierarchy exhaustive.<\/p>\n
Choose a union when you must preserve an established discriminator-free contract, or when the cases can\u2019t derive from one base class. This includes primitives and existing types you don\u2019t control. A union preserves each case\u2019s existing JSON shape and still gives callers a fixed set of types to handle.<\/p>\n
That discriminator-free format is both a benefit and a tradeoff. Writing the active union case is straightforward. When reading, two cases can look the same in JSON and require explicit classification. For a new polymorphic contract you control, a closed hierarchy with a discriminator avoids that ambiguity.<\/p>\n
Also consider how the contract will evolve. Adding a union case or a derived type to a closed hierarchy can produce warnings in existing exhaustive switches, immediately showing callers what they need to handle. An open hierarchy avoids that coupling by requiring a fallback from the start.<\/p>\n
Closed-hierarchy serialization uses the same STJ polymorphism infrastructure described above. The closed<\/code> modifier adds language-level guardrails, and InferClosedTypePolymorphism<\/code> lets STJ discover the derived types from those guardrails.<\/p>\n
ASP.NET Core union support comes from STJ. Unions therefore work where ASP.NET Core uses STJ: JSON request and response bodies, SignalR<\/a>\u2018s JsonHubProtocol<\/code>, and Blazor<\/a>\u2018s JavaScript interop, persisted component state, and prerendered component parameters. They aren\u2019t supported for query strings, route values, headers, or form fields. For more information, see Limitations<\/a>.<\/p>\n
Serializing and deserializing unions<\/h2>\n
A union type is declared with the union<\/code> keyword and a list of case types. The examples throughout this article use the following declarations:<\/p>\n
public union UnionIntString(int, string);\npublic union UnionBoolString(bool, string);\npublic union UnionNullableIntString(int?, string);\n\npublic record Cat(string Name, string Coat);\npublic record Dog(string Name, string Breed);\npublic union UnionPet(Cat, Dog);<\/code><\/pre>\n
STJ serializes a union value as its active case, with nothing added to represent the union itself. The union wrapper is unpacked and only the active case is written, using that case\u2019s own JSON contract. There\u2019s no envelope object, no $type<\/code> field, and no discriminator of any kind:<\/p>\n
JsonSerializer.Serialize(new UnionIntString(42));      \/\/ 42\nJsonSerializer.Serialize(new UnionIntString(\"hello\")); \/\/ \"hello\"\nJsonSerializer.Serialize(new UnionPet(new Cat(\"Whiskers\", \"Tabby\"))); \/\/ { \"name\": \"Whiskers\", \"coat\": \"Tabby\" }<\/code><\/pre>\n
STJ can select a union case automatically when the cases use different JSON types. For example, UnionBoolString(bool, string)<\/code> is unambiguous because a JSON boolean maps to bool<\/code> and a JSON string maps to string<\/code>.<\/p>\n
When multiple cases could match the same JSON value, STJ needs help choosing one. UnionPet(Cat, Dog)<\/code> is ambiguous because both cases are JSON objects. If the payload follows an established discriminator-free contract that can\u2019t be changed, the built-in structural classifier can distinguish object cases by their property names:<\/p>\n
[JsonUnion(TypeClassifier = typeof(JsonUnionTypeStructuralClassifier))]\npublic union UnionPet(Cat, Dog);<\/code><\/pre>\n\n
\n
<\/i>Structural classification tradeoffs<\/strong><\/p>\n
The structural classifier must scan the JSON object before STJ can deserialize it, so classification adds work proportional to the payload size. Its decision depends on the case property names, which means changing those shapes can change how existing payloads are classified or make them ambiguous. Prefer a closed hierarchy with a discriminator for new contracts you control.<\/p><\/div>\n
If the cases can\u2019t be distinguished by structure, an advanced scenario can supply a custom JsonTypeClassifier<\/code>.<\/p>\n
The opening IntOrString<\/code> endpoint is an output example. When that union is used as an HTTP request body, the web JSON settings also allow numbers to be read from strings, so a JSON string could match either case. Deserializing that contract requires explicit custom classification.<\/p>\n
For an overview of STJ\u2019s union support and classifier APIs, see What\u2019s new in .NET libraries for .NET 11<\/a>.<\/p>\n
Serializing and deserializing closed hierarchies<\/h2>\n
The closed<\/code> modifier doesn\u2019t require polymorphic serialization. When code uses a concrete derived type, STJ serializes and deserializes it like any other type and doesn\u2019t add a discriminator:<\/p>\n
var json = JsonSerializer.Serialize(new PaymentAuthorized(\"p-123\", 42.5m), JsonSerializerOptions.Web);\n\nvar payment = JsonSerializer.Deserialize<PaymentAuthorized>(json, JsonSerializerOptions.Web);<\/code><\/pre>\n
{\"paymentId\":\"p-123\",\"amount\":42.5}<\/code><\/pre>\n
This round trip works because both the writer and reader use the concrete PaymentAuthorized<\/code> type. If an API instead uses the PaymentEvent<\/code> base type, the JSON needs to identify which derived type to create. Polymorphic serialization can be enabled on the closed base type:<\/p>\n
[JsonPolymorphic(InferClosedTypePolymorphism = true)]\npublic closed record class PaymentEvent(string PaymentId);<\/code><\/pre>\n
STJ then infers the derived types in the closed hierarchy and uses their type names as discriminators. An endpoint can deserialize a PaymentEvent<\/code> request and serialize the active derived type back:<\/p>\n
app.MapPost(\"\/payment-event\", (PaymentEvent paymentEvent) => paymentEvent);<\/code><\/pre>\n
This JSON is deserialized as PaymentAuthorized<\/code> and serialized with the same discriminator:<\/p>\n
{\"$type\":\"PaymentAuthorized\",\"paymentId\":\"p-123\",\"amount\":42.5}<\/code><\/pre>\n
The opt-in can instead be applied to a JSON pipeline with JsonSerializerOptions.InferClosedTypePolymorphism<\/code><\/a>. The following sections use unions in their examples, but configured closed hierarchies flow through the same STJ-backed Minimal API, MVC, SignalR, and Blazor paths.<\/p>\n
Minimal APIs<\/h2>\n
Unions work as request body parameters and as return types in both the runtime path (RequestDelegateFactory<\/code>) and the source-generated Request Delegate Generator (RDG)<\/a>. Behavior is identical across both.<\/p>\n
var builder = WebApplication.CreateBuilder(args);\nvar app = builder.Build();\n\n\/\/ Request body: UnionBoolString is unambiguous (bool vs string), so it binds without a classifier.\napp.MapPost(\"\/flag\", (UnionBoolString flag) => flag);\n\n\/\/ Request body: UnionPet's cases are both objects, so it uses the built-in classifier shown earlier.\napp.MapPost(\"\/pet\", ([FromBody] UnionPet pet) => TypedResults.Ok(pet));\n\n\/\/ Return types: only the active case is serialized, and no classifier is needed to write.\napp.MapGet(\"\/value\", () => new UnionIntString(42));\napp.MapGet(\"\/pet\", () => new UnionPet(new Cat(\"Whiskers\", \"Tabby\")));\n\napp.Run();<\/code><\/pre>\n
Unions compose with the usual Minimal API return types. For example, a union can be returned asynchronously, wrapped in a nullable, or handed back through TypedResults<\/code><\/a>:<\/p>\n
app.MapGet(\"\/maybe\", () => new UnionNullableIntString((int?)null));\napp.MapGet(\"\/typed\", () => TypedResults.Ok(new UnionPet(new Cat(\"Whiskers\", \"Tabby\"))));<\/code><\/pre>\n
A union can also be a property of another model, an item streamed from an IAsyncEnumerable<T><\/code>, or the body slot of an [AsParameters]<\/code> container. Union serialization also respects options configured through ConfigureHttpJsonOptions<\/code>.<\/p>\n
MVC controllers<\/h2>\n
Unions flow through the STJ input and output formatters, so controllers support them as action parameters and return types, including Task<TUnion><\/code> and ValueTask<TUnion><\/code> results:<\/p>\n
[ApiController]\n[Route(\"[controller]\/[action]\")]\n[Produces(\"application\/json\")]\npublic class PetsController : ControllerBase\n{\n    [HttpPost]\n    public UnionBoolString Echo([FromBody] UnionBoolString value) => value;\n\n    [HttpGet(\"{kind}\")]\n    public UnionIntString Primitive(string kind) => kind switch\n    {\n        \"value\" => new UnionIntString(42),\n        _ => new UnionIntString(\"hi\"),\n    };\n}<\/code><\/pre>\n
Union serialization and deserialization follow the rules described earlier<\/a>. Controllers use JsonSerializerDefaults.Web<\/code> just like Minimal APIs, so the IntOrString<\/code> input caveat in that section applies to controller actions too.<\/p>\n
SignalR<\/h2>\n
JsonHubProtocol<\/code> forwards reads and writes to System.Text.Json<\/code>, so unions work as hub method parameters, return values, and stream items without any extra configuration:<\/p>\n
public class ChatHub : Hub\n{\n    \/\/ Union argument (client \u2192 server).\n    public Task Send(UnionIntString message) => Clients.All.SendAsync(\"Receive\", message);\n\n    \/\/ Union return value (server \u2192 client).\n    public UnionPet GetPet() => new UnionPet(new Cat(\"Whiskers\", \"Tabby\"));\n\n    \/\/ Union stream items (server \u2192 client).\n    public async IAsyncEnumerable<UnionIntString> Stream()\n    {\n        yield return 1;\n        yield return \"two\";\n    }\n}<\/code><\/pre>\n
On the read path, the parameter, return, or stream-item Type<\/code> resolved from the invocation binder drives the union converter, including any [JsonUnion]<\/code> classifier.<\/p>\n
Unlike HTTP JSON binding in Minimal APIs and MVC, JsonHubProtocol<\/code> doesn\u2019t treat a JSON String<\/code> token as ambiguous for numeric cases, so a union such as UnionIntString(int, string)<\/code> round-trips both the int<\/code> and string<\/code> cases without a classifier. Unions whose cases share the StartObject<\/code> token, such as UnionPet(Cat, Dog)<\/code>, are still ambiguous on read and require a classifier.<\/p>\n
Unions are supported only with JsonHubProtocol<\/code>. The MessagePack and Newtonsoft.Json hub protocols don\u2019t support unions, because their underlying serializers have no union support.<\/p>\n
Blazor<\/h2>\n
Blazor works with unions in two ways, depending on whether a value stays in-process or crosses a serialization boundary. In-process component parameters are assigned directly and need no serialization, while JavaScript interop, persisted component state, and prerendered parameters serialize unions with System.Text.Json<\/code> and follow the same rules described earlier in this article.<\/p>\n
Component parameters<\/h3>\n
A component parameter is set by direct assignment when a component is rendered from Razor markup or through RenderTreeBuilder.AddComponentParameter<\/code>. In-process rendering doesn\u2019t serialize parameters, so a union parameter works with no extra configuration:<\/p>\n
<PetCard Pet=\"@(new UnionPet(new Cat(\"Whiskers\", \"Tabby\")))\" \/><\/code><\/pre>\n
public class PetCard : ComponentBase\n{\n    [Parameter]\n    public UnionPet Pet { get; set; }\n}<\/code><\/pre>\n
JavaScript interop<\/h3>\n
JavaScript interop through IJSRuntime<\/code><\/a> serializes arguments and return values with System.Text.Json<\/code>. This is useful when a JavaScript API already accepts a union-shaped contract. For example, Element.scrollIntoView<\/code><\/a> accepts either a Boolean alignment shorthand or an options object:<\/p>\n
public sealed record ScrollIntoViewOptions(string Behavior, string Block, string Inline);\n\npublic union ScrollIntoViewArgument(bool, ScrollIntoViewOptions);\n\nprivate ValueTask ScrollAsync(\n    ElementReference element,\n    ScrollIntoViewArgument argument) =>\n    JS.InvokeVoidAsync(\"scrollElementIntoView\", element, argument);\n\nawait ScrollAsync(target, false);\nawait ScrollAsync(target, new ScrollIntoViewOptions(\"instant\", \"start\", \"nearest\"));<\/code><\/pre>\n
window.scrollElementIntoView = (element, argument) =>\n    element.scrollIntoView(argument);<\/code><\/pre>\n
The active union case is serialized using the representation expected by JavaScript: either a JSON Boolean or an options object. No union envelope or discriminator is added.<\/p>\n
Persisted component state<\/h3>\n
PersistentComponentState<\/code><\/a> serializes state with System.Text.Json<\/code>, so a union round-trips through PersistAsJson<\/code> and TryTakeFromJson<\/code>, including a union whose active case is null<\/code>.<\/p>\n
Prerendering<\/h3>\n
When a component is prerendered with Blazor Server or Blazor WebAssembly, its parameters are serialized into the component marker with System.Text.Json<\/code> and deserialized when the component initializes on the client. Unions are supported across this boundary, including a union whose active case serializes to JSON null<\/code>, such as a UnionNullableIntString<\/code> that holds a null int?<\/code>.<\/p>\n
OpenAPI<\/h2>\n
The OpenAPI document represents a union as an anyOf<\/code><\/a> schema, with one entry per case type:<\/p>\n
\"Cat\": {\n  \"type\": \"object\",\n  \"properties\": {\n    \"name\": { \"type\": \"string\" },\n    \"coat\": { \"type\": \"string\" }\n  }\n},\n\"Dog\": {\n  \"type\": \"object\",\n  \"properties\": {\n    \"name\": { \"type\": \"string\" },\n    \"breed\": { \"type\": \"string\" }\n  }\n},\n\"UnionIntString\": {\n  \"anyOf\": [\n    { \"type\": \"integer\", \"format\": \"int32\" },\n    { \"type\": \"string\" }\n  ]\n},\n\"UnionPet\": {\n  \"type\": \"object\",\n  \"anyOf\": [\n    { \"$ref\": \"#\/components\/schemas\/Cat\" },\n    { \"$ref\": \"#\/components\/schemas\/Dog\" }\n  ]\n}<\/code><\/pre>\n
Because a union case has no discriminator and is structurally identical to the standalone type, each case schema reuses the standalone component name. The Cat<\/code> and Dog<\/code> schemas referenced by UnionPet<\/code> are the same components that a standalone Cat<\/code> or Dog<\/code> endpoint produces. This differs from polymorphic types, whose derived schemas are lifted to prefixed component names because they carry a $type<\/code> discriminator.<\/p>\n
An endpoint can also produce multiple response types for the same status code and content type. The Microsoft.AspNetCore.Mvc.ApiExplorer<\/code><\/a> namespace preserves every declared response type, and the generated document emits an anyOf<\/code> schema when several types share a content type:<\/p>\n
public record Tyrannosaurus(string Name, double BiteForceNewtons);\npublic record Triceratops(string Name, int HornCount);\npublic record Velociraptor(string Name, double TopSpeedKmh);\npublic union UnionDinosaur(Tyrannosaurus, Triceratops, Velociraptor);\n\napp.MapGet(\"\/any-of\", () => Results.Ok())\n    .Produces<UnionPet>(StatusCodes.Status200OK, \"application\/json\")\n    .Produces<UnionDinosaur>(StatusCodes.Status200OK, \"application\/json\");<\/code><\/pre>\n
The same support applies to MVC controllers that declare multiple ProducesResponseTypeAttribute<\/code><\/a> attributes for one status code and content type.<\/p>\n
Limitations<\/h2>\n
Union support requires System.Text.Json<\/code>. Binding sources that don\u2019t<\/em> route through STJ don\u2019t support unions:<\/p>\n