Class NanoRouteExceptionExtensions

Adds helpers for normalizing exceptions and extracting structured error details.

Inheritance

object

NanoRouteExceptionExtensions

Inherited Members

object.GetType()

object.MemberwiseClone()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Namespace: NanoRoute

Assembly: NanoRoute.dll

Syntax

public static class NanoRouteExceptionExtensions

Examples

builder.AddExceptionHandler();

Methods

AddExceptionHandler<TBuilder>(TBuilder)

Adds an exception-handling middleware for all supported HTTP methods.

Declaration

public static TBuilder AddExceptionHandler<TBuilder>(this TBuilder routeScopeBuilder) where TBuilder : notnull, RouteScopeBuilder

Parameters

Type	Name	Description
TBuilder	routeScopeBuilder

Returns

Type	Description
TBuilder	The current routeScopeBuilder instance.

Type Parameters

Name	Description
TBuilder

Remarks

The inserted middleware converts unexpected exceptions into HttpRequestException values with normalized status codes and diagnostic payloads. Existing HttpRequestException values are allowed to flow through unchanged. OperationCanceledException is intentionally not normalized so caller-driven cancellation can propagate unchanged. This overload uses CurrentPrefix as the route pattern, so the middleware is bound to the whole current builder scope for all supported HTTP methods.

Examples

builder.AddExceptionHandler();

Exceptions

Type	Condition
ArgumentNullException	Thrown when routeScopeBuilder is null.

AddExceptionHandler<TBuilder>(TBuilder, Action<ExceptionHandlingOptions>)

Adds an exception-handling middleware for all supported HTTP methods.

Declaration

public static TBuilder AddExceptionHandler<TBuilder>(this TBuilder routeScopeBuilder, Action<ExceptionHandlingOptions> configure) where TBuilder : notnull, RouteScopeBuilder

Parameters

Type	Name	Description
TBuilder	routeScopeBuilder
Action<ExceptionHandlingOptions>	configure	Configures normalizers for this exception-handling middleware.

Returns

Type	Description
TBuilder	The current routeScopeBuilder instance.

Type Parameters

Name	Description
TBuilder

Examples

builder.AddExceptionHandler(options => options.Map<InvalidOperationException>
(
    static ex => new HttpRequestException("Conflict", ex, HttpStatusCode.Conflict)
));

Exceptions

Type	Condition
ArgumentNullException	Thrown when routeScopeBuilder or configure is null.

AddExceptionHandler<TBuilder>(TBuilder, IEnumerable<string>)

Adds an exception-handling middleware for the selected HTTP methods.

Declaration

public static TBuilder AddExceptionHandler<TBuilder>(this TBuilder routeScopeBuilder, IEnumerable<string> verbs) where TBuilder : notnull, RouteScopeBuilder

Parameters

Type	Name	Description
TBuilder	routeScopeBuilder
IEnumerable<string>	verbs	The HTTP methods that should use the exception-handling middleware.

Returns

Type	Description
TBuilder	The current routeScopeBuilder instance.

Type Parameters

Name	Description
TBuilder

Remarks

The inserted middleware converts unexpected exceptions into HttpRequestException values with normalized status codes and diagnostic payloads. Existing HttpRequestException values are allowed to flow through unchanged. OperationCanceledException is intentionally not normalized so caller-driven cancellation can propagate unchanged. This overload uses CurrentPrefix as the route pattern, so the middleware is bound to the whole current builder scope for the selected HTTP methods.

Examples

builder.AddExceptionHandler(["GET", "POST"]);

Exceptions

Type	Condition
ArgumentNullException	Thrown when routeScopeBuilder or verbs is null.
ArgumentException	Thrown when an entry in verbs is not a supported HTTP method.

AddExceptionHandler<TBuilder>(TBuilder, IEnumerable<string>, Action<ExceptionHandlingOptions>)

Adds an exception-handling middleware for the selected HTTP methods.

Declaration

public static TBuilder AddExceptionHandler<TBuilder>(this TBuilder routeScopeBuilder, IEnumerable<string> verbs, Action<ExceptionHandlingOptions> configure) where TBuilder : notnull, RouteScopeBuilder

Parameters

