Chapter 9 – Understanding Routing

This is a rough draft of a chapter from the book ASP.NET MVC Framework Unleashed by Stephen Walther. Comments are welcome and appreciated. When the book is published, the text from this blog entry will be removed and only the code listings will remain.

When you request a page from an ASP.NET MVC application, the request gets routed to a particular controller. In this chapter, you learn how to use the ASP.NET Routing module to control how browser requests get mapped to controllers and controller actions.

In the first part of this chapter, you learn about the Default route that you get when you create a new ASP.NET MVC application. You learn about the standard parts of any route.

Next, you learn how to debug the routes in your ASP.NET MVC applications. You learn how to use the Route Debugger project included with this book to see how browser requests get mapped to particular routes.

We also discuss how you can create custom routes. You learn how to extract custom parameters from a URL. You also learn how to create custom constraints that restrict the URLs that match a particular route.

Finally, we tackle the important topic of testing your routes. You learn how to build unit tests for custom routes and route constraints.

Using the Default Route

You configure ASP.NET Routing in an application’s Global.asax file. This makes sense because the Global.asax file contains event handlers for application lifecycle events such as the application Start and application End events. Because you want your routes to be enabled when an application first starts, routing is set up in the application Start event.

When you create a new ASP.NET MVC application, you get the Global.asax file in Listing 1.

*** Begin Note ***

The default route defined in the Global.asax file only works with Internet Information Server 7.0 and the ASP.NET Development Web Server. If you need to deploy your ASP.NET MVC application to an older version of Internet Information Server, see Chapter 15, Deploying MVC Applications.

The Global.asax file in Listing 1 includes two methods named Application_Start() and RegisterRoutes(). The Application_Start() method is called once, and only once, when an ASP.NET application first starts. In Listing 1, the Application_Start() method simply calls the RegisterRoutes() method.

*** Begin Note ***

Why does the Global.asax file include a separate method called RegisterRoutes()? Why isn’t the code in the RegisterRoutes() method simply contained in the Application_Start() method?

A separate method was created to improve testability. You can call the RegisterRoutes() method from your unit tests without instantiating the HttpApplication class.

*** End Note ***

The RegisterRoutes() method is used to configure all of the routes in an application. The RegisterRoutes() method in Listing 1 configures the Default route with the following code:

You configure a new route by calling the MapRoute() method. This method accepts the following parameters:

· Name – The name of the route

· URL – The URL pattern for the route

· Defaults – The default values of the route parameters

· Constraints – A set of constraints that restrict the requests that match the route

· Namespaces – A set of namespaces that restrict the classes that match the route

The MapRoute() method has multiple overloads. You can call the MapRoute() method without supplying the Defaults, Constraints, or Namespaces parameters.

The default route configured in the Global.asax file in Listing 1 is named, appropriate enough, Default.

The URL parameter for the Default route matches URLs that satisfy the pattern {controller}/{action}/{id}. Therefore, the Default route matches URLs that look like this:

· /Product/Insert/23

· /Home/Index/1

· /Do/Something/Useful

However, the Default route does not match a URL that looks like this:

· /Product/Insert/Another/Item

The problem with this last URL is that it has too many segments. It has four different segments (four forward slashes) and the URL pattern {controller}/{action}/{id} only matches URLs that have three segments.

The URL pattern {controller}/{action}/{id} maps the first segment to a parameter named controller, the second segment to a parameter named action, and the final segment to a parameter named id.

The controller and action parameters are special. The ASP.NET MVC framework uses the controller parameter to determine which MVC controller to use to handle the request. The action parameter represents the action to call on the controller in response to the request.

If you create additional parameters – parameters that are not named controller or action – then the additional parameters are passed to an MVC controller action when the action is invoked. For example, the id parameter is passed as a parameter to a controller action.

Finally, the Default route includes a set of default values for the controller, action, and id parameters. By default, the controller parameter has the value Home, the action parameter has the value Index, and the id parameter has the value “” (empty string).

For example, imagine that you enter the following URL into the address bar of your browser:

http://www.MySite.com/Product

In that case, the controller, action, and id parameter would have the following values:

controller : Product

action: Index

id : “”

Now, imagine that you request the default page for a website:

http://www.MySite.com/

In that case, the controller, action, and id parameters would have the following values:

controller : Home

action: Index

id : “”

In this case, the ASP.NET MVC framework would invoke the Index() action method on the HomeController class.

*** Begin Note ***

