The routing system was originally designed for ASP.NET MVC, but it was always intended to be shared with other ASP.NET technologies, including Web Forms. That's why the routing code doesn't live in System.Web.Mvc.dll, but instead is in a separate assembly (System.Web.Routing.dll in .NET 3.5, and simply System.Web.dll in .NET 4). Routing isn't aware of the concepts of "controller" and "action"—these parameter names are just arbitrary strings as far as routing is concerned, and are treated the same as any other parameter names you may choose to use. This chapter focuses on how to use routing with ASP.NET MVC, but much of the information also applies when using routing with other technologies.

The routing mechanism runs early in the framework's request processing pipeline. Its job is to take an incoming URL and use it to obtain an IHttpHandler object that will handle the request.

Many newcomers to the MVC Framework struggle with routing. It isn't comparable to anything in earlier ASP.NET technologies, and it's easy to configure wrong. By understanding its inner workings, you'll avoid these difficulties, and you'll also be able to extend the mechanism powerfully to add extra behaviors across your whole application.

routes.MapRoute(
  "Default",                                             // Route name
  "{controller}/{action}/{id}",                          // URL with parameters
  new { controller = "Home", action = "Index",           // Parameter defaults
        id = UrlParameter.Optional }
);
routes.MapRoute(
    "Specials",                                             // Route name
    "DailySpecials/{date}",                                 // URL with parameters
    new { controller = "Catalog", action = "ShowSpecials" } // Parameter defaults
);

The default route (matching {controller}/{action}/{id}) is so general in purpose that you could build an entire application around it without needing any otherrouting configuration entry. However, if you do want to handle URLs that don't bear any resemblance to the names of your controllers or actions, then you will need other configuration entries.

Starting with a simple example, let's say you want the URL /Catalog to lead to a list of products. You may have a controller class called ProductsController, itself having an action method called List(). In that case, you'd add this route:

routes.Add(new Route("Catalog", new MvcRouteHandler())
{
    Defaults = new RouteValueDictionary(
        new { controller = "Products", action = "List" }
    )
});

This entry will match /Catalog or /Catalog?some=querystring, but not /Catalog/Anythingelse. To understand why, let's consider which parts of a URL are significant to a Route entry.

URL Patterns Match the Path Portion of a URL

When a Route object decides whether it matches a certain incoming URL, it only considers the path portion of that incoming URL. That means it doesn't consider the domain name (also called host) or any query string values. Figure 8-1 depicts the path portion of a URL.^[49]

Figure 8-1. Identifying the path portion of a URL

Continuing the previous example, the URL pattern "Catalog" would therefore match both http://example.com/Catalog and https://a.b.c.d:1234/Catalog?query=string.

If you deploy to a virtual directory, your URL patterns are understood to be relative to that virtual directory root. For example, if you deploy to a virtual directory called virtDir, the same URL pattern ("Catalog") would match http://example.com/virtDir/Catalog. Of course, it could no longer match http://example.com/Catalog, because IIS would no longer ask your application to handle that URL.

routes.Add(new Route("Catalog", new MvcRouteHandler())
{
    Defaults = new RouteValueDictionary
    {
        { "controller", "Products" },
        { "action", "List" }
    }
});

routes.MapRoute("PublicProductsList", "Catalog",
                new { controller = "Products", action = "List" });

As you've seen several times already, parameters can be accepted via acurly brace syntax. Let's add aparameter called color to our route:

routes.Add(new Route("Catalog/{color}", new MvcRouteHandler())
{
    Defaults = new RouteValueDictionary(
        new { controller = "Products", action = "List" }
    )
});

Or, equivalently:

routes.MapRoute(null, "Catalog/{color}",
                new { controller = "Products", action = "List" });

This route will now match URLs such as /Catalog/yellow or /Catalog/1234, and the routing system will add a corresponding name/value pair to the request's RouteData object. On a request to /Catalog/yellow, for example, RouteData.Values["color"] would be given the value yellow.

public ActionResult List(string color)
{
    // Do something
}

You didn't give a default value for {color}, so it became a mandatory parameter. The Route entry no longer matches a request for /Catalog. You can make the parameter optional by adding to your Defaults object:

routes.Add(new Route("Catalog/{color}", new MvcRouteHandler())
{
    Defaults = new RouteValueDictionary(
        new { controller = "Products", action = "List", color=(string)null }
    )
});

Or, equivalently:

routes.MapRoute(null, "Catalog/{color}",
    new { controller = "Products", action = "List", color = (string)null }
);

Now this Route entry will match both /Catalog and /Catalog/orange. For /Catalog, RouteData.Values["color"] will be null, while for /Catalog/orange, RouteData.Values["color"] will equal "orange".

If you want a non-null default value, as you must for nonnullable types like int, you can specify that in the obvious way:

routes.Add(new Route("Catalog/{color}", new MvcRouteHandler())
{
    Defaults = new RouteValueDictionary(
        new { controller = "Products", action = "List", color = "Beige", page = 1 }
    )
});

