You can associate multiple filters with a single action method:

[ShowMessage(Message = "A")]
[ShowMessage(Message = "B")]
public ActionResult SomeAction()
{

Response.Write("Action is running");
    return Content("Result is running");
}

This outputs the following (the line break is added for clarity):

[BeforeAction B][BeforeAction A]Action is running[AfterAction A][AfterAction B]
[BeforeResult B][BeforeResult A]Result is running[AfterResult A][AfterResult B]

As you can see, it's like a stack: the OnActionExecuting() calls build up, then the actual action method runs, and then the stack unwinds with OnActionExecuted() calls in the opposite order—likewise with OnResultExecuting() and OnResultExecuted().

It just so happens that when I ran this code, filter B was chosen to go first in the stack, but your results may vary—technically, the filter stack order is undefined unless you specify an explicit order. You can assign an explicit stack order by assigning an int value to each filter's Order property (it's defined on the FilterAttribute base class):

[ShowMessage(Message = "A", Order = 1)]
[ShowMessage(Message = "B", Order = 2)]
public ActionResult SomeAction()
{
    Response.Write("Action is running");
    return Content("Result is running");
}

Lower Order values go first, so this time A and B appear in the opposite order:

[BeforeAction A][BeforeAction B]Action is running[AfterAction B][AfterAction A]
[BeforeResult A][BeforeResult B]Result is running[AfterResult B][AfterResult A]

All action filters are sorted by Order. It doesn't matter what action filter type they are, or whether they are defined at the action level, at the controller level, or on the controller's base class—lower Order values always run first. Afterward, all the result filters are run in order of their Order values.

If you don't assign an Order value, that filter is "unordered," and by default takes the special Order value of −1. You can't explicitly assign an order lower than −1, so unordered filters are always among the first to run. As I hinted at earlier, groups of filters with the same Order value (e.g., unordered ones) run in an undefined order among themselves.^[63]

What would you expect to happen if you attached the same type of filter both to a controller and to one of its action methods? The following code gives an example:

[ShowMessage(Message = "C")]
public class FiltersDemoController : Controller
{
    [ShowMessage(Message = "A")]
    public ActionResult SomeAction()
    {
        Response.Write("Action is running");
        return Content("Result is running");
    }
}

If the filter attribute is itself marked with an [AttributeUsage] attribute specifying AllowMultiple=true, then ASP.NET MVC will invoke both instances of the filter, so you'd get the following output (line break added):

[BeforeAction C][BeforeAction A]Action is running[AfterAction A][AfterAction C]
[BeforeResult C][BeforeResult A]Result is running[AfterResult A][AfterResult C]

But if the filter attribute is not marked with AllowMultiple=true—and by default it isn't—then the framework will consider instances associated with actions as overriding and replacing any instances of an identical type associated with controllers. So, you'd get the following output (line break added):

[BeforeAction A]Action is running[AfterAction A]
[BeforeResult A]Result is running[AfterResult A]

This behavior is useful if you want to establish a default behavior by applying a filter at the controller level, but also override and replace that behavior by using the same filter type on an individual action.

There is another way to attach code as a filter without having to create any attribute. The Controller base class itself implements IActionFilter, IResultFilter, IAuthorizationFilter, and IExecutionFilter. That means it exposes the following overridable methods:

If you override any of these, your code will be run at the exact same point in the request processing pipeline as the equivalent filter attribute. These controller methods are treated as being higher in the filter stack, above any filter attributes of the equivalent type, regardless of your attributes' Order properties. These methods give you a very quick and easy way to add controller code that runs before or after all action methods on that particular controller, or whenever an unhandled exception occurs in that particular controller.

So, when should you create and attach a filter attribute, and when should you just override a filter method on the Controller base class? It's simple: if you want to reuse your behavior across multiple controllers, then it needs to be an attribute. If you're only going to use it on one specific controller, then it's easier just to override one of the preceding methods.

This also means that if you create a common base class for all your controllers, you can apply filter code globally across all controllers just by overriding a filter method on your base class. This is a flexible and powerful pattern known as layer supertype. The cost of that power, however, can be extra difficulty in long-term maintenance—it's all too easy to add more and more code to the base class over time, even code that's relevant only to a subset of your controllers, and then have every controller become a complex and slow-running beast. You have to weigh the power of this approach against the responsibility of prudent base-class management. In many cases, it's tidier not to use a layer supertype, but instead to compose functionality by combining the relevant filter attributes for each separate controller.