Type	Name	Description
TBuilder	routeScopeBuilder
IEnumerable<string>	verbs	The HTTP methods that should use the exception-handling middleware.
Action<ExceptionHandlingOptions>	configure	Configures normalizers for this exception-handling middleware.

Returns

Type	Description
TBuilder	The current routeScopeBuilder instance.

Type Parameters

Name	Description
TBuilder

Examples

builder.AddExceptionHandler(["GET", "POST"], options => options.Map<InvalidOperationException>
(
    static ex => new HttpRequestException("Conflict", ex, HttpStatusCode.Conflict)
));

Exceptions

Type	Condition
ArgumentNullException	Thrown when routeScopeBuilder, verbs, or configure is null.
ArgumentException	Thrown when an entry in verbs is not a supported HTTP method.

AddExceptionHandler<TBuilder>(TBuilder, IEnumerable<string>, string)

Adds an exception-handling middleware for the selected HTTP methods.

Declaration

public static TBuilder AddExceptionHandler<TBuilder>(this TBuilder routeScopeBuilder, IEnumerable<string> verbs, string pattern) where TBuilder : notnull, RouteScopeBuilder

Parameters

Type	Name	Description
TBuilder	routeScopeBuilder
IEnumerable<string>	verbs	The HTTP methods that should use the exception-handling middleware.
string	pattern	The route pattern where the exception-handling middleware should be inserted. Use / to apply it to the whole pipeline, or a narrower prefix/exact pattern to scope normalization to selected routes.

Returns

Type	Description
TBuilder	The current routeScopeBuilder instance.

Type Parameters

Name	Description
TBuilder

Remarks

The inserted middleware converts unexpected exceptions into HttpRequestException values with normalized status codes and diagnostic payloads. Existing HttpRequestException values are allowed to flow through unchanged. OperationCanceledException is intentionally not normalized so caller-driven cancellation can propagate unchanged.

Examples

builder.AddExceptionHandler(["POST", "PUT"], "/api/users/*");

Exceptions

Type	Condition
ArgumentNullException	Thrown when routeScopeBuilder, verbs, or pattern is null.
ArgumentException	Thrown when an entry in verbs is not supported or pattern has invalid route-template syntax.
InvalidOperationException	Thrown when pattern uses unsupported route-template features, references a missing value parser, or conflicts with an existing parser-backed branch.

AddExceptionHandler<TBuilder>(TBuilder, IEnumerable<string>, string, ExceptionHandlingOptions)

Adds an exception-handling middleware with preconfigured exception normalizers.

Declaration

public static TBuilder AddExceptionHandler<TBuilder>(this TBuilder routeScopeBuilder, IEnumerable<string> verbs, string pattern, ExceptionHandlingOptions options) where TBuilder : notnull, RouteScopeBuilder

Parameters

Type	Name	Description
TBuilder	routeScopeBuilder
IEnumerable<string>	verbs	The HTTP methods that should use the exception-handling middleware.
string	pattern	The route pattern where the exception-handling middleware should be inserted. Use / to apply it to the whole pipeline, or a narrower prefix/exact pattern to scope normalization to selected routes.
ExceptionHandlingOptions	options	The exception-handling options used by this middleware registration.

Returns

Type	Description
TBuilder	The current routeScopeBuilder instance.

Type Parameters

Name	Description
TBuilder

Examples

ExceptionHandlingOptions options = new();
options.Map<InvalidOperationException>(static ex => new HttpRequestException("Conflict", ex, HttpStatusCode.Conflict));

builder.AddExceptionHandler(["POST", "PUT"], "/api/users/*", options);

Exceptions

Type	Condition
ArgumentNullException	Thrown when routeScopeBuilder, verbs, pattern, or options is null.
ArgumentException	Thrown when an entry in verbs is not supported or pattern has invalid route-template syntax.
InvalidOperationException	Thrown when pattern uses unsupported route-template features, references a missing value parser, or conflicts with an existing parser-backed branch.

AddExceptionHandler<TBuilder>(TBuilder, IEnumerable<string>, string, Action<ExceptionHandlingOptions>)

Adds an exception-handling middleware for the selected HTTP methods.

Declaration

public static TBuilder AddExceptionHandler<TBuilder>(this TBuilder routeScopeBuilder, IEnumerable<string> verbs, string pattern, Action<ExceptionHandlingOptions> configure) where TBuilder : notnull, RouteScopeBuilder

