Offside 0.2.0

Offside

catch it before the whistle

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

Documentation · Wiki · Português · Wiki em português

Install

dotnet add package Offside
dotnet add package Offside.AspNetCore               # ASP.NET hosts only
dotnet add package Offside.FluentValidation         # FluentValidation → Error
dotnet add package Offside.FastEndpoint             # FastEndpoints hosts only
dotnet add package Offside.AzureAppConfiguration    # Azure App Configuration catalogs

Offside.MediatR is not published to NuGet yet. Its source and local package remain available; see Pack locally when using MediatR before publication.

Agent skills + catalog templates:

dotnet tool install -g Offside.Tool
offside init

offside init copies nine skills into .cursor/skills, .agents/skills, and .claude/skills, and writes errors/errors.json plus errors/errors.pt-BR.json. The setup, implementation, and refactoring skills ask the user to select a message source (JSON, Azure, or custom), an exposure mode (domain only, ASP.NET Core, or FastEndpoints), and optional FluentValidation. Setup also offers optional MediatR domain notifications. Use --dir <path> and --force as needed.

Compatibility and status

Offside, Offside.FluentValidation, Offside.AzureAppConfiguration, and Offside.MediatR support netstandard2.0, net8.0, and net10.0. Offside.AspNetCore and Offside.FastEndpoint support net8.0 and net10.0; Offside.Tool runs on net8.0. Offside.MediatR supports MediatR 12.0.1 through 14.x.

The project is pre-1.0. Minor releases may include breaking changes. Releases follow Semantic Versioning, and notable changes are recorded in CHANGELOG.md.

Packages

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

The Core package has no ASP.NET or MediatR dependency.

Example

using System.Globalization;
using Offside;
using Offside.AspNetCore;

builder.Services.AddOffside(options =>
{
    options.AddJsonFile(CultureInfo.InvariantCulture, "errors/errors.json");
});
builder.Services.AddOffsideAspNetCore();

Result GetOrder(string id) =>
    Result.Failure(Error.NotFound("Order", id));

app.MapGet("/orders/{id}", (string id, HttpContext http) =>
    GetOrder(id).ToHttpResult(http));

MediatR hosts can publish every error in a failed result, in order, and read them back from a scoped collector:

builder.Services.AddMediatR(configuration =>
    configuration.RegisterServicesFromAssemblyContaining<Program>());
builder.Services.AddOffsideMediatR();

Result result = CancelOrder(id);
return await result.PublishDomainNotificationsAsync(publisher, cancellationToken);

A failure becomes application/problem+json, with the status taken from the most severe error present:

{
  "type": "https://httpstatuses.io/404",
  "title": "NotFound",
  "status": 404,
  "detail": "Order '42' was not found.",
  "errorCode": "NOT_FOUND",
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
  "errors": [
    { "code": "not_found", "errorCode": "NOT_FOUND", "kind": "NotFound", "detail": "Order '42' was not found.", "field": null }
  ]
}

Full guides: getting started · concepts · domain · ASP.NET Core · FluentValidation · FastEndpoints · MediatR · messages · API reference

Pack locally

dotnet pack -c Release -o artifacts

Produces Offside, Offside.AspNetCore, Offside.FluentValidation, Offside.FastEndpoint, Offside.AzureAppConfiguration, Offside.MediatR, and Offside.Tool nupkgs (plus snupkgs).

CI and publish

CI builds, tests (net8 + net10), and packs on master and pull requests.

To publish to nuget.org, add a Trusted Publishing policy:

• Repository Owner: vpcmps
• Repository: Offside
• Workflow File: release.yml
• Environment: leave blank

Then push a version tag (the tag is the package version):

git tag v0.1.0
git push origin v0.1.0

Spec

The internal design specification records the original decisions (in Portuguese). For usage, prefer the documentation.

Community and security

Read CONTRIBUTING.md before opening a pull request. For help, see SUPPORT.md. Report vulnerabilities privately according to SECURITY.md.