As you'll learn in more detail in a few pages, ASP.NET MVC also supports output caching through its built-in [OutputCache] filter. This works just like ASP.NET Web Forms' output caching, in that it caches the entire response so that it can be reused immediately next time the same URL is requested. Behind the scenes, [OutputCache] is actually implemented using the core ASP.NET platform's output-caching technology, which means that if there's a cache entry for a particular URL, it will be served without invoking any part of ASP.NET MVC (not even the authorization filters).

So, what happens if you combine an authorization filter with [OutputCache]? In the worst case, you run the risk of an authorized user first visiting your action, causing it to run and be cached, shortly followed by an unauthorized user, who gets the cached output even though they aren't authorized. Fortunately, the ASP.NET MVC team has anticipated this problem, and has added special logic to AuthorizeAttribute to make it play well with ASP.NET output caching. It uses a little-known output-caching API to register itself to run when the output-caching module is about to serve a response from the cache. This prevents unauthorized users from getting cached content.

You might be wondering why I've bothered explaining this obscure technicality. I've done so to warn you that if you implement your own authorization filter from scratch—by deriving from FilterAttribute and implementing IAuthorizationFilter—you won't inherit this special logic, so you'll risk allowing unauthorized users to obtain cached content. Therefore, don't implement IAuthorizationFilter directly, but instead derive a subclass of AuthorizeAttribute.

As explained previously, the best way to create a custom authorization filter is to derive a subclass of AuthorizeAttribute. All you need to do is override its virtual AuthorizeCore() method and return a bool value to specify whether the user is authorized—for example:

public class EnhancedAuthorizeAttribute : AuthorizeAttribute
{
    public bool AlwaysAllowLocalRequests = false;

    protected override bool AuthorizeCore(System.Web.HttpContextBase httpContext)
    {
        if (AlwaysAllowLocalRequests && httpContext.Request.IsLocal)
            return true;

        // Fall back on normal [Authorize] behavior
        return base.AuthorizeCore(httpContext);
    }
}

You could use this custom authorization filter as follows:

[EnhancedAuthorize(Roles = "RemoteAdmin", AlwaysAllowLocalRequests = true)]

This would grant access to visitors if they were in the RemoteAdmin role or if they were directly logged into Windows on the server itself. This could be handy to allow server administrators to access certain configuration functions, but without necessarily letting them do so from across the Internet.

Since it's derived from FilterAttribute, it inherits an Order property, so you can specify its order among other authorization filters. The MVC Framework's default ControllerActionInvoker will run each one in turn. If any of the authorization filters denies access, then ControllerActionInvoker short-circuits the process by not bothering to run any subsequent authorization filters.

Also, since this class is derived from AuthorizeAttribute, it shares the behavior of being safe to use with output caching, and of applying an HttpUnauthorizedResult if access is denied.

If you want to intercept authorization failures and add some custom logic at that point, you can override the virtual HandleUnauthorizedRequest() method on your custom authorization filter.

This is a common requirement in Ajax scenarios. If an Ajax request is denied authorization, then usually you don't want to return an HTTP redirection to the login page, because your client-side code is not expecting that and may do something unwanted such as injecting the entire login page into the middle of whatever page the user is on. Instead, you'll want to send back a more useful signal to the client-side code, perhaps in JSON format, to explain that the request was not authorized. You could implement this as follows:

public class EnhancedAuthorizeAttribute : AuthorizeAttribute
{
    protected override void HandleUnauthorizedRequest(AuthorizationContext context)
    {
        if (context.HttpContext.Request.IsAjaxRequest()) {
            UrlHelper urlHelper = new UrlHelper(context.RequestContext);
            context.Result = new JsonResult {
                Data = new {
                    Error = "NotAuthorized",
                    LogOnUrl = urlHelper.Action("LogOn", "Account")
                },
                JsonRequestBehavior = JsonRequestBehavior.AllowGet
            };
        }
        else
            base.HandleUnauthorizedRequest(context);
    }
}

To use this, you would also need to enhance your client-side code to detect this kind of response and notify the user appropriately. You'll learn more about working with Ajax and JSON in Chapter 14.

HandleErrorAttribute lets you detect specific types of exceptions, and when it detects one, it just renders a particular view template and sets the HTTP status code to 500 (meaning "internal server error"). The idea is that you can use it to render some kind of "Sorry, there was a problem" screen. It doesn't log the exception in any way—you need to create a custom exception filter to do that.

HandleErrorAttribute has four properties for which you can specify values, as listed in Table 10-5.

