How to use Newtonsoft in ASP.NET Core

By default, ASP.NET Core uses System.Text.Json for JSON serialization. If you want to use Newtonsoft instead:

• Add the Microsoft.AspNetCore.Mvc.NewtonsoftJson package.
• Call AddNewtonsoftJson() in the initialization code, like this:

var builder = WebApplication.CreateBuilder(args);

// rest of adding services

builder.Services.AddControllers().AddNewtonsoftJson();

var app = builder.Build();

//rest of init code
Code language: C# (cs)

Note: Before .NET 6, do this in Startup.ConfigureServices().

Install the right package

Microsoft packaged up Microsoft.AspNetCore.Mvc.NewtonsoftJson based on the framework version, so you can’t just install the latest package. You have to find the latest one for the framework version you’re using.

If you try to install the latest package, and you’re not on the framework version that it targets, then you’ll get an error:

Error NU1202 Package Microsoft.AspNetCore.Mvc.NewtonsoftJson 5.0.8 is not compatible with netcoreapp3.1

I’ve listed the latest packages (at the time of this writing) for each framework version below.

.NET Version	Install Package
.NET 7	Install-Package Microsoft.AspNetCore.Mvc.NewtonsoftJson -Version 7.0.4
.NET 6	Install-Package Microsoft.AspNetCore.Mvc.NewtonsoftJson -Version 6.0.15
.NET 5	Install-Package Microsoft.AspNetCore.Mvc.NewtonsoftJson -Version 5.0.17
.NET Core 3.1	Install-Package Microsoft.AspNetCore.Mvc.NewtonsoftJson -Version 3.1.32
.NET Core 3.0	Install-Package Microsoft.AspNetCore.Mvc.NewtonsoftJson -Version 3.0.3

Note: All of these are using the Package Manager Console (View > Other Windows > Package Manager Console).

Configuring Newtonsoft in ASP.NET Core

You can configure the JSON serialization options for Newtonsoft in AddNewtonsoftJson(), like this:

using Newtonsoft.Json.Converters;

//rest of adding services

builder.Services.AddControllers().AddNewtonsoftJson(jsonOptions =>
{
    jsonOptions.SerializerSettings.Converters.Add(new StringEnumConverter());
});

//rest of initialization code
Code language: C# (cs)

Note: Before .NET 6, do this in Startup.ConfigureServices().

These settings apply to all requests/responses in all controllers.

In this example, it’s adding the StringEnumConverter. This makes Newtonsoft serialize / deserialize enums names instead of values.

Override settings per response with JsonResult

Let’s say you want to override the Newtonsoft serialization settings for a specific response. To do that, return a JsonResult with a Newtonsoft JsonSerializerSettings object, like this:

using Newtonsoft.Json;
using System.Net;
using Newtonsoft.Json.Converters;

[HttpGet("{symbol}")]
public async Task<IActionResult> Get(string symbol)
{
	var stock = await GetStockFromRepo(symbol);

	var settings = new JsonSerializerSettings()
	{
		Converters =
		{
			new StringEnumConverter()
		}
	};

	return new JsonResult(stock, settings)
	{
		StatusCode = (int)HttpStatusCode.OK
	};
}
Code language: C# (cs)

When you return JsonResult with settings, the framework uses the configured serializer (Newtonsoft or System.Text.Json) to serialize the model object.