UnambitiousFx.Functional.AspNetCore
4.0.0
See the version list below for details.
dotnet add package UnambitiousFx.Functional.AspNetCore --version 4.0.0
NuGet\Install-Package UnambitiousFx.Functional.AspNetCore -Version 4.0.0
<PackageReference Include="UnambitiousFx.Functional.AspNetCore" Version="4.0.0" />
<PackageVersion Include="UnambitiousFx.Functional.AspNetCore" Version="4.0.0" />
<PackageReference Include="UnambitiousFx.Functional.AspNetCore" />
paket add UnambitiousFx.Functional.AspNetCore --version 4.0.0
#r "nuget: UnambitiousFx.Functional.AspNetCore, 4.0.0"
#:package UnambitiousFx.Functional.AspNetCore@4.0.0
#addin nuget:?package=UnambitiousFx.Functional.AspNetCore&version=4.0.0
#tool nuget:?package=UnambitiousFx.Functional.AspNetCore&version=4.0.0
Functional.AspNetCore
ASP.NET Core integration for Result<T> and Maybe<T>. Provides one-line conversion to HTTP responses for both Minimal
APIs and MVC controllers, with predictable defaults and zero boilerplate for common cases.
Features
- ✅ AOT-Compatible: Designed for Native AOT compilation
- ✅ Minimal API Support: Convert
Result<T>/Maybe<T>toIResult - ✅ MVC Controller Support: Convert
Result<T>/Maybe<T>toIActionResult - ✅ async-first: First-class
ValueTask<Result<T>>andValueTask<Maybe<T>>overloads - ✅ Policy-based defaults: Configure success/none HTTP behavior globally via
AddResultHttp - ✅ Extensible Error Mapping: Typed helper builders and chain-of-responsibility mapper pipeline
- ✅ Problem Details: RFC 7807 compliant error responses out of the box
Installation
dotnet add package UnambitiousFx.Functional.AspNetCore
Setup
Register the services once in your app startup:
builder.Services.AddResultHttp();
The mappers and policy configured here are read from the request services when the response is written, so every
AsHttpBuilder() / AsActionResultBuilder() call without an explicit mapper uses them. Without AddResultHttp, the
built-in defaults apply.
Quick Start
The builders are awaitable: await result.AsHttpBuilder() gives an IResult, await result.AsActionResultBuilder()
gives an IActionResult.
Minimal API
using UnambitiousFx.Functional.AspNetCore.Http;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddResultHttp();
var app = builder.Build();
// Result<T> — success: 200 OK with value, failure: mapped error status
app.MapGet("/users/{id:guid}", async (Guid id, IUserService svc) =>
await svc.GetUserAsync(id).AsHttpBuilder());
// Maybe<T> — Some: 200 OK with value, None: 404 Not Found (by default)
app.MapGet("/profiles/{id:guid}", async (Guid id, IProfileService svc) =>
await svc.TryGetProfileAsync(id).AsHttpBuilder());
// Result (non-generic) — success: 204 No Content (by default), failure: mapped error status
app.MapDelete("/users/{id:guid}", async (Guid id, IUserService svc) =>
await svc.DeleteUserAsync(id).AsHttpBuilder());
// Created response from Result<T>
app.MapPost("/users", async (CreateUserRequest req, IUserService svc) =>
await svc.CreateUserAsync(req).AsHttpBuilder().AsCreated(user => $"/users/{user.Id}"));
app.Run();
MVC Controllers
using UnambitiousFx.Functional.AspNetCore.Mvc;
[ApiController]
[Route("api/[controller]")]
public class UsersController : ControllerBase
{
private readonly IUserService _svc;
public UsersController(IUserService svc) => _svc = svc;
[HttpGet("{id:guid}")]
public async Task<IActionResult> GetUser(Guid id)
=> await _svc.GetUserAsync(id).AsActionResultBuilder();
[HttpGet("profiles/{id:guid}")]
public async Task<IActionResult> GetProfile(Guid id)
// Maybe<T> — Some: 200 OK, None: 404 Not Found (by default)
=> await _svc.TryGetProfileAsync(id).AsActionResultBuilder();
[HttpPost]
public async Task<IActionResult> CreateUser(CreateUserRequest req)
=> await _svc.CreateUserAsync(req)
.AsActionResultBuilder()
.WithResponseFormatter(user => new UserDto(user))
.AsCreated(user => $"/api/users/{user.Id}");
[HttpDelete("{id:guid}")]
public async Task<IActionResult> DeleteUser(Guid id)
=> await _svc.DeleteUserAsync(id).AsActionResultBuilder();
}
Error Handling
The built-in default mapper converts standard failure types to RFC 7807 Problem Details responses:
| Failure Type | HTTP Status |
|---|---|
ValidationFailure |
422 Unprocessable Content |
NotFoundFailure |
404 Not Found |
UnauthorizedFailure |
403 Forbidden |
UnauthenticatedFailure |
401 Unauthorized |
ConflictFailure |
409 Conflict |
ExceptionalFailure |
500 Internal Server Error |
Unrecognised Failure |
500 Internal Server Error, or DefaultStatus(...) |
Example error response (RFC 7807 Problem Details):
{
"type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5.21",
"title": "Validation Error",
"status": 422,
"detail": "Email is required; Password too short",
"code": "VALIDATION",
"errors": { "Email": ["Email is required"], "Password": ["Password too short"] },
"errorCodes": { "Email": ["Required"] }
}
errors groups messages by field (errors without a field use the "" key). errorCodes is present only when at least one ValidationError has a Code.
RFC 9457 validation errors
The dictionary loses the link between a message and its code, the order of the errors, and has no syntax for nested fields. Opt into the RFC 9457 list instead, one entry per ValidationError, in order:
builder.Services.AddResultHttp(o => o.ValidationErrors(ValidationErrorsFormat.Rfc9457));
{
"errors": [
{ "detail": "Must be positive.", "pointer": "#/amount", "code": "amount_negative" },
{ "detail": "At most 2 decimals.", "pointer": "#/payload/movements/3/amount", "code": "amount_scale" },
{ "detail": "The period is closed." }
]
}
detail is the message, pointer the field as a JSON Pointer (ValidationError.Pointer) and code the error code; pointer and code are omitted when null, and no errorCodes is written. A field already written as a pointer (#/… or /…) is kept; a dotted / indexed path (payload.movements[3].amount, $.amount) is converted, escaping ~ and / and percent-encoding characters not allowed in a URI fragment (first name → #/first%20name). ValidationErrorsFormat.AspNetCore (the dictionary) stays the default for now.
Configuration
Global policy defaults
builder.Services.AddResultHttp(options =>
{
// Result (non-generic) success: 204 NoContent (default) or 200 OK
options.Policy = new ResultHttpAdapterPolicy
{
ResultSuccessBehavior = ResultSuccessHttpBehavior.NoContent, // default
MaybeNoneBehavior = MaybeNoneHttpBehavior.NotFound // default
};
// Include the failure message, exception type and stack trace in 500 responses (development only)
options.IncludeExceptionDetails = builder.Environment.IsDevelopment();
});
ResultSuccessHttpBehavior
| Value | Behaviour |
|---|---|
NoContent (default) |
Non-generic Result success → 204 No Content |
Ok |
Non-generic Result success → 200 OK |
MaybeNoneHttpBehavior
| Value | Behaviour |
|---|---|
NotFound (default) |
Maybe<T> None → 404 Not Found |
NoContent |
Maybe<T> None → 204 No Content |
Per-endpoint override
The builders override the global policy and mappers at any call site:
// Status code on success, instead of the policy default
app.MapPost("/publish", async (IPublishService svc) =>
await svc.PublishAsync().AsHttpBuilder().WithStatusCode(StatusCodes.Status200OK));
// Response on None, instead of the policy default
app.MapGet("/drafts/{id}", async (string id, IDraftService svc) =>
await svc.TryGetAsync(id).AsHttpBuilder().AsNone(() => Results.NoContent()));
// Explicit mapper, instead of the one registered by AddResultHttp
app.MapGet("/legacy/{id}", async (string id, ILegacyService svc) =>
await svc.GetAsync(id).AsHttpBuilder(new LegacyFailureMapper()));
Custom error mappers
Typed helper (most common)
Register a handler for a specific failure type using a status code or a factory:
builder.Services.AddResultHttp(options =>
{
// Simple: status code + default ProblemDetails body
options.AddMapper<RateLimitFailure>(429);
options.AddMapper<PaymentRequiredFailure>(402);
// Full control: custom factory
options.AddMapper<RateLimitFailure>(f => new FailureHttpResponse
{
StatusCode = 429,
Body = new { message = f.Message, retryAfter = f.RetryAfterSeconds },
Headers = new Dictionary<string, string>
{
["Retry-After"] = f.RetryAfterSeconds.ToString()
}
});
});
Typed mappers participate in the same first-match-wins chain and fall through to the default mapper for unhandled types.
By failure code
builder.Services.AddResultHttp(options => options
.MapCode("fx.sync_running", 409) // exact code
.MapCodePrefix("documents.", 413) // code prefix; an exact MapCode wins
.DefaultStatus(422) // failures with no mapping, instead of 500
.ExposeMetadata("freeBp", "line")); // metadata keys copied into the ProblemDetails
Code mappings are checked after the typed mappers and before the built-in mapping by type, and keep the body built
for the failure type. The default mapper always writes code into the ProblemDetails extensions; metadata is exposed
only for the keys listed in ExposeMetadata.
Full IFailureHttpMapper implementation
Use this when one mapper needs to handle several related failure types:
public sealed class DomainErrorMapper : IFailureHttpMapper
{
public FailureHttpResponse? GetFailureResponse(IFailure failure) =>
failure switch
{
RateLimitFailure f => new FailureHttpResponse
{
StatusCode = 429,
Body = new { message = f.Message },
Headers = new Dictionary<string, string> { ["Retry-After"] = "60" }
},
PaymentRequiredFailure f => new FailureHttpResponse
{
StatusCode = 402,
Body = new { message = f.Message, subscriptionRequired = true }
},
_ => null // return null to pass to the next mapper in the chain
};
}
builder.Services.AddResultHttp(options =>
{
options.AddMapper(new DomainErrorMapper());
});
Custom mappers registered via AddMapper are tried in the order they are added, before the built-in default mapper.
API Reference
Minimal API (IResult) — namespace UnambitiousFx.Functional.AspNetCore.Http
| Entry point | Available on |
|---|---|
AsHttpBuilder(failureMapper?) |
Result, ValueTask<Result>, Result<T>, ValueTask<Result<T>> |
AsHttpBuilder() |
Maybe<T>, ValueTask<Maybe<T>> |
| Builder method | Result | Result<T> | Maybe<T> | Effect |
|---|---|---|---|---|
WithStatusCode(int) |
✓ | ✓ | ✓ | Success status code (default 200; Result: 204/200 per policy) |
WithHeader(key, value) |
✓ | ✓ | ✓ | Adds a response header on success |
WithResponseFormatter(v => …) |
✓ | ✓ | Maps the value to the response body | |
AsCreated(v => location) |
✓ | ✓ | 201 Created with a Location header |
|
AsNone(() => IResult) |
✓ | Response on None (default 404/204 per policy) |
Failures go through failureMapper when given, else the mapper registered by AddResultHttp, else the default mapper.
MVC (IActionResult) — namespace UnambitiousFx.Functional.AspNetCore.Mvc
AsActionResultBuilder(failureMapper?) on the same types, with the same builder methods. AsNone takes a
Func<IActionResult>.
ResultHttpOptions configuration
| Member | Type | Default | Description |
|---|---|---|---|
Policy |
ResultHttpAdapterPolicy |
Default |
Global success/none behavior defaults |
IncludeExceptionDetails |
bool |
false |
Include message, exception type and stack trace in 500 bodies |
AddMapper(IFailureHttpMapper) |
— | — | Register a custom mapper instance |
AddMapper<TFailure>(int statusCode) |
— | — | Register a typed mapper returning a status code |
AddMapper<TFailure>(Func<TFailure, FailureHttpResponse>) |
— | — | Register a typed mapper with a custom factory |
MapCode(code, statusCode) |
— | — | Map a failure code to a status code |
MapCodePrefix(prefix, statusCode) |
— | — | Map codes starting with a prefix |
DefaultStatus(statusCode) |
— | 500 |
Status of failures with no mapping |
ExposeMetadata(params keys) |
— | none | Copy these metadata keys into the ProblemDetails |
IFailureHttpMapper contract
public interface IFailureHttpMapper
{
/// <summary>
/// Returns a response for the given failure, or null to pass to the next mapper.
/// </summary>
FailureHttpResponse? GetFailureResponse(IFailure failure);
}
FailureHttpResponse properties: StatusCode (required), Body, Headers, ContentType.
Migration from v1
| v1 | v2 |
|---|---|
result.ToHttpResult() |
await result.AsHttpBuilder() |
result.ToHttpResult(v => dto) |
await result.AsHttpBuilder().WithResponseFormatter(v => dto) |
result.ToCreatedHttpResult(loc) |
await result.AsHttpBuilder().AsCreated(loc) |
result.ToActionResult() |
await result.AsActionResultBuilder() |
result.ToCreatedActionResult(...) |
await result.AsActionResultBuilder().AsCreated(v => location) |
options.UseProblemDetails = true |
Removed — Problem Details is always on |
Implicit IFailureHttpMapper.GetStatusCode / GetResponseBody |
Implement GetFailureResponse(IFailure) → FailureHttpResponse? |
Thread Safety
All components are thread-safe and designed for concurrent use in ASP.NET Core applications.
AOT Compatibility
This library is fully compatible with Native AOT compilation. All error mappings use static patterns that do not require runtime code generation.
License
This library is part of the UnambitiousFx project and follows the same license.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 is compatible. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. net11.0 is compatible. |
-
net10.0
- UnambitiousFx.Functional (>= 4.0.0)
-
net11.0
- UnambitiousFx.Functional (>= 4.0.0)
-
net8.0
- UnambitiousFx.Functional (>= 4.0.0)
-
net9.0
- UnambitiousFx.Functional (>= 4.0.0)
NuGet packages (1)
Showing the top 1 NuGet packages that depend on UnambitiousFx.Functional.AspNetCore:
| Package | Downloads |
|---|---|
|
UnambitiousFx.Synapse.AspNetCore
A lightweight, performance-oriented library for building message-driven applications and in-process mediators. Provides composable primitives for Commands, Queries, Events, and Pipelines with a focus on low latency and minimal allocations. |
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 4.0.1 | 5,358 | 11/15/2026 |
| 4.0.0 | 161 | 11/15/2026 |
| 3.1.0 | 88 | 11/15/2026 |
| 3.0.0 | 96 | 11/15/2026 |
| 2.6.0 | 186 | 11/11/2026 |
| 2.5.0 | 87 | 11/11/2026 |
| 2.4.0 | 81 | 11/11/2026 |
| 2.3.0 | 91 | 11/11/2026 |
| 2.2.0 | 853 | 11/9/2026 |
| 2.1.0 | 115 | 11/6/2026 |
| 2.0.9 | 3,033 | 8/13/2026 |
| 2.0.8 | 175 | 8/10/2026 |
| 2.0.7 | 464 | 7/20/2026 |
| 2.0.6 | 870 | 6/27/2026 |
| 2.0.5 | 137 | 5/23/2026 |
| 2.0.4 | 143 | 5/23/2026 |
| 2.0.3 | 325 | 5/14/2026 |
| 2.0.2 | 134 | 5/12/2026 |
| 2.0.1 | 137 | 5/10/2026 |
| 2.0.0 | 219 | 4/8/2026 |