If you apply the filter as follows:

[HandleError(View = "Problem")]
public class ExampleController : Controller
{
    /* ... action methods here ... */
}

then, if there's an exception while running any action method (or associated filter) on that controller, HandleErrorAttribute will try to render a view from one of the following locations:

When rendering the view, HandleErrorAttribute will supply a Model object of type HandleErrorInfo. So, if you make your error handling view template strongly typed (specifying HandleErrorInfo as the model type), you'll be able to access and render information about the exception. For example, by adding the following to /Views/Shared/Problem.aspx:

<%@ Page Language="C#" Inherits="System.Web.Mvc.ViewPage<HandleErrorInfo>" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
          "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" >
    <head runat="server">
        <title>Sorry, there was a problem!</title>
    </head>
    <body>
        <p>
             There was a <b><%: Model.Exception.GetType().Name %></b>
             while rendering <b><%: Model.ControllerName %></b>'s
             <b><%: Model.ActionName %></b> action.
        </p>
        <p>
             The exception message is: <b><%: Model.Exception.Message %></b>
        </p>
        <p>Stack trace:</p>
        <pre><%: Model.Exception.StackTrace %></pre>
    </body>
</html>

you can render a screen like that shown in Figure 10-2. Of course, for a publicly deployed web site, you won't usually want to expose this kind of information (especially not the stack trace), but it might be helpful during development.

Figure 10-2. Rendering a view from HandleErrorAttribute

When HandleErrorAttribute handles an exception and renders a view, it marks the exception as "handled" by setting a property called ExceptionHandled to true. You'll learn about the meaning and significance of this during the next example.

Not surprisingly, you can create a custom exception filter by creating a class derived from FilterAttribute and implementing IExceptionFilter. You might just silently log the exception to your database or to the Windows Application event log, and leave it to some other filter to produce visible output for the user. Or, you can produce visible output (e.g., render a view or perform a redirection) by assigning an ActionResult object to the filterContext.Result property.

Here's a custom exception filter that performs a redirection:

public class RedirectOnErrorAttribute : FilterAttribute, IExceptionFilter
{
    public void OnException(ExceptionContext filterContext)
    {
        // Don't interfere if the exception is already handled
        if(filterContext.ExceptionHandled)
            return;

        // Let the next request know what went wrong
        filterContext.Controller.TempData["exception"] = filterContext.Exception;

        // Set up a redirection to my global error handler
        filterContext.Result = new RedirectToRouteResult(new RouteValueDictionary(
                new { controller = "Exception", action = "HandleError" }
            ));

        // Advise subsequent exception filters not to interfere
        // and stop ASP.NET from producing a "yellow screen of death"

filterContext.ExceptionHandled = true;

        // Erase any output already generated
        filterContext.HttpContext.Response.Clear();
    }
}

This example demonstrates the use of filterContext.ExceptionHandled. It's a bool property that starts off false, but as each exception filter is run in turn, one of them might choose to switch it to true. This does not cause ControllerActionInvoker to stop running subsequent exception filters, however. It will still run all the remaining exception filters, which is helpful if a subsequent filter is supposed to log the exception.^[64]

The filterContext.ExceptionHandled flag tells subsequent exception filters that you've taken care of things, and they can ignore the exception. But that doesn't force them to ignore the exception—they might still wish to log it, and they could even overwrite your filterContext.Result. The built-in HandleErrorAttribute is well behaved—if filterContext.ExceptionHandled is already set to true, then it will ignore the exception entirely.

After all the exception filters have been run, the default ControllerActionInvoker looks at filterContext.ExceptionHandled to see whether the exception is considered to be handled. If it's still false, then it will rethrow the exception into ASP.NET itself, which will produce a familiar "yellow screen of death" (unless you've set up an ASP.NET global exception handler).

To make DefaultControllerFactory give priority to controller classes defined in a certain collection of namespaces, you can add values to a static collection called ControllerBuilder.Current.DefaultNamespaces—for example, in your Global.asax.cs file:

protected void Application_Start()
{
    RegisterRoutes(RouteTable.Routes);
    ControllerBuilder.Current.DefaultNamespaces.Add("MyApp.Controllers.*");
    ControllerBuilder.Current.DefaultNamespaces.Add("OtherAssembly.MyNamespace.*");
}

