Share via

How to: Construct a URL from a Route

You can use ASP.NET routing to generate URLs that match patterns that are defined in an ASP.NET application. You create the URL by calling the GetVirtualPath method of the RouteCollection class and passing a dictionary of parameter values. ASP.NET routing compares the parameter values to the URL patterns and generates a URL based on the first route whose pattern matches the parameters.

You can pass extra values in the dictionary of parameter values. Values that match a parameter in the route definition are included in the URL. Extra values are included as query-string values.

When you create a URL, more than one route definition might match the parameters that you pass in. You can specify which route to use to create the URL by providing the name of a route. You specify a name for a route when you add it to the route collection.

You must define routes in the ASP.NET application before you construct URLs with URL routing. For more information, see How to: Define a Route. For information about how to configure an ASP.NET Web site project to use routing, see How to: Use Routing with Web Forms.

Creating a URL Based on a Matching Route

When ASP.NET routing constructs a URL, it uses either the named route that you specify or the first route that has a pattern that matches the parameters that you provide.

To create a URL

  1. Create an instance of the RouteValueDictionary class that contains all the parameter values that you want to include in the URL. The parameter values must include values that match a route pattern. It can include extra values; if it does, those values will be assigned to the query string.

  2. Call the GetVirtualPath method of the RouteCollection class and pass the RouteValueDictionary object to construct the URL. To indicate a specific route, include the route name.

    The GetVirtualPath method returns a VirtualPathData object.

  3. From the VirtualPathData object that is returned from the GetVirtualPath method, retrieve the VirtualPath property to get the string that represents the URL.


The following example shows how to create a URL from a route. The example assumes that you have added two routes to the ASP.NET application. The first route is named SalesRoute and defines the pattern SalesReport/{locale}/{year}. The second route is named ExpensesRoute and defines the pattern ExpensesReport/{locale}/{year}. For more information, see How to: Define a Route.

The example shows how to specify the name of the route when you construct the URL. Both SalesRoute and ExpensesRoute take the parameters year and locale. Therefore, you specify the route that you want by using a name.

The example also shows how to include an extra parameter when you construct the URL. The category parameter will be included as a query-string value when the URL is constructed.

Dim vpd As VirtualPathData
Dim url As String
Dim parameters As RouteValueDictionary

parameters = New RouteValueDictionary(New With _
    {.year = "2007", .locale = "en-CA", .category = "recreation"})

vpd = RouteTable.Routes.GetVirtualPath _
  (Nothing, _
  "SalesRoute", _

url = vpd.VirtualPath
RouteValueDictionary parameters = new RouteValueDictionary { 
    { "year", "2007" }, { "locale", "en-CA" }, {"category", "recreation"} };

VirtualPathData vpd = RouteTable.Routes.GetVirtualPath(

string url = vpd.VirtualPath;

See Also


How to: Define a Route


ASP.NET Routing