Skip to content
Purview Dev logo

A C# 15 union is a natural TError: the error cases stay strongly typed, and a caller still matches on one value. This page covers the modelling rules and the helper the source generator supplies so a case value can be returned where a result is expected.

using Purview.Results;
[GenerateResult]
public readonly union TenantError(TenantNotFound, TenantDisabled, TenantAlreadyExists);
public readonly record struct TenantNotFound(TenantId TenantId);
public readonly record struct TenantDisabled(TenantId TenantId);
public readonly record struct TenantAlreadyExists(TenantId TenantId);

[GenerateResult] is generated by the source generator bundled in Purview.Results during post-initialization, so the consuming project does not declare it and needs no second package reference. Opt-in is explicit: a compilation that never applies the attribute gets no helpers.

For each case type the generator emits two per-case overloads in a {Union}ResultExtensions static class in the union’s own namespace — a value-producing AsFailure<TValue>() and a non-generic AsFailure() that produces a unit result:

public static class TenantErrorResultExtensions
{
public static Result<TValue, TenantError> AsFailure<TValue>(this TenantNotFound error) =>
Result<TValue, TenantError>.Failure(error);
public static Result<TenantError> AsFailure(this TenantNotFound error) =>
Result<TenantError>.Failure(error);
// ... the same pair for TenantDisabled and TenantAlreadyExists
}
Result<Tenant, TenantError> GetTenant(TenantId tenantId) =>
_tenants.TryGetValue(tenantId, out var tenant)
? Result<Tenant, TenantError>.Success(tenant)
: new TenantNotFound(tenantId).AsFailure<Tenant>();
Result<TenantError> DeleteTenant(TenantId tenantId) =>
_tenants.Remove(tenantId)
? Result<TenantError>.Success()
: new TenantNotFound(tenantId).AsFailure();

The same class also declares a C# 14 extension block on the union type, so the union can name the call instead of the case:

Result<Tenant, TenantError> GetTenant(TenantId tenantId) =>
TenantError.Failure<Tenant>(new TenantNotFound(tenantId));
Result<TenantError> DeleteTenant(TenantId tenantId) =>
TenantError.Failure(new TenantNotFound(tenantId));
Result<TenantError> ok = TenantError.Success();
Result<Tenant, TenantError> created = TenantError.Success(tenant);

The per-case AsFailure helper is generated once per case type, not once per union, because C# does not apply union conversions to an instance extension-method receiver (CS1929). A leaf case type shared by two unions therefore gets a single AsFailure helper, reported as RSG1006, which can bind to the wrong union. The union-receiver factory is a static extension member (extension(Union) { public static ... }): the receiver is the union type itself and the case is an argument, so it is generated for every union and every case and is the form to use when a case type is shared.

A case type that is itself a union is an included union, and sharing it is composition rather than a shared leaf: the including union’s factory also covers every case reachable through it (constructing the nested value new Outer(new Inner(leaf))), no RSG1006 is reported, and no ambiguous per-case helper is generated for it. A case reachable through two different included unions cannot name a construction path, so it is reported as RSG1008 and skipped.

The shortest possible call site would be return new TenantNotFound(id);. C# blocks every route to a generated implicit conversion, and each rule is recorded as a compiler experiment in src/tests/SourceGenerator.UnitTests/UnionCompilerBehaviourTests.cs:

Rule Diagnostic
A user-defined operator cannot be declared in a static class — the generated helper class is one CS0715
A conversion operator must be declared by the source or the target type; a helper class is neither CS0556
Conversion operators are not permitted as extension members CS9282
A conversion operator cannot declare its own type parameters, so TValue is out of scope for a non-generic case type CS0246
Only one user-defined conversion may participate in a sequence, so case → union → Result<…> can never compose CS0029

The one shape the language accepts is a generic case type carrying the value type parameter — the shape a generic union’s generated helper declares. The per-case helper is therefore the best ergonomics the language allows.

A cast closes the case → union conversion so only the library’s union → result conversion remains, which means the cast form needs no generated code:

Result<Tenant, TenantError> GetTenant(TenantId tenantId) =>
(TenantError)new TenantNotFound(tenantId);

It is not prettier than AsFailure<Tenant>(), but it is a legitimate choice when a project does not want the generator applied to a union.

Returning a bare case value where a result is expected is a compiler error (CS0029). The package ships UnionCaseResultCodeFixProvider, which offers the rewrite in the IDE from the lightbulb:

return new TenantNotFound(id); // CS0029
return TenantError.Failure<Tenant>(new TenantNotFound(id)); // after the fix, for a value result
return TenantError.Failure(new TenantNotFound(id)); // after the fix, for a unit result

A fix is offered only when the rewrite will bind: the converted type is Purview.Results.Result<TValue, TError> or the unit Purview.Results.Result<TError>, TError is a union and opted in with [GenerateResult], the expression’s type is one of that union’s case types, and the union is reachable by its simple name at the call site. A value result gets Union.Failure<TValue>(case); a unit result gets Union.Failure(case). For a generic union, the extension block’s type arguments come first, so the rewrite is Union<T>.Failure<T, TValue>(case). The rewrite names the union, so it is correct even when the case type is shared with another union.