Now, if a desired controller name is unique to a single controller type within or below those namespaces, DefaultControllerFactory will select and use that controller type rather than throwing an exception. However, if there are still multiple matching controller types within or below those namespaces, it will again throw an InvalidOperationException. (Don't be mistaken into thinking it gives priority to the namespaces in DefaultNamespaces according in the order that you've added them—it doesn't care about how they are ordered.)

If DefaultControllerFactory can't find any suitable controller type in those nominated namespaces, it reverts to its usual behavior of picking a controller type from anywhere, regardless of namespace.

You can also prioritize a set of namespaces to use when handling a particular RouteTable.Routes entry. For example, you might decide that the URL pattern admin/{controller}/{action} should prefer to pick a controller class from the MyApp.Admin.Controllers namespace and ignore any clashing controllers that are in other namespaces.

To do this, add to your route entry a DataTokens value called Namespaces. The value you assign must implement IEnumerable<string>—for example:

routes.Add(new Route("admin/{controller}/{action}", new MvcRouteHandler())
{
    Defaults = new RouteValueDictionary(new {
        controller = "Home", action = "Index"
    }),

DataTokens = new RouteValueDictionary(new {
        Namespaces = new[] { "MyApp.Admin.Controllers.*",
                             "AnotherAssembly.Controllers.*" }
    })
});

Or equivalently, you can call MapRoute() and pass a namespaces parameter:

routes.MapRoute(null, "admin/{controller}/{action}",
    new { controller = "Home", action = "Index" },
    new[] { "MyApp.Admin.Controllers.*", "AnotherAssembly.Controllers.*"}
);

These namespaces will be prioritized only during requests that match this route entry. These prioritizations themselves take priority over ControllerBuilder.Current.DefaultNamespaces.

If you're using custom RouteBase subclasses rather than Route objects, you can support controller namespace prioritization there, too. During the GetRouteData() method, put an IEnumerable<string> value into the returned RouteData object's DataTokens collection—for example:

public class CustomRoute : RouteBase
{
    public override RouteData GetRouteData(HttpContextBase httpContext)
    {
        if (choosing to match this request)
        {
            RouteData rd = new RouteData(this, new MvcRouteHandler());
            rd.Values["controller"] = chosen controller
            rd.Values["action"] = chosen action method name
            rd.DataTokens["namespaces"] = new[] { "MyApp.Admin.Controllers.*" };
            return rd;
        }
        else
            return null;
    }
    public override VirtualPathData GetVirtualPath(...) { /* etc */ }
}

If you want to ensure that your route entry only ever matches controllers in the namespaces you've specified (and doesn't merely prioritize them over others, as described previously), then you can add a further DataTokens entry called UseNamespaceFallback and set it to false.

routes.Add(new Route("admin/{controller}/{action}", new MvcRouteHandler())
{
    Defaults = new RouteValueDictionary(new {
        controller = "Home", action = "Index"
    }),
    DataTokens = new RouteValueDictionary(new {
        Namespaces = new[] { "MyApp.Admin.Controllers.*",
                             "AnotherAssembly.Controllers.*" },
        UseNamespaceFallback = false
    })
});

Now, this route entry will completely ignore all controllers except those in the nominated namespaces. It won't even pay attention to ControllerBuilder.Current.DefaultNamespaces.

To start using your custom controller factory, register an instance of it on a static object called ControllerBuilder.Current. Do this only once, early in the application's lifetime. For example, add the following to Global.asax.cs:

protected void Application_Start()
{
    RegisterRoutes(RouteTable.Routes);
    ControllerBuilder.Current.SetControllerFactory(new MyControllerFactory());
}

That's all there is to it!

So far throughout this book, all of our actions have beenC# methods, and the name of each action has always matched the name of the C# method. Most of the time, that's exactly how things work, but the full story is slightly subtler.

Strictly speaking, an action is a named piece of functionalityon a controller. That functionality might be implemented as a method on the controller (and it usually is), or it might be implemented in some other way. The name of the action might correspond to the name of a method that implements it (and it usually does), or it might differ.

How does a controller method get counted as an action in the first place? Well, if you create a controller derived from the default controller base class, then each of its methods is considered to be an action, as long as it meets the following criteria:

As mentioned, an action is a named piece of functionality on a controller. The MVC Framework's usual convention is that the name of the action is taken from the name of the method that defines and implements that functionality. You can override this convention using ActionNameAttribute—for example:

[ActionName("products-list")]
public ActionResult DisplayProductsList()
{
    // ...
}

Under the default routing configuration, you would not find this action on the usual URL, /controllername/DisplayProductsList. Instead, its URL would be /controllername/products-list.

