After you create a new ASP.NET MVC Web Application project, take a quick look at the code in Global.asax.cs. You'll notice that the Application_Start method contains a call to a method named the RegisterRoutes method. This method is where all routes for the application are registered.

var routes = new RouteCollection();
GlobalApplication.RegisterRoutes(routes);

//Write tests to verify your routes here...
Code snippet 4-1.txt

Let's clear out the routes in there for now and replace them with this very simple route:

routes.MapRoute("simple", "{first}/{second}/{third}");
Code snippet 4-2.txt

The simplest form of the MapRoute method takes in a name for the route and the URL pattern for the route. The name is discussed later. For now, focus on the URL pattern.

Notice that the route URL consists of several URL segments (a segment is everything between slashes but not including the slashes), each of which contains a placeholder delimited using curly braces. These placeholders are referred to as URL parameters.

This is a pattern-matching rule used to determine if this route applies to an incoming request. In this example, this rule will match any URL with three segments because a URL parameter, by default, matches any nonempty value. When it matches a URL with three segments, the text in the first segment of that URL corresponds to the {first} URL parameter, the value in the second segment of that URL corresponds to the {second} URL parameter, and the value in the third segment corresponds to the {third} parameter.

We can name these parameters anything we'd like, as we did in this case. When a request comes in, Routing parses the request URL into a dictionary (specifically a RouteValueDictionary accessible via the RequestContext), using the URL parameter names as the keys and subsections of the URL in the corresponding position as the values. Later you'll learn that when using routes in the context of an MVC application, there are certain parameter names that carry a special purpose. Table 4-1 displays how the route we just defined will convert certain URLs into a RouteValueDictionary:

If you actually make a request to the URLs listed above, you'll notice that your ASP.NET MVC application will appear to be broken. While you can define a route with any parameter names you'd like, there are certain special parameter names required by ASP.NET MVC in order to function correctly — {controller} and {action}.

The value of the {controller} parameter is used to instantiate a controller class to handle the request. By convention, MVC appends the suffix Controller to the {controller} value and attempts to locate a type of that name (case insensitively) that also inherits from the System.Web.Mvc.IController interface.

Going back to the simple route example, let's change it from

routes.MapRoute("simple", "{first}/{second}/{third}");

to:

routes.MapRoute("simple", "{controller}/{action}/{id}");
Code snippet 4-3.txt

so that it contains the special URL parameter names.

Now looking again at the first example in the previous table, you see that the request for /products/list/123 is a request for a {controller} named Products. ASP.NET MVC takes that value and appends the Controller suffix to get a type name, ProductsController. If a type of that name that implements the IController interface exists, it is instantiated and used to handle the request.

The {action} parameter value is used to indicate which method of the controller to call in order to handle the current request. Note that this method invocation only applies to controller classes that inherit from the System.Web.Mvc.Controller base class. Continuing with the example of /products/list/123, the method of ProductsController that MVC will invoke is List.

Note that the third URL in the preceding table, while it is a valid route URL, will probably not match any real Controller and action, as it would attempt to instantiate a Controller named a.bController and call the method named c-d, which are not valid method names.

Any route parameters other than {controller} and {action} are passed as parameters to the action method, if they exist. For example, assuming the following Controller:

public class ProductsController : Controller
{
  public ActionResult Display(int id)
  {
    //Do something
    return View();
  }
}
Code snippet 4-4.txt

a request for /products/display/123 would cause MVC to instantiate this class and call the Display method, passing in 123 for the id. You'll get more into the details of how Controllers work in Chapter 5 after you've mastered Routing.

In the previous example with the route URL {controller}/{action}/{id}, each segment contains a URL parameter that takes up the entire segment. This doesn't have to be the case. Route URLs do allow for literal values within the segments. For example, you might be integrating MVC into an existing site and want all your MVC requests to be prefaced with the word site; you could do this as follows:

