Class RouteScopeBuilder

Builder responsible for configuring a route scope and its child route tree.

Inheritance
object
RouteScopeBuilder
RouterBuilder<TRouter, TConfig>
Inherited Members
Namespace: NanoRoute
Assembly: NanoRoute.dll
Syntax
public class RouteScopeBuilder
Remarks

Route patterns support literal segments and parser-backed parameter segments such as /users/{id:int}/. Patterns must start with /, exact patterns must end with /, prefix patterns must end with /*, and repeated / separators such as // are invalid.

Examples
builder
    .AddDefaultValueParsers()
    .AddHandler("GET", "/users/{id:int}/", (context, _) => Results.Ok(context.Parameters["id"]));

Fields

CurrentExact

The route pattern that matches the current route scope exactly.

Declaration
public const string CurrentExact = "/"
Field Value
Type Description
string
Examples
builder.AddHandler("GET", RouteScopeBuilder.CurrentExact, (context, _) => Results.Ok());

CurrentPrefix

The route pattern that matches the current route scope as a prefix.

Declaration
public const string CurrentPrefix = "/*"
Field Value
Type Description
string
Examples
builder.AddHandler("GET", RouteScopeBuilder.CurrentPrefix, (context, next) => next());

Properties

BasePattern

Gets the route pattern prefix for this route scope.

Declaration
public string BasePattern { get; }
Property Value
Type Description
string
Remarks

The root scope exposes CurrentPrefix. Child scopes created with CreatePrefix(string) expose the accumulated prefix inherited from their parent scopes.

Metadata

Gets extension-defined builder metadata visible from this route scope.

Declaration
public BuilderMetadata Metadata { get; }
Property Value
Type Description
BuilderMetadata
Remarks

Metadata is public for extension authors who need scoped build-time settings behind module-specific configuration methods. Application code usually should prefer those module APIs instead of reading or writing metadata directly.

Child scopes created with CreatePrefix(string) inherit a scoped copy of their parent's metadata. Metadata updates made after the child scope is created stay local to the scope where they are made.

Examples
builder.Metadata.Set(new MyFeatureOptions { Enabled = true });

Patterns

Gets the distinct route patterns currently visible from this route scope.

Declaration
public IEnumerable<string> Patterns { get; }
Property Value
Type Description
IEnumerable<string>
Remarks

Each entry is formatted as [Verb] Pattern. Child scopes list only the routes reachable from their base path, while the root scope lists the whole configured tree.

Examples
foreach (string pattern in builder.Patterns)
    Console.WriteLine(pattern);

ValueParsers

Gets the value parser registrations currently visible from this route scope.

Declaration
public IReadOnlyDictionary<string, ValueParserRegistration> ValueParsers { get; }
Property Value
Type Description
IReadOnlyDictionary<string, ValueParserRegistration>
Remarks

For child scopes created with CreatePrefix(string), this dictionary reflects the inherited registrations plus any overrides added to that child scope.

Examples
bool hasIntParser = builder.ValueParsers.ContainsKey("int");

Methods

AddHandler(string, string, RequestHandlerDelegate)

Registers a handler for a single HTTP method.

Declaration
public RouteScopeBuilder AddHandler(string verb, string pattern, RequestHandlerDelegate handler)
Parameters
Type Name Description
string verb

The HTTP method that activates 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. If several handlers match, calling the supplied next delegate continues the pipeline with the next compatible handler from the already selected route branch.
Returns
Type Description
RouteScopeBuilder

The current route scope builder instance.
Examples
builder.AddHandler("GET", "/files/{path:any}/*", (context, next) =>
{
    string path = (string) context.Parameters["path"]!;
    return ServeFile(path);
});
Exceptions
Type Condition
ArgumentNullException

Thrown when verb, pattern, or handler is null.
ArgumentException

Thrown when verb is not a supported HTTP method.
InvalidOperationException

Thrown when pattern uses an unsupported optional parameter or list parser, references a value parser that has not been registered yet, or reuses a parser-backed branch with a different parameter name.
ArgumentException

Thrown when pattern has invalid route-template syntax.

AddValueParser(string, BindArgumentsDelegate, ValueParserDelegate)

Registers a parser that can convert a route segment into a typed value and bind parser arguments once during route registration.

Declaration
public RouteScopeBuilder AddValueParser(string parserName, BindArgumentsDelegate bindArguments, ValueParserDelegate tryParseDelegate)
Parameters
Type Name Description
string parserName

The name used in route patterns such as {id:int(min=1)}.
BindArgumentsDelegate bindArguments

Converts raw parser arguments into typed values once per route-template branch.
ValueParserDelegate tryParseDelegate

The delegate that validates and parses a single path segment.
Returns
Type Description
RouteScopeBuilder

The current instance.
Examples
builder.AddValueParser("slug", static rawArgs => null, static context =>
    ValueTask.FromResult(new ValueParseResult(context.Segment.Length > 0, context.Segment.ToString())));
Exceptions
Type Condition
ArgumentNullException

Thrown when parserName, bindArguments, or tryParseDelegate is null.

CreatePrefix(string)

Creates a child route scope whose routes are rooted under the given prefix.

Declaration
public RouteScopeBuilder CreatePrefix(string pattern)
Parameters
Type Name Description
string pattern

The base prefix. It must be a valid route pattern ending in /* so child routes can be appended to it.
Returns
Type Description
RouteScopeBuilder

A child route scope builder that shares the current route tree but has its own parser registration scope.
Remarks

Child route scopes inherit the parent's registered value parsers at creation time. Additional parser registrations or overrides made on the child scope stay local to that branch.

Examples
RouteScopeBuilder api = builder.CreatePrefix("/api/*");

api.AddHandler("GET", "/health/", (context, _) => Results.Ok());
Exceptions
Type Condition
ArgumentException

Thrown when pattern does not end with /*.
ArgumentNullException

Thrown when pattern is null.
InvalidOperationException

Thrown when pattern uses an unsupported optional parameter or list parser, references a value parser that has not been registered yet, or reuses a parser-backed branch with a different parameter name.
ArgumentException

Thrown when pattern has invalid route-template syntax.

Extension Methods