Discriminated unions for .NET with fluent error handling. ErrorOr<T> provides railway-oriented programming, nullable-to-ErrorOr extensions (OrNotFound, OrValidation, OrError), Match/Then/Else/Switch/FailIf fluent API, and rich typed errors mapped to HTTP status codes.
Railway-Oriented Programming for .NET with source-generated ASP.NET Core Minimal API integration. Zero boilerplate, full
Native AOT support.
Features
Discriminated Unions - ErrorOr<T> represents success or a list of typed errors
Fluent API - Chain operations with Then, Else, Match, Switch, and FailIf
Nullable Extensions - Convert nullable values with OrNotFound(), OrValidation(), and more
Source Generator - Auto-generates MapErrorOrEndpoints() from attributed static methods
Smart Binding - Automatic parameter inference based on HTTP method and type
OpenAPI Ready - Typed Results<...> unions for complete API documentation
Native AOT - Reflection-free code generation with JSON serialization contexts
Middleware Support - Translates ASP.NET Core attributes to Minimal API fluent calls (authorization, rate limiting,
caching)
API Versioning - Integrates with Asp.Versioning.Http for versioned endpoint groups
41 Analyzers - Real-time IDE feedback for route conflicts, binding errors, AOT compatibility
What the Generator Produces
The source generator transforms your handler methods into complete ASP.NET Core Minimal API endpoints.
You write the business logic, the generator handles everything else.
Endpoint Wiring
For each [Get], [Post], [Put], [Delete], [Patch] method:
Registers endpoint with app.MapGet(), app.MapPost(), etc.
This package includes both the source generator and the ErrorOrX runtime library.
Quick Start
// Program.cs
var app = WebApplication.CreateSlimBuilder(args).Build();
app.MapErrorOrEndpoints();
app.Run();
// TodoApi.cs
using ErrorOr;
public static class TodoApi
{
[Get("/todos/{id:guid}")]
public static ErrorOr<Todo> GetById(Guid id, ITodoService svc)
=> svc.GetById(id).OrNotFound($"Todo {id} not found");
[Post("/todos")]
public static ErrorOr<Todo> Create(CreateTodoRequest req, ITodoService svc)
=> svc.Create(req); // 201 Created
[Delete("/todos/{id:guid}")]
public static ErrorOr<Deleted> Delete(Guid id, ITodoService svc)
=> svc.Delete(id) ? Result.Deleted : Error.NotFound();
}
Error Types
Create structured errors mapped to HTTP status codes:
Error.Validation("User.InvalidEmail", "Email format is invalid") // 400
Error.Unauthorized("Auth.InvalidToken", "Token has expired") // 401
Error.Forbidden("Auth.InsufficientRole", "Admin role required") // 403
Error.NotFound("User.NotFound", "User does not exist") // 404
Error.Conflict("User.Duplicate", "Email already registered") // 409
Error.Failure("Db.ConnectionFailed", "Database unavailable") // 500
Error.Unexpected("Unknown", "An unexpected error occurred") // 500
Error.Custom(422, "Validation.Complex", "Complex validation failed")
Nullable-to-ErrorOr Extensions
Convert nullable values to ErrorOr<T> with auto-generated error codes:
// Error code auto-generated from type name (e.g., "Todo.NotFound")
return _todos.Find(t => t.Id == id).OrNotFound($"Todo {id} not found");
return user.OrUnauthorized("Invalid credentials");
return record.OrValidation("Record is invalid");
// Custom errors
return value.OrError(Error.Custom(422, "Custom.Code", "Custom message"));
return value.OrError(() => BuildExpensiveError()); // Lazy evaluation
Extension
Error Type
HTTP
Description
.OrNotFound()
NotFound
404
Resource not found
.OrValidation()
Validation
400
Input validation failed
.OrUnauthorized()
Unauthorized
401
Authentication required
.OrForbidden()
Forbidden
403
Insufficient permissions
.OrConflict()
Conflict
409
State conflict
.OrFailure()
Failure
500
Operational failure
.OrUnexpected()
Unexpected
500
Unexpected error
.OrError(Error)
Any
Any
Custom error
.OrError(Func)
Any
Any
Lazy custom error
Fluent API
Chain operations using railway-oriented programming patterns:
// Chain operations - errors short-circuit the pipeline
var result = ValidateOrder(request)
.Then(order => ProcessPayment(order))
.Then(order => CreateShipment(order))
.FailIf(order => order.Total <= 0, Error.Validation("Order.InvalidTotal", "Total must be positive"));
// Handle both cases
return result.Match(
order => Ok(order),
errors => BadRequest(errors.First().Description));
// Provide fallback on error
var user = GetUser(id).Else(errors => DefaultUser);
// Side effects
GetUser(id).Switch(
user => Console.WriteLine($"Found: {user.Name}"),
errors => Logger.LogError(errors.First().Description));
Result Markers
Use semantic markers for endpoints without response bodies:
Result.Success // 200 OK (no body)
Result.Created // 201 Created (no body)
Result.Updated // 204 No Content
Result.Deleted // 204 No Content
Interface Types with [ReturnsError]
Document possible errors on interface methods for OpenAPI generation:
var builder = WebApplication.CreateSlimBuilder(args);
builder.Services.AddErrorOrEndpoints()
.UseJsonContext<AppJsonSerializerContext>(); // Uses options from [JsonSourceGenerationOptions]
var app = builder.Build();
app.MapErrorOrEndpoints();
app.Run();
The [JsonSourceGenerationOptions] on your context controls serialization behavior (camelCase, null handling).
The builder methods WithCamelCase() and WithIgnoreNulls() are only needed if you want to override at runtime.
