UnambitiousFx.Functional.AspNetCore 3.0.0

There is a newer version of this package available.
See the version list below for details.
dotnet add package UnambitiousFx.Functional.AspNetCore --version 3.0.0
                    
NuGet\Install-Package UnambitiousFx.Functional.AspNetCore -Version 3.0.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="UnambitiousFx.Functional.AspNetCore" Version="3.0.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="UnambitiousFx.Functional.AspNetCore" Version="3.0.0" />
                    
Directory.Packages.props
<PackageReference Include="UnambitiousFx.Functional.AspNetCore" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add UnambitiousFx.Functional.AspNetCore --version 3.0.0
                    
#r "nuget: UnambitiousFx.Functional.AspNetCore, 3.0.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package UnambitiousFx.Functional.AspNetCore@3.0.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=UnambitiousFx.Functional.AspNetCore&version=3.0.0
                    
Install as a Cake Addin
#tool nuget:?package=UnambitiousFx.Functional.AspNetCore&version=3.0.0
                    
Install as a Cake Tool

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> to IResult
  • ✅ MVC Controller Support: Convert Result<T> / Maybe<T> to IActionResult
  • ✅ async-first: First-class ValueTask<Result<T>> and ValueTask<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 400 Bad Request
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://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 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 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. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

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
Loading failed