Skip to main content

Results to HTTP Responses

This guide shows how to turn an IMessageResult into an HTTP response at the edge of an ASP.NET Core Minimal API, without breaking the functional composition chain. For the result type itself -- how to create, inspect, and compose results -- see Results and Errors.

Before You Start​

  • .NET 10.0
  • Install the hosting package -- the terminal operators live here, not in Excalibur.Dispatch:
    dotnet add package Excalibur.Dispatch.Hosting.AspNetCore
  • Familiarity with results and errors

Minimal API Integration​

When using ASP.NET Core Minimal APIs, Dispatch provides terminal operators that convert IMessageResult directly to IResult — enabling fluent ROP chains without breaking the pipeline.

Terminal Operators​

MethodInputHTTP Response
ToApiResult()Task<IMessageResult>202 Accepted
ToApiResult<T>()Task<IMessageResult<T>>200 OK with value
ToNoContentResult()IMessageResult or Task<IMessageResult>204 No Content
ToCreatedResult<T>(location)IMessageResult<T> or Task<IMessageResult<T>>201 Created with location
ToCreatedResult<T>(factory)Task<IMessageResult<T>>201 Created with dynamic location
ToHttpResult()IMessageResult or IMessageResult<T>202 Accepted or 200 OK (sync)

All methods share a ProblemDetails-aware failure mapping:

Failure ConditionHTTP Response
Authorization failed403 Forbidden
Validation failed400 Bad Request
ProblemDetails with StatusRFC 7807 Problem with that status
Other failure500 Internal Server Error

Complete Example: Minimal API Endpoints​

using Excalibur.Dispatch.Hosting.AspNetCore;

var app = builder.Build();

// Query — 200 OK with value
app.MapGet("/orders/{id}", (Guid id, IDispatcher dispatcher, CancellationToken ct) =>
dispatcher
.DispatchAsync<GetOrderAction, Order>(new GetOrderAction(id), ct)
.Map(order => new OrderResponse(order))
.ToApiResult());

// Command — 201 Created with location
app.MapPost("/orders", (CreateOrderRequest request, IDispatcher dispatcher, CancellationToken ct) =>
dispatcher
.DispatchAsync<CreateOrderAction, Order>(
new CreateOrderAction(request.CustomerId, request.Items), ct)
.ToCreatedResult(order => $"/orders/{order.Id}"));

// Command — 204 No Content
app.MapDelete("/orders/{id}", (Guid id, IDispatcher dispatcher, CancellationToken ct) =>
dispatcher
.DispatchAsync(new DeleteOrderAction(id), ct)
.ToNoContentResult());

Notice the difference from an MVC controller, which awaits the dispatch and then branches: the async terminal operators (ToApiResult, ToCreatedResult, ToNoContentResult) accept Task<IMessageResult> directly, so there's no need to await and break the chain.

Custom Response Mapping with Match​

ToApiResult() uses convention-based status codes. When you need full control over the HTTP response for each outcome, use .Match() instead — it's the same ROP operator from Functional Composition, and it works as a terminal operator in Minimal APIs because Match<TIn, IResult> returns Task<IResult> directly:

// Full control — .Match() replaces .ToApiResult()
app.MapGet("/orders/{id}", (Guid id, IDispatcher dispatcher, ILogger<Program> logger, CancellationToken ct) =>
dispatcher
.DispatchAsync<GetOrderAction, Order>(new GetOrderAction(id), ct)
.Map(order => new OrderDto(order))
.Tap(dto => logger.LogInformation("Retrieved order {OrderId}", dto.Id))
.Match(
onSuccess: dto => Results.Ok(dto),
onFailure: problem => problem?.Status switch
{
404 => Results.NotFound(),
400 => Results.BadRequest(problem),
_ => Results.Problem(detail: problem?.Detail)
}));

When to use which terminal:

TerminalUse when
.ToApiResult()Convention-based mapping is sufficient (auto 200/202/403/400/500)
.ToCreatedResult()You need 201 Created with a location URI
.ToNoContentResult()You need 204 No Content for commands
.Match()You need custom per-status response logic (e.g., 404 → NotFound())

.Tap() works anywhere in the chain as a pass-through side effect — use it for logging, metrics, or notifications without affecting the result.

Sync vs Async Usage​

The sync variants (ToHttpResult, ToNoContentResult, ToCreatedResult) work on IMessageResult directly — useful when you already have an awaited result:

app.MapGet("/orders/{id}", async (Guid id, IDispatcher dispatcher, CancellationToken ct) =>
{
var result = await dispatcher.DispatchAsync<GetOrderAction, Order>(
new GetOrderAction(id), ct);

return result.ToHttpResult(); // Sync — returns IResult
});

The async variants accept Task<IMessageResult> and enable full pipeline chaining:

app.MapGet("/orders/{id}", (Guid id, IDispatcher dispatcher, CancellationToken ct) =>
dispatcher
.DispatchAsync<GetOrderAction, Order>(new GetOrderAction(id), ct)
.Map(order => new OrderResponse(order))
.ToApiResult()); // Async — returns Task<IResult>

See Also​