ASP.NET Routing

ASP.NET routing enables you to use URLs that do not have to map to specific files in a Web site. Because the URL does not have to map to a file, you can use URLs that are descriptive of the user's action and therefore are more easily understood by users.

The ASP.NET MVC framework and ASP.NET Dynamic Data extend routing to provide features that are used only in MVC applications and in Dynamic Data applications. For more information about MVC, see ASP.NET MVC 3. For more information about Dynamic Data, see ASP.NET Dynamic Data Content Map.

In an ASP.NET application that does not use routing, an incoming request for a URL typically maps to a physical file that handles the request, such as an .aspx file. For example, a request for https://server/application/Products.aspx?id=4 maps to a file that is named Products.aspx that contains code and markup for rendering a response to the browser. The Web page uses the query string value of id=4 to determine what type of content to display.

In ASP.NET routing, you can define URL patterns that map to request-handler files, but that do not necessarily include the names of those files in the URL. In addition, you can include placeholders in a URL pattern so that variable data can be passed to the request handler without requiring a query string.

For example, in the request for https://server/application/Products/show/beverages, the routing parser can pass the values Products, show, and beverages to the page handler. In this example, if the route is defined by using the URL pattern server/application/{area}/{action}/{category}, the page handler would receive a dictionary collection in which the value associated with the key area is Products, the value for the key action is show, and the value for the key category is beverages. In a request that is not managed by URL routing, the /Products/show/beverages fragment would be interpreted as the path of a file in the application.

This topic contains the following sections:

• Routes

• URL Patterns

• Adding Routes to a Web Forms Application

• Adding Routes to an MVC Application

• Setting Default Values for URL Parameters

• Handling a Variable Number of Segments in a URL Pattern

• Adding Constraints to Routes

• Scenarios When Routing Is Not Applied

• How URLs Are Matched to Routes

• Creating URLs from Routes

• Accessing URL Parameters in a Routed Page

• Configuration Settings for Routing

• ASP.NET Routing and Security

• ASP.NET Web Forms and Route Security

• ASP.NET MVC and Route Security

• Class Reference

• ASP.NET Routing versus URL Rewriting

Routes

A route is a URL pattern that is mapped to a handler. The handler can be a physical file, such as an .aspx file in a Web Forms application. A handler can also be a class that processes the request, such as a controller in an MVC application. To define a route, you create an instance of the Route class by specifying the URL pattern, the handler, and optionally a name for the route.

You add the route to the application by adding the Route object to the static Routes property of the RouteTable class. The Routes property is a RouteCollection object that stores all the routes for the application.

You typically do not have to write code to add routes in an MVC application. Visual Studio project templates for MVC include preconfigured URL routes. These are defined in the MvcApplication class, which is defined in the Global.asax file.

URL Patterns

A URL pattern can contain literal values and variable placeholders (referred to as URL parameters). The literals and placeholders are located in segments of the URL which are delimited by the slash (/) character.

When a request is made, the URL is parsed into segments and placeholders, and the variable values are provided to the request handler. This process is similar to the way the data in query strings is parsed and passed to the request handler. In both cases variable information is included in the URL and passed to the handler in the form of key-value pairs. For query strings both the keys and the values are in the URL. For routes, the keys are the placeholder names defined in the URL pattern, and only the values are in the URL.

In a URL pattern, you define placeholders by enclosing them in braces ( { and } ). You can define more than one placeholder in a segment, but they must be separated by a literal value. For example, {language}-{country}/{action} is a valid route pattern. However, {language}{country}/{action} is not a valid pattern, because there is no literal value or delimiter between the placeholders. Therefore, routing cannot determine where to separate the value for the language placeholder from the value for the country placeholder.

The following table shows valid route patterns and examples of URL requests that match the patterns.

Typical URL Patterns in MVC Applications

URL patterns for routes in MVC applications typically include {controller} and {action} placeholders.

When a request is received, it is routed to the UrlRoutingModule object and then to the MvcHandler HTTP handler. The MvcHandler HTTP handler determines which controller to invoke by adding the suffix "Controller" to the controller value in the URL to determine the type name of the controller that will handle the request. The action value in the URL determines which action method to call.

