Class NanoRouteHandlerExtensions

Adds typed handler overloads that project a RequestContext into a request object.

Inheritance

object

NanoRouteHandlerExtensions

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 NanoRouteHandlerExtensions

Remarks

By default, writable public properties are bound from Parameters using the property name as the lookup key.

Properties of type RequestContext and CancellationToken are populated automatically from the current request.

Use ValueSourceAttribute to bind a property from a specific parameter key or service. Missing required parameter values and services throw InvalidOperationException.

Examples

builder
    .AddDefaultValueParsers()
    .AddHandler<UserRequest>("GET", "/users/{id:int}/", request =>
        Results.Ok(request.Id));

Methods

AddHandler<TBuilder>(TBuilder, IEnumerable<string>, RequestHandlerDelegate)

Registers the same handler for multiple HTTP methods at the current builder root.

Declaration

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

Parameters

Type	Name	Description
TBuilder	routeScopeBuilder
IEnumerable<string>	verbs	The HTTP methods that should use the handler.
RequestHandlerDelegate	handler	The handler to execute when a matching request enters this builder scope.

Returns

Type	Description
TBuilder	The current router instance.

Type Parameters

Name	Description
TBuilder

Remarks

This overload uses CurrentPrefix as the route pattern, so the handler is bound to the whole current builder scope. If the handler calls next, routing continues with the next compatible handler on the selected branch.

Examples

builder.AddHandler(["GET", "POST"], (context, next) => next());

Exceptions

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

AddHandler<TBuilder>(TBuilder, IEnumerable<string>, string, RequestHandlerDelegate)

Registers the same handler for multiple HTTP methods.

Declaration

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

Parameters

