Use Newtonsoft's Json.NET instead of System.Text.Json in ASP.NET Core 3+ MVC projects How to replace the ASP.NET Core's native System.Text.Json APIs with the Newtonsoft.Json package library, also known as Json.NET

If you're a ASP.NET developer and you've got some programming experience with ASP.NET Core 3+, you most likely already know that the ASP.NET Core development team introduced a brand new namespace called System.Text.Json with support for a reader/writer, a document object model (DOM), a serializer and (almost) everything you might reasonably expect from a set of APIs to work with JSON data.

It's no mistery that they added such namespace to give the developers a "built-in" alternative to the Json.NET NuGet package, also known as Newtonsoft.Json, a popular high-performance JSON framework for .NET: such library has been around since june 2006 and it's now a well-established framework for working with JSON, which hundreds of thousands of downloads by developers from around the world.

In recent years, the ASP.NET Core development team has done everything possible to "sell" the new APIs to the developer community by publishing a series of informative articles about the new product, from high-level "commercial-like" approaches...

• Try the new System.Text.Json APIs

... to in-depth migration tutorials:

• How to migrate from Newtonsoft.Json to System.Text.Json

Honestly speaking, the System.Text.Json namespace ain't bad at all and undeniably has a lot of advantages, such as:

• it's a native, built-in package (which is never a bad thing, provided it works);
• it's getting a huge support from the ASP.NET development team (not limited to the "community push" which we've talked about early on);
• it's extremely fast, even more than its competitor in various performance tests (if you just need to do what it currently does);
• it has a strict and severe approach to data types (which is a good thing for a serializer, as long as it can be configured to allow a more flexible approach);

However, despite all that, in my honest opinion the Json.NET package still got the edge, mostly because it gained a gigantic amount of features through the course of its 15 years of lifetime; the experience gained through all these years also made the Newtonsoft's library more resilient, reliable and capable to better deal with some edge-case scenarios where the System.Text.Json still fails - such as this nasty circular reference looping issue that can likely occur when working with EF Core entities.

For all the above reasons, the first thing I do whenever I create a new ASP.NET Core project is replacing the default JSON serializer with it; in this post I'll briefly explain how to properly do that.

Introduction

For the sake of simplicity, in this tutorial we'll take as an example a typical .NET Core 3 MVC Web Application, but the same exact steps can be done for a .NET Core Web API or any other ASP.NET Core web-based project.

The first thing we need to do is to choose between two possible ways of implementing Json.NET package:

• As a drop-in replacement of System.Text.Json, meaning that it will become the default JSON serializer of our web application.
• As a separate package, meaning that we'll be able to selectively (and manually) use it whenever we need or want and have the System.Text.Json namespace to handle all the remaining JSON-related tasks.

In my honest opinion the drop-in approach is the suggested one, unless you need to keep System.Text.Json as the default serializer for some reasons; however, in this post we'll cover both approaches.

Installing Json.NET as the default JSON Serializer

The first thing we need to do is to install the following NuGet package using the Visual Studio's NuGet package manager console:

As we can see, instead of installing the standard Newtonsoft.Json NuGet package, we're installing a set of ASP.NET Core MVC features and extensions that will allow us to add the Newtonsoft.Json APIs within our web application's pipeline - more specifically, to the IMVCBuilder interface, which is responsible to configure MVC services for our app.

The next step depends on what we currently have in our project's Setup.cs file's ConfigureServices() method, which in turn depends on how we have set up our new (or existing) project. For example, if we've migrated our project from an existing one, we could have a call to the AddMvc() method, meaning that we can attach the Newtonsoft.Json package in the following way:

Conversely, if we're dealing a .NET Core 3+ project, we'll most likely have one of the following calls:

Meaning that we can attach the Newtonsoft.Json package in one of the following ways:

In all the above scenarios, adding the AddNewtonsoftJson() call to the end means that we're going to use the Newtonsoft.Json APIs over the default System.Text.Json implementation.

As long as our project's IMvcBuilder is being intialized including that call, every time we'll call the Json() method from our app's action methods the Newtonsoft.Json API will be used under the hood. Here's an example:

That's basically it.

Installing Json.NET as a separate package

Alternatively, we can just install the standard Newtonsoft.Json package with the following Visual Studio's NuGet package manager console command:

And then use the Json.NET resources whenever we want (or need) to in the following way:

It's worth noting that, if we implement Json.NET in the following way, all calls to the JSON-related methods provided by the Microsoft.AspNetCore.Mvc namespace - such as the Json() method we've used in the preceeding paragraph - will default to the System.Text.Json APIs: in other words, we won't be using Newtonsoft.Json package unless when we really want to.

Conclusion

That's it, at least for now: I hope that this small tutorial will help other ASP.NET developers to implement the Json.NET package to their ASP.NET Core project in a easy and effective way.

Print Friendly & PDF Download