Class NanoRouteQueryExtensions

Adds query-parameter binding helpers to NanoRoute.

Inheritance

object

NanoRouteQueryExtensions

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 NanoRouteQueryExtensions

Examples

builder
    .AddDefaultValueParsers()
    .AddQueryBindings("{page?:int(min=1)}")
    .AddHandler("GET", "/items/", (context, _) => Results.Ok(context.Parameters));

Methods

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

Parses configured query parameters and stores their values in Parameters.

Declaration

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

Parameters

Type	Name	Description
TBuilder	routeScopeBuilder
IEnumerable<string>	verbs	The HTTP methods that activate the query-binding middleware.
string	bindings	A query-parameter descriptor such as {filter:str(min=3)}&{page?:int(min=1)}.

Returns

Type	Description
TBuilder	The current routeScopeBuilder instance.

Type Parameters

Name	Description
TBuilder

Remarks

Parsed query values are written into Parameters. If that dictionary already contains the same key because of route binding, JSON binding, or earlier middleware, the query binding overwrites the existing value. This overload uses CurrentPrefix as the route pattern, so the query-binding middleware is bound to the whole current builder scope for the selected HTTP methods.

Examples

builder.AddQueryBindings(["GET", "HEAD"], "{filter?:str}&{page?:int(min=1)}");

Exceptions

Type	Condition
InvalidOperationException	Thrown when bindings references a value parser that is not registered.
ArgumentNullException	Thrown when routeScopeBuilder, verbs, or bindings is null.
ArgumentException	Thrown when an entry in verbs is not supported or bindings has invalid query-binding syntax.
HttpRequestException	Thrown during request processing when the query string is invalid for the configured bindings.

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

Parses configured query parameters and stores their values in Parameters.

Declaration

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

Parameters

Type	Name	Description
TBuilder	routeScopeBuilder
IEnumerable<string>	verbs	The HTTP methods that activate the query-binding middleware.
string	pattern	The route pattern where the query-binding middleware should be inserted. Use / to apply it to the whole pipeline, or a narrower prefix/exact pattern to scope query binding to selected routes.
string	bindings	A query-parameter descriptor such as {filter:str(min=3)}&{page?:int(min=1)}.

Returns

Type	Description
TBuilder	The current routeScopeBuilder instance.

Type Parameters

Name	Description
TBuilder

Remarks

Parsed query values are written into Parameters. If that dictionary already contains the same key because of route binding, JSON binding, or earlier middleware, the query binding overwrites the existing value.

Examples

builder.AddQueryBindings(["GET", "HEAD"], "/items/*", "{filter?:str}&{page?:int(min=1)}");

Exceptions

Type	Condition
InvalidOperationException	Thrown when bindings references a value parser that is not registered.
ArgumentNullException	Thrown when routeScopeBuilder, verbs, pattern, or bindings is null.
ArgumentException	Thrown when an entry in verbs is not supported, pattern has invalid route-template syntax, or bindings has invalid query-binding syntax.
HttpRequestException	Thrown during request processing when the query string is invalid for the configured bindings.

AddQueryBindings<TBuilder>(TBuilder, string)

Parses configured query parameters and stores their values in Parameters.

Declaration

public static TBuilder AddQueryBindings<TBuilder>(this TBuilder routeScopeBuilder, string bindings) where TBuilder : notnull, RouteScopeBuilder

Parameters

Type	Name	Description
TBuilder	routeScopeBuilder
string	bindings	A query-parameter descriptor such as {filter:str(min=3)}&{page?:int(min=1)}.

Returns

Type	Description
TBuilder	The current routeScopeBuilder instance.

Type Parameters

Name	Description
TBuilder

Remarks

Parsed query values are written into Parameters. If that dictionary already contains the same key because of route binding, JSON binding, or earlier middleware, the query binding overwrites the existing value. This overload uses CurrentPrefix as the route pattern, so the query-binding middleware is bound to the whole current builder scope for all supported HTTP methods.

Examples

builder.AddQueryBindings("{filter?:str}&{page?:int(min=1)}");

Exceptions

Type	Condition
InvalidOperationException	Thrown when bindings references a value parser that is not registered.
ArgumentNullException	Thrown when routeScopeBuilder or bindings is null.
ArgumentException	Thrown when bindings has invalid query-binding syntax.
HttpRequestException	Thrown during request processing when the query string is invalid for the configured bindings.

AddQueryBindings<TBuilder>(TBuilder, string, string)