For example, a URL that includes the URL path /Products is mapped to a controller named ProductsController. The value in the action parameter is the name of the action method that is called. A URL that includes the URL path /Products/show would result in a call to the Show method of the ProductsController class.

The following table shows the default URL patterns, and it shows examples of URL requests that are handled by the default routes.

The route with the pattern {resource}.axd/{*pathInfo} is included to prevent requests for the Web resource files such as WebResource.axd or ScriptResource.axd from being passed to a controller.

For IIS 7.0, no file-name extension is needed. For IIS 6.0, you must add the .mvc file-name extension to the URL pattern, as in the following example:

{controller}.mvc/{action}/{id}

Adding Routes to a Web Forms Application

In a Web Forms application, you create routes by using the MapPageRoute(String, String, String) method of the RouteCollection class. The MapPageRoute method creates a Route object and adds it to the RouteCollection object. You specify properties for the Route object in parameters that you pass to the MapPageRoute method.

Typically, you add routes in a method that is called from the handler for the Application_Start event in the Global.asax file. This approach makes sure that the routes are available when the application starts. It also enables you to call the method directly when you unit-test the application. If you want to call a method directly when you unit-test the application, the method that registers the routes must be static (Shared in Visual Basic) and must have a RouteCollection parameter.

The following example shows code from a Global.asax file that adds a Route object that defines two URL parameters named action and categoryName. URLs that have the specified pattern are directed to the physical page named Categories.aspx.

Sub Application_Start(ByVal sender As Object, ByVal e As EventArgs)
    RegisterRoutes(RouteTable.Routes)
End Sub

Shared Sub RegisterRoutes(routes As RouteCollection)
    routes.MapPageRoute("",
        "Category/{action}/{categoryName}",
        "~/categoriespage.aspx")
End Sub

protected void Application_Start(object sender, EventArgs e)
{
    RegisterRoutes(RouteTable.Routes);
}

public static void RegisterRoutes(RouteCollection routes)
{
    routes.MapPageRoute("",
        "Category/{action}/{categoryName}",
        "~/categoriespage.aspx");
}

Adding Routes to an MVC Application

If you adopt the MVC convention of implementing controllers by creating classes that derive from the ControllerBase class and giving them names that end with "Controller", you do not need to manually add routes in an MVC application. The preconfigured routes will invoke the action methods that you implement in the controller classes.

If you want to add custom routes in an MVC application, you use the MapRoute(RouteCollection, String, String) method instead of the MapPageRoute(String, String, String) method.

The following example shows the code that creates default MVC routes in the Global.asax file, as defined in the Visual Studio project template for MVC applications.

Public Class MvcApplication
    Inherits System.Web.HttpApplication

    Shared Sub RegisterRoutes(ByVal routes As RouteCollection)
        routes.IgnoreRoute("{resource}.axd/{*pathInfo}")

        ' MapRoute takes the following parameters, in order: 
        ' (1) Route name 
        ' (2) URL with parameters 
        ' (3) Parameter defaults
        routes.MapRoute( _
            "Default", _
            "{controller}/{action}/{id}", _
            New With {.controller = "Home", .action = "Index", .id = ""} _
        )

    End Sub 

    Sub Application_Start()
        RegisterRoutes(RouteTable.Routes)
    End Sub 
End Class

public class MvcApplication : System.Web.HttpApplication
{
    public static void RegisterRoutes(RouteCollection routes)
    {
        routes.IgnoreRoute("{resource}.axd/{*pathInfo}");

        routes.MapRoute(
            "Default",                                              // Route name 
            "{controller}/{action}/{id}",                           // URL with parameters 
            new { controller = "Home", action = "Index", id = "" }  // Parameter defaults
        );

    }

    protected void Application_Start()
    {
        RegisterRoutes(RouteTable.Routes);
    }
}

Setting Default Values for URL Parameters

When you define a route, you can assign a default value for a parameter. The default value is used if a value for that parameter is not included in the URL. You set default values for a route by assigning a dictionary object to the Defaults property of the Route class. The following example shows how to add a route that has default values, by using the MapPageRoute(String, String, String, Boolean, RouteValueDictionary) method.