site/{controller}/{action}/{id}
Code snippet 4-5.txt

This indicates that first segment of a URL must start with site in order to match this request. Thus, /site/products/display/123 matches this route, but /products/display/123 does not match.

It is even possible to have URL segments that intermix literals with parameters. The only restriction is that two consecutive URL parameters are not allowed. Thus:

{language}-{country}/{controller}/{action}
{controller}.{action}.{id}

are valid route URLs, but

{controller}{action}/{id}
Code snippet 4-6.txt

is not a valid route. There is no way for the route to know when the Controller part of the incoming request URL ends and when the action part should begin.

Looking at some other samples (shown in Table 4-2) will help you see how the URL pattern corresponds to matching URLs.

So far, the chapter has covered defining routes that contain a URL pattern for matching URLs. It turns out that the route URL is not the only factor taken into consideration when matching requests. It's also possible to provide default values for a route URL parameter. For example, suppose that you have an action method that does not have a parameter:

public class ProductsController : Controller
{
  public ActionResult List()
  {
    //Do something
    return View();
  }
}
Code snippet 4-7.txt

Naturally, you might want to call this method via the URL:

/products/list
Code snippet 4-8.txt

However, given the route URL defined above, {controller}/{action}/{id}, this won't work, as this route only matches URLs containing three segments and /products/list only contains two segments.

At this point, it would seem you need to define a new route that looks like the above route, but only defines two segments like {controller}/{action}. Wouldn't it be nicer if you didn't have to define another route and could instead indicate to the route that the third segment is optional when matching a request URL?

Fortunately, you can! The routing API has the notion of default values for parameter segments. For example, you can define the route like this:

routes.MapRoute("simple", "{controller}/{action}/{id}", new {id = ""});
Code snippet 4-9.txt

The new {id = ""} defines a default value for the {id} parameter. This allows this route to match requests for which the id parameter is missing (supplying an empty string as the value for {id} in those cases). In other words, this route now matches any two or three segment URLs, as opposed to only matching three segment URLs before you tacked on the defaults.

This now allows you to call the List action method, using the URL /products/list, which satisfies our goal, but let's see what else we can do with defaults.

Multiple default values can be provided. The following snippet demonstrates providing a default value for the {action} parameter as well:

routes.MapRoute("simple"
  , "{controller}/{action}/{id}"
  , new {id = "" , action="index"});
Code snippet 4-10.txt

This example supplies a default value for the {action} parameter within the URL via the Defaults dictionary property of the Route class. While the URL pattern of {controller}/{action} would normally only match a two-segment URL, by supplying a default value for one of the parameters, this route no longer requires that the URL contain two segments. It may now simply contain the {controller} parameter in order to match this route. In that case, the {action} value is supplied via the default value.

Let's revisit the previous table on route URL patterns and what they match and now throw in defaults into the mix, shown in Table 4-3.

One thing to understand is that the position of a default value relative to other URL parameters is important. For example, given the URL pattern {controller}/{action}/{id}, providing a default value for {action} like new{action="index"} is effectively the same as not having a default value for {action} because there is no default value for the {id} parameter.

Why is this the case?

A quick example will make the answer to this question clear. Suppose that Routing allowed a middle parameter to have a default value and you had the following two routes defined:

routes.MapRoute("simple", "{controller}/{action}/{id}", new {action="index"});
routes.MapRoute("simple2", "{controller}/{action}");

Now if a request comes in for /products/beverage, which route should it match? Should it match the first because you provide a default value for {action}, and thus {id} should be "beverage"? Or should it match the second route, with the {action} parameter set to "beverage"?

The problem here is which route the request should match is ambiguous and difficult to keep track of when defining routes. Thus, default values only work when every URL parameter after the one with the default also has a default value assigned. Thus, in the previous route, if you have a default value for {action}, you must also have a default value for {id}, which is defined after {action}.

