Replace JSON.NET with Jil JSON serializer in ASP.NET Web API

I have recently come across a comparison of fast JSON serializers in .NET, which shows that Jil JSON serializer is one of the fastest.

Jil is created by Kevin Montrose developer at StackOverlow and it is apparently heavily used by Stackoveflow.

This is only one of many benchmarks you can find on Github project website.


You can find more benchmarks and the source code at this location

In this short article I will cover how to replace default JSON serializer in Web API with Jil.

Create Jil MediaTypeFormatter

First, you need to grab Jil from NuGet

PM> Install-Package Jil

After that, create JilFormatter using code below.

    public class JilFormatter : MediaTypeFormatter
        private readonly Options _jilOptions;
        public JilFormatter()
            _jilOptions=new Options(dateFormat:DateTimeFormat.ISO8601);
            SupportedMediaTypes.Add(new MediaTypeHeaderValue("application/json"));

            SupportedEncodings.Add(new UTF8Encoding(encoderShouldEmitUTF8Identifier: false, throwOnInvalidBytes: true));
            SupportedEncodings.Add(new UnicodeEncoding(bigEndian: false, byteOrderMark: true, throwOnInvalidBytes: true));
        public override bool CanReadType(Type type)
            if (type == null)
                throw new ArgumentNullException("type");
            return true;

        public override bool CanWriteType(Type type)
            if (type == null)
                throw new ArgumentNullException("type");
            return true;

        public override Task<object> ReadFromStreamAsync(Type type, Stream readStream, System.Net.Http.HttpContent content, IFormatterLogger formatterLogger)
	        return Task.FromResult(this.DeserializeFromStream(type, readStream));           

        private object DeserializeFromStream(Type type,Stream readStream)
                using (var reader = new StreamReader(readStream))
                    MethodInfo method = typeof(JSON).GetMethod("Deserialize", new Type[] { typeof(TextReader),typeof(Options) });
                    MethodInfo generic = method.MakeGenericMethod(type);
                    return generic.Invoke(this, new object[]{reader, _jilOptions});
                return null;


        public override Task WriteToStreamAsync(Type type, object value, Stream writeStream, System.Net.Http.HttpContent content, TransportContext transportContext)
            var streamWriter = new StreamWriter(writeStream);
            JSON.Serialize(value, streamWriter, _jilOptions);
            return Task.FromResult(writeStream);


This code uses reflection for deserialization of JSON.

Replace default JSON serializer

In the end, we need to remove default JSON serializer.

Place this code at beginning of WebApiConfig

config.Formatters.Insert(0, new JilFormatter());


