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
mapperFunc<TException, CancellationToken, Task<IMessageProblemDetails>>An async function that converts the exception to problem details.
Returns
- IExceptionMappingBuilder
The builder for fluent configuration.
Type Parameters
TExceptionThe 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
mapperFunc<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
predicateFunc<TException, bool>A predicate that determines if this mapping should be used.
mapperFunc<TException, IMessageProblemDetails>A function that converts the exception to problem details.
Returns
- IExceptionMappingBuilder
The builder for fluent configuration.
Type Parameters
TExceptionThe 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
mapperFunc<TException, IMessageProblemDetails>A function that converts the exception to problem details.
Returns
- IExceptionMappingBuilder
The builder for fluent configuration.
Type Parameters
TExceptionThe 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.