When To Use System.Text.Json with ASP.NET Core

This is the last post in a series on System.Text.Json. The previous articles in the series are:

• Part 1: Why System.Text.Json exists, major differences with Newtonsoft, and how to find help with the new library
• Part 2: Reading JSON documents
• Part 3: Writing JSON documents
• Part 4 [this post]: When To Use System.Text.Json with ASP.NET Core

Usage of .NET’s shiny new JSON library is far from being unanimous. The adoption by customers has been slow, mostly because it’s not — and isn’t meant to be — a one-for-one replacement of Json.NET.

It doesn’t change the fact that System.Text.Json is here to stay and that it’s now the default serializer for ASP.NET Core projects. But that’s a far stretch from saying that you should always use it for everything.

I’ll go over the considerations I look at when deciding which library to use in an ASP.NET Core project. My recommendations stem from the usage I’ve done of it in real-world projects. Your mileage may vary.

New ASP.NET Core Projects

Greenfield projects are one of the safest places to get started with System.Text.Json. The project comes pre-loaded with System.Text.Json as the default serializer, so you don’t have to do anything to enable it. More importantly, you don’t need to retrofit any Json.NET code since you’re starting from scratch.

A shiny new project is the ideal time to explore and learn the APIs provided with the library. There will undoubtedly be some frustration as things work differently from Json.NET, but with a bit of research, you can usually find a workaround. There are also some highly requested features coming soon to System.Text.Json, but any additions need to adhere to the strict design guidelines they’ve established for the project. That limits what can be done moving forward, much to the chagrin of many GitHub commenters.

I avoid using System.Text.Json if it interacts with other applications still using Json.NET, such as in a microservices architecture. I prefer the same serializer across projects to make usage uniform across applications. But more importantly, I want to reduce the risk of serialization differences between the libraries. I’ve had issues in the past between different versions of Newtonsoft, so using entirely different libraries across applications sounds like a recipe for trouble.

Existing ASP.NET Core Projects

I wouldn’t move any existing project to System.Text.Json if it’s working fine with Json.NET, unless you’ve got a really good reason to do so, such as stringent performance requirements. The new library has shown significant improvements in that area and could give you the gains you need. There is a cost to migrating though.

You’re going to run into roadblocks re-writing the code with the new library if you’ve done anything beyond the basics with Json.NET. That’s because System.Text.Json isn’t meant to be an in-place replacement for Json.NET. Think of it more like an alternative to Json.NET. The effort required for such an undertaking is rarely worth it.

Similarly to new projects, I don’t like the idea of mixing JSON libraries across applications that need to speak to each other. Stick with one JSON library for all your applications, be it System.Text.Json or Json.NET.

Libraries referenced by ASP.NET Core Projects

Sometimes a library project needs to create or read JSON data. System.Text.Json is an appealing choice for libraries, considering that it comes packaged with .NET out of the box. That means one less dependency and therefore less chances of dependency version conflicts. In fact, there’s very little reason to consider anything else, so long as the JSON isn’t later processed by an application using Json.NET.

Similarly, it might be tempting to put a type from System.Text.Json namespace as part of your library’s public contracts. For example, you might consider the following method signatures:

public interface MyPublicContract 
{
    void DoSomething(JsonDocument document);
    JsonElement DoAnotherThing();
}

Normally, this would seem like a bad idea, but since the types are built into the framework, is there really any difference with any other type? I wouldn’t do this on a regular basis, but it can be useful in some cases.

Using System.Text.Json and Json.NET Together

The last possibility, of course, is to use both libraries in the same project. I’m sure lots of people are having heart attacks just reading that, but it is something you could consider in the most dire of circumstances.

Of course, you can only use one or the other for serialization and deserialization at the ASP.NET Core level. But nothing prevents you from using both libraries within the application. There is no way to go from Json.NET’s types to System.Text.Json’s types, but you could get away with it by serializing with the first library and deserializing with the other. There will likely be some JSON compatibility issues, and you’d lose cycles during serialization and deserialization, but you might consider it if you’re really, really desperate.

Wrap Up

Like with many things in software development, there is never one clear cut answer. The right choice of JSON library is going to depend on how it’s going to be used, where it’s going to be used and what it’s going to interact with. My rule of thumb can be summarized into a single sentence: use System.Text.Json for greenfield projects, so long as you have the willingness to learn and adapt to the new library.

And that’s a wrap for this series on System.Text.Json. It was an introductory level overview of the APIs and how to use them, but I hope it’s pointed you in the right direction.