Parameters

Type	Name	Description
TBuilder	routeScopeBuilder
IEnumerable<string>	verbs	The HTTP methods that should use the exception-handling middleware.
string	pattern	The route pattern where the exception-handling middleware should be inserted. Use / to apply it to the whole pipeline, or a narrower prefix/exact pattern to scope normalization to selected routes.
Action<ExceptionHandlingOptions>	configure	Configures normalizers for this exception-handling middleware.

Returns

Type	Description
TBuilder	The current routeScopeBuilder instance.

Type Parameters

Name	Description
TBuilder

Remarks

The inserted middleware converts unexpected exceptions into HttpRequestException values with normalized status codes and diagnostic payloads. Existing HttpRequestException values are allowed to flow through unchanged. OperationCanceledException is intentionally not normalized so caller-driven cancellation can propagate unchanged.

Examples

builder.AddExceptionHandler(["POST", "PUT"], "/api/users/*", options => options.Map<InvalidOperationException>
(
    static ex => new HttpRequestException("Conflict", ex, HttpStatusCode.Conflict)
));

Exceptions

Type	Condition
ArgumentNullException	Thrown when routeScopeBuilder, verbs, pattern, or configure is null.
ArgumentException	Thrown when an entry in verbs is not supported or pattern has invalid route-template syntax.
InvalidOperationException	Thrown when pattern uses unsupported route-template features, references a missing value parser, or conflicts with an existing parser-backed branch.

AddExceptionHandler<TBuilder>(TBuilder, string)

Adds an exception-handling middleware for all supported HTTP methods.

Declaration

public static TBuilder AddExceptionHandler<TBuilder>(this TBuilder routeScopeBuilder, string pattern) where TBuilder : notnull, RouteScopeBuilder

Parameters

Type	Name	Description
TBuilder	routeScopeBuilder
string	pattern	The route pattern where the exception-handling middleware should be inserted. Use / to apply it to the whole pipeline, or a narrower prefix/exact pattern to scope normalization to selected routes.

Returns

Type	Description
TBuilder	The current routeScopeBuilder instance.

Type Parameters

Name	Description
TBuilder

Remarks

The inserted middleware converts unexpected exceptions into HttpRequestException values with normalized status codes and diagnostic payloads. Existing HttpRequestException values are allowed to flow through unchanged. OperationCanceledException is intentionally not normalized so caller-driven cancellation can propagate unchanged.

Examples

builder.AddExceptionHandler("/api/*");

Exceptions

Type	Condition
ArgumentNullException	Thrown when routeScopeBuilder or pattern is null.
ArgumentException	Thrown when pattern has invalid route-template syntax.
InvalidOperationException	Thrown when pattern uses unsupported route-template features, references a missing value parser, or conflicts with an existing parser-backed branch.

AddExceptionHandler<TBuilder>(TBuilder, string, Action<ExceptionHandlingOptions>)

Adds an exception-handling middleware for all supported HTTP methods.

Declaration

public static TBuilder AddExceptionHandler<TBuilder>(this TBuilder routeScopeBuilder, string pattern, Action<ExceptionHandlingOptions> configure) where TBuilder : notnull, RouteScopeBuilder

Parameters

Type	Name	Description
TBuilder	routeScopeBuilder
string	pattern	The route pattern where the exception-handling middleware should be inserted. Use / to apply it to the whole pipeline, or a narrower prefix/exact pattern to scope normalization to selected routes.
Action<ExceptionHandlingOptions>	configure	Configures normalizers for this exception-handling middleware.

Returns

Type	Description
TBuilder	The current routeScopeBuilder instance.

Type Parameters

Name	Description
TBuilder

Examples

builder.AddExceptionHandler("/api/*", options => options.Map<InvalidOperationException>
(
    static ex => new HttpRequestException("Conflict", ex, HttpStatusCode.Conflict)
));

Exceptions

Type	Condition
ArgumentNullException	Thrown when routeScopeBuilder, pattern, or configure is null.
ArgumentException	Thrown when pattern has invalid route-template syntax.
InvalidOperationException	Thrown when pattern uses unsupported route-template features, references a missing value parser, or conflicts with an existing parser-backed branch.

