Home English

Offside documentation

catch it before the whistle · Português

Domain errors as Result, not exceptions. The domain returns an Error; ASP.NET Core maps it to Problem Details (RFC 7807). Messages live in JSON catalogs, not in C#.

Start here

Page	What it covers
Getting started	Install, register, and return your first Problem Details response
Concepts	Error, ErrorCode, ErrorKind, Result, primary error, catalogs, the escape hatch
Domain guide	Writing domain code with Result<T>: factories, Custom, Bind/Map/Combine
ASP.NET Core guide	ToHttpResult / ToActionResult, status selection, the response shape, 500 handling
FluentValidation	Map FluentValidation failures to Offside Error / Result
FastEndpoints	UseOffside, SendOffsideAsync, OpenAPI expected errors
MediatR integration	Publish result errors as notifications, collect them per scope, and handle retries safely
Messages and cultures	Catalog format, culture fallback, {token} interpolation
CLI	offside init — agent skills and catalog templates
API reference	Every public type and member, in one page
FAQ	Design decisions and common pitfalls

Architecture

Page	What it covers
Architecture	Seven projects, package boundaries and dependency graph
Error and result lifecycle	Domain failure creation, composition and HTTP mapping
Message resolution	Catalog lookup, culture fallback, interpolation and Azure limits
Integrations and adapters	Problem Details, FluentValidation, FastEndpoints and MediatR
Build, testing and release	Solution validation, CI, release and CLI installation

The shape of it

// Domain — knows nothing about HTTP
public Result<Order> Get(string id)
{
    var order = _orders.Find(id);
    return order is null
        ? Result<Order>.Failure(Error.NotFound("order", id))
        : Result<Order>.Success(order);
}

// Endpoint — one line
app.MapGet("/orders/{id}", (string id, HttpContext http) => _orders.Get(id).ToHttpResult(http));

// Response — 404, application/problem+json
{
  "type": "https://httpstatuses.io/404",
  "title": "NotFound",
  "status": 404,
  "detail": "order '42' was not found.",
  "errorCode": "NOT_FOUND",
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "errors": [
    { "code": "not_found", "errorCode": "NOT_FOUND", "kind": "NotFound", "detail": "order '42' was not found.", "field": null }
  ]
}

Packages

Package	Version	Target frameworks	Role
Offside		netstandard2.0, net8.0, net10.0	Error, ErrorKind, Result / Result<T>, JSON resolver, AddOffside
Offside.AspNetCore		net8.0, net10.0	ToHttpResult / ToActionResult, Problem Details, AddOffsideAspNetCore
Offside.FluentValidation		netstandard2.0, net8.0, net10.0	FluentValidation failures → Error / Result
Offside.FastEndpoint		net8.0, net10.0	UseOffside, SendOffsideAsync, OpenAPI expected errors
Offside.AzureAppConfiguration		netstandard2.0, net8.0, net10.0	Dynamic resolver for catalogs loaded by Azure App Configuration
Offside.MediatR	Publication pending	netstandard2.0, net8.0, net10.0	MediatR notifications for failed results and a scoped collector
Offside.Tool		net8.0	offside init — agent skills and catalog templates

The core package has no ASP.NET or MediatR dependency, so domain projects can reference it freely.

Elsewhere

• Changelog · Contributing · Support · Security