Table of Contents

Interface IExceptionMappingBuilder

Namespace
Excalibur.Dispatch.Configuration
Assembly
Excalibur.Dispatch.Abstractions.dll

Fluent builder interface for configuring exception-to-problem-details mappings.

public interface IExceptionMappingBuilder
Extension Methods

Remarks

Provides a fluent API for registering mappings that convert exceptions to RFC 7807 Problem Details format. Mappings are evaluated in registration order, with the first matching mapper being used.

Example usage:

builder.WithExceptionMapping(mapping =>
{
    mapping.UseApiExceptionMapping();     // Auto-map ApiException hierarchy
    mapping.Map<DbException>(ex => new MessageProblemDetails { ... });
    mapping.MapWhen<HttpRequestException>(
        ex => ex.StatusCode == HttpStatusCode.NotFound,
        ex => new MessageProblemDetails { Status = 404 });
    mapping.MapDefault(ex => MessageProblemDetails.InternalError("An unexpected error occurred."));
});

Methods

MapAsync<TException>(Func<TException, CancellationToken, Task<IMessageProblemDetails>>)

Registers an asynchronous mapping for a specific exception type.

IExceptionMappingBuilder MapAsync<TException>(Func<TException, CancellationToken, Task<IMessageProblemDetails>> mapper) where TException : Exception

Parameters

mapper Func<TException, CancellationToken, Task<IMessageProblemDetails>>

An async function that converts the exception to problem details.

Returns

IExceptionMappingBuilder

The builder for fluent configuration.

Type Parameters

TException

The type of exception to map.

Remarks

Use async mappings when the conversion requires I/O operations, such as looking up error details from a database or external service.

MapDefault(Func<Exception, IMessageProblemDetails>)

Registers a default mapping for exceptions that don't match any specific mapping.

IExceptionMappingBuilder MapDefault(Func<Exception, IMessageProblemDetails> mapper)

Parameters

mapper Func<Exception, IMessageProblemDetails>

A function that converts any exception to problem details.

Returns

IExceptionMappingBuilder

The builder for fluent configuration.

Remarks

The default mapper is used as a fallback when no type-specific mapping matches. If not specified, a built-in default mapper returns a 500 Internal Server Error.

MapWhen<TException>(Func<TException, bool>, Func<TException, IMessageProblemDetails>)

Registers a conditional mapping for a specific exception type.

IExceptionMappingBuilder MapWhen<TException>(Func<TException, bool> predicate, Func<TException, IMessageProblemDetails> mapper) where TException : Exception

Parameters

predicate Func<TException, bool>

A predicate that determines if this mapping should be used.

mapper Func<TException, IMessageProblemDetails>

A function that converts the exception to problem details.

Returns

IExceptionMappingBuilder

The builder for fluent configuration.

Type Parameters

TException

The type of exception to map.

Remarks

Use conditional mappings when different instances of the same exception type should map to different problem details based on exception properties.

Map<TException>(Func<TException, IMessageProblemDetails>)

Registers a synchronous mapping for a specific exception type.

IExceptionMappingBuilder Map<TException>(Func<TException, IMessageProblemDetails> mapper) where TException : Exception

Parameters

mapper Func<TException, IMessageProblemDetails>

A function that converts the exception to problem details.

Returns

IExceptionMappingBuilder

The builder for fluent configuration.

Type Parameters

TException

The type of exception to map.

Remarks

Mappings are evaluated in registration order. The first mapping that handles the exception type (or a base type) wins.

UseApiExceptionMapping()

Enables automatic mapping of ApiException and derived types using their ToProblemDetails() method.

IExceptionMappingBuilder UseApiExceptionMapping()

Returns

IExceptionMappingBuilder

The builder for fluent configuration.

Remarks

When enabled, any exception that inherits from ApiException will automatically use its ToProblemDetails() method to generate problem details.

This is enabled by default. Call this method to explicitly enable it if you previously disabled it, or to ensure the behavior in configuration.