NuGet Package of the Week #4 - Deserializing JSON with Json.NET

Hey, have you implemented the NuGet Action Plan? Get on it, it'll take only 5 minutes: NuGet Action Plan - Upgrade to 1.2, Setup Automatic Updates, Get NuGet Package Explorer. NuGet 1.2 is out, so make sure you're set to automatically update!

The Backstory: I was thinking since the NuGet .NET package management siteis starting to fill up that I should start looking for gems (no pun intended) in there. You know, really useful stuff that folks might otherwise not find. I'll look for mostly open source projects, ones I think are really useful. I'll look at how they built their NuGet packages, if there's anything interesting about the way the designed the out of the box experience (and anything they could do to make it better) as well as what the package itself does.

Json.NET is a popular high-performance JSON framework for .NET

If you're moving data around on the web, you'll eventually come upon JSON (JavaScript Object Notation) or as I like to call it, XML with curly braces. (Kidding) (No, I'm not kidding, you can easily convert between XML and JSON in most cases)

It's a lightweight data-interchange format. "It is easy for humans to read and write. It is easy for machines to parse and generate." It's also just JavaScript.

From JSON.ORG:

JSON is built on two structures:

• A collection of name/value pairs. In various languages, this is realized as an object, record, struct, dictionary, hash table, keyed list, or associative array.
• An ordered list of values. In most languages, this is realized as an array, vector, list, or sequence.

Basically stuff is either a name/value pair, or a list of stuff. That's it. It's great way to push data around, and since it's so flexible and works with JavaScript, it has become THE way to access many popular APIs for sites like Twitter and Facebook.

Json.NET is James Newton-King's excellent library for accessing and working with JSON on .NET. The 4.0 release is cool not only because it's in NuGet, but also because it's currently the best way to deal with JSON data structures on the Windows Phone. Json.NET is notable particularly for James' obsessive focus on performance (check the charts and graphs!) It's also been around FOREVER. I blogged about Json.NET in 2006, in fact.

Inside the Json.NET NuPkg

If you open up the Newtonsoft.Json.4.0.1.nupkg using the NuGet Package Explorer (that's a ClickOnce link, son) I can learn a lot about how James has packaged up his library.

First, notice now he's got a number of folders under his /lib folder. I talked about this a little with the last NuGet Package of the Week, but James has taken it to the max. Kudos to him!

With NuGet, you can have one package that includes versions of assemblies for many different Framework Versions. Check the NuGet documentation on Supporting Multiple .NET Framework Versions and Profiles.

James has create a single NuGet package for Json.NET that does the right thing for .NET 2.0, 3.5, 4, SL4, and the Windows Phone 7. Nice.

One thing I think James should add is a Newtonsoft.Json.Sample package per David Ebbo's post "Take NuGet to the next level with sample packages." I found myself wondering where to start with Json.NET as there was no sample code included. No worries, to the cloud web! James has amazing documentation on Json.NET on his site.

Using Json.NET

I've got this silly little site called SmallestDotNet.com that will look at your system using your Browser's UserAgent (and some JavaScript) to determine what version of .NET you have, and suggest the smallest possible download for you to up to date.

NOTE: This SmallestDotNet site was launched in 2008 but was broken on IE9 until my new friend Calinoiu Alexandru Nicolae from Romania (@CalinBalauru on Twitter) volunteered to fix it. Big thanks to Calin for his work on the SmallestDotNet site! Work is ongoing.)

The site also has a simple JSON payload that will give you the correct direct link to the right download for you. I never understood why it was so hard to get a direct download for .NET, so we put it in a basic JSON payload so you could access it programmatically.

The SmallestDotNet JSON payload looks like this. It's not very sophisticated, but it is what it is.

{
    "latestVersion": null,
    "allVersions": [
        
    ],
    "downloadableVersions": [
        {
            "major": 4,
            "minor": 0,
            "profile": "client",
            "servicePack": null,
            "url": "http://www.microsoft.com/downloads/details.aspx?displaylang=en&FamilyID=5765d7a8-7722-4888-a970-ac39b33fd8ab" 
        },
        {
            "major": 4,
            "minor": 0,
            "profile": "full",
            "servicePack": null,
            "url": "http://www.microsoft.com/downloads/details.aspx?FamilyID=9cfb2d51-5ff4-4491-b0e5-b386f32c0992&displaylang=en" 
        },
        {
            "major": 3,
            "minor": 5,
            "profile": "client",
            "servicePack": 1,
            "url": "http://www.microsoft.com/downloads/details.aspx?FamilyId=8CEA6CD1-15BC-4664-B27D-8CEBA808B28B&displaylang=en" 
        },
        {
            "major": 3,
            "minor": 5,
            "profile": "full",
            "servicePack": 1,
            "url": "http://go.microsoft.com/fwlink/?LinkId=124150" 
        },
        {
            "major": 3,
            "minor": 0,
            "profile": "full",
            "servicePack": 1,
            "url": "http://www.microsoft.com/downloads/details.aspx?FamilyId=10CC340B-F857-4A14-83F5-25634C3BF043&displaylang=en" 
        },
        {
            "major": 2,
            "minor": 0,
            "profile": "full",
            "servicePack": 2,
            "url": "http://www.microsoft.com/downloads/details.aspx?familyid=5B2C0358-915B-4EB5-9B1D-10E506DA9D0F&displaylang=en" 
        },
        {
            "major": 1,
            "minor": 1,
            "profile": "full",
            "servicePack": 1,
            "url": "http://www.microsoft.com/downloads/details.aspx?FamilyID=a8f5654f-088e-40b2-bbdb-a83353618b38&DisplayLang=en" 
        }
    ] 
}

Maybe I can access it with Json.NET? I wonder if it'll be easy or hard. There's a number of ways I can do it. This one uses the JObject "DOM" in JSON.NET:

var client = new WebClient();
client.Headers.Add("User-Agent", "Nobody");
var response = client.DownloadString(new Uri("http://www.hanselman.com/smallestdotnet/json.ashx"));
JObject o = JObject.Parse(response);'
//Now o is an object I can walk around...

Or, I can make C# classes that LOOK like the shape of my JSON payload and deserialize directly into them, which is cool:

class Program
{
    static void Main(string[] args)
    {
        var client = new WebClient();
        client.Headers.Add("User-Agent", "Nobody"); //my endpoint needs this...
        var response = client.DownloadString(new Uri("http://www.hanselman.com/smallestdotnet/json.ashx"));

        var j = JsonConvert.DeserializeObject<SmallestDotNetThing>(response);
    }

    public class SmallestDotNetThing
    {
        public DotNetVersion latestVersion { get; set; }
        public List<DotNetVersion> allVersions { get; set; }
        public List<DotNetVersion> downloadableVersions { get; set; }
    }

    public class DotNetVersion
    {
        public int major { get; set; }
        public int minor { get; set; }
        public string profile { get; set; }
        public int? servicePack { get; set; }
        public string url { get; set; }
    }
}

Now, look at the j variable in this screenshot. How cool is that?

There's lots of choices on how you want to consume your JSON with .NET.

New Json.NET Features

The new Json.NET is compiled on .NET 4, and includes some really cool dynamic support. From James' blog, see how things used to work, and how the new C#4 dynamic keyword makes working with JSON more fun.

JObject oldAndBusted = new JObject();
oldAndBusted["Name"] = "Arnie Admin";
oldAndBusted["Enabled"] = true;
oldAndBusted["Roles"] = new JArray(new[] { "Admin", "User" });
 
string oldRole = (string) oldAndBusted["Roles"][0];
// Admin

 
dynamic newHotness = new JObject();
newHotness.Name = "Arnie Admin";
newHotness.Enabled = true;
newHotness.Roles = new JArray(new[] { "Admin", "User" });
 
string newRole = newHotness.Roles[0];
// Admin

This is really an amazing open source library and I encourage you to check it out if you're doing anything at all with JSON, and maybe throw JamesNK a few coins for his efforts. Thanks, James!

Another Json Library: JsonFx 2.0

If you're really interested in ways to consume JSON using C# dynamics, also check out JsonFx 2.0 on GitHub or JsonFx on NuGet! This library is extremely easy to use with dynamics.

Check out how this simple code:

dynamic foo = new JsonFx.Json.JsonReader().Read(response);

Gets you this result...note that is a C# dynamic typed object:

Very nice. Enjoy!

Related Links

• Json.NET CodePlex Project
• Json.NET 4.0 Release 1 Download – Json.NET source code, documentation and binaries
• Hosting a Simple Read-Only NuGet Package Feed on the Web
• NuGet 1.2 Released with some new features
• JsonFx 2.0 on GitHub