Routing — ASP.NET documentation (2024)

URL matching¶

URL matching is the process by which routing dispatches an incoming request to a handler. This process is generally based on data in the URL path, but can be extended to consider any data in the request. The ability to dispatch requests to separate handlers is key to scaling the size and complexity of an application.

Incoming requests enter the RouterMiddleware which calls the RouteAsync method on each route in sequence. The IRouter instance chooses whether to handle the request by setting the RouteContext Handler to a non-null RequestDelegate. If a handler is set a route, it will be invoked to process the request and no further routes will be processed. If all routes are executed, and no handler is found for a request, the middleware calls next and the next middleware in the request pipeline is invoked.

The primary input to RouteAsync is the RouteContext HttpContext associated with the current request. The RouteContext.Handler and RouteContext RouteData are outputs that will be set after a successful match.

A successful match during RouteAsync also will set the properties of the RouteContext.RouteData to appropriate values based on the request processing that was done. The RouteContext.RouteData contains important state information about the result of a route when it successfully matches a request.

RouteData Values is a dictionary of route values produced from the route. These values are usually determined by tokenizing the URL, and can be used to accept user input, or to make further dispatching decisions inside the application.

RouteData DataTokens is a property bag of additional data related to the matched route. DataTokens are provided to support associating state data with each route so the application can make decisions later based on which route matched. These values are developer-defined and do not affect the behavior of routing in any way. Additionally, values stashed in data tokens can be of any type, in contrast to route values which must be easily convertable to and from strings.

RouteData Routers is a list of the routes that took part in successfully matching the request. Routes can be nested inside one another, and the Routers property reflects the path through the logical tree of routes that resulted in a match. Generally the first item in Routers is the route collection, and should be used for URL generation. The last item in Routers is the route that matched.

URL generation¶

URL generation is the process by which routing can create a URL path based on a set of route values. This allows for a logical separation between your handlers and the URLs that access them.

URL generation follows a similar iterative process, but starts with user or framework code calling into the GetVirtualPath method of the route collection. Each route will then have its GetVirtualPath method called in sequence until a non-null VirtualPathData is returned.

The primary inputs to GetVirtualPath are:

• VirtualPathContext HttpContext
• VirtualPathContext Values
• VirtualPathContext AmbientValues

Routes primarily use the route values provided by the Values and AmbientValues to decide where it is possible to generate a URL and what values to include. The AmbientValues are the set of route values that were produced from matching the current request with the routing system. In contrast, Values are the route values that specify how to generate the desired URL for the current operation. The HttpContext is provided in case a route needs to get services or additional data associated with the current context.

The output of GetVirtualPath is a VirtualPathData. VirtualPathData is a parallel of RouteData; it contains the VirtualPath for the output URL as well as the some additional properties that should be set by the route.

The VirtualPathData VirtualPathproperty contains the virtual path produced by the route. Depending on your needs you may need to process the path further. For instance, if you want to render the generated URL in HTML you need to prepend the base path of the application.

The VirtualPathData Router is a reference to the route that successfully generated the URL.

The VirtualPathData DataTokens properties is a dictionary of additional data related to the route that generated the URL. This is the parallel of RouteData.DataTokens.

Creating routes¶

Routing provides the Route class as the standard implementation of IRouter. Route uses the route template syntax to define patterns that will match against the URL path when RouteAsync is called. Route will use the same route template to generate a URL when GetVirtualPath is called.

Most applications will create routes by calling MapRoute or one of the similar extension methods defined on IRouteBuilder. All of these methods will create an instance of Route and add it to the route collection.

This is an example of a MapRoute call used by a typical ASP.NET MVC route definition:

routes.MapRoute( name: "default", template: "{controller=Home}/{action=Index}/{id?}");

This template will match a URL path like /Products/Details/17 and extract the route values { controller = Products, action = Details, id = 17 }. The route values are determined by splitting the URL path into segments, and matching each segment with the route parameter name in the route template. Route parameters are named. They are defined by enclosing the parameter name in braces { }.