Sub Application_Start(ByVal sender As Object, ByVal e As EventArgs)
    RegisterRoutes(RouteTable.Routes)
End Sub

Shared Sub RegisterRoutes(ByVal routes As RouteCollection)
    routes.MapPageRoute("",
        "Category/{action}/{categoryName}",
        "~/categoriespage.aspx",
        True,
        New RouteValueDictionary(New With _
            {.categoryName = "food", _
             .action = "show"} ))
End Sub

void Application_Start(object sender, EventArgs e) 
{
    RegisterRoutes(RouteTable.Routes);
}

public static void RegisterRoutes(RouteCollection routes)
{
    routes.MapPageRoute("",
        "Category/{action}/{categoryName}",
        "~/categoriespage.aspx",
        true,
        new RouteValueDictionary 
            {{"categoryName", "food"}, {"action", "show"}});
}

When ASP.NET routing handles a URL request, the route definition shown in the example (with default values of food for categoryName and show for action) produces the results that are listed in the following table.

For MVC applications, overloads of the RouteCollectionExtensions.MapRoute method, such as MapRoute(RouteCollection, String, String, Object, Object), enable you to specify defaults.

Handling a Variable Number of Segments in a URL Pattern

Sometimes you have to handle URL requests that contain a variable number of URL segments. When you define a route, you can specify that if a URL has more segments than there are in the pattern, the extra segments are considered to be part of the last segment. To handle additional segments in this manner you mark the last parameter with an asterisk (*). This is referred to as a catch-all parameter. A route with a catch-all parameter will also match URLs that do not contain any values for the last parameter. The following example shows a route pattern that matches an unknown number of segments.

query/{queryname}/{*queryvalues}

When ASP.NET routing handles a URL request, the route definition shown in the example produces the results that are listed in the following table.

Adding Constraints to Routes

In addition to matching a URL request to a route definition by the number of parameters in the URL, you can specify that values in the parameters meet certain constraints. If a URL contains values that are outside the constraints for a route, that route is not used to handle the request. You add constraints to make sure that the URL parameters contain values that will work in your application.

Constraints are defined by using regular expressions or by using objects that implement the IRouteConstraint interface. When you add the route definition to the Routes collection, you add constraints by creating a RouteValueDictionary object that contains the verification test. The key in the dictionary identifies the parameter that the constraint applies to. The value in the dictionary can be either a string that represents a regular expression or an object that implements the IRouteConstraint interface.

If you provide a string, routing treats the string as a regular expression and checks whether the parameter value is valid by calling the IsMatch method of the Regex class. The regular expression is always treated as case-insensitive. For more information, see .NET Framework Regular Expressions.

If you provide an IRouteConstraint object, ASP.NET routing checks whether the parameter value is valid by calling the Match method of the IRouteConstraint object. The Match method returns a Boolean value that indicates whether the parameter value is valid.

The following example shows how to use the MapPageRoute method to create a route that has constraints that limit what values can be included in the locale and year parameters. (In an MVC application, you would use the MapRoute method.)

Shared Sub RegisterRoutes(ByVal routes As RouteCollection)
    routes.MapPageRoute("",
        "Category/{action}/{categoryName}",
        "~/categoriespage.aspx",
        True,
        New RouteValueDictionary(New With _
            {.categoryName = "food", _
             .action = "show"} ),
        New RouteValueDictionary(New With _
            {.locale = "[a-z]{2}-[a-z]{2}", .year = "\d{4}"}))
End Sub

public static void RegisterRoutes(RouteCollection routes)
{
    routes.MapPageRoute("",
        "Category/{action}/{categoryName}",
        "~/categoriespage.aspx",
        true,
        new RouteValueDictionary 
            {{"categoryName", "food"}, {"action", "show"}},
        new RouteValueDictionary 
            {{"locale", "[a-z]{2}-[a-z]{2}"},{"year", @"\d{4}"}}
       );
}

When routing handles a URL request, the route definition shown in the previous example produces the results that are listed in the following table.

Scenarios When Routing Is Not Applied

Under some circumstances, ASP.NET routing does not handle a request even when is enabled for the Web site. This section describes some scenarios in which routing does not handle the request.

