Last week we compared a number of different data-interchange formats and I explained why my current favourite is JSON.
JSON’s syntax is very simple. So easy in fact, that it can be expressed on a single page.
This makes it easy to remember and write. Further, it makes writing a JSON parser very easy as well.
However, there already are many solutions for all major, and many smaller languages and environments.
So instead of reinventing the wheel, today I would like to give an introduction to Json.NET, the library I have been using to read and write JSON for about two years now.
I will take a very practical approach, giving an overview over the basic features. Further, I will highlight some of the additional features of the library that I have found useful in the past, and we will extend the library to allow for parsing of custom non-trivial types.
The basic usage of Json.Net is very simple.
The static class
JsonConvert has a number of methods to serialise to and deserialise from JSON.
It does so by using reflection to do all the heavy lifting for us, and no additional code on our side is needed.
The library is very flexible however, and most of its behaviour can be extended or overridden as needed.
We will use the following class from last week (albeit slightly simplified) to show basic serialisation and deserialisation.
To serialise an object using Json.NET, we can simply pass it to
Doing so with the object created as follows:
yields this result:
By default Json.NET will use no white space to improve the size of the output. However, by passing
Formatting.Indented to the above method’s formatting parameter, we can easily get the following output.
This is much more readable, and I would prefer this in almost all cases unless the size is a definite problem.
Note that this method works great for pretty much any type, including dictionaries and other collections. It also works great with anonymous types, allowing easy dumping of arbitrary data to a file in a structured way without having to create container types that are not used for anything else.
Apart from its additional parameters, we can also modify this method’s behaviour in a number of different ways. One of them is by using attributes, to control how our data is serialised.
They can be found in the official documentation, but there is one I have found particularly useful:
This attribute is an easy way to prevent Json.NET from serialising properties that do not have to be. This is particularly useful if a type contains a property which does not have any backing data on its own, but infers its value from other properties.
Imagine for example a rectangle type with properties
Area. The area would neither have to be stored in memory, nor in JSON, but could always be calculated on the fly when needed.
By simply placing
[JsonIgnore] in front of our
Area property, Json.NET will ignore it when serialising.
Deserialisation with Json.NET is almost equally simple to serialisation.
We can simply use the generic method
There also is a non-generic overload, but if we know the type of data we are expecting – which should be the case most of the time – using the generic version will give us type-safety and relieves us from having to do additional parsing.
Without giving an example, it suffices to say that parsing either of the JSON from above results in a new object identical to the one we had before.
Serialiser settings and converters
Json.Net’s static serialisation and deserialisation methods also take additional parameters.
One of them is the
JsonSerializerSettings, which can be used to control the process in a variety of ways.
If you are looking into using Json.NET for more than minor things, I encourage you to take a look at the type’s documentation`.
Alternatively, the static methods take a list of
These converters are in essence the meat of the Json.NET library, determining how different values and types are written and read.
The library comes with several implementations that can be quite useful. My personal favourite is
StringEnumConverter, which reads and writes enum values as their string names, instead of as numbers, greatly improving readability.
Custom converters – extending Json.NET
In additional to the provided converters, we can also write our own by extending
Take for example the following converter, which serialises
System.Color into a hexadecimal string, and back.
Note that Json.NET already serialises
Color without any problems. The example merely serves to show how easy it is to create custom converters.
For more advanced examples, I invite you to take a look at the serialisation namespace in my C# graphics library.
One last useful feature of Json.NET I will mention here is the
This class can be used to keep both the state from
JsonSerializerSettings as well as a list of converters. As a result, one only has to configure it once and can then use it as many times as needed.
In this post, I gave a short introduction into the basics of serialising and deserialising JSON in C#, using Json.NET.
I hope this has been useful, and please let me know if you have any questions.
Also make sure to leave a comment if you would like me to go further into this or any other topic.
Enjoy the pixels!