Notice here that we're specifying "default" values for some "parameters" that don't actually correspond to any curly brace parameters in the URL (i.e., controller, action, and page, even though there's no {controller}, {action}, or {page} in the URL pattern). That's a perfectly fine thing to do; it's the correct way to set up RouteData values that are actually fixed for a given Route entry. For example, for this Route object, RouteData["controller"] will always equal "Products", regardless of the incoming URL, so matching requests will always be handled by ProductsController.

Remember that when you use MvcRouteHandler (as you do by default in ASP.NET MVC), you must have a value called controller; otherwise, the framework won't know what to do with the incoming request and will throw an error. The controller value can come from a curly brace parameter in the URL, or can just be specified in the Defaults object, but it cannot be omitted.

routes.MapRoute(null, "Catalog/{page}",
    new { controller = "Products", action = "List", page = UrlParameter.Optional }
);

Sometimes you will want to add extra conditions that must be satisfied for a request to match a certain route—for example:

In these cases, you'll use the Route's Constraints property. It's another RouteValueDictionary,^[50] in which the dictionary keys correspond to parameter names and values correspond to constraint rules for that parameter. Each constraint rule can be a string, which is interpreted as a regular expression; or, for greater flexibility, it can be a custom constraint of type IRouteConstraint. Let's see some examples.

routes.Add(new Route("Articles/{id}", new MvcRouteHandler())
{
    Defaults = new RouteValueDictionary(
            new { controller = "Articles", action = "Show" }
        ),
    Constraints = new RouteValueDictionary(new { id = @"d{1,6}" })
});

routes.MapRoute(null, "Articles/{id}",
    new { controller = "Articles", action = "Show" },
    new { id = @"d{1,6}" }
);

routes.Add(new Route("Articles/{id}", new MvcRouteHandler())
{
    Defaults = new RouteValueDictionary(
            new { controller = "Articles", action = "Show" }
    ),
    Constraints = new RouteValueDictionary(
        new { httpMethod = new HttpMethodConstraint("GET") }
    )
});

routes.MapRoute(null, "Articles/{id}",
    new { controller = "Articles", action = "Show" },
    new { httpMethod = new HttpMethodConstraint("GET") }
);

public class UserAgentConstraint : IRouteConstraint
{
    private string _requiredSubstring;
    public UserAgentConstraint(string requiredSubstring)
    {
        this._requiredSubstring = requiredSubstring;
    }

    public bool Match(HttpContextBase httpContext, Route route, string paramName,
                      RouteValueDictionary values, RouteDirection routeDirection)
    {
        if (httpContext.Request.UserAgent == null)
            return false;
        return httpContext.Request.UserAgent.Contains(_requiredSubstring);
    }
}

routes.Add(new Route("Articles/{id}", new MvcRouteHandler())
{
    Defaults = new RouteValueDictionary(
        new { controller = "Articles", action = "Show" }
    ),
    Constraints = new RouteValueDictionary(
        new { id = @"d{1,6}", userAgent = new UserAgentConstraint("iPhone") }
    )
});

Normally, when an incoming request matches a particular route entry, the MVC Framework takes the controller parameter (either from a curly brace {controller} parameter in the URL pattern or from the route entry's Defaults collection), and then looks for any controller class with a matching name. For example, if the incoming controller valuewas products, it would look for a controller class called ProductsController (case insensitively). There has to be only one matching controller among all your referenced assemblies—if there are two or more, it will fail, reporting that there was an ambiguous match.

If you want to make ASP.NET MVC prioritize certain namespaces when choosing a controller to handle a request, you can pass an extra parameter called namespaces.

routes.MapRoute(null, "Articles/{id}",
    new { controller = "Articles", action = "Show" },
    new[] { "MyApp.Controllers", "AnotherAssembly.Controllers" }
);

Now, it doesn't matter if there are other ArticlesController classes in other namespaces—it will try to find a class in any of the explicitly chosen namespaces. Only if there is no matching class in the chosen namespaces will it revert to the usual behavior of finding one from all other namespaces.

Internally, this MapRoute() overload is equivalent to writing the following:

routes.Add(new Route("Articles/{id}", new MvcRouteHandler())
{
    Defaults = new RouteValueDictionary(
            new { controller = "Articles", action = "Show" }
    ),
    DataTokens = new RouteValueDictionary(
        new { Namespaces = new[] { "MyRoutingApp.Controllers",
                                   "AnotherAssembly.Controllers" } }
    )
});

You'll learn more about how DataTokens["Namespaces"] underpins the notion of areas later in this chapter, and more about how controller factories respond to this option in Chapter 10.

So far, you've seen how to acceptonly a fixed number of curly brace parameters on each route entry. But what if you want to create the impression of an arbitrary directory structure, so you could have URLs such as /Articles/Science/Paleontology/Dinosaurs/Stegosaurus? How many curly brace parameters will you put into the URL pattern?

The routing system allows you to define catchallparameters, which ignore slashes and capture everything up to the end of a URL. Designate a parameter as being catchall by prefixing it with an asterisk (*). Here's an example:

routes.MapRoute(null, "Articles/{*articlePath}",
    new { controller = "Articles", action = "Show" }
);

This route entry would match /Articles/Science/Paleontology/Dinosaurs/Stegosaurus, yielding the route values shown in Table 8-6.

Naturally, you can only have one catchall parameter in a URL pattern, and it must be the last (i.e., rightmost) thing in the URL, since it captures the entire URL path from that point onward. However, it still doesn't capture anything from the query string. As mentioned earlier, Route objects only look at the path portion of a URL.

Catchall parameters are useful if you're letting visitors navigate through some kind of arbitrary depth hierarchy, such as in a content management system (CMS).

The whole goal of routing is to break the one-to-one association between URLs and files in the server's file system. However, the routing system still does check the file system to see if an incoming URL happens to match a file or disk, and if so, routing ignores the request (bypassing any route entries that the URL might also match) so that the file will be served directly.

This is very convenient for static files, such as images, CSS files, and JavaScript files. You can keep them in your project (e.g., in your /Content or /Script folders), and then reference and serve them directly, just as if you were not using routing at all. Since the file genuinely exists on disk, that takes priority over your routing configuration.

public static void RegisterRoutes(RouteCollection routes)
{
    // Before or after adding route entries, you can set this:
    routes.RouteExistingFiles = true;
}

If you want to set up specific exclusions in the URL space, preventing certain patterns from being matched by the routing system,^[51] you can use IgnoreRoute()—for example:

public static void RegisterRoutes(RouteCollection routes)
{
    routes.IgnoreRoute("{filename}.xyz");

    // Rest of routing config goes here
}

Here, {filename}.xyz is treated as a URL pattern just like in a normal route entry, so in this example, the routing system will now ignore any requests for /blah.xyz or /foo.xyz?some=querystring. (Of course, you must place this entry higher in the route table than any other entry that would match and handle those URLs.) You can also pass a constraints parameter if you want tighter control over exactly which URLs are ignored by routing.

IgnoreRoute() is helpful if

How does this work? Internally, IgnoreRoute() sets up a route entry whose RouteHandler is an instance of StopRoutingHandler (rather than MvcRouteHandler). In fact, the example shown here is exactly equivalent to writing the following:

routes.Add(new Route("{filename}.xyz", new StopRoutingHandler()));

The routing system is hard-coded to look out for StopRoutingHandler and recognizes it as a signal to bypass routing. You can use StopRoutingHandler as the route handler in your own custom routes and RouteBase classes if you want to set up more complicated rules for not routing certain requests.

The simplest way to generate a URL and render it in a normal HTML hyperlink is to call Html.ActionLink() from a view template—for example:

<%: Html.ActionLink("See all of our products", "List", "Products") %>

will render an HTML hyperlink to whatever URL, under your current routing configuration, goes to the List action on your controller class ProductsController. Under the default routing configuration, it therefore renders

<a href="/Products/List">See all of our products</a>

Note that if you don't specify a controller (i.e., if you call Html.ActionLink("See all of our products", "List")), then by default it assumes that you're referring to another action on the same controller currently being executed.

That's a lot cleaner than hard-coded URLs and raw string manipulation.Most importantly, it solves the problem of changing URL schema. Any changes to your routing configuration will be reflected immediately by any URLs generated this way.

It's also better from a separation-of-concerns perspective. As your application grows, you might prefer to consider routing (i.e., the business of choosing URLs to identify controllers and actions) a totally separate concern from placing everyday links and redirections between views and actions. Each time you place a link or redirection, you don't want to think about URLs; you only want to think about which action method the visitor should end up on. Automatic outbound URL generation helps you to avoid muddling these concerns—minimizing your mental juggling.

<%: Html.ActionLink("Red items", "List", "Products",
                     new { color="Red", page=2 }, null) %>

<a href="/Products/List?color=Red&amp;page=2">Red items</a>

<a href="/Products/List/Red/2">Red items</a>

<%: Html.ActionLink("Products homepage", "Index", "Products") %>

<a href="/Products">Products homepage</a>

<%: Html.ActionLink("Click me", "MyAction", "MyController", "https",
                    "www.example.com", "anchorName", new { param = "value" },
                    new { myattribute = "something" }) %>

<a myattribute="something"
   href="https://www.example.com/MyController/MyAction?param=value#anchorName">
Click me</a>

You know that the routing system isn't intended only for ASP.NET MVC, so it doesn't give special treatment to parameters called controller or action. However, all the URL-generating methods you've seen so far do require you to specify an explicit action method (e.g., Html.ActionLink() always takes an action parameter).

Sometimes it's handy not to treat controller or action as special cases, but simply to treat them just like any other routing parameter. For example, in Chapter 5, the navigation links were built from NavLink objects that just held arbitrary collections of routing data. For these scenarios, there are alternative URL-generating methods that don't force you to treat controller or action as special cases. They just take an arbitrary collection of routing parameters and match that against your routing configuration.

Html.RouteLink() is the equivalent of Html.ActionLink()—for example:

<%: Html.RouteLink("Click me", new { controller = "Products", action = "List" }) %>

will render the following (under the default routing configuration):

<a href="/Products/List">Click me</a>

Similarly, Url.RouteUrl() is equivalent to Url.Action(). For example, under the default URL configuration

<%: Url.RouteUrl(new { controller = "Products", action = "List" }) %>

will render the following URL:

/Products/List

Note that this is just a URL string, not a complete HTML <a> tag.

In ASP.NET MVC applications, these methods aren't often needed. However, it's good to know that you have such flexibility if you do need it, or if it simplifies your code (as it did in Chapter 5).

The most common reason to generate URLs is to render HTML hyperlinks. The second most common reason is when an action method wants to issue an HTTP redirection command, which instructs the browser to move immediately to some other URL in your application.

To issue an HTTP redirection, simply return the result of RedirectToAction(), passing it the target controller and action method:

public ActionResult MyActionMethod()
{
    return RedirectToAction("List", "Products");
}

This returns a RedirectToRouteResult object, which, when executed, uses the URL-generating methods internally to find the correct URL for those route parameters, and then issues an HTTP 302 redirection to it. As usual, if you don't specify a controller (e.g., return RedirectToAction("List")), it will assume you're talking about another action on the same controller that is currently executing.

Alternatively, you can specify an arbitrary collection of routing data using RedirectToRoute():

public ActionResult MyActionMethod()
{
    return RedirectToRoute(new { action = "SomeAction", customerId = 456 });
}

If, rather than performing an HTTP redirection, you simply want to obtain a URL as a string, you can call Url.Action() or Url.RouteUrl() from your controller code—for example:

public ActionResult MyActionMethod()
{
    string url = Url.Action("SomeAction", new { customerId = 456 });
    // ... now do something with url
}

You've now seen a lot of examples of generating outbound URLs. But routing configurations can contain multiple entries, so how does the framework decide which route entry to use when generating a URL from a given set of routing values? The actual algorithm has a few subtleties that you wouldn't guess, so it's helpful to have the details on hand in case you hit any surprising behavior.

Just like inbound route matching, it starts at the top of the route table and works down in sequence until it hits the first RouteBase object that returns a non-null URL for the supplied collection of routing values. Standard Route objects will return a non-null URL only when these three conditions are met:

The first Route object meeting these criteria will produce a non-null URL, and that will terminate the URL-generating process. The chosen parameter values will be substituted in for each curly brace placeholder, with any trailing sequence of default values omitted. If you've supplied any explicit parameters that don't correspond to curly brace or default parameters, then it will render them as a set of query string name/value pairs.

Just to make it ridiculously clear, the framework doesn't try to pick the most specific route entry or URL pattern. It stops when it finds the first one that matches; so follow the golden rule of routing—put more specific entries above less specific ones! If a certain entry matches when you don't want it to, you must either move it further down the list or make it even more specific (e.g., by adding constraints or removing defaults) so that it no longer matches when you don't want it to.

routes.MapRoute(null, "{controller}/{action}/{color}/{page}");

<%: Html.ActionLink("Click me", "List", "Catalog", new {page=789}, null) %>

<a href="/Catalog/List/Purple/789">Click me</a>

<%: Html.ActionLink("Click me", "List", "Catalog", new {color="Aqua"}, null) %>

Using Html.ActionLink() is better than using hard-coded string manipulations, but you could still argue that it's not especially type-safe. There's no IntelliSense to help you specify an action name or pass the correct set of custom parameters to it.

The MVC Futures assembly, Microsoft.Web.Mvc.dll,^[53] contains a generic overload, Html.ActionLink<T>(). Here's how it looks:

<%: Html.ActionLink<ProductsController>(x =>x.List(), "All products") %>

This would render the following (under the default routing configuration):

<a href="/Products/List">All products</a>

This time, the generic ActionLink<T>() method takes a generic parameter T specifying the type of the target controller, and then the action method is indicated by a lambda expressionacting on that controller type. The lambda expression is never actually executed. During compilation, it becomes a data structure that the routing system can inspect at runtime to determine what method and parameters you're referencing.

With Html.ActionLink<T>(), you get a strongly typed interface to your URL schema with full IntelliSense. Most newcomers imagine that this is hugely advantageous, but actually it brings both technical and conceptual problems:

It would be great if Html.ActionLink<T>() could be guaranteed to work properly, because the benefits of a strongly typed API and IntelliSense are compelling indeed. However, there are many scenarios in which it cannot work, and that's why the MVC team put this helper into the MVC Futures assembly, not the ASP.NET MVC core package. Most ASP.NET MVC developers prefer to stick to the regular string-based overloads of Html.ActionLink().

You can give each route entry a unique name—for example:

routes.Add("intranet", new Route("staff/{action}", new MvcRouteHandler())
{
    Defaults = new RouteValueDictionary(new { controller = "StaffHome" })
});

Or equivalently, using MapRoute():

routes.MapRoute("intranet", "staff/{action}", new { controller = "StaffHome" });

Either way, this code creates a named route entry called intranet. Everyone seems to think it's a good idea to gives names to their children, but what's the point of giving names to our route entries? In some cases, it can simplify outbound URL generation. Instead of having to put your route entries in the right order so the framework will pick the right one automatically, you can just specify which one you want by name. You can specify a route name when calling Url.RouteUrl() or Html.RouteLink()—for example:

<%: Html.RouteLink("Click me", "intranet", new { action = "StaffList" }) %>

This will generate

<a href="/staff/StaffList">Click me</a>

regardless of any other entries in your routing configuration.

Without named routes, it can be difficult to make sure that both inbound and outbound routing always select exactly the route you want. Sometimes it seems that the correct priority order for inbound matching conflicts with the correct priority order for outbound URL generation, and you have to figure out what constraints and defaults give the desired behavior. Naming your routes lets you stop worrying about ordering and directly select them by name. At times, this obviously can be advantageous.

The easiest way to add a new area to your ASP.NET MVC project is to right-click the project name in Solution Explorer and choose Add

Figure 8-2. Visual Studio's prompt for an area name

Once you enter a name, Visual Studio will add to your project a new top-level folder called Areas (unless that folder already exists), and inside that folder it will prepare a directory structure for the new area.

For example, call your area Admin. Figure 8-3 shows what you'll get.

Figure 8-3. Folder structure created for a new area called Admin

Obviously, the folders Controllers, Models, and Views are area-specific versions of the equivalent folders that you normally have in your project's root folder. I'll explain AdminAreaRegistration.cs in just a moment.

The workflow for adding functionality to an area is exactly like the workflow when building your top-level ASP.NET MVC project.

Continuing the example, you could add the following controller to the Adminarea:

namespace MyAppName.Areas.Admin.Controllers
{
    public class StatsController : Controller
    {
        public ViewResult Index()
        {
            // To do: Generate some stats for display
            return View();
        }
    }
}

Now, assuming you also create a view for the Index action (which Visual Studio will automatically place at /Areas/Admin/Views/Stats/Index.aspx), you'll be able to run the action by browsing either to /Admin/Stats/Index or /Admin/Stats.

At runtime, how does ASP.NET MVC find out what areas exist, and how does it integrate them into the host application?When your application starts up, it runs a method in Global.asax.cs called Application_Start(). By default, this method contains the following.

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

The line shown in bold tells the framework to scan your referenced assemblies for all area registration classes. An area registration class is any public class inherited from AreaRegistration. You'll recall from Figure 8-2 that when Visual Studio creates the files for a new area, it creates one called AdminAreaRegistration.cs. For an area called Admin, that class will contain the following by default.

namespace MyAppName.Areas.Admin
{
    public class AdminAreaRegistration : AreaRegistration
    {
        public override string AreaName { get { return "Admin"; } }

        public override void RegisterArea(AreaRegistrationContext context)
        {
            context.MapRoute(
                "Admin_default",
                "Admin/{controller}/{action}/{id}",
                new { action = "Index", id = UrlParameter.Optional }
            );
        }
    }
}

As you can guess, each area registration class declares the name and routing entries for a particular area. The MVC Framework finds each such class, constructs an instance using its default (parameterless) constructor, and calls its RegisterArea() method. This is where you can add any initialization logic for your area, such as registering route entries.

<%: Html.ActionLink("Export...", "Export", "Stats", new { area = "Admin" }, null) %>

<a href="/Admin/Stats/Export">Export...</a>

Normally, it doesn't matter if you use the same controller name in multiple areas. That's pretty much the whole point of areas! Unfortunately there is one exception, and that's to do with the root area.

When an incoming request matches a route entry associated with the root area (i.e., a regular top-level entry configured in Global.asax.cs), that route entry won't be associated with any particular area namespaceby default. So, when the controller factory goes looking for a matching controller, it will consider controllers in any namespace—in all areas and outside them all. If you have a HomeController in /Controllers and another one in /Areas/anyName/Controllers, then if you request the URL /Home, the framework won't know which controller to use, so it will fail, saying "Multiple types were found that match the controller name 'Home'."

To resolve this, you need to alter your root area routing configuration and specify your root area controller namespace explicitly. For example, you could alter the default route entry in Global.asax.cs as follows:

routes.MapRoute(
    "Default",                                    // Route name
    "{controller}/{action}/{id}",                 // URL with parameters
    new { controller = "Home", action = "Index",  // Parameter defaults
          id = UrlParameter.Optional },
    new [] { "MyAppName.Controllers" }           // Prioritized namespace
);

Now, when somebody requests a URL such as /Home or simply /, it will match this route entry and use the controller normally located at /Controllers/HomeController.cs. And if someone requests /Admin/Home, it will use the controller normally located at /Areas/Admin/Controllers/HomeController.cs. This is the behavior that most ASP.NET MVC developers will expect and want.

You now know how to create multiple areas in a single Visual Studio project, populate them with controllers and views, configure their routing entries, and place links within them and across them. This is the most common way to use areas and has proven to be an effective way to structure large ASP.NET MVC applications.

Remember that you can access your routing configuration via a public static method in Global.asax.cs called RegisterRoutes(). So, a basic route test looks like the following:

[TestFixture]
public class InboundRouteMatching
{
    [Test]
    public void TestSomeRoute()
    {
        // Arrange (obtain routing config + set up test context)
        RouteCollection routeConfig = new RouteCollection();
        MvcApplication.RegisterRoutes(routeConfig);
        HttpContextBase testContext = Need to get an instance somehow

        // Act (run the routing engine against this HttpContextBase)
        RouteData routeData = routeConfig.GetRouteData(testContext);

        // Assert
        Assert.IsNotNull(routeData, "NULL RouteData was returned");
        Assert.IsNotNull(routeData.Route, "No route was matched");
        // Add other assertions to test that this is the right RouteData
    }
}

The tricky part is obtaining an HttpContextBase instance. Of course, you don't want to couple your test code to any real web server context (so you're not going to use System.Web.HttpContext). The idea is to set up a special test instance of HttpContextBase. You could create a test double or a mock—let's examine both techniques.

Using Test Doubles

The first way to obtain an HttpContextBase instance is to write your own test double. Essentially, this means deriving a class from HttpContextBase and supplying test implementations of only the methods and properties that will actually get used.

Here's a minimal test double that's enough to test inbound and outbound routing. It tries to do as little as possible. It only implements the methods that routing will actually call (you discover which ones by trial and error), and even then, those implementations are little more than stubs.

public class TestHttpContext : HttpContextBase
{
    TestHttpRequest testRequest;
    TestHttpResponse testResponse;
    public override HttpRequestBase Request { get { return testRequest; } }
    public override HttpResponseBase Response { get { return testResponse; } }
    public TestHttpContext(string url)
    {
        testRequest = new TestHttpRequest() {
            _AppRelativeCurrentExecutionFilePath = url
        };
        testResponse = new TestHttpResponse();
    }

    class TestHttpRequest : HttpRequestBase
    {
        public string _AppRelativeCurrentExecutionFilePath { get; set; }
        public override string AppRelativeCurrentExecutionFilePath
        {
            get { return _AppRelativeCurrentExecutionFilePath; }
        }

        public override string ApplicationPath { get { return null; } }
        public override string PathInfo { get { return null; } }
        public override NameValueCollection ServerVariables {
            get { return null; }
        }
    }
    class TestHttpResponse : HttpResponseBase
    {
        public override string ApplyAppPathModifier(string x) { return x; }
    }
}

Now, using your test double, you can write a complete test:

[Test]
public void ForwardSlashGoesToHomeIndex()
{
    // Arrange (obtain routing config + set up test context)
    RouteCollection routeConfig = new RouteCollection();
    MvcApplication.RegisterRoutes(routeConfig);

HttpContextBase testContext = new TestHttpContext("~/");

    // Act (run the routing engine against this HttpContextBase)
    RouteData routeData = routeConfig.GetRouteData(testContext);

    // Assert
    Assert.IsNotNull(routeData, "NULL RouteData was returned");
    Assert.IsNotNull(routeData.Route, "No route was matched");
    Assert.AreEqual("Home", routeData.Values["controller"], "Wrong controller");
    Assert.AreEqual("Index", routeData.Values["action"], "Wrong action");
}

After recompiling your tests project, you can run it. Launch NUnit GUI from your start menu or from Program FilesNUnit versionin et-2.0 unit.exe, choose File

Note

If you're using .NET 4, you must use NUnit 2.5.5 or later. Otherwise, NUnit GUI will be unable to load your assembly, and will report an error saying "System.BadImageFormatException" or similar.

NUnit will scan the assembly to find the [TestFixture] classes, and will display a hierarchy of test fixtures and tests, as shown in Figure 8-4. Once you click Run, you should see a green light—the test has passed! This proves that the URL / is handled by the Index action on HomeController.

Figure 8-4. NUnit GUI displaying a successful test run

[Test]
public void ForwardSlashGoesToHomeIndex()
{
    // Arrange (obtain routing config + set up test context)
    RouteCollection routeConfig = new RouteCollection();
    MvcApplication.RegisterRoutes(routeConfig);
    var mockHttpContext = MakeMockHttpContext("~/");

    // Act (run the routing engine against this HttpContextBase)
    RouteData routeData = routeConfig.GetRouteData(mockHttpContext.Object);

    // Assert
    Assert.IsNotNull(routeData, "NULL RouteData was returned");
    Assert.IsNotNull(routeData.Route, "No route was matched");
    Assert.AreEqual("Home", routeData.Values["controller"], "Wrong controller");
    Assert.AreEqual("Index", routeData.Values["action"], "Wrong action");
}

private static Mock<HttpContextBase> MakeMockHttpContext(string url)
{
    var mockHttpContext = new Mock<HttpContextBase>();

    // Mock the request
    var mockRequest = new Mock<HttpRequestBase>();
    mockHttpContext.Setup(x => x.Request).Returns(mockRequest.Object);
    mockRequest.Setup(x => x.AppRelativeCurrentExecutionFilePath).Returns(url);

    // Mock the response
    var mockResponse = new Mock<HttpResponseBase>();
    mockHttpContext.Setup(x => x.Response).Returns(mockResponse.Object);
    mockResponse.Setup(x => x.ApplyAppPathModifier(It.IsAny<string>()))
                .Returns<string>(x => x);

    return mockHttpContext;
}

[Test]
public void ForwardSlashGoesToHomeIndex()
{
    TestRoute("~/", new { controller = "Home", action = "Index" });
}

public RouteData TestRoute(string url, object expectedValues)
{
    // Arrange (obtain routing config + set up test context)
    RouteCollection routeConfig = new RouteCollection();
    MvcApplication.RegisterRoutes(routeConfig);
    var mockHttpContext = MakeMockHttpContext(url);

    // Act (run the routing engine against this HttpContextBase)
    RouteData routeData = routeConfig.GetRouteData(mockHttpContext.Object);

    // Assert
    Assert.IsNotNull(routeData.Route, "No route was matched");
    var expectedDict = new RouteValueDictionary(expectedValues);
    foreach (var expectedVal in expectedDict)
    {
        if (expectedVal.Value == null)
            Assert.IsNull(routeData.Values[expectedVal.Key]);
        else
            Assert.AreEqual(expectedVal.Value.ToString(),
                            routeData.Values[expectedVal.Key].ToString());
    }

    return routeData; // ... in case the caller wants to add any other assertions
}

[Test]
public void ProductDeletionGoesToProductsDeleteWithId()
{
    TestRoute("~/Products/Delete/58",
              new { controller = "Products", action = "Delete", id = 58 });
}

It's equally possible to test how the framework generates outbound URLs from your configuration. You might want to do this if you consider your public URL schema to be a contract that must not be changed except deliberately.

This is slightly different from testing inbound route matching. Just because a particular URL gets mapped to a certain set of RouteData values, it doesn't mean that same set of RouteData values will be mapped back to the that same URL (there could be multiple matching route entries). Having a solid set of tests for both inbound and outbound routing can be invaluable if you're creating a complex routing configuration and find yourself changing it frequently.

You can use the same test double from before:

[Test]
public void EditProduct50_IsAt_Products_Edit_50()
{
    string result = GenerateUrlViaTestDouble(
        new { controller = "Products", action = "Edit", id = 50 }
    );

    Assert.AreEqual("/Products/Edit/50", result);
}

private string GenerateUrlViaTestDouble(object values)
{
    // Arrange (get the routing config and test context)
    RouteCollection routeConfig = new RouteCollection();
    MvcApplication.RegisterRoutes(routeConfig);
    var testContext = new TestHttpContext(null);
    RequestContext context = new RequestContext(testContext, new RouteData());

    // Act (generate a URL)
    return UrlHelper.GenerateUrl(null, null, null, /* Explained below */
        new RouteValueDictionary(values), routeConfig, context, true);
}

The reason for all the null parameters in the call to UrlHelper.GenerateUrl() is that, instead of explicitly passing a routeName, a controller, or an action, it's easier to let the framework take its values from the RouteValueDictionary parameter.

Alternatively, you can choose not to bother with the HttpContextBase test double, and instead create a mock implementation on the fly. Simply replace GenerateUrlViaTestDouble() with GenerateUrlViaMocks():

private string GenerateUrlViaMocks(object values)
{
    // Arrange (get the routing config and test context)
    RouteCollection routeConfig = new RouteCollection();
    MvcApplication.RegisterRoutes(routeConfig);
    var mockContext = MakeMockHttpContext(null);
    RequestContext context = new RequestContext(mockContext.Object,new RouteData());

    // Act (generate a URL)
    return UrlHelper.GenerateUrl(null, null, null,
        new RouteValueDictionary(values), routeConfig, context, true);
}

Note that MakeMockHttpContext() was defined in the previous mocking example.

// Arrange (get the routing config and test context)
RouteCollection routeConfig = new RouteCollection();
RegisterAllAreas(routeConfig);
MvcApplication.RegisterRoutes(routeConfig);
// ... rest as before ...

private static void RegisterAllAreas(RouteCollection routes)
{
    var allAreas = new AreaRegistration[] {
        new AdminAreaRegistration(),
        new BlogAreaRegistration(),
        // ...etc. (Manually add whichever ones you're using)
    };

    foreach (AreaRegistration area in allAreas) {
        var context = new AreaRegistrationContext(area.AreaName, routes);
        context.Namespaces.Add(area.GetType().Namespace);
        area.RegisterArea(context);
    }
}

[Test]
public void AdminAreaStatsExport_IsAt_Admin_Stats_Export()
{
    string result = GenerateUrlViaMocks(
        new { area = "Admin", controller = "Stats", action = "Export" }
    );

    Assert.AreEqual("/Admin/Stats/Export", result);
}

If you don't like the way that standard Route objects match URLs, or want to implement something unusual, you can derive an alternative class directly from RouteBase. This gives you absolute control over URL matching, parameter extraction, and outbound URL generation. You'll need to supply implementations for two methods:

Of course, you can mix custom RouteBase objects with normal Route objects in the same routing configuration. For example, if you're replacing an old web site with a new one, you might have a disorganized collection of old URLs that you want to retain support for on the new site (to avoid breaking incoming links). Instead of setting up a complex routing configuration that recognizes a range of legacy URL patterns, you might create a single custom RouteBase entry that recognizes specific legacy URLs and passes them on to some controller that can deal with them:

using System.Linq;

public class LegacyUrlsRoute : RouteBase
{
    // In practice, you might fetch these from a database
    // and cache them in memory
    private static string[] legacyUrls = new string[] {
        "~/articles/may/zebra-danio-health-tips.html",
        "~/articles/VelociraptorCalendar.pdf",
        "~/guides/tim.smith/BuildYourOwnPC_final.asp"
    };

    public override RouteData GetRouteData(HttpContextBase httpContext)
    {
        string url = httpContext.Request.AppRelativeCurrentExecutionFilePath;
        if(legacyUrls.Contains(url, StringComparer.OrdinalIgnoreCase)) {
            RouteData rd = new RouteData(this, new MvcRouteHandler());
            rd.Values.Add("controller", "LegacyContent");
            rd.Values.Add("action", "HandleLegacyUrl");
            rd.Values.Add("url", url);
            return rd;
        }
        else
            return null; // Not a legacy URL
    }

public override VirtualPathData GetVirtualPath(RequestContext requestContext,
                                                   RouteValueDictionary values)
    {
        // This route entry never generates outbound URLs
        return null;
    }
}

Register this at the top of your routing configuration (so it takes priority over other entries):

public static void RegisterRoutes(RouteCollection routes)
{
    routes.IgnoreRoute("{resource}.axd/{*pathInfo}");
    routes.Add(new LegacyUrlsRoute());
    // ... other route entries go here
}

and you'll now find that any of those legacy URLs get handled by a HandleLegacyUrl() action method on LegacyContentController (assuming that it exists). All other URLs will match against the rest of your routing configuration as usual.

All the routing examples so far have used MvcRouteHandler for their RouteHandler property. In most cases, that's exactly what you want—it's the MVC Framework's default route handler, and it knows how to find and invoke your controller classes.

Even so, the routing system lets you use your own custom IRouteHandler if you wish. You can use custom route handlers on individual routes, or on any combination of routes. Supplying a custom route handler lets you take control of the request processing at a very early stage: immediately after routing and before any part of the MVC Framework kicks in. You can then replace the remainder of the request processing pipeline with something different.

Here's a very simple IRouteHandler that writes directly to the response stream:

public class HelloWorldHandler : IRouteHandler
{
    public IHttpHandler GetHttpHandler(RequestContext requestContext)
    {
        return new HelloWorldHttpHandler();
    }

    private class HelloWorldHttpHandler : IHttpHandler
    {
        public bool IsReusable { get { return false; } }

        public void ProcessRequest(HttpContext context)
        {
            context.Response.Write("Hello, world!");
        }
    }
}

You can register it in the route table like this:

routes.Add(new Route("SayHello", new HelloWorldHandler()));

and then invoke it by browsing to /SayHello (see Figure 8-5).

Figure 8-5. Output from the custom IRouteHandler

There's no concept of controllers or actions here, because you've bypassed everything in the MVC Framework after routing. You could invent a completely independent web application platform and attach it to the core routing system to take advantage of its placeholder, defaults, route validation, and URL generation features.

In Chapter 18, you'll see how to use a .NET 4 route handler type called PageRouteHandler, which knows how to locate and invoke ASP.NET Web Forms pages. That lets you integrate ASP.NET Web Forms into the routing system.

Please remember that URLs are just as much part of your UI as the fonts and graphics you choose. End users certainly notice the contents of their browser's address bar, and they will feel more comfortable bookmarking and sharing URLs if they can understand them. Consider this URL:

http://www.amazon.com/gp/product/1430210079/ref=r2_dwew_cc_e22_d3?pf_rd_m=
LCIEMCJSLEMCJ&pf_rd_s=center-2&pf_rd_r=3984KEDMDJEMDKEMDKE&pf_rd_t=103
&pf_rd_p=489302938&pf_rd_i=493855

Now, do you want to share that link with your mother? Is it safe for work? Does it contain your private account information? (I actually changed the random-looking query string values because I don't know.) Can you read it out over the phone? Is it a permanent URL, or will it change over time? I'm sure all those query string parameters are being used for something, but their damage on the site's usability is quite severe. The same page could be reachable via:

http://www.amazon.com/books/pro-aspnet-mvc-framework

The following list gives some guidelines on how to make your URLs human-friendly:

URLs should be short, easy to type, hackable (human-editable), and persistent, and should visualize site structure. Jakob Nielsen, usability guru, expands on this topic at www.useit.com/alertbox/990321.html. Tim Berners-Lee, inventor of the Web, offers similar advice (see www.w3.org/Provider/Style/URI).

The Web has a long history of permissiveness. Even the most mangled HTML is rendered to the best of the browser's abilities, and HTTP can be abused without apparent consequence. But as you will see, standards-compliant web applications are more reliable, more usable, and can make more money.

public static class PermanentRedirectionExtensions
{
    public static PermanentRedirectToRouteResult AsMovedPermanently
        (this RedirectToRouteResult redirection)
    {
        return new PermanentRedirectToRouteResult(redirection);
    }

    public class PermanentRedirectToRouteResult : ActionResult
    {
        public RedirectToRouteResult Redirection { get; private set; }
        public PermanentRedirectToRouteResult(RedirectToRouteResult redirection)
        {
            this.Redirection = redirection;
        }
        public override void ExecuteResult(ControllerContext context)
        {
            // After setting up a normal redirection, switch it to a 301
            Redirection.ExecuteResult(context);
            context.HttpContext.Response.StatusCode = 301;
        }
    }
}

public ActionResult MyActionMethod()
{
    return RedirectToAction("AnotherAction").AsMovedPermanently();
}

You've just considered URL design in terms of maximizing usability and compliance with HTTP conventions. Let's now consider specifically how URL design is likely to affect search engine rankings.

Here are some techniques that can improve your chances of being ranked highly:

SEO is a dark and mysterious art, because Google and the other search engines will never reveal the inner details of their ranking algorithms. URL design is only part of it—link placement and getting inbound links from other popular sites are more critical. Focus on making your URLs work well for humans, and those URLs will tend to do well with search engines, too.