A Physical File is Found that Matches the URL Pattern

By default, routing does not handle requests that map to an existing physical file on the Web server. For example, a request for https://server/application/Products/Beverages/Coffee.aspx is not handled by routing if a physical file exists at Products/Beverages/Coffee.aspx. Routing does not handle the request even if it matches a defined pattern, such as {controller}/{action}/{id}.

If you want routing to handle all requests, even requests that point to files, you can override the default behavior by setting the RouteExistingFiles property of the RouteCollection object to true. When you set this value to true, all requests that match a defined pattern are handled by routing.

Routing Is Explicitly Disabled for a URL Pattern

You can also specify that routing should not handle certain URL requests. You prevent routing from handling certain requests by defining a route and specifying that the StopRoutingHandler class should be used to handle that pattern. When a request is handled by a StopRoutingHandler object, the StopRoutingHandler object blocks any additional processing of the request as a route. Instead, the request is processed as an ASP.NET page, Web service, or other ASP.NET endpoint. You can use the RouteCollection.Ignore method (or RouteCollectionExtensions.IgnoreRoute for MVC applications) to create routes that use the StopRoutingHandler class. The following example shows how to prevent routing from handling requests for the WebResource.axd file.

Shared Sub RegisterRoutes(ByVal routes As RouteCollection)
    routes.Ignore ("{resource}.axd/{*pathInfo}")
End Sub

public static void RegisterRoutes(RouteCollection routes)
{
  routes.Ignore("{resource}.axd/{*pathInfo}");
}

How URLs Are Matched to Routes

When routing handles URL requests, it tries to match the URL of the request to a route. Matching a URL request to a route depends on all the following conditions:

• The route patterns that you have defined or the default route patterns, if any, that are included in your project type.

• The order in which you added them to the Routes collection.

• Any default values that you have provided for a route.

• Any constraints that you have provided for a route.

• Whether you have defined routing to handle requests that match a physical file.

To avoid having the wrong handler handle a request, you must consider all these conditions when you define routes. The order in which Route objects appear in the Routes collection is significant. Route matching is tried from the first route to the last route in the collection. When a match occurs, no more routes are evaluated. In general, add routes to the Routes property in order from the most specific route definitions to least specific ones.

For example, suppose that you add routes with the following patterns:

• Route 1 is set to {controller}/{action}/{id}

• Route 2 is set to products/show/{id}

Route 2 will never handle a request because Route 1 is evaluated first, and it will always match requests that could also work for Route 2. A request for https://server/application/products/show/bikes seems to match Route 2 more closely, but it is handled by Route 1 with the following values:

• controller is products.

• action is show.

• id is bikes.

Default values are used if a parameter is missing from the request. Therefore, they can cause a route to match a request that you did not expect. For example, suppose that you add routes with the following patterns:

• Route 1: {report}/{year}/{month}, with default values for year and month.

• Route 2: {report}/{year}, with a default value for year.

Route 2 will never handle a request. Route 1 might be intended for a monthly report, and Route 2 might be intended for an annual report. However, the default values in Route 1 mean that it will match any request that could also work for Route 2.

You can avoid ambiguity in the patterns by including constants, such as annual/{report}/{year} and monthly/{report}/{year}/{month}.

If a URL does not match any Route object that is defined in the RouteTable collection, ASP.NET routing does not process the request. Instead, processing is passed to an ASP.NET page, Web service, or other ASP.NET endpoint.

Creating URLs from Routes

If you want to create hyperlinks to pages in your site, you can use the URL patterns to programmatically create URLs that correspond to the routes. When you change the patterns, URLs matching the new patterns will be generated automatically. For information about how to generate URLs in code or in markup, see How to: Construct URLs from Routes.

Accessing URL Parameters in a Routed Page

In the handler for a routed page request you can access the values that are passed in the URL placeholders by using code or markup. For more information, see How to: Access URL Parameters in a Routed Page.

For MVC applications, the MVC framework automatically handles the values passed in URL placeholders. For more information, see Passing Data in an ASP.NET MVC Application.

Configuration Settings for Routing

