{"id":47732,"date":"2023-09-19T08:15:00","date_gmt":"2023-09-19T15:15:00","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/dotnet\/?p=47732"},"modified":"2023-09-26T13:27:07","modified_gmt":"2023-09-26T20:27:07","slug":"system-text-json-in-dotnet-8","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/dotnet\/system-text-json-in-dotnet-8\/","title":{"rendered":"What’s new in System.Text.Json in .NET 8"},"content":{"rendered":"

There are a lot of exciting updates for developers in System.Text.Json in .NET 8. In this release, we have substantially improved the user experience when using the library in Native AOT applications, as well as delivering a number of highly requested features and reliability enhancements. These include support for populating read-only members<\/a>, customizable unmapped member handling<\/a>, support for interface hierarchies<\/a>, snake case and kebab case naming policies<\/a> and much more.<\/p>\n

Getting the latest bits<\/h3>\n

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

Source generator improvements<\/h2>\n

This release marks an important milestone in our investment to ensure compatibility with .NET libraries being used in Native AOT applications. System.Text.Json has evolved over the years to use reflection and runtime code generation for serialization and then in .NET 6 the option to use source generators that are compiled into your application. There have always been trade offs between these two options and in this release we have shortened the functional gap between these two options to ensure that ASP.NET Core and other apps have first-class support for source-generated JSON serialization.<\/p>\n

required<\/code> and init<\/code> member support<\/h3>\n

Required members<\/a> and init-only properties<\/a> are relatively recent C# language features that control how fields or properties are meant to be initialized. Even though these have been well-supported by the reflection serializer (the modifiers are compile-time guards that can be bypassed by reflection), this has not been the case with the source generator where referencing required<\/code> or init<\/code> members could result in generated code with compiler errors.<\/p>\n

Starting in .NET 8, full support for required<\/code> and init<\/code> members has been added:<\/p>\n

JsonSerializer.Deserialize(\"\"\"{\"Real\" : 0, \"Im\" : 1 }\"\"\", MyContext.Default.Complex);\n\npublic record Complex\n{\n    public required double Real { get; init; }\n    public required double Im { get; init; }\n}\n\n[JsonSerializable(typeof(Complex))]\npublic partial class MyContext : JsonSerializerContext { }<\/code><\/pre>\n
Combining source generators<\/h3>\n
The contract customization<\/a> feature introduced in .NET 7 added support for chaining source generators by means of the JsonTypeInfoResolver.Combine<\/code> method. This makes it possible to combine contracts from multiple source generated contexts inside a single JsonSerializerOptions<\/code> instance:<\/p>\n
var options = new JsonSerializerOptions\n{\n    TypeInfoResolver = JsonTypeInfoResolver.Combine(ContextA.Default, ContextB.Default, ContextC.Default);\n};<\/code><\/pre>\n
Based on feedback we\u2019ve received, this approach has a couple of usability issues:<\/p>\n
    \n
  1. It necessitates specifying all chained components at one call site \u2014 resolvers cannot be prepended or appended to the chain after the fact.<\/li>\n
  2. Because the chaining implementation is abstracted behind a IJsonTypeInfoResolver<\/code> implementation, there is no way for users to introspect the chain or remove components from it.<\/li>\n<\/ol>\n
    The JsonSerializerOptions<\/code> class now includes a TypeInfoResolverChain<\/code> property that is complementary to TypeInfoResolver<\/code>:<\/p>\n
    namespace System.Text.Json;\n\npublic partial class JsonSerializerOptions\n{\n    public IJsonTypeInfoResolver? TypeInfoResolver { get; set; }\n    public IList<IJsonTypeInfoResolver> TypeInfoResolverChain { get; }\n}<\/code><\/pre>\n
    This lets users both introspect and modify the chain of resolvers, as can be seen in the following ASP.NET Core configuration snippet:<\/p>\n
    WebApplicationBuilder builder = WebApplication.CreateSlimBuilder(args);\n\nbuilder.Services.ConfigureHttpJsonOptions(options =>\n{\n    \/\/ Prepend my source generated context so that it takes precedence over other registered contexts\n    options.SerializerOptions.TypeInfoResolverChain.Insert(0, MyContext.Default);\n});<\/code><\/pre>\n
    Unspeakable type support<\/h3>\n
    Compiler-generated or \u201cunspeakable\u201d types have been challenging to support in weakly typed source gen scenarios. In .NET 7, the following application will fail:<\/p>\n
    object value = Test();\nStream stdout = Console.OpenStandardOutput();\nawait JsonSerializer.SerializeAsync(stdout, value, MyContext.Default.Options);\n\nasync IAsyncEnumerable<int> Test()\n{\n    for (int i = 0; i < 5; i++)\n    {\n        await Task.Delay(500);\n        yield return i;\n    }\n}\n\n[JsonSerializable(typeof(IAsyncEnumerable<int>))]\npublic partial class MyContext : JsonSerializerContext { }<\/code><\/pre>\n
    producing the error message<\/p>\n
    Metadata for type 'Program+<<<Main>$>g__Test|0_5>d' was not provided by TypeInfoResolver of type 'MyContext'<\/code><\/pre>\n
    This happens because the compiler-generated type Program+<<<Main>$>g__Test|0_5>d<\/code> cannot be explicitly specified by the source generator.<\/p>\n
    Starting with .NET 8, System.Text.Json will perform run-time nearest-ancestor resolution to determine the most appropriate supertype with which to serialize the value (in this case, IAsyncEnumerable<int><\/code>), making the above snippet output a JSON array as expected:<\/p>\n
    [0,1,2,3,4]<\/code><\/pre>\n
    JsonStringEnumConverter<TEnum><\/code><\/h3>\n
    The JsonStringEnumConverter<\/code> class<\/a> is the API of choice for users looking to serialize enum types as string values. The type however requires run-time code generation and as such cannot be used in Native AOT applications.<\/p>\n
    The new release of System.Text.Json includes the generic JsonStringEnumConverter<TEnum><\/code> class which does not require run-time code generation. Users wishing to target Native AOT should annotate their enums as follows:<\/p>\n
    [JsonConverter(typeof(JsonStringEnumConverter<MyEnum>))]\npublic enum MyEnum { Value1, Value2, Value3 }\n\n[JsonSerializable(typeof(MyEnum))]\npublic partial class MyContext : JsonSerializerContext { }<\/code><\/pre>\n
    The source generator will emit diagnostic SYSLIB1034<\/a> if it does encounter the unsupported JsonStringEnumConverter<\/code> in the type graph, prompting users to replace it with the new generic type.<\/p>\n
    String enum conversion can also be applied as a blanket policy in the source generator using the JsonSourceGenerationOptions<\/code> attribute; the following is equivalent to the previous code:<\/p>\n
    public enum MyEnum { Value1, Value2, Value3 }\n\n[JsonSourceGenerationOptions(UseStringEnumConverter = true)]\n[JsonSerializable(typeof(MyEnum))]\npublic partial class MyContext : JsonSerializerContext { }<\/code><\/pre>\n
    Extended JsonSourceGenerationOptionsAttribute<\/code> functionality<\/h3>\n
    The JsonSourceGenerationOptions<\/code> attribute<\/a> lets users specify compile-time configuration for a small subset of settings available in the JsonSerializerOptions<\/code> class. Users looking to configure the source generator using settings beyond what was available on the attribute needed to manually create a JsonSerializerContext<\/code> instance:<\/p>\n
    var options = new JsonSerializerOptions(JsonSerializerDefaults.Web)\n{\n    AllowTrailingCommas = true,\n    DefaultBufferSize = 10\n};\n\nvar context = new MyContext(options);\n\npublic record MyPoco(int Id, string Title);\n\n[JsonSerializable(typeof(MyPoco))]\npublic partial class MyContext : JsonSerializerContext { }<\/code><\/pre>\n
    The attribute has now been augmented with most settings available in JsonSerializerOptions<\/code>, so the above can now be rendered as follows:<\/p>\n
    MyContext context = MyContext.Default;\n\npublic record MyPoco(int Id, string Title);\n\n[JsonSourceGenerationOptions(\n    JsonSerializerDefaults.Web, \n    AllowTrailingCommas = true, \n    DefaultBufferSize = 10)]\n[JsonSerializable(typeof(MyPoco))]\npublic partial class MyContext : JsonSerializerContext {}<\/code><\/pre>\n
    Disabling reflection defaults<\/h3>\n
    By default, System.Text.Json will use reflection when serializing. Running something as simple as<\/p>\n
    JsonSerializer.Serialize(42);<\/code><\/pre>\n
    either in your code or in a third-party dependency can break your Native AOT application since it requires unsupported reflection under the hood. This can be challenging to diagnose since you’re most likely debugging your application in CoreCLR where the above works just fine.<\/p>\n
    It is now possible to disable default reflection in applications using the System.Text.Json.JsonSerializer.IsReflectionEnabledByDefault<\/code> feature switch. This can be turned off using the JsonSerializerIsReflectionEnabledByDefault<\/code> MSBuild property in your project configuration:<\/p>\n
    <JsonSerializerIsReflectionEnabledByDefault>false<\/JsonSerializerIsReflectionEnabledByDefault><\/code><\/pre>\n
    which makes the previous snippet fail with the following error:<\/p>\n
    System.InvalidOperationException: Reflection-based serialization has been disabled for this application. Either use the source generator APIs or explicitly configure the 'JsonSerializerOptions.TypeInfoResolver' property.<\/code><\/pre>\n
    It should be noted that this behavior is consistent regardless of runtime (i.e. both CoreCLR and Native AOT). If left unspecified, the feature switch will be turned off automatically in projects that enable the PublishTrimmed<\/code> property.<\/p>\n
    The run-time value of the feature switch is reflected by the JsonSerializer.IsReflectionEnabledByDefault<\/code> property. Library authors can consult that value when configuring their serializers:<\/p>\n
    static JsonSerializerOptions CreateDefaultOptions()\n{\n    return new()\n    {\n        TypeInfoResolver = JsonSerializer.IsReflectionEnabledByDefault\n            ? new DefaultJsonTypeInfoResolver()\n            : MyContext.Default\n    };\n}<\/code><\/pre>\n
    Because the property is treated as a link-time constant, the above method will avoid rooting the reflection-based resolver in applications that do run in Native AOT.<\/p>\n
    Size reduction<\/h3>\n
    We made a number of internal changes that contribute to size reduction of trimmed applications that use System.Text.Json. Consider the following minimal application:<\/p>\n
    Todo value = new(1, \"Walk the dog\");\nstring json = JsonSerializer.Serialize(value, MyContext.Default.Todo);\nJsonSerializer.Deserialize(json, MyContext.Default.Todo);\n\npublic record Todo(int Id, string Title);\n\n[JsonSerializable(typeof(Todo))]\npublic partial class MyContext : JsonSerializerContext { }<\/code><\/pre>\n
    Publishing as a self-contained Native AOT application in .NET 7 on Windows gives a 3.4 MB binary. On .NET 8 the same application is 2.6 MB, a 23% reduction.<\/p>\n
    We’re seeing similar improvements in production apps—the Microsoft Store team had this to share<\/a>:<\/p>\n
    \n
    The Microsoft Store is now happily using System.Text.Json 8.0 RC1 builds, and the new version gave us a whopping 4.2 MB package size improvement compared to 7.0! We’re also using source generators to make serialization code trim\/AOT-friendly and super efficient \ud83d\ude80<\/p>\n<\/blockquote>\n
    Bugfixes<\/h3>\n
    This release includes a large number of bug fixes, performance improvements, and reliability enhancements to the source generator:<\/p>\n