AddExceptionHandler<TBuilder>(TBuilder, string, string)

Adds an exception-handling middleware for a single HTTP method.

Declaration

public static TBuilder AddExceptionHandler<TBuilder>(this TBuilder routeScopeBuilder, string verb, string pattern) where TBuilder : notnull, RouteScopeBuilder

Parameters

Type	Name	Description
TBuilder	routeScopeBuilder
string	verb	The HTTP method that should use the exception-handling middleware.
string	pattern	The route pattern where the exception-handling middleware should be inserted. Use / to apply it to the whole pipeline, or a narrower prefix/exact pattern to scope normalization to selected routes.

Returns

Type	Description
TBuilder	The current routeScopeBuilder instance.

Type Parameters

Name	Description
TBuilder

Remarks

The inserted middleware converts unexpected exceptions into HttpRequestException values with normalized status codes and diagnostic payloads. Existing HttpRequestException values are allowed to flow through unchanged. OperationCanceledException is intentionally not normalized so caller-driven cancellation can propagate unchanged.

Examples

builder.AddExceptionHandler("GET", "/api/*");

Exceptions

Type	Condition
ArgumentNullException	Thrown when routeScopeBuilder, verb, or pattern is null.
ArgumentException	Thrown when verb is not supported or pattern has invalid route-template syntax.
InvalidOperationException	Thrown when pattern uses unsupported route-template features, references a missing value parser, or conflicts with an existing parser-backed branch.

AddExceptionHandler<TBuilder>(TBuilder, string, string, Action<ExceptionHandlingOptions>)

Adds an exception-handling middleware for a single HTTP method.

Declaration

public static TBuilder AddExceptionHandler<TBuilder>(this TBuilder routeScopeBuilder, string verb, string pattern, Action<ExceptionHandlingOptions> configure) where TBuilder : notnull, RouteScopeBuilder

Parameters

Type	Name	Description
TBuilder	routeScopeBuilder
string	verb	The HTTP method that should use the exception-handling middleware.
string	pattern	The route pattern where the exception-handling middleware should be inserted. Use / to apply it to the whole pipeline, or a narrower prefix/exact pattern to scope normalization to selected routes.
Action<ExceptionHandlingOptions>	configure	Configures normalizers for this exception-handling middleware.

Returns

Type	Description
TBuilder	The current routeScopeBuilder instance.

Type Parameters

Name	Description
TBuilder

Examples

builder.AddExceptionHandler("GET", "/api/*", options => options.Map<InvalidOperationException>
(
    static ex => new HttpRequestException("Conflict", ex, HttpStatusCode.Conflict)
));

Exceptions

Type	Condition
ArgumentNullException	Thrown when routeScopeBuilder, verb, pattern, or configure is null.
ArgumentException	Thrown when verb is not supported or pattern has invalid route-template syntax.
InvalidOperationException	Thrown when pattern uses unsupported route-template features, references a missing value parser, or conflicts with an existing parser-backed branch.

GetErrorDetails(HttpRequestException, bool, string?)

Converts an HttpRequestException into an ErrorDetails payload.

Declaration

public static ErrorDetails GetErrorDetails(this HttpRequestException requestException, bool populateErrorInfo = false, string? traceId = null)

Parameters

Type	Name	Description
HttpRequestException	requestException
bool	populateErrorInfo	true to include developer-facing details when present; otherwise false.
string	traceId	The trace identifier to expose in the resulting payload.

Returns

Type	Description
ErrorDetails	The structured error payload.

Examples

ErrorDetails details = exception.GetErrorDetails(populateErrorInfo: false, traceId);

Exceptions

Type	Condition
ArgumentNullException	Thrown when requestException is null.

Throw(HttpStatusCode, string, Exception?, IEnumerable<string>?, IEnumerable<string>?)

Throws an HttpRequestException enriched with routing-specific metadata.

Declaration

[DoesNotReturn]
public static void Throw(HttpStatusCode status, string title, Exception? original = null, IEnumerable<string>? errors = null, IEnumerable<string>? developerMessages = null)

Parameters

Type	Name	Description
HttpStatusCode	status	The HTTP status code that should be associated with the exception.
string	title	The human-readable error title.
Exception	original	The original exception, if any.
IEnumerable<string>	errors	Optional client-facing error messages that should not contain sensitive data.
IEnumerable<string>	developerMessages	Optional developer-facing messages that may contain sensitive data.

