How to: Define a Route

You use ASP.NET routing to handle URL requests that do not map to a physical file in the Web site. You create a route by defining a pattern for the URL and specifying a handler that is invoked in response to the request.

When you define a route, you can specify default values that can provide a value that is used if a parameter is missing in the URL request. You can also specify constraints to make sure that the parameters contain valid values.

You can use routing to generate URLs in your application, such as to dynamically create URLs for hyperlinks. When you construct a URL, more than one route definition might match the parameters that you provide. You can specify which route to use for creating the URL by providing the name of a route that was specified when you registered the route.

Creating a Route

You create a route to match a URL pattern and specify how requests for that URL pattern are handled.

To create a route

1. Add a method to the Global.asax file that creates an instance of the Route class. In the class constructor, set the url parameter to the URL pattern that is used for matching URL requests, and set the routeHandler parameter to an instance of the class that processes the request.

   You can add a catch-all parameter to the URL pattern if you want to match a route to a URL request even if the request includes more parameters than those that are defined in the route. To add a catch-all parameter, precede the name of the last parameter with an asterisk (*).

2. If you want to specify default values for route parameters, set the Defaults property.

3. If you want to validate route parameter values, set the Constraints property to one of the following:

   • A string that defines a regular expression. The regular expression is case-insensitive.

   • An object that implements the IRouteConstaint interface and that includes a Match method.

4. Add the Route object to the Routes property of the RouteTable object. If you want to provide a name for the route, call the Add method; otherwise, call the Add method.

5. In the Application_Start handler in the Global.asax file, call the method that you added in the first step.

Example

The following example shows a method named RegisterRoutes that is called from Application_Start in the Global.asax file. The method adds two Route objects that have both a year and locale parameter. When you generate a URL, the routes can be distinguished by a name. The example shows how to add these routes as named routes. The routes also have constraints, default values, and a catch-all parameter.

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

Shared Sub RegisterRoutes(routes As RouteCollection)
    Dim salesUrlPattern As String
    Dim expensesUrlPattern As String
    Dim salesRoute As Route
    Dim expensesRoute As Route

    salesUrlPattern = "SalesReport/{locale}/{year}/{*queryvalues}"
    salesRoute = New Route(salesUrlPattern, New SalesRouteHandler)
    salesRoute.Constraints = New RouteValueDictionary(New With _
        {.locale = "[a-z]{2}-[a-z]{2}", .year = "\d{4}"})
    salesRoute.Defaults = New RouteValueDictionary(New With _
        {.locale = "en-US", .year = DateTime.Now.Year.ToString()})

    routes.Add("SalesRoute", salesRoute)

    expensesUrlPattern = "ExpensesReport/{locale}/{year}/{*queryvalues}"
    expensesRoute = New Route(expensesUrlPattern, New ExpensesRouteHandler)
    expensesRoute.Constraints = New RouteValueDictionary(New With _
        {.locale = "[a-z]{2}-[a-z]{2}", .year = "\d{4}"})
    expensesRoute.Defaults = New RouteValueDictionary(New With _
        {.locale = "en-US", .year = DateTime.Now.Year.ToString()})

    routes.Add("ExpensesRoute", expensesRoute)

End Sub

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

public static void RegisterRoutes(RouteCollection routes)
{
    routes.Add("SalesRoute", new Route
    (
         "SalesReport/{locale}/{year}/{*queryvalues}"
         , new SalesRouteHandler()
    )
       {
          Constraints = new RouteValueDictionary 
          {{"locale", "[a-z]{2}-[a-z]{2}"},{"year", @"\d{4}"}},
          Defaults = new RouteValueDictionary 
           {{"locale", "en-US"}, {"year", DateTime.Now.Year.ToString()}}
       });
    routes.Add("ExpensesRoute", new Route
    (
         "ExpensesReport/{locale}/{year}/{*queryvalues}"
         , new ExpensesRouteHandler()
    )
       {
          Constraints = new RouteValueDictionary 
          {{"locale", "[a-z]{2}-[a-z]{2}"},{"year", @"\d{4}"}},
          Defaults = new RouteValueDictionary 
           {{"locale", "en-US"}, {"year", DateTime.Now.Year.ToString()}}
       });
}

See Also

Tasks

How to: Construct a URL from a Route

Concepts

ASP.NET Routing