If you’ve spent much time working with the .NET platform, ASP.NET’s simple, convention-based approach to exposing JSON endpoints seems just about too good to be true. After years of fiddling with manual settings in XML configuration files, it’s understandable to assume that working with JSON in ASP.NET would require a similar rigmarole, yet it does not.
Unfortunately, this unexpected ease-of-use isn’t obvious if you don’t already know about it, which has led some developers to build needlessly complicated solutions to problems that don’t actually exist. In this post, I want to point out a few ways not to approach JSON in ASP.NET and then show you a couple examples of leveraging the frame work to do it “right”.
A couple examples of what NOT to do
To show you exactly what I’m talking about, let’s start by looking at a few concrete examples of ways that you should not handle sending and receiving JSON in your ASP.NET services.
For all the examples, we’re going to be trying to send and/or receive instances of this Person class:
public class Person
{
public string FirstName { get; set; }
public string LastName { get; set; }
}
Once you progress beyond simple scalar types, sending objects (and collections of them) back and forth is a pretty logical next step, and that’s also the point where this manual serialization trouble seems to begin. So, working with this simple Person class should serve as a realistic example, without being overly complex.
Manual serialization, using JavaScriptSerializer
The most common variant of this mistake that I’ve seen is using JavaScriptSerializer to manually build a JSON string and then returning that string as the result of a service method. For example, if you didn’t know better, you might do this to return an instance of the Person class:
[ScriptService]
public class PersonService : WebService
{
[WebMethod]
public string GetDave()
{
Person dave = new Person();
dave.FirstName = Dave;
dave.LastName = Ward;
JavaScriptSerializer jss = new JavaScriptSerializer();
// Results in {"FirstName":"Dave","LastName":"Ward"}
string json = jss.Serialize<Person>(dave);
return json;
}
}
This may look sensible enough on the surface. After all, the json variable does end up containing a nicely serialized JSON string, which seems to be what we want. However, you should not do this.
What actually happens
Part of the beauty of using ASP.NET’s JSON-enabled services is that you rarely have to think much about the translation between JSON on the client-side and .NET objects on the server-side. When requested with the proper incantations, ASP.NET automatically JSON serializes your service methods’ responses, even if their result is an object or collection of objects.
Unfortunately, that automatic translation also makes it easy to end up with doubly-serialized responses if you aren’t aware that ASP.NET is already handling the serialization for you, which is exactly what would happen in the preceding example. The end result is that the Person object is serialized twice before it gets back to the browser – once as part of the method’s imperative code and then a second time by convention.
In other words, it’s understandable to expect the previous code example would return this response:
{"FirstName":"Dave","LastName":"Ward"}
But, what it actually returns is this:
// All the quotes in the manually generated JSON must be escaped in
// the second pass, hence all the backslashes.
{"d":"{\"FirstName\":\"Dave\",\"LastName\":\"Ward\"}"}
What a mess. That’s probably not what you had in mind, is it?
Using DataContractJsonSerializer or Json.NET is no better
This may seem obvious, but I want to point out that using a different manual serialization tool, like WCF’s DataContractJsonSerializer or Json.NET, in place of JavaScriptSerializer above does not remedy the underlying problem. I only mention it because I’ve seen those variations of the mistake floating around too.
If anything, in the case of DataContractJsonSerializer, it’s even worse. DCJS’ handling of Dictionary collections and Enums makes life unnecessarily tedious at times, and the code to manually invoke it is even more verbose than that for JavaScriptSerializer.
The impact this mistake has on the client-side
If it weren’t bad enough to add extra computational overhead on the server-side, cruft up the response with escaping backslashes, and increase the size of the JSON payload over the wire, this mistake carries a penalty on the client-side too.
Most JavaScript frameworks automatically deserialize JSON responses, but (rightfully) only expect one level of JSON serialization. That means that the standard functionality provided by most libraries will only unwrap one level of the doubly serialized stack of JSON produced by the previous example.
So, even after the response comes back and your framework has deserialized it once, you’ll still need to deserialize it a second time to finally extract a usable JavaScript object if you’ve made the mistake of manually serializing. For example, this is code you might see to mitigate that in jQuery:
$.ajax({
type: 'POST',
dataType: 'json',
contentType: 'application/json',
url: 'PersonService.asmx/GetDave',
data: '{}',
success: function(response) {
// At this point, response is a *string* containing the
// manually generated JSON, and must be deserialized again.
var person;
// This is a very common way of handling
// the second round of JSON deserialization:
person = eval('(' + response + ')');
// You'll also see this approach, which
// uses browser-native JSON handling:
person = JSON.parse(response);
// Using a framework's built-in helper
// method is another common fix:
person = $.parseJSON(person);
}
});
Regardless of which approach is used, if you see code like this running after the framework has already processed a response, it’s a pretty good indication that something is wrong. Not only is this more complicated and verbose than it needs to be, but it adds additional overhead on the client-side for absolutely no valid reason.
Flipping the script (and the JSON)
Redundant JSON serialization on responses is definitely one of the most common variations of this problem I’ve seen, but the inverse of that mistake also seems to be an alluring pitfall. Far too often, I’ve seen service methods that accept a single JSON string as their input parameter and then manually parse several intended inputs from that.
Something like this to accept a Person object form the client-side and save it on the server-side, for example:
[ScriptService]
public class PersonService : WebService
{
[WebMethod]
public void SavePerson(string PersonToSave)
{
JavaScriptSerializer jss = new JavaScriptSerializer();
Person p = jss.Deserialize<Person>(PersonToSave);
p.Save();
}
}
Just as ASP.NET automatically JSON serializes responses on its JSON-friendly services, it also expects that the input parameters will be in JSON format and automatically deserializes those on the way in. So, in reverse order, the approach above makes a mistake similar to the ones shown earlier.
To make this work, we’d need to pass in JSON that looks something like this, obfuscating the actually desired input parameters inside a single, doubly-serialized string parameter.
{"PersonToSave":"{\"FirstName\":\"Dave\",\"LastName\":\"Ward\"}"}
Through the convenience of JSON.stringify(), it’s not even terribly hard to stumble onto a process for cobbling that double-JSON structure together on the client-side and making this approach work. I strongly recommend against it though. Even if the double-JSON didn’t carry extra overhead in several aspects, having a single input parameter of type string on this method is misleading. A year from now, will anyone realize what type of parameter that method accepts without looking down into the manual parsing code? Probably not.
Doing it right
Briefly, here are what I suggest as better ways to handle passing our Person object in and out of ASP.NET services.
Returning an object
Returning a .NET object from ASP.NET services is incredibly easy. If you let go and just trust the service to handle JSON translation for you, “it just works”:
[ScriptService]
public class PersonService : WebService
{
[WebMethod]
public Person GetDave()
{
Person dave = new Person();
dave.FirstName = Dave;
dave.LastName = Ward;
// So easy!
return dave;
}
}
As long as you call that service method through a ScriptManager’s service proxy or using the correct parameters when using a library like jQuery, ASP.NET will automatically serialize the Person object and return it as raw, unencumbered JSON.
Accepting an object from the client-side
Accepting a Person object from the client-side works identically, in reverse. ASP.NET does a great job of matching JSON-serialized request parameters to .NET’s types, collections, and even your own custom objects.
For example this is how you could accept a Person object, which would even then allow you to call that object’s custom methods:
[ScriptService]
public class PersonService : WebService
{
[WebMethod]
public void SavePerson(Person PersonToSave)
{
// No, really, that's it (assuming Person has a Save() method).
PersonToSave.Save();
}
}