Routing treats how it handles default values slightly different when there are literal values within a URL segment. Suppose that you have the following route defined:

routes.MapRoute("simple", "{controller}-{action}", new {action="index"});
Code snippet 4-11.txt

Notice that there is a string literal "-" between the {controller} and {action} parameters. It is clear that a request for /products-list will match this route, but should a request for /products- match? Probably not, as that makes for an awkward-looking URL.

It turns out that with Routing, any URL segment (the portion of the URL between two slashes) with literal values must not leave out any of the parameter values when matching the request URL. The default values in this case come into play when generating URLs, which is covered later in the section, "Under the Hood: How Routes Generate URLs."

Sometimes, you need more control over your URLs than specifying the number of URL segments. For example, take a look at the following two request URLs:

Both of these URLs contain three segments and would both match the default route you've been looking at in this chapter thus far. If you're not careful you'll have the system looking for a Controller called 2008Controller and a method called 01! However, just by looking at these URLs, it seems clear that they should map to different things. So how can we make that happen?

This is where constraints are useful. Constraints allow you to apply a regular expression to a URL segment to restrict whether or not the route will match the request. For example:

routes.MapRoute("blog", "{year}/{month}/{day}"
  , new {controller="blog", action="index"}
  , new {year=@"d{4}", month=@"d{2}", day=@"d{2}"});

routes.MapRoute("simple", "{controller}/{action}/{id}");
Code snippet 4-12.txt

In the above snippet, you create a route with three segments, {year}, {month}, and {day}, and you constrain each of these three segments to be digits via a constraints dictionary. The dictionary is specified again using an anonymous object initializer as a shortcut. The constraint for the {year} segment is

year = @"d{4}"

The keys for the constraint dictionary map to the URL parameter that they constrain. The regular expression value for the key specifies what the value of that URL parameter must match in order for this route to match. The format of this regular expression string is the same as that used by the .NET Framework's Regex class (in fact, the Regex class is used under the hood). If any of the constraints does not match, the route is not a match for the request, and routing moves onto the next route.

So, in this case, the year must be a four-digit string. Thus this route matches /2008/05/25 but doesn't match /08/05/25 because 08 is not a match for the regular expression @"d{4}".

By default, constraints use regular expression strings to perform matching on a request URL, but if you look carefully, you'll notice that the constraints dictionary is of type RouteValueDictionary, which implements from IDictionary<string, object>. This means the values of that dictionary are of type object, not of type string. This provides flexibility in what you pass as a constraint value. You'll see how to take advantage of that in a later section.

Area routes are configured by creating classes for each area that derive from the AreaRegistration class, overriding AreaName and RegisterArea. To register these area routes, you'll call AreaRegistration.RegisterAllAreas from RegisterRoutes in your main application.

public static void RegisterRoutes(RouteCollection routes)
{
    routes.IgnoreRoute("{resource}.axd/{*pathInfo}");
    AreaRegistration.RegisterAllAreas();
    routes.MapRoute(
        "Default",
        "{controller}/{action}/{id}",
        new { controller = "Home", action = "Index", id = "" }
    );
}
Code snippet 4-14.txt

We'll look at a complete example in Chapter 13, but it's good to know what that AreaRegistration.RegisterAllAreas call is about when you're working with routes.

What happens when you have two routes with the same name in different areas of the same MVC solution? You'll get an exception stating that "The controller name 'Home' is ambiguous between the following types: AreasDemoWeb.Controllers.HomeController AreasDemoWeb.Areas.Blogs.Controllers.HomeController."

