Common Newtonsoft.Json options in System.Text.Json

If you’re switching from Newtonsoft.Json to System.Text.Json (or vice versa), you may be wondering how to specify the common options you’re used to using in Newtonsoft. For example, how do you specify the equivalent of Newtonsoft.Json.Converters.StringEnumConverter in System.Text.Json?

The following table shows a few common serialization options used in Newtonsoft.Json and their equivalents in System.Text.Json.

Show enum name instead of numberNewtonsoft.Json.Converters.StringEnumConverterSystem.Text.Json.Serialization.JsonStringEnumConverter
IndentFormatting = Formatting.IndentedWriteIndented = true
Ignore nullsNullValueHandling = NullValueHandling.IgnoreIgnoreNullValues = true

The way you specify options in these two serializers is quite similar. In both, you can pass in converters – such as the StringEnumConverter. Newtonsoft tends to use enums for options, whereas System.Text.Json tends to use bools.

The example below demonstrates how to serialize an object to JSON, using both Newtonsoft and System.Text.Json, with all of the common options mentioned above. They produce the exact same JSON string, as expected.

Example – Serializing with the common options

I have the following object that I want to serialize:

var team = new NFLTeam()
	City = "Detroit",
	Name = "Lions",
	Conference = Conference.NFC,
	Division = Division.North,
	Notes = null
Code language: C# (cs)

When serializing this to JSON, I want to show the enum names instead of their numeric values, ignore null values, and indent the output. Here’s a side-by-side comparison of to serialize this object with these options in both Newtonsoft and System.Text.Json:

Here’s a side-by-side comparison showing how you’d serialize this object with Newtonsoft and System.Text.Json:

Serializing with Newtonsoft:

using Newtonsoft.Json;
using Newtonsoft.Json.Converters;

var json = JsonConvert.SerializeObject(team, 
	new JsonSerializerSettings()
	NullValueHandling = NullValueHandling.Ignore,
	Formatting = Formatting.Indented,
	Converters = { new StringEnumConverter() }
Code language: C# (cs)

Serializing with System.Text.Json:

using System.Text.Json;
using System.Text.Json.Serialization;

var options = new JsonSerializerOptions()
	WriteIndented = true,
	IgnoreNullValues = true,
options.Converters.Add(new JsonStringEnumConverter());
var json = JsonSerializer.Serialize<NFLTeam>(team, options);
Code language: C# (cs)

Both of these produce exactly the same JSON string (as expected):

  "City": "Detroit",
  "Name": "Lions",
  "Conference": "NFC",
  "Division": "North"
Code language: JSON / JSON with Comments (json)

Using both serializers

Newtonsoft has been (or maybe “was” is the right word) the de facto JSON serializer in .NET for many years, whereas System.Text.Json is relatively new. While they’re still actively developing System.Text.Json, you may run into scenarios where you’ll want to use Newtonsoft to get what you want (such as for deserializing JSON to a dynamic object or populating an existing object from JSON). You can definitely use both Newtonsoft and System.Text.Json at the same time. When you do that, I highly suggest using fully qualified names for things (especially the [JsonIgnore] attribute!), otherwise you may run into strange problems.

Leave a Comment