Feel free to test Jil with Web API and don’t forget to subscribe here and don’t miss a new blog post.


  • Jordan Terrell

    Nice post. Just an observation: You probably don’t want to use Task.Factory.StartNew (or Task.Run). It causes the task to be scheduled on a thread pool thread and, in this case, does the work synchronously on another thread. Better just do the work synchronously and return a completed task using Task.FromResult or TaskCompletionSource, and not incur the overhead of marshaling the work onto another thread.

    There is a great video[1] and article[2] explaining why this is a better approach.


    • Hi Jordan. Thanks for a tip. I am not multi-threaded expert. I have just implemented this in usual way all similar formatters are implemented.
      From my point of view if I do all work synchronously maybe it will block current execution thread in case of many concurrent requests.
      Usually job of deserializing data will be finished very fast so Tasks will not live very long.
      I am not sure what is better approach.
      It seams to me to me as if I choose between NodeJs and ASP.NET Web API 🙂

      • The overhead of spinning up a Task on a thread will be worse. For this kind of thing you just want to return Task.FromResult(obj).

        • Thanks for comment Mark. You are probably right especially because deserialization is not long running task so initialization of Task on a thread is not worth for such a small operation.

          • It would be nice for to modify your post to use this incase future readers copy and paste this.

          • I have just updated code in this blog post implementing improvements suggested in this comment.

          • Should this also be applied to WriteToStreamAsync? I’m not really sure what’s going on with calling StartNew and handing it a stream, I would suspect that the work has already been completed synchronously by JSON.Serialize()… unless that method is lazy and will only execute when the Stream is read?

          • Sorry. I have missed that.
            I have implemented a same approach on WriteToStreamAsync.

  • cgatian

    config.Formatters.RemoveAt(0); seems wrong. What if the built-in isn’t the first formatter?

    • Thanks for comment.
      You are correct. Usually JSON formatter is on first place. This is just very quick implementation so feel free to adapt code to your needs.

  • icanhasjonas

    There’s a nuget/github JIL formatter at that should be able to do the job

    • Hi Jonas.
      Thanks for creating the project.
      It is always nice to have Nuget package at hand.

  • Looks awesome, but sadly my project can only run in 4.0 for the next while, so can’t make use of Jil yet

    • Quinton thanks for comment.
      Sorry for hear that. Better luck on your next project.
      Don’t forget to subscribe to this blog and make sure you don’t miss upcoming blog posts.

      • Thanks for the subscription link, subscribed

    • ” but sadly my project can only run in 4.0 for the next while”

      Who gets to make these stupid decisions? Unless it’s a redistributable application/assemblies that you don’t want to preclude customers from, there’s literally zero reasons to not use 4.5 over 4.0.

      • Quinton Viljoen

        We host the application in our data center for multiple large customers, using server 2008. IIS on 2008 doesn’t just plug 4.5 out of the box, so there is a bit of a upgrade that has to take place before we can just recompile for 4.5…

        The project stakeholders say the risk outweighs the benefits of going 4.5 just yet and would rather go that route once we upgrade to server 2012.

  • MethodInfo method = typeof(JSON).GetMethod(“Deserialize”, new Type[] { typeof(TextReader),typeof(Options) });
    MethodInfo generic = method.MakeGenericMethod(type);

    You might want to make these static readonly fields. I can’t say for sure it would be beneficial, i never know off hand what reflection things do all the right caching for you themselves but this is definitely one that would never vary and could easily be a static field. Since it’s all compile time constants and typeofs.

    • Hey Chris.
      Thanks for advice. You are absolutely right.
      It’s something that Resharper will also probably recommend. However I haven’t got time to improve this code after initial blog post.
      I will try to do this in near future.

  • kamerrer

    How to config JilFormatter to camel case like this:

    var jsonFormatter = config.Formatters.OfType().First();
    jsonFormatter.SerializerSettings.ContractResolver = new CamelCasePropertyNamesContractResolver();

    • Hi kamerrer. Unfortunately, I don’s see a way to force Jil to serialize using camel case.
      Currently this option is not available in Jil serializer.
      Jil supports customizable names (via [DataMember] and [JilDirective]), but then you will need to manually decorate all properties of classes.
      Read this explanation here :

      • Waqas Usman

        Hi Radenko,

        First of all thank you for this blog, it was very helpful!

        You may already have noticed, the camelCase serialization is now supported and it is mentioned on the github page you linked to. You can do it by adding the SerializationNameFormat in Options like this:

        _jilOptions = new Options(dateFormat: DateTimeFormat.MillisecondsSinceUnixEpoch, serializationNameFormat:SerializationNameFormat.CamelCase);

  • Guy

    Does any one know if Jil can accept ContentType : json in the http call to the API ?
    From what I see it can only accept ContentType:x-www-formencoded

  • Amit

    It is not working in case of enum. When I try to pass enum to Web Api then it throw exception at Expected character: ‘”‘ in DeserializeFromStream method . this is my Json {"device_id":"1233","device_type":1} here device_type is enum

  • Aniket Bhansali

    I keep getting following error, *Error occurred building a deserializer for HotelFirst.Models.tblHotelTax: Member [Connection] isn’t marked as part of a union, but other members share the same Name [Connection]* whenever I make POST request to web-api.

  • Simon

    I get this error “the best overloaded method match for System.Convert.FromBase64String(string) has some invalid arguments” when trying to retrieve a base64 string using Jil?