This is useful for two main reasons:

It's entirely possible for there to be multiple C# methods that are candidates to handle a single action name. Perhaps you have multiple methods with the same name (taking different parameters), or perhaps you are using [ActionName] so that multiple methods are mapped to the same action name. In this scenario, the MVC Framework needs a mechanism to choose between them.

This mechanism is called actionmethod selection, and is implemented using an attribute class called ActionMethodSelectorAttribute. You've already used one of the subclasses of that attribute, HttpPostAttribute, which prevents action methods from handling requests other than POST requests—for example:

[HttpPost]
public ActionResult DoSomething() { ... }

HttpPostAttribute, along with its friends HttpDeleteAttribute, HttpGetAttribute, and HttpPutAttribute, all work internally by calling an underlying selector attribute, AcceptVerbsAttribute. If you prefer, you can use [AcceptVerbs] directly—for example:

[AcceptVerbs(HttpVerbs.Get)]
public ActionResult DoSomething() { ... }

[AcceptVerbs(HttpVerbs.Post)]
public ActionResult DoSomething(int someParam) { ... }

Here, there is just one logical action named DoSomething. There are two different C# methods that can implement that action, and the choice between them is made on a per-request basis according to the incoming HTTP method. Like all other action method selection attributes, AcceptVerbsAttribute and HttpPost are derived from ActionMethodSelectorAttribute.

public class iPhoneAttribute : ActionMethodSelectorAttribute
{
    public override bool IsValidForRequest(ControllerContext controllerContext,
                                           MethodInfo methodInfo)
    {
        var userAgent = controllerContext.HttpContext.Request.UserAgent;
        return userAgent != null && userAgent.Contains("iPhone");
    }
}

[iPhone]
[ActionName("Index")]
public ActionResult Index_iPhone() { /* Logic for iPhones goes here */ }

[ActionName("Index")]
public ActionResult Index_PC() { /* Logic for other devices goes here */ }

[NonAction]
public void MyMethod()
{
    ...
}

You've now seen that ControllerActionInvoker's choice of action method depends on a range of criteria, including the incoming RouteData.Values["action"] value, the names of methods on the controller, those methods' [ActionName] attributes, and their method selection attributes.

To understand how this all works together, examine the flowchart shown in Figure 10-5.

Figure 10-5. How ControllerActionInvoker chooses which method to invoke

Notice that if a method has multiple action method selection attributes, then they must all agree to match the request; otherwise, the method will be ejected from the candidate list.

The figure also shows that the framework gives priority to methods with selector attributes (such as [HttpPost]). Such methods are considered to be a stronger match than regular methods with no selector attribute. What's the point of this convention? It means that the following code won't throw an ambiguous match exception:

public ActionResult MyAction() { ... }

[HttpPost]
public ActionResult MyAction(MyModel model) { ... }

Even though both methods would be willing to handle POST requests, only the second one has a method selector attribute. Therefore, the second one would be given priority to handle POST requests and the first one would be left to handle any other type of request.

As shown in Figure 10-5, if there are no methods to match a given action name, then the default controller base class will try to run its unknown action handler. This is a virtual method called HandleUnknownAction(). By default, it returns a 404 Not Found response, but you can override it to do something different—for example:

public class HomeController : Controller
{
    protected override void HandleUnknownAction(string actionName)
    {
        Response.Write("You are trying to run an action called "
                       + Server.HtmlEncode(actionName));
    }
}

Now, if you request the URL /Home/Anything, you'll receive the following output instead of a 404 Not Found error:

You are trying to run an action called Anything

This is one of many places where ASP.NET MVC provides extensibility so that you have the power to do anything you want. However, in this case it isn't something you'll need to use often, for the following reasons:

If you are writing the client for an ASP.NET MVC-powered REST web service, then you can use the Html.HttpMethodOverride() helper method to add the appropriate key/value pair to an HTML form. Continuing the previous example, you could write

<% using(Html.BeginForm("People", "People", new { personId = 123 })) { %>
    <%= Html.HttpMethodOverride(HttpVerbs.Delete) %>
    <input type="submit" value="Delete this person" />
<% } %>

This view code will render the following HTML:

<form action="/people/123" method="post">
    <input name="X-HTTP-Method-Override" type="hidden" value="DELETE" />
    <input type="submit" value="Delete this person" />
</form>

When this form is submitted, it will invoke the People_Delete() action method.

