UnambitiousFx.Functional.AspNetCore
2.6.0
See the version list below for details.
dotnet add package UnambitiousFx.Functional.AspNetCore --version 2.6.0
NuGet\Install-Package UnambitiousFx.Functional.AspNetCore -Version 2.6.0
<PackageReference Include="UnambitiousFx.Functional.AspNetCore" Version="2.6.0" />
<PackageVersion Include="UnambitiousFx.Functional.AspNetCore" Version="2.6.0" />
<PackageReference Include="UnambitiousFx.Functional.AspNetCore" />
paket add UnambitiousFx.Functional.AspNetCore --version 2.6.0
#r "nuget: UnambitiousFx.Functional.AspNetCore, 2.6.0"
#:package UnambitiousFx.Functional.AspNetCore@2.6.0
#addin nuget:?package=UnambitiousFx.Functional.AspNetCore&version=2.6.0
#tool nuget:?package=UnambitiousFx.Functional.AspNetCore&version=2.6.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>>andTask<Result<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 required services once in your app startup:
builder.Services.AddResultHttp();
Quick Start
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).ToHttpResult());
// 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).ToHttpResult());
// Result (non-generic) — success: 204 No Content, failure: mapped error status
app.MapDelete("/users/{id:guid}", async (Guid id, IUserService svc) =>
await svc.DeleteUserAsync(id).ToHttpResult());
// Created response from Result<T>
app.MapPost("/users", async (CreateUserRequest req, IUserService svc) =>
await svc.CreateUserAsync(req).ToCreatedHttpResult(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).ToActionResult();
[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).ToActionResult();
[HttpPost]
public async Task<IActionResult> CreateUser(CreateUserRequest req)
// Pass a success mapper lambda to return 201 Created
=> await _svc.CreateUserAsync(req)
.ToActionResult(user => new CreatedAtActionResult(
nameof(GetUser), null, new { id = user.Id }, user));
[HttpDelete("{id:guid}")]
public async Task<IActionResult> DeleteUser(Guid id)
=> await _svc.DeleteUserAsync(id).ToActionResult();
}
Error Handling
The built-in default mapper converts standard failure types to RFC 7807 Problem Details responses:
| Failure Type | HTTP Status |
|---|---|
ValidationFailure |
400 Bad Request |
NotFoundFailure |
404 Not Found |
UnauthorizedFailure |
401 Unauthorized |
UnauthenticatedFailure |
403 Forbidden |
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://tools.ietf.org/html/rfc7231#section-6.5.1",
"title": "Validation Error",
"status": 400,
"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.
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 policy override
The global policy can be overridden at any call site:
var policy = new ResultHttpAdapterPolicy
{
ResultSuccessBehavior = ResultSuccessHttpBehavior.Ok
};
app.MapPost("/publish", async (IPublishService svc) =>
await svc.PublishAsync().ToHttpResult(policy: policy));
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
Result (non-generic)
| Method | Success | Failure |
|---|---|---|
ToHttpResult(successMapper?, failureMapper?, policy?) |
successMapper() or 204/200 per policy |
Mapped error |
Available on: Result, ValueTask<Result>, Task<Result>.
Result<T>
| Method | Success | Failure |
|---|---|---|
ToHttpResult(successMapper?, failureMapper?) |
successMapper(value) or 200 OK(value) |
Mapped error |
ToCreatedHttpResult(locationFactory, failureMapper?) |
201 Created(location, value) |
Mapped error |
Available on: Result<T>, ValueTask<Result<T>>, Task<Result<T>>.
Maybe<T>
| Method | Some | None |
|---|---|---|
ToHttpResult(someMapper?, noneMapper?, policy?) |
someMapper(value) or 200 OK(value) |
noneMapper() or 404/204 per policy |
ToCreatedHttpResult(locationFactory, noneMapper?, policy?) |
201 Created(location, value) |
noneMapper() or 404/204 per policy |
Available on: Maybe<T>, ValueTask<Maybe<T>>, Task<Maybe<T>>.
MVC (IActionResult) — namespace UnambitiousFx.Functional.AspNetCore.Mvc
Result (non-generic)
| Method | Success | Failure |
|---|---|---|
ToActionResult(successMapper?, failureMapper?, policy?) |
successMapper() or 204/200 per policy |
Mapped error |
Available on: Result, ValueTask<Result>, Task<Result>.
Result<T>
| Method | Success | Failure |
|---|---|---|
ToActionResult(successMapper?, failureMapper?) |
successMapper(value) or OkObjectResult(value) |
Mapped error |
Available on: Result<T>, ValueTask<Result<T>>, Task<Result<T>>.
Maybe<T>
| Method | Some | None |
|---|---|---|
ToActionResult(someMapper?, noneMapper?, policy?) |
someMapper(value) or OkObjectResult(value) |
noneMapper() or 404/204 per policy |
Available on: Maybe<T>, ValueTask<Maybe<T>>, Task<Maybe<T>>.
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(v => dto) |
result.ToHttpResult(v => Results.Ok(dto)) |
result.ToCreatedHttpResult(loc, v => dto) |
result.ToCreatedHttpResult(loc) — value returned directly |
result.ToCreatedActionResult("Get", ctrl, routes) |
result.ToActionResult(v => new CreatedAtActionResult("Get", ctrl, routes, v)) |
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 (>= 2.6.0)
-
net11.0
- UnambitiousFx.Functional (>= 2.6.0)
-
net8.0
- UnambitiousFx.Functional (>= 2.6.0)
-
net9.0
- UnambitiousFx.Functional (>= 2.6.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 |