You can add any number of public methods (which we'll call Actions from here on out to keep with convention) to a Controller class, which will all be callable via this pattern. Actions may also contain parameters. Going back to the previous example, add a new action method that takes in a parameter:

public class Simple2Controller : Controller
{
    public void Goodbye(string name)
    {
        Response.Write("Goodbye"  + HttpUtility.HtmlEncode(name));
    }
}
Code snippet 5-6.txt

This method is callable via the URL:

/simple2/goodbye?name=World

Code snippet 5-7.txt

Notice that you can pass in parameters to an action method by name via the query string. You can also pass in parameters via the URL segments, discoverable by position as defined in your routes (discussed in Chapter 4). For example, the following URL is more aesthetically pleasing to many developers and Internet users:

/simple2/goodbye/world
Code snippet 5-8.txt

which provides more information about what we're looking at.

/products/view.aspx?id=45434

/products/view/shoes
Code snippet 5-9.txt

Working with parameters passed by URL segment requires you to define how Routing will identify these parameters in the URL. Fortunately, the default route (created for you when you click File

Changing the action method signature a little bit (by renaming the parameter name to id) like so:

public class Simple2Controller : Controller
{
    public void Goodbye(string id)
    {
        Response.Write("Goodbye"  + HttpUtility.HtmlEncode(id));
    }
}
Code snippet 5-10.txt

allows you to call that method using the cleaner URL, and Routing will pass the parameter by structured URL instead of a query string parameter:

/simple2/goodbye/world
Code snippet 5-11.txt

What if you have a method with more than one parameter? This is a very common scenario, and rest assured that you can still use query strings, but if you want to pass both parameters via the URL segments, you'll need to define a new route specifically for this situation.

For example, suppose that you have an action method that calculates the distance between two points:

public void Distance(int x1, int y1, int x2, int y2)
{
    double xSquared = Math.Pow(x2 - x1, 2);
    double ySquared = Math.Pow(y2 - y1, 2);
    Response.Write(Math.Sqrt(xSquared + ySquared));
}
Code snippet 5-12.txt

Using only the default route, the request would need to look like this:

/simple2/distance?x2=1&y2=2&x1=0&y1=0
Code snippet 5-13.txt

You can improve on this situation a bit by defining a route that allows you to specify the parameters in a cleaner format. This code goes inside the RegisterRoutes methods within the Global.asax.cs file, and uses the MapRoute method (discussed in Chapter 4) to define a new route:

routes.MapRoute("distance",
    "simple2/distance/{x1},{y1}/{x2},{y2}",
    new { Controller = "Simple2", action = "Distance" }
);
Code snippet 5-14.txt

Notice that you are using the comma character to separate x and y coordinates. Now this action method is callable via the URL:

/simple2/distance/0,0/1,2
Code snippet 5-15.txt

The presence of commas in a URL might look strange, but Routing is quite powerful! For more on routing, refer to Chapter 4.

There are many cases in which you'll want to support optional parameters. This took some extra work with ASP.NET MVC 1.0. You could either add a custom route with a default parameter, or you could change the parameter type to accept a nullable value (e.g., int?) and write extra logic to supply the default value.

ASP.NET MVC 2 simplifies this case with default parameters, using the DefaultValueAttribute from the System.ComponentModel namespace. The DefaultValueAttribute lets you specify a parameter value that the controller action will use if it's not contained in the route values.

The controller action in the following listing will respond to both /Dinners/DinnersNearMe/90210 and /Dinners/DinnersNearMe/90210?maxDinners=50. In the first case, the default value of 10 will be used.

public ActionResult DinnersNearMe(string location,
    [DefaultValue(10)]int maxDinners) {
}
Code snippet 5-16.txt

Even better, we can use language support for optional parameters to eliminate the need for the [DefaultValues] attribute. Visual Basic has long had support for optional parameters, and C# 4.0 adds support for optional parameters as well. That allows us to simplify the controller action signature as follows:

public ActionResult DinnersNearMe(string location, int maxDinners = 10) {
}
Code snippet 5-17.txt

As the name implies, the EmptyResult is used to indicate that the framework should do nothing. This follows a common design pattern known as the Null Object pattern, which replaces null references with an instance. In this instance, the ExecuteResult method has an empty implementation. This design pattern was introduced in Martin Fowler's Refactoring book. You can learn more at:

http://martinfowler.com/bliki/refactoring.html.

The ContentResult writes its specified content (via the Content property) to the response. This class also allows for specifying the content encoding (via the ContentEncoding property) and the content type (via the ContentType property).

If the encoding is not specified, then the content encoding for the current HttpResponse instance is used. The default encoding for HttpResponse is specified in the globalization element of web.config.

Likewise, if the content type is not specified, the content type set on the current HttpResponse instance is used. The default content type for HttpResponse is text/html.

The FileResult is very similar to the ContentResult except that it is used to write binary content (e.g., a Microsoft Word document on disk or the data from a blob column in SQL Server) to the response. Setting the FileDownloadName property on the result will set the appropriate value for the Content-Disposition header, causing a file download dialog to appear for the user.

Note that FileResult is an abstract base class for three different file result types:

Usage typically follows the factory pattern in which the specific type returned depends on which overload of the File method (discussed later) is called.

The JsonResult uses the JavaScriptSerializer class to serialize its contents (specified via the Data property) to the JSON (JavaScript Object Notation) format. This is useful for simple AJAX scenarios that have a need for an action method to return data in a format easily consumable by JavaScript.

As for ContentResult, the content encoding and content type for the JsonResult can both be set via properties. The only difference is that the default ContentType is application/json and not text/html for this result.

Note that the JsonResult serializes the entire object graph. Thus, if you give it a ProductCategory object, which has a collection of 20 Product instances, every Product instance will also be serialized and included in the JSON sent to the response. Now imagine if each Product had an Orders collection containing 20 Order instances. As you can imagine, the JSON response can grow huge quickly.

There is currently no way to limit how much to serialize into the JSON, which can be problematic with objects that contain a lot of properties and collections, such as those typically generated by LINQ to SQL. The recommended approach is to create a type that contains the specific information you want included in the JsonResult. This is one situation in which an anonymous type comes in handy.

For example, in the preceding scenario, instead of serializing an instance of ProductCategory, you can use an anonymous object initialize to pass in just the data you need, as the following code sample demonstrates:

public ActionResult PartialJson()
{
       var category = new ProductCategory { Name="Partial"};
       var result = new {
             Name = category.Name,
             ProductCount = category.Products.Count };
       return Json(result);
}
Code snippet 5-21.txt

In this sample, all you needed was the category name and the product count for the category. So rather than serializing the entire object graph, you pulled the information you needed from the actual object and stored that information in an anonymous type instance named result. You then sent that instance to the response, rather than the entire object graph.

The JavaScriptResult is used to execute JavaScript code on the client sent from the server. For example, when using the built-in AJAX helpers to make a request to an action method, the method could simply return a bit of JavaScript that is immediately executed when it gets to the client:

public ActionResult DoSomething() {
    script s = "$('#some-div').html('Updated!'),";

    return JavaScript(s);
}
Code snippet 5-22.txt

This would be called by the following code:

<%: Ajax.ActionLink("click", "DoSomething", new AjaxOptions()) %>
<div id="some-div"></div>
Code snippet 5-23.txt

This assumes that you've referenced the AJAX libraries and jQuery.

The RedirectResult performs an HTTP redirect to the specified URL (set via the Url property). Internally, this result calls the HttpResponse.Redirect method, which sets the HTTP status code to "HTTP/1.1 302 Object Moved," causing the browser to immediately issue a new request for the specified URL.

Technically, you could just make a call to Response.Redirect directly within your action method, but using the RedirectResult defers this action until after your action method finishes its work. This is useful for unit testing your action method and helps keep underlying framework details outside of your action method.

RedirectToRouteResult performs an HTTP redirect in the same manner as the RedirectResult, but instead of specifying a URL directly, this result uses the Routing API to determine the redirect URL.

Note that there are two convenience methods (defined below) that return a result of this type, RedirectToRoute and RedirectToAction.

The ViewResult is the most widely used action result type. It calls the FindView method of an instance of IViewEngine, returning an instance of IView. The ViewResult then calls the Render method on the IView instance, which renders the output to the response. In general, this will merge the specified View data (the data that the action method has prepared to be displayed in the View) with a template that formats the data for displaying.

The next chapter covers Views in more detail.

PartialViewResult works in exactly the same way that the ViewResult does, except that it calls the FindPartialView method to locate a View rather than FindView. It's used to render partial Views such as a ViewUserControl and is useful in partial update scenarios when using AJAX to update a portion of the page with some chunk of HTML.

Once you've identified the name of the action, the invoker attempts to identify a method that can respond to that action. This is the job of the ControllerActionInvoker.

By default, the invoker simply uses reflection to find a public method on a class that derives from Controller that has the same name (case-insensitive) as the current action. Such a method must meet the following criteria:

Like many things within this framework, you can tweak this default behavior.

Applying the ActionNameAttribute attribute to a method allows you to specify the action that the method handles. For example, suppose that you want to have an action named View, but this would conflict with the View method of Controller. An easy way to work around this issue without having to futz with Routing or method hiding is to do the following:

[ActionName("View")]
public ActionResult ViewSomething(string id)
{
  return View();
}
Code snippet 5-29.txt

The ActionNameAttribute redefines the name of this action as View. Thus, this method is invoked in response to requests for /home/view, but not for /home/viewsomething. In the latter case, as far as the action invoker is concerned, an action method named ViewSomething does not exist.

One consequence of this is that if you're using our conventional approach to locate the View that corresponds to this action, the View should be named after the action, not after the method. In the preceding example (assuming that this is a method of HomeController), you would look for the View ~/Views/Home/View.aspx by default.

This attribute is not required for an action method. Implicitly, the name of a method serves as the action name for that method if this attribute is not applied.

You're not done matching the action to a method yet. Once you've identified all methods of the Controller class that match the current action name, you need to whittle the list down further by looking at all instances of the ActionSelectorAttribute applied to the methods in the list.

This attribute is an abstract base class for attributes that provide fine-grained control over which requests an action method can respond to. The API for this method is quite simple and consists of a single method:

public abstract class ActionSelectorAttribute : Attribute
{
  public abstract bool IsValidForRequest(ControllerContext controllerContext,
     MethodInfo methodInfo);
}
Code snippet 5-30.txt

At this point, the invoker looks for any methods in the list that contain attributes that derive from this attribute and calls the IsValidForRequest method on each attribute. If any attribute returns false, the method that the attribute is applied to is removed from the list of potential action methods for the current request.

At the end, you should be left with one method in the list, which the invoker then invokes. If more than one method can handle the current request, the invoker throws an exception indicating the problem. If no method can handle the request, the invoker calls HandleUnknownAction on the Controller.

The ASP.NET MVC Framework includes two implementations of this base attribute, the AcceptVerbsAttribute and the NonActionAttribute.

AcceptVerbsAttribute is a concrete implementation of ActionSelectorAttribute that uses the current HTTP request's HTTP method (verb) to determine whether or not a method is the action that should handle the current request. This allows you to have two methods of the same name (with different parameters, of course), both of which are actions but respond to different HTTP verbs.

ASP.NET MVC 2 introduces a more terse syntax for HTTP method restriction with the [HttpPost] and [HttpPut] attributes. These are simple aliases for the previous [AcceptVerbs(HttpVerbs.Post)] and [AcceptVerbs(HttpVerbs.Put)] attributes, but are easier to both type and read.

For example, you may want two versions of the Edit method, one that renders the edit form and the other that handles the request when that form is posted:

[HttpGet]
public ActionResult Edit(string id)
{
  return View();
}

[HttpPost]
public ActionResult Edit(string id, FormCollection form)
{
  //Save the item and redirect...
}
Code snippet 5-31.txt

When a POST request for /home/edit is received, the action invoker creates a list of all methods of the Controller that match the edit action name. In this case, you would end up with a list of two methods. Afterward, the invoker looks at all of the ActionSelectorAttribute instances applied to each method and calls the IsValidForRequest method on each. If each attribute returns true, then the method is considered valid for the current action.

For example, in this case, when you ask the first method if it can handle a POST request, it will respond with false because it only handles GET requests. The second method responds with true because it can handle the POST request, and it is the one selected to handle the action.

If no method is found that meets these criteria, the invoker will call the HandleUnknownAction method on the Controller, supplying the name of the missing action. If more than one action method meeting these criteria is found, an InvalidOperationException is thrown.

Browsers support two HTTP verbs: GET and POST. However, the REST architectural style also makes use of a few other verbs: DELETE, HEAD, and PUT. ASP.NET MVC 2 allows you to simulate these verbs via the Html.HttpMethodOverride helper method, which accepts the standard HTTP verbs (DELETE, GET, HEAD, POST, and PUT). Internally, this works by sending the verb in an X-HTTP-Method-Override form field.

The behavior of HttpMethodOverride is used by the [AcceptVerbs] attribute as well as the new shorter verb attributes:

While the override can only be used when the real request is a POST request, the override value can also be specified in an HTTP header or in a query string value as a name/value pair.

The following are some guidelines for deciding whether to use synchronous or asynchronous pipelines. Note that these are just guidelines and each application will have its own requirements.

Use synchronous pipelines when:

Use asynchronous pipelines when:

Since asynchronous pipelines have more infrastructure and overhead than synchronous pipelines, asynchronous code is somewhat more difficult to reason about than synchronous code. Testing such code would require mocking more of the infrastructure, and it would also require taking into account that the code can execute in many different orderings. Finally, it's not really beneficial to convert a CPU-bound operation to an asynchronous operation, since all that does is add overhead to an operation that probably wasn't blocked to begin with. In particular, this means that code that performs CPU-bound work within ThreadPool.QueueUserWorkItem() method will not benefit from an asynchronous pipeline.

Asynchronous actions are written in a similar fashion to standard synchronous actions. In much the same way that the Controller type serves as the base class for synchronous controllers, the AsyncController type serves as the base class for asynchronous controllers. For example, consider a portal site that displays news for a given area. A typical synchronous action might look like this.

public class PortalController : Controller {
    public ActionResult News(string city) {
        NewsService newsService = new NewsService();
        NewsModel news = newsService.GetNews(city);
        return View(news);
    }
}
Code snippet 5-34.txt

Accessing /Portal/News?city=Seattle will show local news for Seattle. This can easily be rewritten as an asynchronous action method as follows:

public class PortalController : AsyncController {
    public void NewsAsync(string city) {
        AsyncManager.OutstandingOperations.Increment();
        NewsService newsService = new NewsService();
        newsService.GetNewsCompleted += (sender, e) => {
            AsyncManager.Parameters["news"] = e.News;
            AsyncManager.OutstandingOperations.Decrement();
        };
        newsService.GetNewsAsync(city);
    }

    public ActionResult NewsCompleted(NewsModel news) {
        return View(news);
    }
}
Code snippet 5-35.txt

Note a few patterns here:

If the action name is Sample, then the framework will look for SampleAsync() and SampleCompleted() methods.

View pages should be named Sample.aspx rather than SampleAsync.aspx or SampleCompleted.aspx. (Remember, the action name is Sample.)

The true benefit of asynchronous code can be seen when an action wants to perform several operations at a time. For example, a typical portal site would show not simply news, but also sports, weather, stocks, and other information. A synchronous version of such an action method would take the following form:

public class PortalController : Controller {
    public ActionResult Index(string city) {
        NewsService newsService = new NewsService();
        NewsModel newsModel = newsService.GetNews(city);

        WeatherService weatherService = new WeatherService();
        WeatherModel weatherModel = weatherService.GetWeather(city);

        SportsService sportsService = new SportsService();
        SportsModel sportsModel = sportsService.GetScores(city);

        PortalViewModel model = new PortalViewModel {
            News = newsModel,

Weather = weatherModel,
            Sports = sportsModel
        };

        return View(model);
    }
}
Code snippet 5-36.txt

Note that the calls are performed sequentially, so the time required to respond to the user is equal to the sum of the times required to make each individual call. If the calls are 200, 300, and 400 microseconds (μs), then the total action execution time is 900 μs (plus some insignificant overhead).

Similarly, an asynchronous version of that action would take the following form:

public class PortalController : AsyncController {
    public void IndexAsync(string city) {
        AsyncManager.OutstandingOperations.Increment(3);

        NewsService newsService = new NewsService();
        newsService.GetNewsCompleted += (sender, e) => {
            AsyncManager.Parameters["news"] = e.News;
            AsyncManager.OutstandingOperations.Decrement();
        };
        newsService.GetNewsAsync(city);

        WeatherService weatherService = new WeatherService();
        weatherService.GetWeatherCompleted += (sender, e) => {
            AsyncManager.Parameters["weather"] = e.Weather;
            AsyncManager.OutstandingOperations.Decrement();
        };
        weatherService.GetWeatherAsync(city);

        SportsService sportsService = new SportsService();
        sportsService.GetScoresCompleted += (sender, e) => {
            AsyncManager.Parameters["sports"] = e.Scores;
            AsyncManager.OutstandingOperations.Decrement();
        };
        SportsModel sportsModel = sportsService.GetScoresAsync(city);
    }

    public ActionResult IndexCompleted(NewsModel news,
        WeatherModel weather, SportsModel sports) {

        PortalViewModel model = new PortalViewModel {
            News = news,
            Weather = weather,
            Sports = sports
        };

        return View(model);
    }
}
Code snippet 5-37.txt

Note that the operations are all kicked off in parallel at the same time, so the time required to respond to the user is equal to the longest individual call time. If the calls are 200, 300, and 400 μs, then the total action execution time is 400 μs (plus some insignificant overhead).

In both of the above examples, the URL to access the action is /Portal/Index?city=Seattle (or /Portal?city=Seattle, using the default route), and the View page name is Index.aspx (since the action is Index).

Any filters ([Authorize], [OutputCache], [ActionName], [AcceptVerbs], etc.) should be placed on the ActionAsync() method rather than the ActionCompleted() method. Filters placed on the ActionCompleted() method will be ignored.

[Authorize] // correct
public void ActionAsync() {
    // ...
}

[Authorize] // incorrect
public ActionResult ActionCompleted() {
    // ...
}
Code snippet 5-38.txt

Furthermore, the method pair SampleAsync() and SampleCompleted() must share the same prefix (in this case, Sample), even if an [ActionName] attribute is applied. Consider the following action:

[ActionName("Bravo")]
public void AlphaAsync() {
    // ...
}

public ActionResult AlphaCompleted() {
    // ...
}
Code snippet 5-39.txt

In this example, accessing /controller/Alpha will result in a 404, since the action has been renamed to Bravo. The correct URL is /controller/Bravo. The View page should be named Bravo.aspx.

The default time-out for an asynchronous action is 45 seconds. If the time-out period expires, a TimeoutException will be thrown, and action filters will be able to respond to this from within OnActionExecuted(). [HandleError] can also respond to this exception.

[HandleError(ExceptionType = typeof(TimeoutException))]
Code snippet 5-40.txt

Two attributes are provided to control the time-out period: [AsyncTimeout] and [NoAsyncTimeout]. [AsyncTimeout] specifies a time-out period in milliseconds, and [NoAsyncTimeout] specifies that TimeoutException should never be thrown. Because these attributes are action filters, they can go on an ActionAsync() method to control that individual action, or they can go on the controller to apply to every action within that controller.

[AsyncTimeout(60000)] // this method times out after 60 seconds
public void ActionAsync() {
    // ...
}

[NoAsyncTimeout] // infinite timeout for all actions in controller
public class PortalController : AsyncController {
    // ...
}
Code snippet 5-41.txt

Controllers which derive from AsyncController may mix and match synchronous and asynchronous methods. That is, it is perfectly legal to have methods like Index(), ListAsync(), and ListCompleted(), and the like on the same controller.

The AsyncController will not allow direct access to ActionAsync() or ActionCompleted() methods. That is, the URL to access this action must be /controller/Action rather than /controller/ActionAsync or /controller/ActionCompleted. In particular, this means that RedirectToAction("ActionAsync") is incorrect; use RedirectToAction("Action") instead. The same rule applies to Html.ActionLink() and other APIs that accept action names as parameters.

Synchronous action methods on controllers which derive from AsyncController cannot have an Async or Completed suffix. For example, in an air travel booking site, the following is invalid unless there's a matching ReservationAsync() method.

// will be blocked
public ActionResult ReservationCompleted() {
}
Code snippet 5-42.txt

If you want ReservationCompleted() to be exposed as a standard synchronous method, it needs to be moved to a synchronous controller class, or the method name must be changed. You can restore the original action name using an alias:

[ActionName("ReservationCompleted")]
public ActionResult SomeOtherName() {
}
Code snippet 5-43.txt

If your asynchronous action method calls a service that exposes methods using the BeginMethod()/EndMethod() pattern (http://msdn.microsoft.com/en-us/library/ms228963.aspx), your callback will be executed on a thread that is not under the control of ASP.NET. Some consequences of this are that HttpContext.Current will be null, and there will be race conditions accessing members like AsyncManager.Parameters. To restore HttpContext.Current and eliminate the race condition, call AsyncManager.Sync() from within your callback.

public void NewsAsync(string city) {
    AsyncManager.OutstandingOperations.Increment();
    NewsService newsService = new NewsService();
    newsService.BeginGetNews(city, ar => {
        AsyncManager.Sync(() => {
            AsyncManager.Parameters["news"] =
                newsService.EndGetNews(ar);
            AsyncManager.OutstandingOperations.Decrement();
        });
    }, null);
}
Code snippet 5-44.txt

Alternatively, you can use the AsyncManager.RegisterTask() extension method from MVC Futures, which handles synchronization on your behalf. It also handles incrementing and decrementing the OutstandingOperations counter so that you don't have to.

public void NewsAsync(string city) {
    NewsService newsService = new NewsService();
    AsyncManager.RegisterTask(
        callback =>
            newsService.BeginGetNews(city, callback, null),
        ar => { AsyncManager.Parameters["news"] =
                    newsService.EndGetNews(ar); }
    );
}
Code snippet 5-45.txt

Be sure to reference the Futures assembly and import the Microsoft.Web.Mvc namespace if you want to use this extension method.

You can call AsyncManager.Finish() to force the ActionCompleted() method to be called, even before the OutstandingOperations counter has reached zero.

Html.Action() and Html.RenderAction() can target asynchronous action methods, but they will execute synchronously. That is, the thread servicing the request will not be released back to the thread pool between the calls to ActionAsync() and ActionCompleted().

At this point, you should add another action method to respond to the form post. Note that by using the parameterless Html.BeginForm, the form will post to itself. However, you should avoid having logic in your Edit action to check for the postback (which is similar to checking Page.IsPostBack in Web Forms).

Fortunately, you can add another Edit action, which only responds to POST requests using the AcceptVerbsAttribute like so:

[HttpPost]
public ActionResult Edit(Product product)
{
  //...
}
Code snippet 5-49.txt

When two action methods have the same name, the action invoker will try to differentiate the methods based on the attributes applied to the method. Thus, the initial request for /Home/Edit does not match the attribute applied on the second Edit method, so the first one, which has no attribute, will respond. When a POST request is made, the second action method will respond, because it is an exact match for the POST HTTP verb.

Another thing very much worth mentioning here is the action parameter, which is the type of the object we're trying to bind: Product.

When posting a form to this action, the default ModelBinder will do its best to associate values found in Request.Form, Request.QueryString, and Request.Cookies to the properties of Product. There's a lot more to this, of course, and we'll talk about that later in this chapter.

To use the Model Binders to auto-magically bind your Model object, you simple "ask" for it as a parameter to your action:

[HttpPost]
public ActionResult Edit(Product product)
{
  if(ModelState.IsValid){

    //simulate save to the DB
    db.SaveChanges(product);

    ViewData["Message"] = product.ProductName + " Updated";
    return RedirectToAction("Edit");
  }

else
  {
    return View(product);
  }
}
Code snippet 5-50.txt

There are several things to notice about this code:

Note that redirecting the request only upon success technically violates the PRG pattern, but because no changes were made to the state of anything when validation failed, it doesn't suffer from most of the problems with not following the PRG pattern. Phil likes to call this loose PRG as opposed to strict PRG.

Validation in ASP.NET 1.0 was done by implementing the IDataErrorInfo and writing imperative validation logic. ASP.NET MVC 2 simplifies this quite a bit with Data Annotation-based model validation. Let's retrofit the Product class you used in the previous section to implement a few simple validation rules:

public class Product {
      [Required(ErrorMessage = "The product name must not be empty.")]
      public string ProductName { get; set; }
      [Range(0, double.MaxValue,
             ErrorMessage="The unit price must be larger than 0.00.")]
       public double UnitPrice { get; set; }
}
Code snippet 5-51.txt

Now, if you type −1 for the unit price, you'll see a specific error message in the form.

We'll cover model validation in depth in Chapter 13.