Home

Documentação do Offside

catch it before the whistle · English

Erros de domínio como Result, não como exceções. O domínio devolve um Error; o ASP.NET Core mapeia isso para Problem Details (RFC 7807). As mensagens ficam em catálogos JSON, não em C#.

Comece por aqui

Página	O que cobre
Primeiros passos	Instalar, registrar e devolver a primeira resposta Problem Details
Conceitos	Error, ErrorCode, ErrorKind, Result, erro primário, catálogos, escape hatch
Guia de domínio	Escrever código de domínio com Result<T>: factories, Custom, Bind/Map/Combine
Guia ASP.NET Core	ToHttpResult / ToActionResult, escolha do status, formato da resposta, tratamento de 500
FluentValidation	Mapear falhas do FluentValidation para Error / Result do Offside
FastEndpoints	UseOffside, SendOffsideAsync, erros esperados no OpenAPI
Integração com MediatR	Publicar erros de resultados como notificações, coletá-los por scope e tratar retries com segurança
Mensagens e culturas	Formato do catálogo, fallback de cultura, interpolação de {token}
CLI	offside init — skills de agente e templates de catálogo
Referência de API	Todos os tipos e membros públicos, em uma página
FAQ	Decisões de design e armadilhas comuns

Arquitetura

Página	O que cobre
Arquitetura	Sete projetos, limites dos pacotes e grafo de dependências
Ciclo de erros e resultados	Criação, composição e mapeamento HTTP das falhas de domínio
Resolução de mensagens	Catálogos, fallback de cultura, interpolação e limites do Azure
Integrações e adaptadores	Problem Details, FluentValidation, FastEndpoints e MediatR
Build, testes e release	Validação da solution, CI, release e instalação CLI

O formato disso

// Domínio — não sabe nada sobre 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 — uma linha
app.MapGet("/orders/{id}", (string id, HttpContext http) => _orders.Get(id).ToHttpResult(http));

// Resposta — 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 }
  ]
}

Pacotes

Pacote	Versão	Target frameworks	Papel
Offside		netstandard2.0, net8.0, net10.0	Error, ErrorKind, Result / Result<T>, resolver JSON, AddOffside
Offside.AspNetCore		net8.0, net10.0	ToHttpResult / ToActionResult, Problem Details, AddOffsideAspNetCore
Offside.FluentValidation		netstandard2.0, net8.0, net10.0	Falhas FluentValidation → Error / Result
Offside.FastEndpoint		net8.0, net10.0	UseOffside, SendOffsideAsync, erros esperados no OpenAPI
Offside.AzureAppConfiguration		netstandard2.0, net8.0, net10.0	Resolver dinâmico para catálogos carregados pelo Azure App Configuration
Offside.MediatR	Publicação pendente	netstandard2.0, net8.0, net10.0	Notificações MediatR para resultados com falha e coletor scoped
Offside.Tool		net8.0	offside init — skills de agente e templates de catálogo

O pacote core não tem dependência de ASP.NET nem de MediatR, então projetos de domínio podem referenciá-lo livremente.

Em outro lugar

• Changelog · Contribuindo · Suporte · Segurança