The code used to specify the defaults for a route might appear strange to you. This code is taking advantage of two new features of the Visual Basic .NET 9.0 and the C# 3.0 languages called anonymous types and property initializers. You can learn about these new language features by reading Appendix A.

*** End Note ***

Debugging Routes

In the next section, I show you how you can add custom routes to the Global.asax file. However, before we start creating custom routes, it is important to have some way of debugging our routes. Otherwise, things get confusing fast.

Included with the code that accompanies this book is a project named RouteDebugger. If you add a reference to the assembly generated by this project then you can debug the routes configured within any ASP.NET MVC application.

Here’s how you add a reference to the RouteDebugger assembly. Select the menu option Project, Add Reference to open the Add Reference dialog box (see Figure 1). Select the Browse tab and browse to the assembly named RouteDebugger.dll located in the RouteDebuggerBinDebug folder. Click the OK button to add the assembly to your project.

Figure 1 – Using the Add Reference dialog box

After you add the RouteDebugger assembly to an ASP.NET MVC project, you can debug the routes in the project by entering the following URL into the address bar of your browser:

/RouteDebugger

Invoking the RouteDebugger displays the page in Figure 2. You can enter any relative URL into the form field and view the routes that match the URL. The URL should be an application relative URL and start with the tilde character ~.

Figure 2 – Using the Route Debugger

Whenever you enter a URL into the Route Debugger, the Route Debugger displays all of the routes from the application’s route table. Each route that matches the URL is displayed with a green background. The first route that matches the URL is the route that would actually be invoked when the application is running.

*** Begin Warning ***

Be warned that changing your routes might prevent you from using the route debugger. You cannot invoke the RouteDebugger unless your application includes a route that maps to the RouteDebugger controller.

*** End Warning ***

Creating Custom Routes

You can build an entire ASP.NET MVC application without creating a single custom route. However, there are situations in which it makes sense to create a new route. For example, imagine that you are creating a blog application and you want to route requests that look like this:

/Archive/12-25-2008

When someone requests this URL, you want to display blog entries for the date 12-25-2008.

The Default route defined in the Global.asax would extract the following parameters from this URL:

controller: Archive

action: 12-25-1966

This is wrong. You don’t want to invoke a controller action named 12-25-1966. Instead, you want to pass this date to a controller action.

The BlogArchive route matches any URL that satisfies the pattern /Archive/{entryDate}. The route invokes a controller named Blog and a controller action method named Archive(). The entryDate parameter is passed to the Archive() action method.

You can use the controller in Listing 3 with the BlogArchive route. This controller contains an Archive() action method that echoes back the value of the entryDate parameter.

The order that you add a custom route to the Global.asax file is important. The first route matched is used. For example, if you reverse the order of the BlogArchive and Default routes in Listing 2, then the Default route would always be executed instead of the BlogArchive route.

*** Begin Warning ***

The order of your routes in the Global.asax file matters.

*** End Warning ***

Creating Route Constraints

When you create a custom route, you can include route constraints. A constraint restricts the requests that match a route. There are three basic types of constraints: regular expression constraints, the HttpMethod constraint, and custom constraints.

Using Regular Expression Constraints

You can use a regular expression constraint to prevent a request from matching a route unless a parameter extracted from the request matches a particular regular expression pattern. You can use regular expressions to match just about any string pattern including currency amounts, dates, times, and numeric formats.

For example, the BlogArchive custom route that we created in the previous section was created like this:

There is nothing to prevent you from entering something that is not a date in the URL. If you request a URL like /Archive/apple, then you get the error page in Figure 3.

Figure 3 – Entering a URL with an invalid date

We really need to prevent URLs that don’t contain dates from matching our BlogArchive route. The easiest way to fix our route is to add a regular expression constraint. The following modified version of the BlogArchive route won’t match URLs that don’t contain dates in the format 01-01-0001:

The fourth parameter passed to the MapRoute() method represents the constraints. This constraint prevents a request from matching this route when the entryDate parameter does not match the regular expression d{2}-d{2}-d{4}. In other words, the entryDate must match the pattern of two decimals followed by a dash followed by two decimals followed by a dash followed by four decimals.

You can quickly test your new version of the BlogArchive route with the RouteDebugger. The page in Figure 4 shows the matched routes when an invalid date is entered. Notice that the BlogArchive route is not matched.

Figure 4 – Using the RouteDebugger with the modified BlogArchive route

Using the HttpMethod Constraint

