Per-Type De/Serialisation in Json.Net WebApi

Just a quick post today, to help me remember more than anything - also because I couldn’t find anything on Google with a similar title.

This post will show Per-Type De/Serialisation in a Json.Net WebApi. I’m going to show how to do custom de/serialisation using Json.Net Converters.

Media Formatters vs Converters

There is another way to do custom de/serialisation of a Type. They are called Media Formatters. You can write a custom MediaTypeFormatter. Media Formatters are great if you want to add a new way of “inputting/outputting” (read: Content-Type/Content-Accept) objects to your WebApi. They are especially useful if you want to start accepting/returning different formats, e.g. CSV (something which WebApi does not support “out of the box”). You can map the formatter to a “Mime-type” so when a request/response is getting de/serialised you can control the input/output.

Important - Media Formatters only work at the “root” object level. That is if you’re accepting/returning e.g. an Employee object, then only a media formatter which “CanReadType/CanWriteType”, and has the correct Mime-Type will take over de/serialisation. If however you only want to “step-in” and control the de/serailisation of an object that is not the “root” of the object tree you’re returning then I’m afraid MediaFormatters are not for you! For example if the object is a Corporation and has a list of employees - then you’re media formatters will not fire and you’re custom code wont run.

Step in - Converters

So, now we know Media Formatters only work at the root level - and as their name “hints” and coupled with the fact that you have to map to a Mime-Type - they probably shouldn’t be used when trying to customise “Per-Type” Serialisation in Json.Net and WebApi. Instead, we use Json.Net Converters! Converters will step in at any level in the object hierarchy - so when we want to customise the de/serialisation of Emnployee which is a property of Corporation - this will all work seamlessly.

The example on the Json.Net documentation is a good one - I’m not going to re-hash it here.

Registering the Converter

Getting the Converter into the WebApi pipeline is easy, there are a couple of ways:

Adding to the Json.Net Formatter (in WebApiConfig.cs>Register)

config.Formatters.JsonFormatter.SerializerSettings.Converters.Add(new EmployeeConverter());

Adding the JsonConverterAttribute to the type

[JsonConverter(typeof(EmployeeConverter))]
public class Employee
{
    public string Name { get; set; }
    public int Age { get; set; }
}

Hopefully this has given a good insight into the difference between Media Formatters and Json.Net Converters. The lines were a bit blurry for me when I first looked at them, however after digging deeper and using both, it finally clicked!

If you use another way or have any improvements, give me a shout on Twitter