In ASP.NET, you can add the following configuration setting to applications in order to support routing:

<configuration>
  <system.webServer>
    <modules runAllManagedModulesForAllRequests="true">
      <!-- more -->
    </modules>
  </system.webServer>
</configuration>

When runAllManagedModulesForAllRequests is true, a URL like https://mysite/myapp/home goes to ASP.NET, even though there is no .aspx, .mvc, or similar extension on the URL.

However, an update that was made to IIS 7 makes the runAllManagedModulesForAllRequests setting unnecessary and supports ASP.NET routing natively. (For information about the update, see the Microsoft Support article An update is available that enables certain IIS 7.0 or IIS 7.5 handlers to handle requests whose URLs do not end with a period.)

If your website is running on IIS 7 and if IIS has been updated, you do not need to set runAllManagedModulesForAllRequests to true. In fact, setting it to true is not recommended, because it adds unnecessary processing overhead to request. When this setting is true, all requests, including those for .htm, .jpg, and other static files, also go through the ASP.NET request pipeline.

The default setting for runAllManagedModulesForAllRequests is false. If the site's configuration file does not explicitly set runAllManagedModulesForAllRequests to true, when you then run the website on Windows 7 without SP1 installed, IIS 7 will not include the required update. As a consequence, routing will not work and you will see errors. If you have a problem where routing does not work, you can do the following:

• Update Windows 7 to SP1, which will add the update to IIS 7.

• Install the update that's described in the Microsoft Support article listed previously.

• Set runAllManagedModulesForAllRequests to true in that website's Web.config file. Note that this will add some overhead to requests.

ASP.NET Routing and Security

Authorization rules can be applied to only the route URL or to both the route URL and to the physical URL that it maps to. For example, authorization rules might specify that all users can access URLs that begin with Category but only administrators can access the Categories.aspx page. If the route URL pattern contoso.com/Category/{controller}/{action} maps to the physical URL contoso.com/Categoriespage.aspx, and you apply authorization rules only to the route URL, all users will be allowed access to Categoriespage.aspx when it is requested by using a route URL. However, only administrators will have access to it when it is requested by using a physical URL.

By default, authorization rules are applied to both route URL and physical URL. For more information, see the PageRouteHandler.CheckPhysicalUrlAccess property.

ASP.NET Web Forms and Route Security

In an ASP.NET Web Forms application, you should not depend solely on route authorization rules to secure your site, because that might leave some physical URLs unprotected.

ASP.NET MVC and Route Security

You cannot use routing or web.config files to secure an MVC application. The only supported way to secure an MVC application is to apply the AuthorizeAttribute attribute to each controller and use the AllowAnonymousAttribute attribute on the login and register actions. For more information, see Securing your ASP.NET MVC 4 App and the new AllowAnonymous Attribute on Rick Anderson's blog. To secure an ASP.NET MVC 3 application, see Securing your ASP.NET MVC 3 Application, also on Rick Anderson's blog.

Class Reference

The following table lists the key server classes for ASP.NET routing.

ASP.NET Routing versus URL Rewriting

ASP.NET routing differs from URL rewriting. URL rewriting processes incoming requests by actually changing the URL before it sends the request to the Web page. For example, an application that uses URL rewriting might change a URL from /Products/Widgets/ to /Products.aspx?id=4. Also, URL rewriting typically does not have an API for creating URLs that are based on your patterns. In URL rewriting, if you change a URL pattern, you must manually update all hyperlinks that contain the original URL.

With ASP.NET routing, the URL is not changed when an incoming request is handled, because routing can extract values from the URL. When you have to create a URL, you pass parameter values into a method that generates the URL for you. To change the URL pattern, you change it in one location, and all the links that you create in the application that are based on that pattern will automatically use the new pattern.

See Also

Tasks

Walkthrough: Using ASP.NET Routing in a Web Forms Application

How to: Construct URLs from Routes

How to: Access URL Parameters in a Routed Page

How to: Define Routes for Web Forms Applications

Reference

Route

PageRouteHandler

MvcRouteHandler

RouteData

Concepts

ASP.NET Infrastructure

Other Resources

.NET Framework 4 Migration Issues