Overview [ Documentation]

JSON serialization/deserialization behavior can be controlled through JsonSerializerOptions and various attributes.

Serialization Behavior

By default:

• Public properties are serialized
• Fields are ignored
• Casing of JSON names matches the .NET names

Deserialization Behavior

By default:

• Property name matching is case sensitive
• Read-only properties are ignored (no value is deserialized into readonly properties)
• Fields are ignored
• Non-public constructors are ignored
• Enums are supported as numbers

JsonSerializerOptions Web Defaults

The defaults in ASP.NET Core apps are different than .NET apps. See: https://learn.microsoft.com/en-us/dotnet/standard/serialization/system-text-json/configure-options#web-defaults-for-jsonserializeroptions

Guidance for Using JsonSerializerOptions

1. Caution: Do not create a new instance of JsonSerializerOptions each time you use it.
2. If you need a JsonSerializerOptions instance that has all default options, use the JsonSerializerOptions.Default property.

• Documentation: https://learn.microsoft.com/en-us/dotnet/standard/serialization/system-text-json/configure-options?pivots=dotnet-7-0

Overriding Default Behavior

Properties

Fields

Marking Properties or Fields Required for JSON Deserialization

There are three approaches:

1. Via the required modifier Availability: C# 11

   using System.Text.Json;
   
   // The following line throws a JsonException at run time.
   Console.WriteLine(JsonSerializer.Deserialize<Person>("""{"Age": 42}"""));
   
   public class Person
   {
       public required string Name { get; set; }
       public int Age { get; set; }
   }
   

2. Via the [JsonRequiredAttribute]: Availability: .NET 7

   using System.Text.Json;
   
   // The following line throws a JsonException at run time.
   Console.WriteLine(JsonSerializer.Deserialize<Person>("""{"Age": 42}"""));
   
   public class Person
   {
       [JsonRequired]
       public string Name { get; set; }
       public int Age { get; set; }
   }
   

3. Via the JsonPropertyInfo.IsRequired property of the contract model: Availability: .NET 7

   var options = new JsonSerializerOptions
   {
       TypeInfoResolver = new DefaultJsonTypeInfoResolver
       {
           Modifiers =
           {
               static typeInfo =>
               {
                   if (typeInfo.Kind != JsonTypeInfoKind.Object)
                       return;
   
                   foreach (JsonPropertyInfo propertyInfo in typeInfo.Properties)
                   {
                       // Strip IsRequired constraint from every property.
                       propertyInfo.IsRequired = false;
                   }
               }
           }
       }
   };
   
   // Deserialization now succeeds even though the Name property isn't in the JSON payload.
   JsonSerializer.Deserialize<Person>("""{"Age": 42}""", options);
   

Overriding Other Behavior

Others