Offside.AspNetCore 0.6.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
dotnet add package Offside.MediatR                  # domain notifications for failed results
dotnet add package Offside.Testing                  # assertions for unit tests
dotnet add package Offside.Refit                    # Refit clients calling external APIs
dotnet add package Offside.ApplicationInsights      # domain errors as telemetry (classic SDK)
dotnet add package Offside.OpenTelemetry            # domain errors as telemetry (OpenTelemetry)

Agent skills + catalog templates:

dotnet tool install -g Offside.Tool
offside init

offside init copies ten 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, Offside.MediatR, Offside.Testing, Offside.Refit, Offside.ApplicationInsights, Offside.ApplicationInsights.MediatR, Offside.OpenTelemetry, and Offside.OpenTelemetry.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, Offside.ApplicationInsights.MediatR, and Offside.OpenTelemetry.MediatR support MediatR 12.0.1 through 14.x; Offside.Refit supports Refit 8.x through 15.x ([8.0.0,16.0.0); Refit 5.x is not supported); Offside.FastEndpoint requires FastEndpoints 8.3 or later.

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		Publishes failed results as domain notifications and provides a scoped collector
Offside.Testing		Fluent assertions for Result, Error, and message catalogs, with no test-framework dependency
Offside.Refit		Maps external API failures to Error / Result, with a call wrapper and a diagnostics handler
Offside.ApplicationInsights		Records domain errors as traces via the classic Application Insights SDK
Offside.ApplicationInsights.MediatR		Records published domain notifications through the classic SDK
Offside.OpenTelemetry		Records domain errors as a log, a span event, and a counter, for Azure.Monitor.OpenTelemetry or any OTLP exporter
Offside.OpenTelemetry.MediatR		Records published domain notifications through OpenTelemetry
Offside.Tool		offside init — skills and catalog templates

The Core package has no ASP.NET, MediatR, Refit, or Application Insights 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));

With AddOffsideOpenTelemetry or AddOffsideApplicationInsights registered, that one line also records the failure. There is no RecordTo at the HTTP endpoint.

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, Offside.Testing, Offside.Refit, Offside.ApplicationInsights, Offside.ApplicationInsights.MediatR, Offside.OpenTelemetry, Offside.OpenTelemetry.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.3.0
git push origin v0.3.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.