The built-in method selectors ([HttpPut], [HttpPost], etc.) respect HTTP method overriding because when they need to know the incoming request's HTTP method, they don't look at Request.HttpMethod but instead call Request.GetHttpMethodOverride().

Request.GetHttpMethodOverride() uses the following algorithm:

You may have a regular synchronous action method that performs long-running I/O, such as the following example. It calls a REST web service on Flickr, the popular photo sharing site, to obtain the URL of an image related to a user-supplied tag parameter.

const string FlickrSearchApi = "http://api.flickr.com/services/rest/?"
    + "method=flickr.photos.search"
    + "&text={0}"
    + "&sort=relevance"
    + "&api_key=" + /* Omitted - get your own API key from Flickr */;

public ContentResult GetPhotoByTag(string tag)
{
    // Make a request to Flickr
    string url = string.Format(FlickrSearchApi, HttpUtility.UrlEncode(tag));
    using (var response = WebRequest.Create(url).GetResponse())
    {
        // Parse the response as XML
        var xmlDoc = XDocument.Load(XmlReader.Create(response.GetResponseStream()));

        // Use LINQ to convert each <photo /> node to a URL string
        var photoUrls = from photoNode in xmlDoc.Descendants("photo")
                        select string.Format(
                            "http://farm{0}.static.flickr.com/{1}/{2}_{3}.jpg",
                            photoNode.Attribute("farm").Value,
                            photoNode.Attribute("server").Value,
                            photoNode.Attribute("id").Value,
                            photoNode.Attribute("secret").Value);

        // Return an <img> tag referencing the first photo
        return Content(string.Format("<img src='{0}'/>", photoUrls.First()));
    }
}

Of course, in a real application you'd probably pass the image URL to be rendered as part of a view, but to keep this example focused, let's just return an <img> tag directly from the action.

Now, if a user requests /controller/GetPhotoByTag?tag=stadium, they will be shown a relevant image such as that shown in Figure 10-6.

Figure 10-6. Output from the GetPhotoByTag() action method

This is good, but you can't predict how long the REST call to Flickr will last. It might take several seconds or longer, so if you have a large number of users hitting this action at roughly the same time, it could block a large number of worker threads for a long time, possibly having a serious impact on your server's responsiveness or even making it totally unresponsive.

To convert this into an asynchronous action, you must first change your controller to inherit from AsyncController rather than Controller:

public class ImageController : AsyncController
{
    // Rest of controller as before
}

So far this won't have any noticeable effect on your application. The action will still work synchronously. But now that your controller inherits from AsyncController, you can split any of its actions into two parts:

Here's how this might work in the Flickr example:

public void GetPhotoByTagAsync(string tag)
{
    AsyncManager.OutstandingOperations.Increment();

    // Begin an asynchronous request to Flickr
    string url = string.Format(FlickrSearchApi, HttpUtility.UrlEncode(tag));
    WebRequest request = WebRequest.Create(url);
    request.BeginGetResponse(asyncResult =>
    {
        // This lambda method will be executed when we've got a response from Flickr

        using (WebResponse response = request.EndGetResponse(asyncResult))
        {
           // Parse response as XML, then convert to each <photo> node to a URL
           var xml = XDocument.Load(XmlReader.Create(response.GetResponseStream()));
           var photoUrls = from photoNode in xml.Descendants("photo")
                           select string.Format(
                               "http://farm{0}.static.flickr.com/{1}/{2}_{3}.jpg",
                               photoNode.Attribute("farm").Value,
                               photoNode.Attribute("server").Value,
                               photoNode.Attribute("id").Value,
                               photoNode.Attribute("secret").Value);
           AsyncManager.Parameters["photoUrls"] = photoUrls;

           // Now allow the Completed method to run
           AsyncManager.OutstandingOperations.Decrement();

}
    }, null);
}

public ContentResult GetPhotoByTagCompleted(IEnumerable<string> photoUrls)
{
    return Content(string.Format("<img src='{0}'/>", photoUrls.First()));
}