The template above could also match the URL path / and would produce the values { controller = Home, action = Index }. This happens because the {controller} and {action} route parameters have default values, and the id route parameter is optional. An equals = sign followed by a value after the route parameter name defines a default value for the parameter. A question mark ? after the route parameter name defines the parameter as optional. Route parameters with a default value always produce a route value when the route matches - optional parameters will not produce a route value if there was no corresponding URL path segment.

See route-template-reference for a thorough description of route template features and syntax.

This example includes a route constraint:

routes.MapRoute( name: "default", template: "{controller=Home}/{action=Index}/{id:int}");

This template will match a URL path like /Products/Details/17, but not /Products/Details/Apples. The route parameter definition {id:int} defines a route constraint for the id route parameter. Route constraints implement IRouteConstraint and inspect route values to verify them. In this example the route value id must be convertable to an integer. See route-constraint-reference for a more detailed explaination of route constraints that are provided by the framework.

Additional overloads of MapRoute accept values for constraints, dataTokens, and defaults. These additional parameters of MapRoute are defined as type object. The typical usage of these parameters is to pass an anonymously typed object, where the property names of the anonymous type match route parameter names.

The following two examples create equivalent routes:

routes.MapRoute( name: "default_route", template: "{controller}/{action}/{id?}", defaults: new { controller = "Home", action = "Index" });routes.MapRoute( name: "default_route", template: "{controller=Home}/{action=Index}/{id?}");

This example demonstrates a few more features:

routes.MapRoute( name: "blog", template: "Blog/{*article}", defaults: new { controller = "Blog", action = "ReadArticle" });

This template will match a URL path like /Blog/All-About-Routing/Introduction and will extract the values { controller = Blog, action = ReadArticle, article = All-About-Routing/Introduction }. The default route values for controller and action are produced by the route even though there are no corresponding route parameters in the template. Default values can be specified in the route template. The article route parameter is defined as a catch-all by the appearance of an asterix * before the route parameter name. Catch-all route parameters capture the remainder of the URL path, and can also match the empty string.

This example adds route constraints and data tokens:

routes.MapRoute( name: "us_english_products", template: "en-US/Products/{id}", defaults: new { controller = "Products", action = "Details" }, constraints: new { id = new IntRouteConstraint() }, dataTokens: new { locale = "en-US" });

This template will match a URL path like /en-US/Products/5 and will extract the values { controller = Products, action = Details, id = 5 } and the data tokens { locale = en-US }.

URL generation¶

The Route class can also perform URL generation by combining a set of route values with its route template. This is logically the reverse process of matching the URL path.

This example uses a basic ASP.NET MVC style route:

routes.MapRoute( name: "default", template: "{controller=Home}/{action=Index}/{id?}");

With the route values { controller = Products, action = List }, this route will generate the URL /Products/List. The route values are substituted for the corresponding route parameters to form the URL path. Since id is an optional route parameter, it’s no problem that it doesn’t have a value.

With the route values { controller = Home, action = Index }, this route will generate the URL /. The route values that were provided match the default values so the segments corresponding to those values can be safely omitted. Note that both URLs generated would round-trip with this route definition and produce the same route values that were used to generate the URL.

For more details about the URL generation process, see url-generation-reference.

Tip

Enable Logging to see how the built in routing implementations, such as Route, match requests.

Warning

Avoid using constraints for input validation, because doing so means that invalid input will result in a 404 (Not Found) instead of a 400 with an appropriate error message. Route constraints should be used to disambiguate between similar routes, not to validate the inputs for a particular route.

Warning

Route constraints that verify the URL can be converted to a CLR type (such as int or DateTime) always use the invariant culture - they assume the URL is non-localizable. The framework-provided route constraints do not modify the values stored in route values. All route values parsed from the URL will be stored as strings. For example, the Float route constraint will attempt to convert the route value to a float, but the converted value is used only to verify it can be converted to a float.

Tip

To constrain a parameter to a known set of possible values, you can use a regular expression ( for example {action:regex(list|get|create)}. This would only match the action route value to list, get, or create. If passed into the constraints dictionary, the string “list|get|create” would be equivalent. Constraints that are passed in the constraints dictionary (not inline within a template) that don’t match one of the known constraints are also treated as regular expressions.