Parses configured query parameters and stores their values in Parameters.

Declaration

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

Parameters

Type	Name	Description
TBuilder	routeScopeBuilder
string	pattern	The route pattern where the query-binding middleware should be inserted. Use / to apply it to the whole pipeline, or a narrower prefix/exact pattern to scope query binding to selected routes.
string	bindings	A query-parameter descriptor such as {filter:str(min=3)}&{page?:int(min=1)}.

Returns

Type	Description
TBuilder	The current routeScopeBuilder instance.

Type Parameters

Name	Description
TBuilder

Remarks

Parsed query values are written into Parameters. If that dictionary already contains the same key because of route binding, JSON binding, or earlier middleware, the query binding overwrites the existing value.

Examples

builder.AddQueryBindings("/items/*", "{filter?:str}&{page?:int(min=1)}");

Exceptions

Type	Condition
InvalidOperationException	Thrown when bindings references a value parser that is not registered.
ArgumentNullException	Thrown when routeScopeBuilder, pattern, or bindings is null.
ArgumentException	Thrown when pattern has invalid route-template syntax or bindings has invalid query-binding syntax.
HttpRequestException	Thrown during request processing when the query string is invalid for the configured bindings.

AddQueryBindings<TBuilder>(TBuilder, string, string, string)

Parses configured query parameters and stores their values in Parameters.

Declaration

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

Parameters

Type	Name	Description
TBuilder	routeScopeBuilder
string	verb	The HTTP method that activates the query-binding middleware.
string	pattern	The route pattern where the query-binding middleware should be inserted. Use / to apply it to the whole pipeline, or a narrower prefix/exact pattern to scope query binding to selected routes.
string	bindings	A query-parameter descriptor such as {filter:str(min=3)}&{page?:int(min=1)}.

Returns

Type	Description
TBuilder	The current routeScopeBuilder instance.

Type Parameters

Name	Description
TBuilder

Remarks

Parsed query values are written into Parameters. If that dictionary already contains the same key because of route binding, JSON binding, or earlier middleware, the query binding overwrites the existing value.

Examples

builder.AddQueryBindings("GET", "/items/*", "{filter?:str}&{page?:int(min=1)}");

Exceptions

Type	Condition
InvalidOperationException	Thrown when bindings references a value parser that is not registered.
ArgumentNullException	Thrown when routeScopeBuilder, verb, pattern, or bindings is null.
ArgumentException	Thrown when verb is not supported, pattern has invalid route-template syntax, or bindings has invalid query-binding syntax.
HttpRequestException	Thrown during request processing when the query string is invalid for the configured bindings.

ConfigureQueryParsing<TBuilder>(TBuilder, ConfigureBuilderDelegate<QueryParsingConfig>)

Updates the query-parsing configuration visible from the current builder scope.

Declaration

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

Parameters

Type	Name	Description
TBuilder	routeScopeBuilder
ConfigureBuilderDelegate<QueryParsingConfig>	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 query-binding middleware snapshots the configuration that is current at registration time.

Examples

builder.ConfigureQueryParsing(config => config with
{
    UnexpectedParameterBehavior = UnexpectedParameterBehavior.Reject
});

Exceptions

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

WithQueryBindings(EndpointBuilder, string)

Parses configured query parameters and stores their values in Parameters for the current endpoint.

Declaration

public static EndpointBuilder WithQueryBindings(this EndpointBuilder endpointBuilder, string bindings)

Parameters

Type	Name	Description
EndpointBuilder	endpointBuilder
string	bindings	A query-parameter descriptor such as {filter:str(min=3)}&{page?:int(min=1)}.

Returns

Type	Description
EndpointBuilder	The current endpointBuilder instance.

Remarks

The query-binding middleware is registered for the endpoint's captured HTTP methods and route match kind. Parsed query values are written into Parameters. If that dictionary already contains the same key because of route binding, JSON binding, or earlier middleware, the query binding overwrites the existing value.

Examples

endpoint.WithQueryBindings("{filter?:str}&{page?:int(min=1)}");

Exceptions

Type	Condition
InvalidOperationException	Thrown when bindings references a value parser that is not registered.
ArgumentNullException	Thrown when endpointBuilder or bindings is null.
ArgumentException	Thrown when the endpoint's captured HTTP method is not supported or bindings has invalid query-binding syntax.
HttpRequestException	Thrown during request processing when the query string is invalid for the configured bindings.