The URL Routing framework includes a special constraint named the HttpMethod constraint. You can use the HttpMethod constraint to match a route to a particular type of HTTP operation. For example, you might want to prevent a particular URL from being accessed when performing an HTTP GET but not when performing an HTTP POST.

*** Begin Note ***

Instead of using the HttpMethod constraint, consider using the AcceptVerbs attribute. You can apply the AcceptVerbs attribute to a particular controller action or an entire controller to prevent a controller action from being invoked unless the action is invoked with the right HTTP method. We discuss the AcceptVerbs attribute in Chapter 3, Understanding Controllers.

*** End Note ***

For example, the following route, named ProductInsert, can be called only when performing an HTTP POST operation:

You can check whether the ProductInsert route really works by taking advantage of the RouteDebugger. The RouteDebugger enables you to pick an HTTP method that you want to simulate. The page in Figure 5 illustrates testing the ProductInsert route when performing an HTTP POST operation.

Creating an Authenticated Constraint

If you need to create a more complicated constraint — something that you cannot easily represent with a regular expression — then you can create a custom constraint. You create a custom constraint by creating a class that implements the IRouteConstraint interface. This interface is really easy to implement since it includes only one method: the Match() method.

For example, Listing 4 contains a new constraint named the AuthenticatedConstraint. The AuthenticatedConstraint prevents a request from matching a route when the request is not made by an authenticated user.

In Listing 4, the Match() method simply returns the value of the HttpContext.Request.IsAuthenticated property to determine whether the current request is an authenticated request. If the Match() method returns the value False, then the request fails to match the constraint and the route is not matched.

After you create the AuthenticatedConstraint, you can use it with a route like this:

It is important to understand that the AuthenticatedConstraint prevents only a particular route from matching a request. Another route, that does not include the AuthenticatedConstraint, might match the very same request and invoke the very same controller action. In the next section, I show you how to create a constraint that prevents a route from ever invoking a particular controller.

*** Begin Note ***

The ASP.NET MVC framework includes an Authorize attribute that you can apply to either a particular action or entire controller to prevent access from unauthorized users. We discuss the Authorize attribute in Chapter 3, Understanding Controllers.

*** End Note ***

Creating a NotEqual Constraint

If you want to create a route that will never match a particular controller action — or more generally, that will never match a particular route parameter value – then you can create a NotEqual constraint.

This route works just like the Default route except for the fact that it will never match when the controller parameter has the value Admin. You can test the NotEqual constraint with the RouteDebugger. In Figure 6, the URL /Admin/Delete matches the Default route, but it does not match the DefaultNoAdmin route.

Figure 6 – Using the NotEqual Constraint

Using Catch-All Routes

Normally, in order to match a route, a URL must contain a particular number of segments. For example, the URL /Product/Details matches the following route:

This route requires a URL to have 3 segments and the URL /Product/Details has only two segments (two forward slashes).

*** Begin Note ***

The URL being requested is not required to have the same number of segments as a route’s URL parameter. When a route parameter has a default value, a segment is optional. For example, the URL /Home/Index matches a route that has the URL pattern {controller}/{action}/{id} when the id parameter has a default value.

*** End Note ***

If you want to match a URL, regardless of the number of segments in the URL, then you need to create something called a catch-all parameter. Here’s an example of a route that uses a catch-all parameter:

Notice that the catch-all parameter is passed to the Index() action as a string (you cannot pass the value as an array). The Index() method simply sorts the values contained in the catch-all parameter and returns a string with the values in alphabetical order (see Figure 7).

Figure 7 – Using a catch-all parameter

Testing Routes

Every feature of the ASP.NET MVC framework was designed to be highly testable and URL Routing is no exception. In this section, I describe how you can unit test both your routes and your route constraints.

Why would you want to build unit tests for your routes? If you build route unit tests then you can detect whether changes in your application break existing functionality automatically. For example, if your existing routes are covered by unit tests, then you know immediately whether introducing a new route prevents an existing route from ever being called.

Using the MvcFakes and RouteDebugger Assemblies

In order to unit test your custom routes, I recommend that you add references to two assemblies: the RouteDebugger and the MvcFakes assemblies.

If you want to test your routes by name, then you need to add a reference to the RouteDebugger assembly. The RouteDebugger assembly replaces the anonymous routes in your MVC application with named routes. That way, you can build tests that check whether a particular route is called by name.

I also recommend that you add a reference to the MvcFakes assembly. The MvcFakes assembly contains a set of fake objects that you can use in your unit tests. For example, MvcFakes includes a FakeHttpContext object. You can use the FakeHttpContext object to fake every aspect of a browser request.

