The transition to .NET Core 3.0 brought significant architectural shifts, particularly in how web applications handle JSON serialization. Many developers, accustomed to earlier versions, found themselves asking: Where did IMvcBuilder AddJsonOptions go in .Net Core 3.0? This question highlights a fundamental change in the default JSON serializer, moving from the long-standing Newtonsoft.Json to Microsoft’s new, built-in System.Text.Json. This change was implemented to enhance performance, improve security, and provide a more native, integrated serialization experience within the .NET ecosystem. Understanding this evolution is crucial for modern .NET development, ensuring your applications remain efficient and compliant with the latest framework best practices. This article will guide you through the reasons behind this shift and how to correctly configure JSON serialization in .NET Core 3.0 and subsequent versions.
The Shift from Newtonsoft.Json to System.Text.Json
In .NET Core 3.0, Microsoft made a strategic decision to replace Newtonsoft.Json as the default JSON serializer for ASP.NET Core applications with a new, in-house solution: System.Text.Json. This move was primarily driven by performance considerations, aiming for a more optimized and memory-efficient serialization process. Microsoft’s internal benchmarks showed significant improvements in throughput and reduced memory allocation with System.Text.Json, making it a compelling choice for high-performance web APIs.
While Newtonsoft.Json has been a robust and feature-rich library, its extensive features sometimes came with a performance overhead. System.Text.Json, on the other hand, was designed from the ground up to be lean, fast, and secure, leveraging modern .NET features like Span
To clarify the core change: in .NET Core 3.0 and later, the default JSON serializer for ASP.NET Core MVC is System.Text.Json, not Newtonsoft.Json. Consequently, the IMvcBuilder.AddJsonOptions method, which was previously used to configure Newtonsoft.Json settings, was removed because it no longer applied to the new default serializer. Configuration for System.Text.Json is now handled directly through the MVC service registration options.
This transition impacts how you configure serialization behavior, such as property naming policies (e.g., camelCase vs. PascalCase), handling of null values, and custom converters. While System.Text.Json offers a robust set of features, some advanced or legacy scenarios might still require the flexibility of Newtonsoft.Json. Thankfully, .NET Core provides a straightforward way to re-integrate Newtonsoft.Json if necessary, though it’s recommended to embrace System.Text.Json for new development due to its performance benefits and native integration.
Locating JSON Options in .NET Core 3.0 and Beyond
With the removal of IMvcBuilder.AddJsonOptions, developers might initially feel lost when trying to customize JSON serialization behavior. The key is to understand that the configuration for System.Text.Json is now integrated directly into the MVC service registration methods, specifically within AddControllers, AddControllersWithViews, or AddRazorPages in your Startup.cs file’s ConfigureServices method. This streamlined approach allows you to define serialization rules as part of your overall MVC setup.
To configure System.Text.Json options, you’ll typically chain a call to AddJsonOptions onto your MVC service registration. This method, while sharing a similar name, now operates on JsonOptions (which wrap JsonSerializerOptions from System.Text.Json) rather than MvcJsonOptions from the Newtonsoft.Json era. This allows for direct manipulation of the new serializer’s behavior, ensuring consistency across your application’s API responses.
Configuring System.Text.Json for MVC
Configuring System.Text.Json involves passing a lambda expression to the AddJsonOptions method. Inside this lambda, you can access and modify the JsonSerializerOptions, which provide a rich set of properties to control serialization and deserialization. A common task is setting the property naming policy to camel case, which is standard for web APIs. Here’s a typical example:
public void ConfigureServices(IServiceCollection services) { services.AddControllers() .AddJsonOptions(options => { options.JsonSerializerOptions.PropertyNamingPolicy = JsonNamingPolicy.CamelCase; options.JsonSerializerOptions.WriteIndented = true; // For development/debugging options.JsonSerializerOptions.DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull; // Add custom converters if needed // options.JsonSerializerOptions.Converters.Add(new DateTimeConverter()); }); // You can also use AddControllersWithViews or AddRazorPages // services.AddControllersWithViews() // .AddJsonOptions(options => { / ... / }); }
This approach gives you fine-grained control over how your API payloads are structured. For instance, setting PropertyNamingPolicy = JsonNamingPolicy.CamelCase ensures that your C properties like FirstName are serialized as firstName in the JSON output, aligning with common JavaScript conventions. According to Microsoft’s documentation on how to customize JSON properties in System.Text.Json, this policy is crucial for interoperability.
Reverting to Newtonsoft.Json (If Necessary)
While System.Text.Json is the recommended default, there are legitimate reasons why you might need to continue using Newtonsoft.Json. These include:
- Existing codebase heavily reliant on specific
Newtonsoft.Jsonfeatures not yet available inSystem.Text.Json. - Complex custom converters or contract resolvers that would be difficult to port.
- Interoperability with third-party libraries that explicitly expect
Newtonsoft.Jsonbehavior.
To revert to using Newtonsoft.Json, you first need to install the Microsoft.AspNetCore.Mvc.NewtonsoftJson NuGet package. Once installed, you can enable it by calling AddNewtonsoftJson as an extension method on your IMvcBuilder:
public void ConfigureServices(IServiceCollection services) { services.AddControllers() .AddNewtonsoftJson(options => { // Configure Newtonsoft.Json settings here options.SerializerSettings.ReferenceLoopHandling =
<b>Question & Answer : </b><br></br><p>I've just upgraded my ASP web API project from .NET Core 2.0 to 3.0. I was using</p> services.AddMvc() .AddJsonOptions(opts => opts.SerializerSettings.ContractResolver = new DefaultContractResolver()); <p>previously to ensure lower-casing of the serialized JSON.</p> <p>After the upgrade to 3.0 I get this error:</p> <blockquote> <p>Error CS1061 'IMvcBuilder' does not contain a definition for 'AddJsonOptions' and no accessible extension method 'AddJsonOptions' accepting a first argument of type 'IMvcBuilder' could be found (are you missing a using directive or an assembly reference?)</p> </blockquote> <p>According to <a href="https://stackoverflow.com/questions/54051802/addjsonoptions-for-mvcjsonoptions-in-asp-net-core-2-2">AddJsonOptions for MvcJsonOptions in Asp.Net Core 2.2</a> the AddJsonOptions extension method is/was provided by the <strong>Microsoft.AspNetCore.Mvc.Formatters.Json</strong> nuget package. I have tried installing/reinstalling this but still can't resolve the method. Interestingly, intellisense only shows Microsoft.AspNetCore.Mvc.Formatters.<em>Xml</em> when I try to add the using statement even though I added the <em>Json</em> nuget package.</p> <p>Any ideas what is going on? The <a href="https://learn.microsoft.com/en-us/dotnet/api/microsoft.extensions.dependencyinjection.mvcjsonmvcbuilderextensions.addjsonoptions?view=aspnetcore-2.2&viewFallbackFrom=aspnetcore-3.0" rel="noreferrer">documentation</a> for <em>AddJsonOptions</em> only goes up to .NET 2.2 so perhaps the method has been deprecated in 3.0 in favor of some other configuration mechanism?</p>
<br></br><p>As part of ASP.NET Core 3.0, the team moved away from including Json.NET by default. You can read more about that in general in the <a href="https://github.com/aspnet/Announcements/issues/325" rel="noreferrer">announcement on breaking changes to Microsoft.AspNetCore.App</a>.</p> <p>Instead of Json.NET, ASP.NET Core 3.0 and .NET Core 3.0 include a different JSON API that focuses a bit more on performance. You can learn about that more in the <a href="https://github.com/dotnet/announcements/issues/90" rel="noreferrer">announcement about “The future of JSON in .NET Core 3.0”</a>.</p> <p>The new templates for ASP.NET Core will no longer bundle with Json.NET but you can easily reconfigure the project to use it instead of the new JSON library. This is important for both compatibility with older projects and also because the new library is not supposed to be a full replacement, so you won't see the full feature set there.</p> <p>In order to reconfigure your ASP.NET Core 3.0 project with Json.NET, you will need to add a NuGet reference to Microsoft.AspNetCore.Mvc.NewtonsoftJson, which is the package that includes all the necessary bits. Then, in the Startup’s ConfigureServices, you will need to configure MVC like this:</p> services.AddControllers() .AddNewtonsoftJson(); <p>This sets up MVC controllers and configures it to use Json.NET instead of that new API. Instead of controllers, you can also use a different MVC overload (e.g. for controllers with views, or Razor pages). That AddNewtonsoftJson method has an overload that allows you to configure the Json.NET options like you were used to with AddJsonOptions in ASP.NET Core 2.x.</p> services.AddControllers() .AddNewtonsoftJson(options => { options.SerializerSettings.ContractResolver = new DefaultContractResolver(); });