When one service calls another, the caller’s error type has to include the callee’s. Declare the operation family’s union with the callee’s error union as a case, then widen with Bind’s mapError argument or a guard:

[GenerateResult]
public readonly union BillingError(BillingAccountMissing, BillingServiceUnavailable);
// The caller's operation-family error: its own cases plus the callee's whole error union as one case.
[GenerateResult]
public readonly union RegisterTenantError(TenantError, BillingError);
// Widening Bind: map a billing failure into the registration contract and chain.
Result<Tenant, RegisterTenantError> Register(TenantId id, string name) =>
billing.ReserveQuota(id)
.Bind(quota => CreateTenant(quota, name), error => error);
// Guard idiom: BillingError is a case of RegisterTenantError, so the union-receiver factory produces the
// composite failure directly.
if (reserved.TryGetError(out var billingError))
return RegisterTenantError.Failure<Tenant>(billingError);

List the callee’s union as the case, not its leaf cases. The union’s own cases are then reachable through the including union’s factory, so RegisterTenantError.Failure<Tenant>(new BillingAccountMissing(id)) constructs the nested value directly. A leaf listed in two unions is a shared case, which raises RSG1006 and generates the per-case AsFailure helper for only one of them, so a case-receiver call site can bind to the wrong union; convert it with the union-receiver factory (CallerUnion.Failure(leaf)) instead. A union-typed case shared by two unions is composition, so it is not reported and its per-case helper is not generated at all. If the caller must not expose the callee’s types at all, map the callee’s cases into the caller’s own case types with MapError(error => error switch { ... }) instead — the compiler then forces the mapping to stay exhaustive as the callee’s union grows.

Nesting also works with the HTTP layer: the ASP.NET Core mapper resolves a union error to its innermost case, so a mapping for the leaf (Map<BillingServiceUnavailable>) wins, and a mapping for the enclosing union (Map<BillingError> or Map<RegisterTenantError>) still applies when the leaf has none.

A union declaration always stores its contents in an object?, so a value-type case boxes. When the error union is on a hot path, declare a custom [Union] type with typed storage and the non-boxing access pattern — a HasValue property plus one TryGetValue overload per case. The compiler calls HasValue for a null pattern and TryGetValue for a type pattern, so matching a value-type case keeps it unboxed:

using System.Runtime.CompilerServices;
public readonly record struct Count(int Value);
public readonly record struct Label(string Value);
[Union]
public readonly struct CountOrLabel : IUnion
{
private readonly Count _count;
private readonly Label? _label;
private readonly byte _tag;
public CountOrLabel(Count value) { _count = value; _label = null; _tag = 1; }
public CountOrLabel(Label value) { _count = default; _label = value; _tag = 2; }
public object? Value => _tag switch { 1 => _count, 2 => _label, _ => null };
public bool HasValue => _tag != 0;
public bool TryGetValue(out Count value) { value = _count; return _tag == 1; }
public bool TryGetValue(out Label value) { value = _label.GetValueOrDefault(); return _tag == 2; }
}
// The Count arm calls TryGetValue(out Count): no box.
static int Describe(CountOrLabel value) => value switch
{
Count count => count.Value,
Label label => label.Value.Length,
null => -1,
};

The generator does not change or re-emit the union, so [GenerateResult] works on a custom union exactly as on a union declaration: the per-case AsFailure helpers and the union-receiver factory are emitted. They add no boxing of their own — each is a plain Result<...>.Failure(...) call, and Result<TValue, TError> stores its error in a typed field.

Purview.Unions can generate this custom-union shape from a [GenerateUnion] declaration, and [GenerateResult] works on it directly:

using Purview.Unions;
[GenerateUnion(typeof(TenantNotFound), typeof(TenantDisabled))]
[GenerateResult]
public partial struct TenantError;

A source generator never sees another generator’s output, so the [Union] attribute and the constructors Purview.Unions emits are invisible while the results generator runs. [GenerateResult] therefore reads the union’s source-visible case list instead, in the union generator’s order: the [GenerateUnion] typeof list, the union’s partial static factory signatures, a nested IUnionMembers provider, then any source-visible public single-parameter constructors. It uses the first non-empty list. A generic [GenerateUnion] union must use one of the last three surfaces, because typeof(T) is not a legal attribute argument; a [GenerateUnion] union with no source-visible case list is reported as RSG1001.

That integration is verified against the packaged generators: src/tests/SourceGenerator.UnitTests references Purview.Unions and declares real [GenerateUnion] unions alongside [GenerateResult], and Examples.Unions is the runnable version. The shipped results generator still has no dependency on Purview.Unions; it matches the attribute by metadata identity.

A generic union is supported. Its own type parameters and constraints are repeated on the generated helpers and on the generic extension block that carries the union-receiver factory:

public readonly record struct None;
public readonly record struct Some<T>(T Value);
[GenerateResult]
public readonly union Maybe<T>(None, Some<T>);
Result<int, Maybe<string>> failure = Maybe<string>.Failure<string, int>(new Some<string>("present"));
// The per-case helper declares the union's parameters first and the value type last.
Result<int, Maybe<string>> helper = new Some<string>("present").AsFailure<string, int>();

A static extension member’s explicit type arguments are the extension block’s parameters first, then the method’s, which is why Failure takes the union argument (string) before the value type (int). When the value type can be inferred, it can be omitted: Maybe<string>.Success(42). A bare type parameter case (union ValueOrText<T>(T, string)) is covered by the union-receiver factory but has no per-case AsFailure helper, because an extension method on a bare T would apply to every value. A case that names a type parameter the union does not declare is reported as RSG1002 and skipped.

A custom union can place its creation members on a nested IUnionMembers provider. The generator reads the case list from the provider’s public static single-parameter Create methods and constructs values through IUnionMembers.Create, so a union with a private constructor works:

[Union]
[GenerateResult]
public readonly struct ProvidedError : IUnion, ProvidedError.IUnionMembers
{
private readonly object? _value;
private ProvidedError(object? value) => _value = value;
public interface IUnionMembers
{
static ProvidedError Create(ProvidedCase value) => new(value);
object? Value { get; }
}
object? IUnionMembers.Value => _value;
public object? Value => _value;
}
Result<int, ProvidedError> failure = ProvidedError.Failure<int>(new ProvidedCase(7));

A provider that declares no usable Create method is reported as RSG1007 and blocks generation, because the language would find no union members on it.

C# 15’s closed modifier is the alternative when the cases are classes with shared behaviour or inheritance. It fixes the direct descendants at compile time, so a switch over them is exhaustive without a discard arm, and the hierarchy works as TError:

public closed record class SyncOutcome;
public record class Synced(int Count) : SyncOutcome;
public record class Skipped(string Reason) : SyncOutcome;
Result<int, SyncOutcome> result = new Skipped("offline");
var text = result.Match(
value => $"synced {value}",
error => error switch
{
Synced synced => $"synced {synced.Count}",
Skipped skipped => $"skipped: {skipped.Reason}",
}
);

closed needs the .NET 11 runtime (IsClosedTypeAttribute), just as a union needs IUnion/UnionAttribute. Prefer a union for data-only cases, where every alternative is declared in one place; prefer a closed hierarchy when the cases need members or inheritance. The HTTP mapper keys a non-union error by its runtime type, so register a mapping for each descendant (or handle the base type with a fallback/IResultsFailureMapper); a mapping for the base type alone is not consulted for a derived instance.

Shape Supported
A union declaration whose cases are public single-parameter constructors Yes
A type marked [Union] with public single-parameter constructors Yes
A [GenerateUnion] union with a source-visible case list (typeof list, partial static factory signatures, or an IUnionMembers provider) Yes — cases are read from the source list, not from another generator’s output
A [GenerateUnion] union with no source-visible case list No — RSG1001 blocks the union
A class-based [Union] type with reference semantics Yes — construction and helpers are identical; the null union is a null reference
Nullable value-type and nullable reference-type cases Yes — a nullable value type is exposed as its underlying type (int? → int), and a nullable reference annotation is stripped because it is not part of the case’s identity
A custom [Union] type with HasValue/TryGetValue (non-boxing access pattern) Yes — the generator is unchanged, and value-type cases stay unboxed
A closed hierarchy used as TError (not a union) Yes — no [GenerateResult] helpers, but the result and HTTP mapper accept it
A leaf case type shared by two unions Yes — RSG1006 warning; the per-case AsFailure helper is generated once, and the union-receiver Failure(...) factory is generated for both
A union-typed case shared by two unions (composition) Yes — no warning; the including union’s factory covers the included union’s cases, and no ambiguous per-case helper is generated
A case reachable through two different included unions Yes — RSG1008 warning; that case’s inclusion factory is skipped
A generic union Yes — the factory is emitted as a generic extension block; call Option<string>.Failure<string, TValue>(case) because the union arguments precede the method’s type parameters
A case type that uses the union’s own type parameters Yes — the helper and factory repeat them
A bare union type parameter (for example union ValueOrText<T>(T, string)) Yes — the union-receiver factory covers it; it has no per-case AsFailure helper, because an extension method on a bare T would apply to every value
A case type that names a type parameter the union does not declare, or a union nested in a generic type No — RSG1002 (the remaining cases still generate)
An IUnionMembers provider with a public static single-parameter Create per case Yes — cases are read from the provider and values are constructed through IUnionMembers.Create
An IUnionMembers provider without a usable Create method No — RSG1007 blocks the union
A case type that is not a named type (for example an array) No — RSG1009 warning (the remaining cases still generate; wrap it in a record or struct case)

See Diagnostics for the full rules table and the blocking policy.