Instead of calling WebRequest's GetResponse() method, we're now calling its asynchronous alternative, BeginGetResponse() (if you're unfamiliar with this API, see the following sidebar).^[66] The GetPhotoByTagAsync() method returns without waiting for any response from Flickr, so it frees the worker thread to get on with other tasks.

BeginGetResponse() allows you to supply a callback method that it should invoke once the WebRequest is completed. Inside this callback, we get the finished WebResponse object and use the XML data returned by Flickr to construct a set of image URLs and then store them in a temporary area called AsyncManager.Parameters. Finally, we inform ASP.NET MVC that the operation is complete by decrementing the count of outstanding operations, so it will invoke GetPhotoByTagCompleted(), passing the AsyncManager.Parameters values as method parameters.

public void MyActionAsync() {
    AsyncManager.OutstandingOperations.Increment();
    var webClient = new WebClient();
    webClient.DownloadStringCompleted += (sender, args) => {
        AsyncManager.Parameters["html"] = args.Result;
        AsyncManager.OutstandingOperations.Decrement();
    };
    webClient.DownloadStringAsync(new Uri("http://www.example.com"));
 }

 public ContentResult MyActionCompleted(string html) {
     return Content("Downloaded this HTML: " + HttpUtility.HtmlEncode(html));
 }

In this example, we're only running one asynchronous operation. But of course you can run multiple asynchronous operations concurrently if you wish—just call AsyncManager.OutstandingOperations's Increment() method before each one starts, and Decrement() when each one finishes—and ASP.NET MVC will wait until the last one is done (i.e., as soon as AsyncManager.OutstandingOperations.Count hits zero) before invoking your "completed" method.

As illustrated in the previous example, you can use the AsyncManager.Parameters dictionary to store the results of your asynchronous I/O operations. When the framework invokes your "completed" method, it will try to obtain a value for each parameter by looking for an entry in the dictionary with a matching name.

This mechanism doesn't use the value provider or model binding systems, so it won't automatically use Request.QueryString, Request.Form, or other incoming values to populate the parameters on your "completed" method. It will only pass values from AsyncManager.Parameters. If you do need to access a query string or form parameter in your "completed" method, you should add a line to your "async" method to transfer this value across—for example:

public void GetPhotoByTagAsync(string tag, string someOtherParam)
{
    AsyncManager.Parameters["someOtherParam"] = someOtherParam;

    // ... all else as before ...
}

public ContentResult GetPhotoByTagCompleted(IEnumerable<string> photoUrls,
                                             string someOtherParam)
{
    // ...
}

If the framework can't find a matching value for any "completed" method parameter, or if the value isn't of a compatible type, it will simply supply the default value for that type. For reference types this means null; for value types this means zero, false, or similar.

By default, ASP.NET MVC will not call your "completed" method until the AsyncManager associated with the request says there no outstanding asynchronous operations. It could take a long time, and it's possible that one or more asynchronous operations might never complete.

AsyncManager has a built-in default timeout set to 45 seconds, so if the count of outstanding operations doesn't reach zero after this long, the framework will throw a System.TimeoutException to abort the request. You can alter this timeout duration using the [AsyncTimeout] filter—for example:

[AsyncTimeout(10000)]  // 10000 milliseconds equals 10 seconds
public void GetPhotoByTagAsync(string tag) { ... }

If you want to eliminate the timeout entirely, so that the I/O operations are allowed to run for an unlimited period, then use the [NoAsyncTimeout] filter instead. It's exactly equivalent to [AsyncTimeout(Timeout.Infinite)]. Also, in case you want to use custom logic to select a timeout duration, you can directly assign a timeout value (in milliseconds) to your asynchronous controller's AsyncManager.Timeout property.

Most applications will have an ASP.NET global exception handler that will deal with timeout exceptions in the same way as other unhandled exceptions. But if you want to treat timeouts as a special case and provide different feedback to the user, you can create your own exception filter that catches them, or you can override the controller's OnException() method. For example, you could redirect users to a special "Try again later" page:

protected override void OnException(ExceptionContext filterContext)
{
    if (filterContext.Exception is TimeoutException) {
        filterContext.Result = RedirectToAction("TryAgainLater");
        filterContext.ExceptionHandled = true;
    }
}

You can short-circuit the entire collection of asynchronous operations associated with a request by calling AsyncManager.Finish() from one of your callbacks. This tells the framework to call your "completed" method immediately, without waiting for any outstanding operations to finish. It doesn't stop the current callback method or any other outstanding operation from running—it has no way of doing that—but the framework won't wait for them to signal completion.

Your "completed" method will usually expect to receive some parameters taken from AsyncManager.Parameters. If any of the expected parameters aren't already populated by the time the "completed" method gets called, then it will receive default values (null, zero, false, etc.) for those parameters.

When you begin an asynchronous operation such as BeginGetResponse() and supply a callback parameter, you can't control which thread your callback will be invoked on. In general, it won't be an ASP.NET worker thread, and it won't be associated with your original request's HttpContext. This can lead to two possible problems:

To solve the first problem, AsyncManager provides a method called Sync(), which takes a delegate, runs it on an ASP.NET thread associated with the original HttpContext, and uses locking to ensure that only one such delegate runs at any time. You can call this from inside a callback as follows:

BeginAsyncOperation(asyncResult => {
    var result = EndAsyncOperation(asyncResult);

    // Can't always access System.Web.HttpContext.Current from here...

    Action doSomethingWithHttpContext = () => {
        // ... but can always access it from this delegate
    };
    if (asyncResult.CompletedSynchronously) // Already on an ASP.NET thread
        doSomethingWithHttpContext();
    else
                                            // Must switch to an ASP.NET thread
        AsyncManager.Sync(doSomethingWithHttpContext);

    AsyncManager.OutstandingOperations.Decrement();
}, null);

As an awkward quirk, you're not supposed to call Sync() from any thread that is already associated with ASP.NET, which is why the preceding code checks whether to invoke the doSomethingWithHttpContext delegate via Sync() or just to invoke it directly.

You could also use Sync() as a way of solving the second problem, because it only executes one delegate at a time. However, that's a heavyweight solution involving thread-switching and several extra lines of code. A simpler option is just to take a suitable lock before interacting with a non-thread-safe object—for example:

BeginAsyncOperation(asyncResult => {
    var result = EndAsyncOperation(asyncResult);

    lock(AsyncManager.Parameters) {

AsyncManager.Parameters["result"] = result;
    }

    AsyncManager.OutstandingOperations.Decrement();
}, null);

Normally, you will only need to worry about this if your request sets up multiple asynchronous operations that might complete simultaneously.

With all those caveats in mind, it's extremely valuable to run a real load test to see how much difference (if any) an asynchronous controller will make in your situation. Unless you can practically observe the difference, you won't truly know whether your server is configured to gain any benefit from it, and you won't know where the remaining performance limits are.

To illustrate the real effects and limitations of asynchronous controllers, I created a SQL stored procedure that simulates a long-running process by simply pausing for 2 seconds (using the T-SQL command WAITFOR DELAY '00:00:02') and then returning a fixed value. I set up two ASP.NET MVC controllers that call this stored procedure—one synchronously and the other asynchronously. Finally, I created a small C# console application that simulates an increasing workload by repeatedly making HTTP requests to a given URL; initially on just one thread, but gradually increasing the number of threads to 150 over a 30-minute period. It records a rolling average of the response times, from which I produced the graph shown in Figure 10-7.

Figure 10-7. Synchronous performance vs. asynchronous performance. Lower response times are better.

To make the results clearer, I set my ASP.NET MVC application's maximum thread pool size to the artificially low limit of 50 (by putting ThreadPool.SetMaxThreads(50, 50); into Global.asax.cs). My dual-core server has a more sensible default thread pool limit of 200, but this doesn't change the principles. So, what can we observe from this graph?

Bear in mind that I was simulating a gradual increase in traffic over a 30-minute period. When instead I chose to simulate a more sudden spike in traffic, I found that asynchronous requests performed just the same, whereas synchronous ones performed very badly. My ASP.NET MVC 2 test application running on IIS 7 and .NET 4 took up to 10 minutes to notice the traffic and create enough worker threads to handle it synchronously, during which time the server was extremely unresponsive and most of the requests timed out. Of course, your results may vary depending on your system configuration.

If you plan to use ASP.NET 3.5 on your server, you should be aware that its default MaxConcurrentRequestsPerCPU setting will limit the maximum number of concurrent requests to 12 per CPU, no matter whether those requests are asynchronous or not. This is an incredibly unhelpful default value: it means that you're unlikely to get anywhere near the theoretical worker thread pool limit of 100 threads per CPU, so you won't get any significant benefit from using asynchronous requests. (But if you'll be using ASP.NET 4.0, you can stop worrying because your MaxConcurrentRequestsPerCPU setting is 5000 by default).

To change this setting on ASP.NET 3.5, you can do either of the following:

After changing either of these settings, reset IIS using by calling iisreset from the command line.

When I first performed the preceding investigation, I couldn't observe any performance benefit from using asynchronous requests. First it was because I was using Windows 7, and then it was because I was using Windows Server 2008 with ASP.NET 3.5 and hadn't yet changed the MaxConcurrentRequestsPerCPU setting. If I hadn't been trying to observe the benefit in a practical experiment, I'd never have known that it was completely ineffective. Be sure to verify practically that your implementation works as you expect.