Examples

Exception original = ...
HttpRequestException.Throw
(
    HttpStatusCode.Conflict,
    "Conflict",
    original,
    errors: ["The resource has changed."],
    developerMessages: [original.ToString()]
);

Exceptions

Type	Condition
HttpRequestException	Always thrown with the supplied status and error metadata.

Throw(HttpStatusCode, string, params string[])

Throws an HttpRequestException enriched with an HTTP status code and public error messages.

Declaration

[DoesNotReturn]
public static void Throw(HttpStatusCode status, string title, params string[] errors)

Parameters

Type	Name	Description
HttpStatusCode	status	The HTTP status code that should be associated with the exception.
string	title	The human-readable error title.
string[]	errors	Optional client-facing error messages that should not contain sensitive data.

Examples

HttpRequestException.Throw(HttpStatusCode.BadRequest, "Bad Request", "Missing id.");

Exceptions

Type	Condition
HttpRequestException	Always thrown with the supplied status and error metadata.

get_DeveloperMessages(HttpRequestException)

Gets or sets the developer-facing diagnostic messages associated with this exception.

Declaration

public static IEnumerable<string>? get_DeveloperMessages(HttpRequestException requestException)

Parameters

Type	Name	Description
HttpRequestException	requestException

Returns

Type	Description
IEnumerable<string>

Examples

exception.DeveloperMessages = [original.ToString()];
IEnumerable<string>? messages = exception.DeveloperMessages;

Exceptions

Type	Condition
ArgumentNullException	Thrown when the extended exception is null.

get_Errors(HttpRequestException)

Gets or sets the client-facing error messages associated with this exception.

Declaration

public static IEnumerable<string>? get_Errors(HttpRequestException requestException)

Parameters

Type	Name	Description
HttpRequestException	requestException

Returns

Type	Description
IEnumerable<string>

Examples

exception.Errors = ["Missing id."];
IEnumerable<string>? errors = exception.Errors;

Exceptions

Type	Condition
ArgumentNullException	Thrown when the extended exception is null.

get_Status(HttpRequestException)

Gets or sets the HTTP status code associated with this exception.

Declaration

public static HttpStatusCode get_Status(HttpRequestException requestException)

Parameters

Type	Name	Description
HttpRequestException	requestException

Returns

Type	Description
HttpStatusCode

Examples

exception.Status = HttpStatusCode.BadRequest;
HttpStatusCode status = exception.Status;

Exceptions

Type	Condition
ArgumentNullException	Thrown when the extended exception is null.

set_DeveloperMessages(HttpRequestException, IEnumerable<string>?)

Gets or sets the developer-facing diagnostic messages associated with this exception.

Declaration

public static void set_DeveloperMessages(HttpRequestException requestException, IEnumerable<string>? value)

Parameters

Type	Name	Description
HttpRequestException	requestException
IEnumerable<string>	value

Examples

exception.DeveloperMessages = [original.ToString()];
IEnumerable<string>? messages = exception.DeveloperMessages;

Exceptions

Type	Condition
ArgumentNullException	Thrown when the extended exception is null.

set_Errors(HttpRequestException, IEnumerable<string>?)

Gets or sets the client-facing error messages associated with this exception.

Declaration

public static void set_Errors(HttpRequestException requestException, IEnumerable<string>? value)

Parameters

Type	Name	Description
HttpRequestException	requestException
IEnumerable<string>	value

Examples

exception.Errors = ["Missing id."];
IEnumerable<string>? errors = exception.Errors;

Exceptions

Type	Condition
ArgumentNullException	Thrown when the extended exception is null.

set_Status(HttpRequestException, HttpStatusCode)

Gets or sets the HTTP status code associated with this exception.

Declaration

public static void set_Status(HttpRequestException requestException, HttpStatusCode value)

Parameters

Type	Name	Description
HttpRequestException	requestException
HttpStatusCode	value

Examples

exception.Status = HttpStatusCode.BadRequest;
HttpStatusCode status = exception.Status;

Exceptions

Type	Condition
ArgumentNullException	Thrown when the extended exception is null.