Share via

How to: Define Routes for Web Forms Applications

  • Article

You use ASP.NET routing to handle URL requests that do not map to physical files in the Web site. Because the URL does not have to map to a file, you can use descriptive URLs that are more easily understood by the user. You create a route by defining a pattern for the URL, specifying a handler that is invoked in response to the request, and specifying any associated default values or constraints. For more information, see ASP.NET Routing.

To create a route

  1. In the application's Global.asax file, add a method that accepts a single parameter of type RouteCollection.

  2. In the new method, add routes to the application by using the RouteCollection.MapPageRoute(String, String, String) method or one of its overloads. The base method enables you to set the name, the URL pattern, and the physical file for the route. The overloads enable you to set the following properties:

    For more information about the properties of routes and route handlers, see ASP.NET Routing.

  3. In the Application_Start handler in the Global.asax file, call the new method.

    You can add routes directly in the Application_Start method instead of using a separate method. You can also add routes at other points in an application life cycle. Adding routes in the Application_Start handler makes sure that the routes are available when the application starts. Adding routes in a separate method that is called from the Application_Start method enables you to add the routes when you unit-test the application.

Example

The following example shows how to define routes for Web Forms applications. The example shows a method named RegisterRoutes that is called from Application_Start in the Global.asax file. The method adds six routes, one for each overload of the MapPageRoute method. All routes have parameters named locale, and four routes have parameters named year. Four routes also have a catch-all parameter named querystring. All but one of the routes are named so that they can be distinguished by name when you generate URLs. The example also includes routes that have constraints, default values, and data tokens. The sales report routes are all mapped to the Sales.aspx file, and the expense report routes are mapped to the Expenses.aspx file.

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

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

Sub RegisterRoutes(ByVal routes As RouteCollection)
    routes.MapPageRoute("",
        "SalesReport/{locale}/{year}/{*queryvalues}", "~/sales.aspx")

    routes.MapPageRoute("SalesSummaryRoute",
        "SalesReportSummary/{locale}", "~/sales.aspx")

    routes.MapPageRoute("SalesDetailRoute",
        "SalesReportDetail/{locale}/{year}/{*queryvalues}", "~/sales.aspx",
        False)

    routes.MapPageRoute("SalesCurrentYearRoute",
        "SalesReportCurrent/{locale}/{year}/{*queryvalues}", "~/sales.aspx",
        false,
        new RouteValueDictionary(New With _ 
            { .locale = "US", .year = DateTime.Now.Year.ToString()}))

    routes.MapPageRoute("ExpenseCurrentYearRoute",
        "ExpenseReportCurrent/{locale}", "~/expenses.aspx",
        false,
        new RouteValueDictionary(New With _
            { .locale = "US", .year = DateTime.Now.Year.ToString()}),
        new RouteValueDictionary(New With _
            { .locale = "[a-z]{2}", .year = "\d{4}" }))

    routes.MapPageRoute("ExpenseDetailRoute",
        "ExpenseReportDetail/{locale}/{year}/{*queryvalues}", "~/expenses.aspx",
        false,
        new RouteValueDictionary(New With _
            { .locale = "US", .year = DateTime.Now.Year.ToString()}),
        new RouteValueDictionary(New With _ 
            { .locale = "[a-z]{2}", .year = "\d{4}" }),
        new RouteValueDictionary(New With _
            { .account = "1234", .subaccount = "5678" }))
End Sub

 void RegisterRoutes(RouteCollection routes)
{
    routes.MapPageRoute("",
        "SalesReport/{locale}/{year}/{*queryvalues}", "~/sales.aspx");

    routes.MapPageRoute("SalesSummaryRoute",
        "SalesReportSummary/{locale}", "~/sales.aspx");

    routes.MapPageRoute("SalesDetailRoute",
        "SalesReportDetail/{locale}/{year}/{*queryvalues}", "~/sales.aspx",
        false);

    routes.MapPageRoute("SalesCurrentYearRoute",
        "SalesReportCurrent/{locale}/{year}/{*queryvalues}", "~/sales.aspx",
        false,
        new RouteValueDictionary 
            { { "locale", "US" }, { "year", DateTime.Now.Year.ToString() } });

    routes.MapPageRoute("ExpenseCurrentYearRoute",
        "ExpenseReportCurrent/{locale}", "~/expenses.aspx",
        false,
        new RouteValueDictionary 
            { { "locale", "US" }, { "year", DateTime.Now.Year.ToString() } },
        new RouteValueDictionary 
            { { "locale", "[a-z]{2}" }, { "year", @"\d{4}" } });

    routes.MapPageRoute("ExpenseDetailRoute",
        "ExpenseReportDetail/{locale}/{year}/{*queryvalues}", "~/expenses.aspx",
        false,
        new RouteValueDictionary 
            { { "locale", "US" }, { "year", DateTime.Now.Year.ToString() } },
        new RouteValueDictionary 
            { { "locale", "[a-z]{2}" }, { "year", @"\d{4}" } },
        new RouteValueDictionary 
            { { "account", "1234" }, { "subaccount", "5678" } });
}

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

Reference

System.Web.Routing.Route

System.Web.Routing.PageRouteHandler

System.Web.Routing.RouteCollection

Concepts

ASP.NET Routing