Both of these assemblies are included with the code that accompanies this book. You can add references to these assemblies to your test project by selecting the menu option Project, Add Reference, selecting the Browse tab, and browsing to the following two assemblies (see Figure 12):

Chapter09RouteDebuggerBinDebugRouteDebugger.dll

CommonCodeMvcFakesBinDebugMvcFakes.dll

Figure 12 – Adding a reference to an assembly

Testing If a URL Matches a Route

Let’s start with a basic but very useful unit test. Let’s create a unit test that verifies that a particular URL matches a particular route. The unit test is contained in Listing 8.

You can add the unit test in Listing 8 to a Test project by selecting the menu option Project, Add New Test and selecting the Unit Test template. Remember to add the assembly references discussed in the previous section or the unit test won’t compile.

After you create the unit test in Listing 8, you can run it by entering the keyboard combination CTRL-R, A. Alternatively; you can click the Run All Tests in Solution button contained in the test toolbar (see Figure 9).

Figure 9 – Run all tests in the solution

The test in Listing 8 verifies that the URL ~/Home matches the route named Default. The unit test consists of three parts.

The first part, the Arrange part, sets up the routes by creating a new route collection and passing the route collection to the RegisterRoutes() method exposed by the Global.asax file (notice that you use the MvcApplication class to refer to the class exposed by Global.asax).

The second part, the Act part, sets up the fake HttpContext which represents the browser request for ~/Home. The FakeHttpContext object is part of the MvcFakes project. The FakeHttpContext object is passed to the GetRouteData() method. This method takes an HttpContext and returns a RouteData object that represents information about the route matched by the HttpContext.

Finally, the Assert part verifies that the RouteData represents a route named Default. At this point, the unit test either succeeds or fails. If it succeeds, then you get the test results in Figure 15.

Figure 15 – The test results

Testing Routes with Constraints

Let’s try testing a slightly more complicated route. Earlier in this chapter, we discussed the HttpMethodConstraint which you can use to match a route only when the right HTTP method is used. For example, the following route should only match a browser request performed with an HTTP POST operation:

The HttpMethodConstraint restricts this route to match only POST requests. This is the intention, how do you test it? Easy, fake the HTTP operation with the FakeHttpContext object.

The unit test in Listing 9 contains two unit tests. The first test verifies that the ProductInsert route is matched when performing a POST operation. The second test verifies that the ProductInsert route is not matched when performing a GET operation.

The second parameter passed to the constructor for the FakeHttpContext object determines the HTTP operation that the FakeHttpContext object represents.

Summary

In this chapter, you learned how to control how browser requests map to controllers and controller actions by taking advantage of ASP.NET Routing. We started by discussing the standard parts of a route.

You also learned how to debug the routes contained in the Global.asax file by taking advantage of the RouteDebugger assembly. We took advantage of the RouteDebugger when building our custom routes.

We also discussed how you can use route constraints to limit the routes that match a browser request. In particular, you learned how to use regular expression route constraints, HttpMethod route constraints, and custom route constraints.

Finally, you learned how to build unit tests for your custom routes. You learned how to take advantage of the FakeHttpContext object to fake different browser requests and test the routes that are matched.

ASP.NET 5/MVC 6 Training

