Forge

Forge beautiful ASP.NET Core APIs.

Forge is an opinionated foundation library family for ASP.NET Core Web APIs. Drop one NuGet, call AddForge(), and your API has consistent responses, RFC 7807 errors, validation, pagination, correlation IDs, and structured logging — with full IntelliSense and zero boilerplate.

Packages (v1.0)

Package	Version	Purpose
Narch.Forge		Core types: Result, Result<T>, Error, ApiResponse<T>, PagedResult<T>. No ASP.NET dependency.
Narch.Forge.Abstractions		Interfaces & contracts only (currently IRequestContext).
Narch.Forge.AspNetCore		ASP.NET Core middleware, filters, ProblemDetails handler, builder, registration extensions.
Narch.Forge.Validation		FluentValidation integration with automatic 422 envelopes.

Namespaces and types remain under the Forge.* family — only the published NuGet IDs are prefixed with Narch..

Target frameworks: net10.0 (primary, LTS) and net8.0 (compat, dropped in v2).

Install

dotnet add package Narch.Forge.AspNetCore
dotnet add package Narch.Forge.Validation   # optional

Packages are published to nuget.org.

Quick start

using Forge.AspNetCore.EndpointConventions;
using Forge.AspNetCore.HealthChecks;
using Forge.AspNetCore.Registration;
using Forge.Results;
using Forge.Validation;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddForge(opt => opt
    .UseStandardResponseEnvelope(o => o.Version = "v1")
    .UseGlobalExceptionHandler()
    .UseCorrelationId()
    .UseRequestLogging()
    .UseProblemDetails());

builder.Services.AddForgeValidation(v =>
    v.AddValidatorsFromAssemblyContaining<Program>());

var app = builder.Build();
app.UseForge();
app.MapForgeHealthChecks();

app.MapGet("/users/{id:int}", (int id) =>
        id == 42
            ? Result<UserDto>.Success(new UserDto(42, "Ada", "ada@example.com"))
            : Result<UserDto>.Failure(Error.NotFound("USER_NOT_FOUND", $"User {id} not found")))
    .WithApiResponseEnvelope()
    .ProducesApiResponse<UserDto>();

app.Run();

public sealed record UserDto(int Id, string Name, string Email);

A GET /users/42 returns:

{
  "success": true,
  "data": { "id": 42, "name": "Ada", "email": "ada@example.com" },
  "errors": [],
  "meta": { "correlationId": "01J9...", "timestamp": "2026-05-14T10:30:00Z", "version": "v1" }
}

A GET /users/99 returns 404 with:

{
  "success": false,
  "data": null,
  "errors": [{ "code": "USER_NOT_FOUND", "message": "User 99 not found", "field": null }],
  "meta": { "correlationId": "01J9...", "timestamp": "2026-05-14T10:30:00Z", "version": "v1" }
}

Run the sample

The repository ships with a runnable demo at samples/Forge.Sample.Api that exercises every feature.

dotnet run --project samples/Forge.Sample.Api

Then browse to https://localhost:<port>/users/42, /users/99, /users?page=1&size=2, /explode/7, /health, etc.

Documentation

• Getting started
• Result pattern
• Response envelope
• Exception handling
• Validation
• Pagination
• Request context
• Logging
• Migration from vanilla ASP.NET Core

Quality bar

• TreatWarningsAsErrors=true everywhere
• 100% XML-doc coverage on public surface (CS1591 is a build error)
• StyleCop, Roslynator, Meziantou, and .NET Analyzers on
• xUnit + FluentAssertions; ≥85% line coverage in CI

License

MIT. See LICENSE.

Contributing

See CONTRIBUTING.md. Issues and PRs welcome.