Results
This guide installs the packages, models an error union, returns a result, and maps it onto an HTTP response.
Requirements
Section titled “Requirements”-
.NET 10 or .NET 11 — the runtime packages multi-target
net10.0andnet11.0; the source generator targetsnetstandard2.0so 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.IUnionandUnionAttribute. Onnet10.0the 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, noEnablePreviewFeatures. A project that declares its own[GenerateResult]union needs anet11.0target, where C# 15 is the SDK’s default language version, so it needs noLangVersioneither. Adoption is therefore incremental — you can takeResult<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 samenet10.0/net11.0set. Trimmed, Native AOT and Blazor applications are covered in Blazor and Native AOT.
1. Reference the packages
Section titled “1. Reference the packages”dotnet add package Purview.ResultsPurview.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.
2. Model the error as a union (optional)
Section titled “2. Model the error as a union (optional)”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.
3. Return a result
Section titled “3. Return a result”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";4. Read the result
Section titled “4. Read the result”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.
5. Map it onto HTTP
Section titled “5. Map it onto HTTP”dotnet add package Purview.Results.AspNetCorebuilder.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.
6. Validate without exceptions
Section titled “6. Validate without exceptions”dotnet add package Purview.Results.ZodSharpZodSharp’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.
Runnable examples
Section titled “Runnable examples”Every example is a non-packable project under src/src/Examples.*, built on the same Tenancy domain:
dotnet run --project src/src/Examples.Basicdotnet run --project src/src/Examples.Unionsdotnet run --project src/src/Examples.Zoddotnet run --project src/src/Examples.Blazor.Server --urls http://localhost:5218dotnet run --project src/src/Examples.Blazor.Wasm --urls http://localhost:5217dotnet run --project src/src/Examples.AspNetCore --urls http://localhost:5215dotnet run --project src/src/Examples.AspNetCore.Zod --urls http://localhost:5216dotnet run --project src/src/Examples.ValueObjects.ZodNext steps
Section titled “Next steps”- Core Concepts — the three states and the throw-on-misuse contract.
- Combinators —
Match,Map,Bind,Ensure, probing, and the asynchronous forms. - Guarantees and Limitations — what the suite deliberately does not do.