Blog

I’ve recently updated an MVC 3 project to use unobtrusive ajax. If you create a new ASP.NET MVC 3 project unobtrusive ajax will be enabled by default, but this was a project I had once migrated from MVC 2. Instead of physically adding the unobtrusive ajax JavaScript file to my solution I got it from the Microsoft Ajax CDN.

The unobtrusive ajax libraries not only leave your html cleaner by using the HTML 5 compatible “data-” attribute, but return a much clearer set of results objects from the controller.

The latter was, for me, a great relief, because I always ended up taking care of responses to ajax calls in several different ways within one application. Do I return strings from the controller action or do I go with Json? Or should I always return a HttpStatusCodeResult?

I’ve finally found a pattern, for lack of a better word, that I find clean, clear and consistent. Here’s how.

Calling the controller

Imagine we want to make an ajax call to a controller to, say, change the status of an order. In our view we simply do:

@Ajax.ActionLink("Set to pending", "setstatus", "order", 
    new { id = Model.ID, status = 0 }, new AjaxOptions 
        { OnFailure = "Error", OnSuccess = "StatusChanged", 
            HttpMethod = "POST" })

Two things to notice in the AjaxOptions object:

1. I explicitly set the HttpMethod to POST. We will be returning a Json object from the controller and the unobtrusive ajax library “encourages” us to avoid going to the server with a GET request for security reasons. You’ll know you have this problem because an exception will be thrown saying “This request has been blocked because sensitive information could be disclosed to third party web sites when this is used in a GET request. To allow GET requests, set JsonRequestBehavior to AllowGet.”
2. I’ve defined two callback methods, one for error and another for success. These methods will be passed a default set of arguments by the unobtrusive ajax library which we will be able to use from our action method to return the status of the operation and any meaningful messages we deem necessary. These are the method signatures: 

function Error(response, status, error) {
}

function StatusChanged(response, status, data) {
} 

Action

We want our action to give a meaningful error message when things go wrong, and to return for instance the id and new status of the order if everything goes OK.

[HttpPost]
public ActionResult SetStatus(int id, int status)
{
    try
    {
       // Code to update the order status here

        return Json(new
        {
            ID = id, 
            NewStatus = order.StatusDescription
        });
    }
    catch
    {
        return new HttpStatusCodeResult(418, 
            "Couldn't change the status of the order");
    }
}

Notice how we’ve marked our action to accept HttpPost request only? This is of course because we specified POST as the HttpMethod in our ActionLink to solve JsonReuqestBehavior problem mentioned above. Another solution is to ignore the Http verbs and methods altogether and add JsonRequestBehavior .AllowGet as second parameter of the Json result.

Dealing with the results

Imagine we’ve just changed the status successfully; our action method returns a Json result containing an anonymous type with two properties, ID and NewStatus. We can define these with whatever name we like, or even create a property that is itself an anonymous type. It will all be serialized to Json by ASP.NET MVC. How do we use these on the view? Quite easy really:

function StatusChanged(response, status, data) {
    alert("order #:" + response.ID + "has a new status: " 
        + response.NewStatus);
}

Of course, you’d want to do something a tad more meaningful with your results, but the essence of it is this: The properties you defined in your anonymous type are directly available through the response parameter. Had you defined a property that was itself an anonymous type, named for instance Extras, with other properties in it, you’d simply do response.Extras.WhateverProperty.

And if things go south?

As you can see we have a nice try..catch in our action. When an exception is thrown or there’s an error we want to signal we need make it known in the response. That basically means returning a status code other than 200 (“OK”). Here I’m returning the Http Status Code 418: “I’m a  teapot” :þ I promise it is a valid http status code; if you don’t believe me, check Wikipedia!

Anyway, when returning a status code other than 200 our Error function will be called. How doe we deal with the error message? As easy as before:

function Error(response, status, error) {
    alert("Oops! " + response.statusText);
}

So there you have it. Do you know of a better/different way? Let me know!