How to use Newtonsoft in ASP.NET Core

By default, ASP.NET Core uses System.Text.Json for JSON serialization. To use Newtonsoft.Json in ASP.NET Core, you first need to install the Microsoft.AspNetCore.Mvc.NewtonsoftJson package.

Enable Newtonsoft JSON in Your Application

In your Program.cs (or Startup.cs before .NET 6), add the following code to configure your application to use Newtonsoft.Json for JSON serialization:

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.

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

var app = builder.Build();

// Configure the HTTP request pipeline.

In versions before .NET 6, you would add this configuration inside Startup.ConfigureServices().

Install the Correct Package for Your Framework Version

Microsoft provides the Microsoft.AspNetCore.Mvc.NewtonsoftJson package in different versions, each targeting a specific version of .NET. To avoid compatibility issues, make sure to install the package that matches your framework version. For instance, attempting to install the latest version on an unsupported framework version will result in an error:

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

These commands are to be run in the Package Manager Console (found under View > Other Windows > Package Manager Console).

Configuring Newtonsoft JSON in ASP.NET Core

You can configure the JSON serialization options for Newtonsoft.Json using the AddNewtonsoftJson() method.

For example, to add a StringEnumConverter (which serializes enum names rather than values), you can configure it like this:

using Newtonsoft.Json.Converters;

// Add services to the container.

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

In versions before .NET 6, add this configuration inside Startup.ConfigureServices().

These settings will apply globally to all requests and responses across all controllers.

Override Serialization Settings for Specific Responses

If you want to apply custom Newtonsoft.Json settings for a specific response, you can use JsonResult along with a JsonSerializerSettings object.

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
    };
}

When you return a JsonResult with custom settings, the framework will use the specified serializer (either Newtonsoft.Json or System.Text.Json) to serialize the response object.