Type	Name	Description
TBuilder	routeScopeBuilder
IEnumerable<string>	verbs	The HTTP methods that should use the handler.
string	pattern	The route pattern to match. Literal segments are matched case-insensitively, parameter segments use registered parsers in the form {parameterName:parserName}. Exact patterns must end with /, prefix patterns must end with /*, and repeated / separators are invalid.
RequestHandlerDelegate	handler	The handler to execute when the route matches.

Returns

Type	Description
TBuilder	The current router instance.

Type Parameters

Name	Description
TBuilder

Examples

builder.AddHandler(
    ["GET", "POST"],
    "/api/items/{id:int}/",
    (context, next) => Results.Ok(context.Parameters["id"]));

Exceptions

Type	Condition
ArgumentNullException	Thrown when routeScopeBuilder, verbs, pattern, or handler 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.

AddHandler<TBuilder>(TBuilder, string, RequestHandlerDelegate)

Registers a handler for all supported HTTP methods.

Declaration

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

Parameters

Type	Name	Description
TBuilder	routeScopeBuilder
string	pattern	The route pattern to match. Literal segments are matched case-insensitively, parameter segments use registered parsers in the form {parameterName:parserName}. Exact patterns must end with /, prefix patterns must end with /*, and repeated / separators are invalid.
RequestHandlerDelegate	handler	The handler to execute when the pattern matches.

Returns

Type	Description
TBuilder	The current router instance.

Type Parameters

Name	Description
TBuilder

Examples

builder.AddHandler("/health/", (context, next) => Results.Ok());

Exceptions

Type	Condition
ArgumentNullException	Thrown when routeScopeBuilder, pattern, or handler 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.

AddHandler<TBuilder, TRequestContext>(TBuilder, IEnumerable<string>, string, TypedRequestEndpointHandlerDelegate<TRequestContext>)

Registers a typed handler that receives a request object built from the current RequestContext.

Declaration

public static TBuilder AddHandler<TBuilder, TRequestContext>(this TBuilder routeScopeBuilder, IEnumerable<string> verbs, string pattern, TypedRequestEndpointHandlerDelegate<TRequestContext> handler) where TBuilder : notnull, RouteScopeBuilder where TRequestContext : notnull, new()

Parameters

Type	Name	Description
TBuilder	routeScopeBuilder
IEnumerable<string>	verbs	The HTTP verbs handled by the route.
string	pattern	The route pattern to register.
TypedRequestEndpointHandlerDelegate<TRequestContext>	handler	The typed handler delegate.

Returns

Type	Description
TBuilder	The current routeScopeBuilder.

Type Parameters

Name	Description
TBuilder
TRequestContext	The request-object type populated from the current route parameters, query bindings, services, and special framework values.

Remarks

Writable public properties are bound from Parameters by default.

A property of type RequestContext receives the current context, and a property of type CancellationToken receives the active request token.

Apply ValueSourceAttribute to bind a property from a different parameter name or from the request service provider.

Examples

builder.AddHandler<UserRequest>(["GET", "HEAD"], "/users/{id:int}/", request =>
    Results.Ok(request.Id));

Exceptions

Type	Condition
ArgumentNullException	Thrown when routeScopeBuilder, verbs, pattern, or handler is null.
ArgumentException	Thrown when an entry in verbs is not supported or pattern has invalid route-template syntax.
InvalidOperationException	Thrown for unsupported route-template features, missing value parsers, conflicting parser-backed branches, or when request-time typed binding cannot resolve a required parameter or service.

AddHandler<TBuilder, TRequestContext>(TBuilder, IEnumerable<string>, string, TypedRequestHandlerDelegate<TRequestContext>)

Registers a typed handler that receives a request object and the next handler in the pipeline.

Declaration

public static TBuilder AddHandler<TBuilder, TRequestContext>(this TBuilder routeScopeBuilder, IEnumerable<string> verbs, string pattern, TypedRequestHandlerDelegate<TRequestContext> handler) where TBuilder : notnull, RouteScopeBuilder where TRequestContext : notnull, new()

Parameters

Type	Name	Description
TBuilder	routeScopeBuilder
IEnumerable<string>	verbs	The HTTP verbs handled by the route.
string	pattern	The route pattern to register.
TypedRequestHandlerDelegate<TRequestContext>	handler	The typed handler delegate.

Returns

Type	Description
TBuilder	The current routeScopeBuilder.

Type Parameters

Name	Description
TBuilder
TRequestContext	The request-object type populated from the current route parameters, query bindings, services, and special framework values.

Remarks

Writable public properties are bound from Parameters by default.

A property of type RequestContext receives the current context, and a property of type CancellationToken receives the active request token.

Apply ValueSourceAttribute to bind a property from a different parameter name or from the request service provider.

Examples

builder.AddHandler<UserRequest>(["GET", "POST"], "/users/{id:int}/*", (request, next) => next());

Exceptions

Type	Condition
ArgumentNullException	Thrown when routeScopeBuilder, verbs, pattern, or handler is null.
ArgumentException	Thrown when an entry in verbs is not supported or pattern has invalid route-template syntax.
InvalidOperationException	Thrown for unsupported route-template features, missing value parsers, conflicting parser-backed branches, or when request-time typed binding cannot resolve a required parameter or service.

AddHandler<TBuilder, TRequestContext>(TBuilder, string, TypedRequestEndpointHandlerDelegate<TRequestContext>)

Registers a typed handler that receives a request object built from the current RequestContext.

Declaration

public static TBuilder AddHandler<TBuilder, TRequestContext>(this TBuilder routeScopeBuilder, string pattern, TypedRequestEndpointHandlerDelegate<TRequestContext> handler) where TBuilder : notnull, RouteScopeBuilder where TRequestContext : notnull, new()

Parameters

Type	Name	Description
TBuilder	routeScopeBuilder
string	pattern	The route pattern to register for all supported HTTP methods.
TypedRequestEndpointHandlerDelegate<TRequestContext>	handler	The typed handler delegate.

Returns

Type	Description
TBuilder	The current routeScopeBuilder.

Type Parameters

Name	Description
TBuilder
TRequestContext	The request-object type populated from the current route parameters, query bindings, services, and special framework values.

Remarks

Writable public properties are bound from Parameters by default.

A property of type RequestContext receives the current context, and a property of type CancellationToken receives the active request token.

Apply ValueSourceAttribute to bind a property from a different parameter name or from the request service provider.

Examples

builder.AddHandler<UserRequest>("/users/{id:int}/", request =>
    Results.Ok(request.Id));

Exceptions

Type	Condition
ArgumentNullException	Thrown when routeScopeBuilder, pattern, or handler is null.
ArgumentException	Thrown when pattern has invalid route-template syntax.
InvalidOperationException	Thrown for unsupported route-template features, missing value parsers, conflicting parser-backed branches, or when request-time typed binding cannot resolve a required parameter or service.

AddHandler<TBuilder, TRequestContext>(TBuilder, string, TypedRequestHandlerDelegate<TRequestContext>)

Registers a typed handler that receives a request object and the next handler in the pipeline.

Declaration

public static TBuilder AddHandler<TBuilder, TRequestContext>(this TBuilder routeScopeBuilder, string pattern, TypedRequestHandlerDelegate<TRequestContext> handler) where TBuilder : notnull, RouteScopeBuilder where TRequestContext : notnull, new()

Parameters

Type	Name	Description
TBuilder	routeScopeBuilder
string	pattern	The route pattern to register for all supported HTTP methods.
TypedRequestHandlerDelegate<TRequestContext>	handler	The typed handler delegate.

Returns

Type	Description
TBuilder	The current routeScopeBuilder.

Type Parameters

Name	Description
TBuilder
TRequestContext	The request-object type populated from the current route parameters, query bindings, services, and special framework values.

Remarks

Writable public properties are bound from Parameters by default.

A property of type RequestContext receives the current context, and a property of type CancellationToken receives the active request token.

Apply ValueSourceAttribute to bind a property from a different parameter name or from the request service provider.

Examples

builder.AddHandler<UserRequest>("/users/{id:int}/*", (request, next) => next());

Exceptions

Type	Condition
ArgumentNullException	Thrown when routeScopeBuilder, pattern, or handler is null.
ArgumentException	Thrown when pattern has invalid route-template syntax.
InvalidOperationException	Thrown for unsupported route-template features, missing value parsers, conflicting parser-backed branches, or when request-time typed binding cannot resolve a required parameter or service.

AddHandler<TBuilder, TRequestContext>(TBuilder, string, string, TypedRequestEndpointHandlerDelegate<TRequestContext>)

Registers a typed handler that receives a request object built from the current RequestContext.

Declaration

public static TBuilder AddHandler<TBuilder, TRequestContext>(this TBuilder routeScopeBuilder, string verb, string pattern, TypedRequestEndpointHandlerDelegate<TRequestContext> handler) where TBuilder : notnull, RouteScopeBuilder where TRequestContext : notnull, new()

Parameters

Type	Name	Description
TBuilder	routeScopeBuilder
string	verb	The HTTP verb handled by the route.
string	pattern	The route pattern to register.
TypedRequestEndpointHandlerDelegate<TRequestContext>	handler	The typed handler delegate.

Returns

Type	Description
TBuilder	The current routeScopeBuilder.

Type Parameters

Name	Description
TBuilder
TRequestContext	The request-object type populated from the current route parameters, query bindings, services, and special framework values.

Remarks

Writable public properties are bound from Parameters by default.

A property of type RequestContext receives the current context, and a property of type CancellationToken receives the active request token.

Apply ValueSourceAttribute to bind a property from a different parameter name or from the request service provider.

Examples

builder.AddHandler<UserRequest>("GET", "/users/{id:int}/", request =>
    Results.Ok(request.Id));

Exceptions

Type	Condition
ArgumentNullException	Thrown when routeScopeBuilder, verb, pattern, or handler is null.
ArgumentException	Thrown when verb is not supported or pattern has invalid route-template syntax.
InvalidOperationException	Thrown for unsupported route-template features, missing value parsers, conflicting parser-backed branches, or when request-time typed binding cannot resolve a required parameter or service.

AddHandler<TBuilder, TRequestContext>(TBuilder, string, string, TypedRequestHandlerDelegate<TRequestContext>)

Registers a typed handler that receives a request object and the next handler in the pipeline.

Declaration

public static TBuilder AddHandler<TBuilder, TRequestContext>(this TBuilder routeScopeBuilder, string verb, string pattern, TypedRequestHandlerDelegate<TRequestContext> handler) where TBuilder : notnull, RouteScopeBuilder where TRequestContext : notnull, new()

Parameters

Type	Name	Description
TBuilder	routeScopeBuilder
string	verb	The HTTP verb handled by the route.
string	pattern	The route pattern to register.
TypedRequestHandlerDelegate<TRequestContext>	handler	The typed handler delegate.

Returns

Type	Description
TBuilder	The current routeScopeBuilder.

Type Parameters

Name	Description
TBuilder
TRequestContext	The request-object type populated from the current route parameters, query bindings, services, and special framework values.

Remarks

Writable public properties are bound from Parameters by default.

A property of type RequestContext receives the current context, and a property of type CancellationToken receives the active request token.

Apply ValueSourceAttribute to bind a property from a different parameter name or from the request service provider.

Examples

builder.AddHandler<UserRequest>("GET", "/users/{id:int}/*", (request, next) => next());

Exceptions

Type	Condition
ArgumentNullException	Thrown when routeScopeBuilder, verb, pattern, or handler is null.
ArgumentException	Thrown when verb is not supported or pattern has invalid route-template syntax.
InvalidOperationException	Thrown for unsupported route-template features, missing value parsers, conflicting parser-backed branches, or when request-time typed binding cannot resolve a required parameter or service.

WithHandler<TRequestContext>(EndpointBuilder, TypedRequestEndpointHandlerDelegate<TRequestContext>)

Registers a typed endpoint handler that receives a request object built from the current RequestContext.

Declaration

public static EndpointBuilder WithHandler<TRequestContext>(this EndpointBuilder endpointBuilder, TypedRequestEndpointHandlerDelegate<TRequestContext> handler) where TRequestContext : notnull, new()

Parameters

Type	Name	Description
EndpointBuilder	endpointBuilder
TypedRequestEndpointHandlerDelegate<TRequestContext>	handler	The typed endpoint handler delegate.

Returns

Type	Description
EndpointBuilder	The current endpointBuilder instance.

Type Parameters

Name	Description
TRequestContext	The request-object type populated from the current route parameters, query bindings, services, and special framework values.

Remarks

Writable public properties are bound from Parameters by default.

A property of type RequestContext receives the current context, and a property of type CancellationToken receives the active request token.

Apply ValueSourceAttribute to bind a property from a different parameter name or from the request service provider.

Examples

endpoint.WithHandler<UserRequest>(request => Results.Ok(request.Id));

Exceptions

Type	Condition
ArgumentNullException	Thrown when endpointBuilder or handler is null.
ArgumentException	Thrown when the endpoint's captured HTTP method is not supported.
InvalidOperationException	Thrown when request-time typed binding cannot resolve a required parameter or service.

WithHandler<TRequestContext>(EndpointBuilder, TypedRequestHandlerDelegate<TRequestContext>)

Registers a typed endpoint handler that receives a request object and the next handler in the pipeline.

Declaration

public static EndpointBuilder WithHandler<TRequestContext>(this EndpointBuilder endpointBuilder, TypedRequestHandlerDelegate<TRequestContext> handler) where TRequestContext : notnull, new()

Parameters

Type	Name	Description
EndpointBuilder	endpointBuilder
TypedRequestHandlerDelegate<TRequestContext>	handler	The typed endpoint handler delegate.

Returns

Type	Description
EndpointBuilder	The current endpointBuilder instance.

Type Parameters

Name	Description
TRequestContext	The request-object type populated from the current route parameters, query bindings, services, and special framework values.

Remarks

Writable public properties are bound from Parameters by default.

A property of type RequestContext receives the current context, and a property of type CancellationToken receives the active request token.

Apply ValueSourceAttribute to bind a property from a different parameter name or from the request service provider.

Examples

endpoint.WithHandler<UserRequest>((request, next) => next());

Exceptions

Type	Condition
ArgumentNullException	Thrown when endpointBuilder or handler is null.
ArgumentException	Thrown when the endpoint's captured HTTP method is not supported.
InvalidOperationException	Thrown when request-time typed binding cannot resolve a required parameter or service.