Transitioning to System.Text.Json from Newtonsoft.Json

Transitioning to System.Text.Json from Newtonsoft.Json in .NET

We are migrating to System.Text.Json from Newtonsoft.Json, as it is the recommended and more performant library in .NET.

Please note that the transition occured in 8.0.1 version.

Compatibility and Workarounds

There exist several compatibility issues between Newtonsoft and System.Text.Json. Check the following link for detailed insights: Migrate from Newtonsoft to System.Text.Json.

To ensure compatibility, we've implemented various workarounds such as using custom converters, specific serializer settings, etc. In versions before .NET 8, handling missing members by raising an exception was not feasible.

Update Requirements for Users

After the transition, users must add attributes specific to System.Text.Json to properties and classes that previously had Newtonsoft-specific attributes. For instance:

Replace Newtonsoft.Json.JsonProperty with System.Text.Json.Serialization.JsonPropertyName.
Modify converters and usage of attributes like JsonIgnore, among others.

An example includes the UserListRequest DataProtector property, which previously had a JsonIgnore attribute specific to Newtonsoft.

You may choose to keep Newtonsoft specific attributes while adding their System.Text.Json counterparts to keep compatibility and still use Newtonsoft.Json in some parts of your application.

Transition Guidelines

The converter classes unique to System.Text.Json reside in the Serenity.JsonConverters namespace and end with JsonConverter. For example:

The former converter specific to Newtonsoft.Json for rows was JsonRowConverter.
The new one for System.Text.Json is Serenity.JsonConverters.RowJsonConverter.

When using [JsonConverter(typeof(...))] attribute, users should exercise caution to specify the correct type, as the attribute name remains the same for both libraries.

To transition, users need to:

Remove the .AddNewtonsoftJson block in Startup.cs.
Replace it with the following line to configure serialization settings similar to the previous Serenity Newtonsoft.Json-based settings:
```
services.Configure<JsonOptions>(options => JSON.Defaults.Populate(options.JsonSerializerOptions));
```

Additionally, remove this package reference from the project file:

<PackageReference Include="Microsoft.AspNetCore.Mvc.NewtonsoftJson" Version="8.0.0" />

Behavior Changes

Unlike Newtonsoft.Json, IncludeNulls is replaced with WriteNulls as we will only ignore nulls during serialization. The parameter names are also changed to writeNulls to align with this behavior.

System.Text.Json will be used for JSON.Stringify methods, and there won't be any means to use Newtonsoft other than manually calling Newtonsoft.Json.JsonConvert, etc.

Retaining Newtonsoft.Json Reference

We have not yet removed the Newtonsoft.Json reference as it is necessary for referencing serialization attributes, ensuring compatibility. While we may consider its removal in the future, it won't happen immediately.

serenity-is / Serenity