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();

Fields

DeveloperMessagesName

The Data key used to store developer-facing diagnostic details.

Declaration

public const string DeveloperMessagesName = "DeveloperMessages"

Field Value

Type	Description
string

Remarks

Written by Throw(HttpStatusCode, string, Exception?, IEnumerable<string>?, IEnumerable<string>?) and read by GetErrorDetails(HttpRequestException, bool, string?).

Examples

HttpRequestException exception = ...
object? messages = exception.Data[NanoRouteExceptionExtensions.DeveloperMessagesName];

ErrorsName

The Data key used to store client-facing error messages.

Declaration

public const string ErrorsName = "Errors"

Field Value

Type	Description
string

Remarks

Written by Throw(HttpStatusCode, string, Exception?, IEnumerable<string>?, IEnumerable<string>?) and read by GetErrorDetails(HttpRequestException, bool, string?).

Examples

HttpRequestException exception = ...
object? errors = exception.Data[NanoRouteExceptionExtensions.ErrorsName];

StatusName

The Data key used to store the HTTP status code.

Declaration

public const string StatusName = "StatusCode"

Field Value

Type	Description
string

Remarks

Written by Throw(HttpStatusCode, string, Exception?, IEnumerable<string>?, IEnumerable<string>?) and read by GetErrorDetails(HttpRequestException, bool, string?).

Examples

HttpRequestException exception = ...
object? status = exception.Data[NanoRouteExceptionExtensions.StatusName];

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, 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>, 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, 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, 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.

ConfigureExceptionHandling<TBuilder>(TBuilder, ConfigureBuilderDelegate<ExceptionHandlingConfig>)

Updates the exception-handling configuration visible from the current builder scope.

Declaration

public static TBuilder ConfigureExceptionHandling<TBuilder>(this TBuilder routeScopeBuilder, ConfigureBuilderDelegate<ExceptionHandlingConfig> configure) where TBuilder : notnull, RouteScopeBuilder

Parameters

Type	Name	Description
TBuilder	routeScopeBuilder
ConfigureBuilderDelegate<ExceptionHandlingConfig>	configure	A callback that receives the current configuration and returns the replacement configuration.

Returns

Type	Description
TBuilder	The current routeScopeBuilder instance.

Type Parameters

Name	Description
TBuilder

Remarks

The configuration is stored in Metadata. Child builders created after this method is called inherit the updated configuration; existing child builders keep their own scoped copy. Registered exception handlers snapshot the configuration that is current at registration time.

Examples

builder.ConfigureExceptionHandling(config => config with
{
    ExceptionNormalizers = config.ExceptionNormalizers.Remove(typeof(AggregateException))
});

Exceptions

Type	Condition
ArgumentNullException	Thrown when routeScopeBuilder, configure, or the value returned by configure is null.

For<TException>(TypedExceptionNormalizer<TException>)

Creates an exception-normalizer registration for a concrete exception type.

Declaration

public static KeyValuePair<Type, ExceptionNormalizer> For<TException>(TypedExceptionNormalizer<TException> normalizer) where TException : notnull, Exception

Parameters

Type	Name	Description
TypedExceptionNormalizer<TException>	normalizer	The typed normalizer that converts TException into an enriched HttpRequestException.

Returns

Type	Description
KeyValuePair<Type, ExceptionNormalizer>	A key/value pair suitable for adding to ExceptionNormalizers.

Type Parameters

Name	Description
TException	The concrete exception type handled by normalizer.

Remarks

The returned entry is keyed by typeof(TException). Exception handlers perform exact runtime type lookup, so derived exception types need their own registrations.

Examples

builder.ConfigureExceptionHandling(config => config with
{
    ExceptionNormalizers = config.ExceptionNormalizers.SetItems
    ([
        ExceptionNormalizer.For<InvalidOperationException>
        (
            static ex => new HttpRequestException("Conflict", ex, HttpStatusCode.Conflict)
        )
    ])
});

Exceptions

Type	Condition
ArgumentNullException	Thrown when normalizer is null.

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, params IEnumerable<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 IEnumerable<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.
IEnumerable<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.

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.