{"id":42762,"date":"2022-10-13T08:15:00","date_gmt":"2022-10-13T15:15:00","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/dotnet\/?p=42762"},"modified":"2022-10-31T10:47:39","modified_gmt":"2022-10-31T17:47:39","slug":"system-text-json-in-dotnet-7","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/dotnet\/system-text-json-in-dotnet-7\/","title":{"rendered":"What’s new in System.Text.Json in .NET 7"},"content":{"rendered":"

In .NET 7, our focus for System.Text.Json has been to substantially improve extensibility of the library, adding new performance-oriented features and addressing high impact reliability and consistency issues. More specifically, .NET 7 sees the release of contract customization<\/a>, which gives you more control over how types are serialized or deserialized, polymorphic serialization for user-defined type hierarchies<\/a>, required member support<\/a>, and much more.<\/p>\n

Getting the latest bits<\/h3>\n

You can try out the new features by using the latest build of System.Text.Json NuGet package<\/a> or the latest SDK for .NET 7<\/a>, which is currently RC.<\/p>\n

Contract Customization<\/a><\/h2>\n

System.Text.Json determines how a given .NET type is meant to be serialized and deserialized by constructing a JSON contract for that type. The contract is derived from the type’s shape — such as its available constructors, properties and fields, and whether it implements IEnumerable<\/code> or IDictionary<\/code> — either at runtime using reflection or at compile time using the source generator. In previous releases, users were able to make limited adjustments to the derived contract using System.Text.Json attribute annotations<\/a>, assuming they are able to modify the type declaration.<\/p>\n

The contract metadata for a given type T<\/code> is represented using JsonTypeInfo<T><\/code><\/a>, which in previous versions served as an opaque token used exclusively in source generator APIs. Starting in .NET 7, most facets of the JsonTypeInfo<\/code> contract metadata have been exposed and made user-modifiable. Contract customization allows users to write their own JSON contract resolution logic using implementations of the IJsonTypeInfoResolver<\/code><\/a> interface:<\/p>\n

public interface IJsonTypeInfoResolver\r\n{\r\n    JsonTypeInfo? GetTypeInfo(Type type, JsonSerializerOptions options);\r\n}<\/code><\/pre>\n
A contract resolver returns a configured JsonTypeInfo<\/code> instance for the given Type<\/code> and JsonSerializerOptions<\/code> combination. It can return null<\/code> if the resolver does not support metadata for the specified input type.<\/p>\n
Contract resolution performed by the default, reflection-based serializer is now exposed via the DefaultJsonTypeInfoResolver<\/a> class, which implements IJsonTypeInfoResolver<\/code>. This class lets users extend the default reflection-based resolution with custom modifications or combine it with other resolvers (such as source-generated resolvers).<\/p>\n
Starting from .NET 7 the JsonSerializerContext<\/a> class used in source generation also implements IJsonTypeInfoResolver<\/code>. To learn more about the source generator, see How to use source generation in System.Text.Json<\/a>.<\/p>\n
A JsonSerializerOptions<\/code> instance can be configured with a custom resolver using the new TypeInfoResolver<\/code><\/a> property:<\/p>\n
\/\/ configure to use reflection contracts\r\nvar reflectionOptions = new JsonSerializerOptions \r\n{ \r\n    TypeInfoResolver = new DefaultJsonTypeInfoResolver()\r\n};\r\n\r\n\/\/ configure to use source generated contracts\r\nvar sourceGenOptions = new JsonSerializerOptions \r\n{ \r\n    TypeInfoResolver = EntryContext.Default \r\n};\r\n\r\n[JsonSerializable(typeof(MyPoco))]\r\npublic partial class EntryContext : JsonSerializerContext { }<\/code><\/pre>\n
Modifying JSON contracts<\/h3>\n
The DefaultJsonTypeInfoResolver<\/code> class is designed with contract customization in mind and can be extended in a couple of ways:<\/p>\n
    \n
  1. Inheriting from the class, overriding the GetTypeInfo<\/code><\/a> method, or<\/li>\n
  2. Using the Modifiers<\/code><\/a> property to subscribe delegates that modify the default JsonTypeInfo<\/code> results.<\/li>\n<\/ol>\n
    Here’s how you could define a custom contract resolver that uses uppercase JSON properties, first using inheritance:<\/p>\n
    var options = new JsonSerializerOptions\r\n{\r\n    TypeInfoResolver = new UpperCasePropertyContractResolver()\r\n};\r\n\r\nJsonSerializer.Serialize(new { value = 42 }, options); \/\/ {\"VALUE\":42}\r\n\r\npublic class UpperCasePropertyContractResolver : DefaultJsonTypeInfoResolver\r\n{\r\n    public override JsonTypeInfo GetTypeInfo(Type type, JsonSerializerOptions options)\r\n    {\r\n        JsonTypeInfo typeInfo = base.GetTypeInfo(type, options);\r\n\r\n        if (typeInfo.Kind == JsonTypeInfoKind.Object)\r\n        {\r\n            foreach (JsonPropertyInfo property in typeInfo.Properties)\r\n            {\r\n                property.Name = property.Name.ToUpperInvariant();\r\n            }\r\n        }\r\n\r\n        return typeInfo;\r\n    }\r\n}<\/code><\/pre>\n
    and the same implementation using the Modifiers<\/code> property:<\/p>\n
    var options = new JsonSerializerOptions\r\n{\r\n    TypeInfoResolver = new DefaultJsonTypeInfoResolver\r\n    {\r\n        Modifiers = { UseUppercasePropertyNames }\r\n    }\r\n};\r\n\r\nJsonSerializer.Serialize(new { value = 42 }, options); \/\/ {\"VALUE\":42}\r\n\r\nstatic void UseUppercasePropertyNames(JsonTypeInfo jsonTypeInfo)\r\n{\r\n    if (typeInfo.Kind != JsonTypeInfoKind.Object)\r\n        return;\r\n\r\n    foreach (JsonPropertyInfo property in typeInfo.Properties)\r\n    {\r\n        property.Name = property.Name.ToUpperInvariant();\r\n    }\r\n}<\/code><\/pre>\n
    Each DefaultJsonTypeInfoResolver<\/code> can register multiple modifier delegates, which it runs sequentially on metadata resolved for each type:<\/p>\n
    var options = new JsonSerializerOptions\r\n{\r\n    TypeInfoResolver = new DefaultJsonTypeInfoResolver\r\n    {\r\n        Modifiers = { Modifier1, Modifier2, Modifier3 }\r\n    }\r\n};\r\n\r\nJsonTypeInfo typeInfo = options.GetTypeInfo(typeof(string)); \/\/ Prints messages in sequence\r\n\r\nstatic void Modifier1(JsonTypeInfo typeInfo) { Console.WriteLine(\"Runs first\"); }\r\nstatic void Modifier2(JsonTypeInfo typeInfo) { Console.WriteLine(\"Runs second\"); }\r\nstatic void Modifier3(JsonTypeInfo typeInfo) { Console.WriteLine(\"Runs third\"); }<\/code><\/pre>\n
    Modifier syntax affords a more concise and compositional API compared to inheritance. As such, subsequent examples will focus on that approach.<\/p>\n
    Notes on authoring contract modifiers<\/h4>\n
    The DefaultJsonTypeInfoResolver.Modifiers<\/code> property allows developers to specify a series of handlers to update the metadata contract for all types in the serialization type closure. Modifiers are consulted in the order that they were specified in the DefaultJsonTypeInfoResolver.Modifiers<\/code> list. This makes it possible for modifiers to make changes that conflict with each other, possibly resulting in unintended serialization contracts.<\/p>\n
    For example, consider how the UseUppercasePropertyNames<\/code> modifier above would interact with a modifier that filters out properties that are only used in a hypothetical “v0” version of a serialization schema:<\/p>\n
    JsonSerializerOptions options0 = new()\r\n{\r\n    TypeInfoResolver = new DefaultJsonTypeInfoResolver\r\n    { \r\n        Modifiers = { ExcludeV0Members, UseUppercasePropertyNames } \r\n    }\r\n};\r\n\r\nJsonSerializerOptions options1 = new()\r\n{\r\n    TypeInfoResolver = new DefaultJsonTypeInfoResolver \r\n    {\r\n        Modifiers = { UseUppercasePropertyNames, ExcludeV0Members }\r\n    }\r\n};\r\n\r\nEmployee employee = FetchEmployee();\r\nJsonSerializer.Serialize(employee, options0); \/\/ {\"NAME\":\"Jane Doe\",\"ROLE\":\"Contractor\"}\r\nJsonSerializer.Serialize(employee, options1); \/\/ {\"NAME\":\"Jane Doe\",\"ROLE\":\"Contractor\",\"ROLE_V0\":\"Temp\"}\r\n\r\nstatic void ExcludeV0Members(JsonTypeInfo jsonTypeInfo)\r\n{\r\n    if (typeInfo.Kind != JsonTypeInfoKind.Object)\r\n        return;\r\n\r\n    foreach (JsonPropertyInfo property in typeInfo.Properties)\r\n    {\r\n        if (property.Name.EndsWith(\"_v0\"))\r\n        {\r\n            property.ShouldSerialize = false;\r\n        }\r\n    }\r\n}\r\n\r\nclass Employee\r\n{\r\n    public string Name { get; set; }\r\n    public Role Role { get; set; }\r\n    public string Role_v0 => { get; set; }\r\n}<\/code><\/pre>\n
    Even though not always possible, it is a good idea to design modifiers with composability in mind. One way to do this is by ensuring that any modifications to the contract are append-only, rather than replacing or removing work done by previous modifiers. Consider the following example, where we define a modifier that appends a property with diagnostic information for every object. Such a modifier might want to confirm that a “Data” property does not already exist on a given type:<\/p>\n
    static void AddDiagnosticDataProperty(JsonTypeInfo typeInfo)\r\n{\r\n    if (typeInfo.Kind == JsonTypeInfoKind.Object && \r\n        typeInfo.Properties.All(prop => prop.Name != \"Data\"))\r\n    {\r\n        JsonPropertyInfo propertyInfo = typeInfo.CreateJsonPropertyInfo(string, \"Data\");\r\n        propertyInfo.Get = obj => GetDiagnosticData(obj);\r\n        typeInfo.Properties.Add(propertyInfo);\r\n    }\r\n}<\/code><\/pre>\n
    Example: Custom Attribute Support<\/h3>\n
    Contract customization makes it possible to add support for attributes that are not inbox to System.Text.Json<\/code>. Here is an example implementing support for DataContractSerializer<\/code>‘s IgnoreDataMemberAttribute<\/code><\/a>:<\/p>\n
    var options = new JsonSerializerOptions\r\n{\r\n    TypeInfoResolver = new DefaultJsonTypeInfoResolver\r\n    {\r\n        Modifiers = { DetectIgnoreDataMemberAttribute }\r\n    }\r\n};\r\n\r\nJsonSerializer.Serialize(new MyPoco(), options); \/\/ {\"Value\":3}\r\n\r\nstatic void DetectIgnoreDataMemberAttribute(JsonTypeInfo typeInfo)\r\n{\r\n    if (typeInfo.Kind != JsonTypeInfoKind.Object)\r\n        return;\r\n\r\n    foreach (JsonPropertyInfo propertyInfo in typeInfo.Properties)\r\n    {\r\n        if (propertyInfo.AttributeProvider is ICustomAttributeProvider provider &&\r\n            provider.IsDefined(typeof(IgnoreDataMemberAttribute), inherit: true))\r\n        {\r\n            \/\/ Disable both serialization and deserialization \r\n            \/\/ by unsetting getter and setter delegates\r\n            propertyInfo.Get = null;\r\n            propertyInfo.Set = null;\r\n        }\r\n    }\r\n}\r\n\r\npublic class MyPoco\r\n{\r\n    [JsonIgnore]\r\n    public int JsonIgnoreValue { get; } = 1;\r\n\r\n    [IgnoreDataMember]\r\n    public int IgnoreDataMemberValue { get; } = 2;\r\n\r\n    public int Value { get; } = 3;\r\n}<\/code><\/pre>\n
    Example: Conditional Serialization<\/h3>\n
    You can use the JsonPropertyInfo.ShouldSerialize<\/code><\/a> delegate to determine dynamically whether a given property value should be serialized:<\/p>\n
    var options = new JsonSerializerOptions\r\n{\r\n    TypeInfoResolver = new DefaultJsonTypeInfoResolver\r\n    {\r\n        Modifiers = { IgnoreNegativeValues }\r\n    }\r\n};\r\n\r\nJsonSerializer.Serialize(new MyPoco { IgnoreNegativeValues = false, Value = -1 }, options); \/\/ {\"Value\":-1}\r\nJsonSerializer.Serialize(new MyPoco { IgnoreNegativeValues = true, Value = -1 }, options); \/\/ {}\r\n\r\nstatic void IgnoreNegativeValues(JsonTypeInfo typeInfo)\r\n{\r\n    if (typeInfo.Type != typeof(MyPoco))\r\n        return;\r\n\r\n    foreach (JsonPropertyInfo propertyInfo in typeInfo.Properties)\r\n    {\r\n        if (propertyInfo.PropertyType == typeof(int))\r\n        {\r\n            propertyInfo.ShouldSerialize = static (obj, value) => \r\n                (int)value! >= 0 || !((MyPoco)obj).IgnoreNegativeValues;\r\n        }\r\n    }\r\n}\r\n\r\npublic class MyPoco\r\n{\r\n    [JsonIgnore]\r\n    public bool IgnoreNegativeValues { get; set; }\r\n\r\n    public int Value { get; set; }\r\n}<\/code><\/pre>\n
    Example: Serializing private fields<\/h3>\n
    System.Text.Json does not support private field serialization, as doing that is generally not recommended. However, if really necessary it’s possible to write a contract resolver that only serializes the fields of a given type:<\/p>\n
    var options = new JsonSerializerOptions\r\n{\r\n    TypeInfoResolver = new DefaultJsonTypeInfoResolver\r\n    {\r\n        Modifiers = { SerializeObjectFields }\r\n    }\r\n};\r\n\r\nJsonSerializer.Serialize(new { value = 42 }, options); \/\/ {\"\\u003Cvalue\\u003Ei__Field\":42}\r\n\r\nstatic void SerializeObjectFields(JsonTypeInfo typeInfo)\r\n{\r\n    if (typeInfo.Kind != JsonTypeInfoKind.Object)\r\n        return;\r\n\r\n    \/\/ Remove any properties included by the default resolver\r\n    typeInfo.Properties.Clear();\r\n\r\n    const BindingFlags Flags = BindingFlags.Public | BindingFlags.NonPublic | BindingFlags.Instance;\r\n    foreach (FieldInfo fieldInfo in typeInfo.Type.GetFields(Flags))\r\n    {\r\n        JsonPropertyInfo propertyInfo = typeInfo.CreateJsonPropertyInfo(fieldInfo.FieldType, fieldInfo.Name);\r\n        propertyInfo.Get = obj => fieldInfo.GetValue(obj);\r\n        propertyInfo.Set = (obj, value) => fieldInfo.SetValue(obj, value);\r\n\r\n        typeInfo.Properties.Add(propertyInfo);\r\n    }\r\n}<\/code><\/pre>\n
    Although as the serialized output would suggest, serializing private fields can be very brittle and error prone. This example has been shared for illustrative purposes only and is not recommended for most real-word applications.<\/p>\n
    Combining resolvers<\/h3>\n
    It is possible to combine contracts from multiple sources using the JsonTypeInfoResolver.Combine<\/code><\/a> method. This is commonly applicable to source generated JsonSerializerContext<\/code> instances that can only generate contracts for a restricted subset of types:<\/p>\n
    var options = new JsonSerializerOptions\r\n{\r\n    TypeInfoResolver = JsonTypeInfoResolver.Combine(ContextA.Default, ContextB.Default)\r\n};\r\n\r\n\/\/ Successfully handles serialization for both types\r\nJsonSerializer.Serialize(new PocoA(), options);\r\nJsonSerializer.Serialize(new PocoB(), options);\r\n\r\n\/\/ Types from Library A\r\n[JsonSerializable(typeof(PocoA))]\r\npublic partial class ContextA : JsonSerializerContext { }\r\npublic class PocoA { }\r\n\r\n\/\/ Types from Library B\r\n[JsonSerializable(typeof(PocoB))]\r\npublic partial class ContextB : JsonSerializerContext { }\r\npublic class PocoB { }<\/code><\/pre>\n
    The Combine<\/code> method produces a contract resolver that sequentially queries each of its constituent resolvers in order of definition, returning the first result that is not null<\/code>. The method supports chaining arbitrarily many resolvers, including DefaultJsonTypeInfoResolver<\/code>:<\/p>\n
    var options = new JsonSerializerOptions\r\n{\r\n    TypeInfoResolver = JsonTypeInfoResolver.Combine(\r\n        ContextA.Default, \r\n        ContextB.Default, \r\n        new DefaultJsonTypeInfoResolver())\r\n};\r\n\r\n\/\/ Uses reflection for the outer class, source gen for the property types\r\nJsonSerializer.Serialize(new { A = new PocoA(), B = new PocoB() } , options);<\/code><\/pre>\n
    Metadata Kinds<\/h3>\n
    JsonTypeInfo<\/code> metadata should be thought of as configuration objects for System.Text.Json’s built-in converters. As such, what metadata is configurable on each type is largely dependent on the underlying converter being used for the type: types using the built-in converter for objects can configure property metadata, whereas types using custom user-defined converters cannot be configured at all. What can be configured is determined by the value of the JsonTypeInfo.Kind<\/code><\/a> property. There are currently four kinds of metadata available to the user:<\/p>\n