One way to prevent that exception is to use unique Controller names across your projects. However, you might not want to change your Controller names for a variety of reasons (e.g., you don't want to affect your generated route URLs). In that case, you can specify a namespace for a controller action when creating a named URL, which will give you a unique way to refer to each specific controller action regardless of area. Listing 4-1 shows how you'd do that:

routes.MapRoute(
    "Default",
    "{controller}/{action}/{id}",
    new { controller = "Home", action = "Index", id = "" },

new [] { "AreasDemoWeb.Controllers" }
);

The code above uses a fourth parameter that is an array of namespaces. The Controllers for the example project live in a namespace called AreasDemoWeb.Controllers.

At its core, the routing system is a simple abstraction based on the RouteCollection and RouteBase classes. It's instructive to first look at how routing works with these classes before digging into the interaction of the more complex Route class with routing. URL construction starts with a method call, RouteCollection.GetVirtualPath, passing in the RequestContext and user-specified route values (dictionary) used to select the desired route in the form of a dictionary of parameter values.

The Route class provides a specific more powerful default implementation of the above high-level algorithm. This is the logic most developers will use for routing.

Here is how the URL generation algorithm works, expressed as an outlined use case.

For named routes, you can pass the name for the route to the GetVirtualPath method. In this case, you don't iterate through all routes looking for a match; you simply grab the route corresponding to the specified name and apply the route matching rules to that route to see if it can generate a URL.

There are scenarios in which URL generation makes use of values that were not explicitly supplied to the GetVirtualPath method by the caller. Let's look at a scenario for an example of this.

SIMPLE CASE

Stewie is developing a reusable control for page navigation that includes Previous and Next hyperlinks. This is meant to be used on any view with a corresponding action that accepts a page parameter. For example, he can drop it on an existing todo list view (see Figure 4-4).

Figure 4.4. FIGURE 4-4

The Previous and Next buttons click to the previous and next pages of the current controller and action, respectively. Assume that he has the following route for the todo list:

public static void RegisterRoutes(RouteCollection routes)
{
    routes.MapRoute(null, "todo/{action}/{page}",
        new {controller="todo", action="list", page=0 });
}
Code snippet 4-15.txt

Stewie doesn't know the current controller and action to generate the URL for the previous and next pages. Fortunately, URL generation makes use of ambient values. These are values currently in route data. For example, suppose that the following request comes in for the todo list:

/todo/list/2

The route data looks like this (Table 4-6):

Table 4.6. Route Data

KEY	VALUE
Controller	todo
Action	List
Page	2

In generating the URL for the next page, Stewie calls the following code:

public string NextPageUrl(int currentPage
  , RouteCollection routes)
{
  int nextPage = currentPage + 1;
  VirtualPathData vp = routes.GetVirtualPath(null,
      new RouteValueDictionary(new {page = nextPage}));
  if(vp != null)
  {
    return vp.VirtualPath;
  }
  return null;
}
Code snippet 4-16.txt

Even though GetVirtualPath only supplied the page parameter, the routing system used the ambient values for the controller and action when performing the route lookup. The ambient values are the current values for those parameters within the RouteData for the current request. Explicitly supplied values for the controller and action would, of course, override the ambient values.

Yeah, this title is a mouthful. This is a unique scenario that bears explanation. Suppose that you have the following routes defined. Notice the first route has no {controller} parameter in the URL, but there is a default value for the controller URL parameter.

public static void RegisterRoutes(RouteCollection routes)
{
    routes.MapRoute("todo-route", "todo/{action}",
         new {controller="todo", action="list", page=0});

    routes.MapRoute("another-route", "{controller}/{action}",

new {controller="home", action="list", page=0});
}
Code snippet 4-17.txt

Also suppose that the current request looks like this:

/home/list

The route data for the current request (ambient values) looks like Table 4-7.

Now suppose that you want to generate a URL pointing to the TodoController like this:

VirtualPathData vp = routes.GetVirtualPath(null,
  "todo-route", new RouteValueDictionary());

  if(vp != null)
  {
    return vp.VirtualPath;
  }
  return null;
}
Code snippet 4-18.txt

According to the rules listed in the first "Simple Case" above, because there is a default value for {controller} but {controller} is not within the URL, any user-supplied value for {controller} must match the default value.