Stephen – Very good content and I understand why you chose to have this as the second chapter, but as person new to the subject this chapter dives heavily into advanced routing scenarios before having a good understanding of the MVC paradiagm (which I assume you will be covering in more depth in CH3+. You could simply put a note at the start of “Creating Custom Routes” to skip this section for now and come back to later. Just an opinion.

well, Stephen, I’ve received your “webforms” book on my birthday, and it was really great. Although I liked some parts of it more than the others (content of .net 3.5 was somewhat “unfinished”. I mean whole LINQ part and some new C# 3.0 features.) I haven’t had doubt it is one of the most popular books there…

I thought the MVC will be another milestone, but I can’t say that I like the too much “theoretical” approach you have taken in this new book (the 1st and 2nd part).

As an example I’ll give you Bruce Eckel’s writing, which nice in the first editions of Java, to the time when he began working on C# (after finishing 4th Java ed) he had to abandon the book 😉There was too-too much theory how things works. Although I had some “wow” moments reading it (the “beta” electronic version) that you can get only by reading Eckel’s excellent matterial, the electronic version was more or less boring and I often slept after few pages. It was slow-paced and too much theoretical. And it was just about the language.

That’s why I think you should probably start your chapters with building your first application (from scratch) using scaffolding features and HTML helpers. And showing how “easy” to the contrary, it is. Because, basicaly, you can explain whole MVC concept in a few minutes.

Then probably explain and dive more to the Views/Controllers problematic, and later on to the model/OR/M topic. And all that is needed.

Last but not least something about routes, but which dear reader doesn’t need to understand too much in the begining. As simple modification is easy to do and simple explanation that routes doesn’t point to the resource on the server/disc will do.

Because once reader grasp a concept, will make his first app, and later grasp advanced concept, he will begin seeing problems with the routes and will need your chapter as a salt. But I think he (and I) won’t get it in the beginning of the book.

A newbie reading a book, and seeing Routes as 2nd chapter, still not able to build application yet, will be imho distracted.For me, starting learning ASP.NET MVC, routes were the last thing I’ve learnt (and I’ve skipped ScottGu blog part), and honestly I didn’t need it too much (basic stuff is easy to do).

Just my 2 cents, I am really looking forward for your book (I pre-ordered it) but I want it to be concise, practical, to the point with advanced code.And you can throw more theory in some later chapters “how things works”.

Because non-English readers like myself will get really bored when they need to read 300 pages to get to the metal.

I hope you know what I mean. Thanks. And sorry for criticism, there are certainly ppl that like your approach.

Steve,I believe I have all the books you’ve ever written on .Net, but there’s one thing I have found missing in all. You do not include a “Try it” section. That is, at the end of every chapter, you throw in a problem for the reader to resolve and then at the very end of the book, you provide a solution to the problem. This reinforces what was learned in the chapter and MVC being an entirely new (almost) concept, this may be very helpful.My 1.5cents ofcourse.cheers,yousaid

@craig, @cowgaR – Thanks for the comments. I’ve rearranged the chapters in the book in response. I’ve now pushed the Routing chapter back to Chapter 9. I’ve created a new Chapter 2 that consists of a walkthrough of a basic ASP.NET MVC application. The new chapter is here:stephenwalther.com/…/…net-mvc-application.aspx

Creating routes that include dashes allows you to include keywords in a URL. This is beneficial from a search engine optimization perspective. You might consider mentioning the SEO benefits that can be achieved by having dashes in URLs.

Stephen – More good stuff. I’m glad you’ve rearranged the order which this chapter appears.

You mention in one of the notes above that you discuss authorized requests in Chapter 3:

“The ASP.NET MVC framework includes an Authorize attribute that you can apply to either a particular action or entire controller to prevent access from unauthorized users. We discuss the Authorize attribute in Chapter 3, Understanding Controllers.”

In the current version of Chapter 3, I don’t believe you discuss the Authorize attribute. Maybe you’ll add that to the chapter?

Recent articles

Update on April, 30 2015 When I wrote this blog post, I wrote that Microsoft was not planning to support VB.NET in ASP.NET 5/MVC 6. That was true when I wrote the blog post, but this blog post generated some strong reactions from the VB.NET community. Well, it looks like VB.NET is back! http://www.infoq.com/news/2015/04/VB-Core I […]

In this blog post, I focus on how routing is implemented in ASP.NET 5 and MVC 6. I explain how to create routes, use RESTful routes, and use route constraints. While researching this blog post, I took full advantage of the open-source code for ASP.NET 5 located at the following GitHub repositories: https://github.com/aspnet Routing in […]

This is the seventh part in a multiple part blog series on building ASP.NET 5 (ASP.NET vNext) apps with AngularJS. In this series of blog posts, I show how you can create a simple Movie app using ASP.NET 5, MVC 6, and AngularJS. ASP.NET 5 and AngularJS Part 1, Grunt, Uglify, and AngularJS ASP.NET 5 […]

This is the sixth part in a multiple part blog series on building ASP.NET 5 (ASP.NET vNext) apps with AngularJS. In this series of blog posts, I show how you can create a simple Movie app using ASP.NET 5, MVC 6, and AngularJS. ASP.NET 5 and AngularJS Part 1, Grunt, Uglify, and AngularJS ASP.NET 5 […]

This is the fifth part in a multiple part blog series on building ASP.NET 5 (ASP.NET vNext) apps with AngularJS. In this series of blog posts, I show how you can create a simple Movie app using ASP.NET 5, MVC 6, and AngularJS. ASP.NET 5 and AngularJS Part 1, Grunt, Uglify, and AngularJS ASP.NET 5 […]