Source Generator
The Purview.Results package ships an incremental Roslyn
source generator that makes C# 15 union error cases ergonomic with Result<TValue, TError> and the value-less
Result<TError>. It generates the [GenerateResult] attribute, the per-case AsFailure<TValue>() and AsFailure()
helpers, the union-receiver Union.Failure(...) and Union.Success(...) factories for every union case (including
the cases reachable through an included union), and the diagnostics that keep unsupported shapes out of a build. It
is not published as a separate package.
Installation
Section titled “Installation”dotnet add package Purview.ResultsThe component targets netstandard2.0 (with the SDK’s Roslyn defaults) so any compiler host can load it, and it
is applied to the compilation automatically from the package’s analyzers/dotnet/cs folder. Requirements: a
C# 15 compiler with union declaration support (the .NET 11 SDK or later) and a net11.0 target. C# 15 is the
default language version for net11.0 in the .NET 11 SDK, so no LangVersion is needed.
Activation and design
Section titled “Activation and design”- Opt-in only. Nothing is generated for a compilation that never applies
[GenerateResult]; discovery runs throughForAttributeWithMetadataNameand only the attribute source is produced for every compilation. - The attribute is generated during post-initialization (
GenerateResultAttribute.g.cs), so consumers do not declare it and do not need another package reference. - One analyzer, one generator, one diagnostics library. The analyzer raises the per-target rules; the generator shares the same analysis to decide whether generation can continue. No rule is reported twice.
- One suppressor, with one narrow job.
UnionEqualityDiagnosticSuppressoranswersCA1815for opted-in unions only and reports no diagnostics of its own. - Union membership is decided by the language or by a metadata identity, never by type names, source text,
reflection or the union’s runtime value. A target is a union when
ITypeSymbol.IsUnionis true, or when it carriesPurview.Unions.GenerateUnionAttribute(matched by metadata name only; this package does not depend onPurview.Unions). - Case types come from the source-visible list. A language union uses its public single-parameter
constructors (with an
IUnionMembersprovider taking precedence when one exists); auniondeclaration synthesises one per declared case. A[GenerateUnion]union uses the first non-empty source list in the union generator’s order — the attribute’stypeoflist, partial static factory signatures, a nestedIUnionMembersprovider, then source-visible constructors — because the[Union]attribute and constructors another generator emits are never visible here.
The incremental pipeline
Section titled “The incremental pipeline”The pipeline resolves Roslyn symbols during discovery and converts them into value-equatable models
(ResultUnionModel, ResultUnionCaseModel, ResultSourceLocation, EquatableArray<T>). No ISymbol,
Compilation, SemanticModel, IOperation, SyntaxNode, SyntaxTree or Location ever reaches cached
state, which is what stops an unrelated edit from regenerating output.
ResultsSourceGeneratorCacheTests proves this stage by stage with GenerateIncrementalAsync: New on the first
run, Cached/Unchanged on an identical rerun, and Modified only for the stages whose inputs actually changed.
CodeWriter is created inside the RegisterSourceOutput callback, never stored in cached state.
Deterministic output
Section titled “Deterministic output”- Cases are ordered ordinally by fully-qualified name.
- Unions are processed in ordinal order.
- Hint names derive from the union’s identity.
- Nothing emits timestamps, GUIDs or machine paths, so the same inputs always produce byte-identical output.
Accessibility and nullability
Section titled “Accessibility and nullability”Accessibility never widens: the generated class is public only when the union and every case type it references
are visible; otherwise it is internal. Generated files start with #nullable enable, reference fully qualified
names, and do not add ? to non-nullable case types.
Generated shape
Section titled “Generated shape”namespace Test.Tenancy;
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
extension(TenantError) { public static Result<TenantError> Failure(TenantNotFound error) => Result<TenantError>.Failure(error);
public static Result<TValue, TenantError> Failure<TValue>(TenantNotFound error) => Result<TValue, TenantError>.Failure(error);
// ... the same Failure pair per case ...
public static Result<TenantError> Success() => Result<TenantError>.Success();
public static Result<TValue, TenantError> Success<TValue>(TValue value) => Result<TValue, TenantError>.Success(value); }}The per-case AsFailure helpers let the case name the call (new TenantNotFound(id).AsFailure<Tenant>()); the
union-receiver factory lets the union name it (TenantError.Failure<Tenant>(new TenantNotFound(id))). The
factory is the shared-case safe form: when a leaf case type belongs to more than one union, its per-case
AsFailure helper is generated once and reported as RSG1006, while the factory is generated for every union.
A case type that is itself a union is an included union. The factory then also covers every case reachable
through it and constructs the nested value (RegisterTenantError.Failure<Tenant>(new BillingAccountMissing(id))
builds RegisterTenantError(BillingError(BillingAccountMissing))). Inclusion is automatic and is the supported way
to avoid RSG1006: list the callee’s union as a case instead of repeating its leaf cases. A union-typed case shared
by two unions is composition, so it is not reported as RSG1006 and its ambiguous per-case helper is not generated
at all. A case reachable through two different included unions is reported as RSG1008 and skipped.
The generated helpers are pure static methods that call the existing Result<...>.Failure/.Success factories:
there is no reflection, no dynamic, no runtime type discovery and no mutable static state. The generator does not
change, wrap or replace Result<TValue, TError> or Result<TError>.
Build properties
Section titled “Build properties”| Property | Default | Purpose |
|---|---|---|
DisableResultsSourceGenerator |
false |
Disables generation while still emitting the opt-in attribute |
The switch reaches PackageReference consumers through buildTransitive/Purview.Results.props, so
-p:DisableResultsSourceGenerator=true (or a Directory.Build.props setting) disables the helpers there too.
Release tracking for the rules lives in src/src/SourceGenerator/AnalyzerReleases.Shipped.md (every rule, under
Release 1.0.0); AnalyzerReleases.Unshipped.md holds new or changed rules until the next release.
Packaging
Section titled “Packaging”The generator is never packed loose: Purview.Results ships the runtime library as
lib/<tfm>/Purview.Results.dll with its XML documentation, and the generator’s merged analyzer under
analyzers/dotnet/cs/ only — never under lib/ — with no analyzer PDB, because the packaged analyzer is the
framework’s ILRepack-merged assembly whose rewritten PDB carries no Roslyn compiler-flags record. The CS0029 code fix ships beside it as a second
analyzer assembly (Purview.Results.SourceGenerator.CodeFixes.dll) and is never IL-merged into the generator.
The generator is not a separate NuGet package.
Related
Section titled “Related”- Union Errors — the union modelling this generator targets.
- Diagnostics — the rules, the blocking policy and the suppression.
- Testing — the generation, cache and compiler-experiment tests.