In this case, you only look at the user-supplied value and not the ambient value. So this call would match the first route.

Overflow parameters are route values explicitly passed into the GetVirtualPath that are not specified in the route URL. Note that ambient values are not used as overflow parameters. Overflow parameters used in route generation are appended to the generated URL as query string parameters unless the overflow parameter is specified in the route's Defaults dictionary or in the route's Constraints dictionary. In that case, the parameter value must match the corresponding default value.

Again, an example is most instructive in this case. Assume that the following routes are defined: Note that in this case, we're not defining ASP.NET MVC routes, so we switch from calling MapRoute to explicitly adding routes to our RouteCollection. When explicitly adding routes, it is necessary to specify a route handler (an instance of a type that implements IRouteHandler). The MapRoute method specifies the MvcRouteHandler as the route handler. In this example, we specify a ReportRouteHandler, which we made up for the sake of discussion.

public static void RegisterRoutes(RouteCollection routes)
{
    routes.Add(new Route
     (
        "blog/{user}/{action}"
        , new ReportRouteHandler()
    )
    {
        Defaults = new RouteValueDictionary{
             {"controller", "blog"},
             {"user", "admin"}}
    });

    routes.Add(new Route
    (
        "forum/{user}/{action}"
        , new ReportRouteHandler()
    )
    {
        Defaults = new RouteValueDictionary{
               {"controller", "forum"},
               {"user", "admin"}}
    });
}
Code snippet 4-19.txt

In this example, there is no route URL parameter for controller, but the route does define a default. Any requests that match the first route will have the value blog for the key controller in the RouteData. Any requests that match the second route will have the value forum.

Now suppose that the developer wants to generate a URL:

string url1 = RouteCollection.GetVirtualPath(
            context,
            new {action="Index", controller="forum"}).VirtualPath;
            //Should check for null, but this is an example.

VirtualPathData vpd2 = RouteCollection.GetVirtualPath(
            context,
            new {action="Index", controller="blah"});
            //returns null.
Code snippet 4-20.txt

The first URL generated will be /forum/admin/Index. Because the call to GetVirtualPath specifies the overflow parameter controller, but the routes don't specify controller as a parameter, the defaults of the route are checked to see if there's an exact match.

The default of user has a corresponding parameter in the route URL, so its value is used in URL generation and doesn't need to be specified in the call to GetVirtualPath.

The second URL will return null because the call to GetVirtualPath doesn't match any of the routes. Even though the controller value specified is an overflow parameter, these routes define a default with the same name and the values do not match.

Let's assume that the following route is defined:

void Application_Start(object sender, EventArgs e)
{
    RouteTable.Routes.Add(new Route
    (
        "reports/{year}/{month}/{day}"
        , new ReportRouteHandler()

    )
    {
        Defaults = new RouteValueDictionary{{"day",1}}
    });
}
Code snippet 4-21.txt

Here are some results of some GetVirtualPath calls that take the following general form:

RouteCollection.GetVirtualPath(
    context,
    new RouteValueDictionary {
      {param1, value1},
      {param2,value2},
      ...,
      {paramN,valueN}
     });
Code snippet 4-22.txt

Parameters and the resulting URL are shown in Table 4-8.

Recall that when we call GetRouteData, it returns an instance of RouteData. What exactly is RouteData? RouteData contains information about the route that matched a particular request, including context information for the specific request that matched.

Recall in the previous section that we showed a route with the following URL: {foo}/{bar}/{baz}. When a request for /products/list/123 comes in, the route attempts to match the request. If it does match, it then creates a dictionary that contains information parsed from the URL. Specifically, it adds a key to the dictionary for each url parameter in the route URL.

So in the case of {foo}/{bar}/{baz}, you would expect the dictionary to contain at least three keys: "foo", "bar", and "baz". In the case of /products/list/123, the URL is used to supply values for these dictionary keys. In this case, foo = products, bar = list, and baz = 123.