Skip to content
Purview Dev logo

This guide installs the packages, models an error union, returns a result, and maps it onto an HTTP response.

  • .NET 10 or .NET 11 — the runtime packages multi-target net10.0 and net11.0; the source generator targets netstandard2.0 so any compiler host can load it. .NET 8 and .NET 9 are not targeted; both are out of support.

  • Unions require .NET 11, because the compiler needs System.Runtime.CompilerServices.IUnion and UnionAttribute. On net10.0 the result types, combinators, ASP.NET Core mapping and ZodSharp bridge all work; only the union declaration itself is unavailable, so map the error type directly instead of a case.

  • C# 15 — only a union declaration needs .NET 11. Using the result types and combinators needs nothing special: no LangVersion, no EnablePreviewFeatures. A project that declares its own [GenerateResult] union needs a net11.0 target, where C# 15 is the SDK’s default language version, so it needs no LangVersion either. Adoption is therefore incremental — you can take Result<TValue, TError> into an existing solution first and introduce unions per project later.

    These packages do not set EnablePreviewFeatures, so they do not force preview features on your solution. See Guarantees and Limitations.

  • Purview.ZodSharp 3 for the ZodSharp integrations (Purview.Results.ZodSharp, Purview.Results.ZodSharp.AspNetCore), which target the same net10.0/net11.0 set. Trimmed, Native AOT and Blazor applications are covered in Blazor and Native AOT.

Terminal window
dotnet add package Purview.Results

Purview.Results carries the result type and, under analyzers/dotnet/cs, the Roslyn component that makes union errors ergonomic: it applies to the compilation automatically and brings the analyzer, the CS0029 code fix, and the CA1815 suppression for opted-in unions. There is no separate generator package to reference.

A C# 15 union makes the error cases strongly typed without giving up the single TError the result needs:

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 itself, so it needs no separate reference. For every case the generator emits a value-producing AsFailure<TValue>() and a non-generic AsFailure() in the union’s namespace, plus a union-receiver factory on the union type itself:

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 per case type
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 type, plus Success() and Success<TValue>(value)
}
}

The union-receiver factory names the union, so it stays unambiguous when a leaf case type is shared with another union (RSG1006). A case type that is itself a union is an included union: the factory also covers its cases and builds the nested value, so list the callee’s union as a case instead of repeating its leaf cases.

See Union Errors for the modelling rules and Source Generator for the generated shape.

using Purview.Results;
Result<Tenant, TenantError> GetTenant(TenantId tenantId) =>
_tenants.TryGetValue(tenantId, out var tenant)
? Result<Tenant, TenantError>.Success(tenant)
: new TenantNotFound(tenantId).AsFailure<Tenant>();

Result.Success<TValue, TError>(value) and Result.Failure<TValue, TError>(error) are the same factories without repeating the value type. Both member states are also reachable through the result’s implicit conversions, so a non-union error or a value can be returned directly:

Result<int, string> ok = 42;
Result<int, string> failed = "not a number";
var result = GetTenant(tenantId);
if (result.IsSuccess)
Console.WriteLine(result.Value.Name);
var message = result.Match(
tenant => $"Found {tenant.Name}",
error => $"Could not load the tenant: {error}"
);

default is uninitialized: IsInitialized, IsSuccess and IsFailure are all false, and Value, Error, Match, Map, Bind and MapError throw InvalidOperationException rather than guessing. See Core Concepts and Combinators.

Terminal window
dotnet add package Purview.Results.AspNetCore
builder.Services.AddResultsHttp(options => options
.Map<TenantNotFound>(error => TypedResults.NotFound())
.Map<TenantDisabled>(error => TypedResults.Problem(statusCode: StatusCodes.Status403Forbidden))
.Map<TenantError>(error => TypedResults.Problem(statusCode: StatusCodes.Status409Conflict)));
app.MapGet("/tenants/{id}", (string id) => GetTenant(new TenantId(id))).WithResultsHttp();

A mapping for the case type wins, the mapping for the error type covers the remaining cases, and an unmapped failure is a logged 500 (and is counted in telemetry with its case type), so a mapping gap is never silent. See ASP.NET Core Integration.

Terminal window
dotnet add package Purview.Results.ZodSharp

ZodSharp’s Validate already returns a ValidationResult<T>; ToResult turns that into a result whose error type you choose:

return TenantInputSchema
.Validate(input)
.ToResult<TenantInput, TenantError>(errors => new TenantInputInvalid(input, errors));

See ZodSharp Integration and, for ProblemDetails rendering, ZodSharp Problem Details.

Every example is a non-packable project under src/src/Examples.*, built on the same Tenancy domain:

Terminal window
dotnet run --project src/src/Examples.Basic
dotnet run --project src/src/Examples.Unions
dotnet run --project src/src/Examples.Zod
dotnet run --project src/src/Examples.Blazor.Server --urls http://localhost:5218
dotnet run --project src/src/Examples.Blazor.Wasm --urls http://localhost:5217
dotnet run --project src/src/Examples.AspNetCore --urls http://localhost:5215
dotnet run --project src/src/Examples.AspNetCore.Zod --urls http://localhost:5216
dotnet run --project src/src/Examples.ValueObjects.Zod