From 6597baaf5e67728e785ad27d4f39308a07be762a Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Fri, 18 Oct 2024 18:02:25 -0700 Subject: [PATCH] add note about AllowOutOfOrderMetadataProperties --- .../system-text-json/polymorphism.md | 23 +++++++++++++------ .../system-text-json/preserve-references.md | 4 ++-- 2 files changed, 18 insertions(+), 9 deletions(-) diff --git a/docs/standard/serialization/system-text-json/polymorphism.md b/docs/standard/serialization/system-text-json/polymorphism.md index 8c778cebfe98d..0998367e856d2 100644 --- a/docs/standard/serialization/system-text-json/polymorphism.md +++ b/docs/standard/serialization/system-text-json/polymorphism.md @@ -1,7 +1,7 @@ --- title: How to serialize properties of derived classes with System.Text.Json description: "Learn how to serialize polymorphic objects while serializing to and deserializing from JSON in .NET." -ms.date: 09/30/2022 +ms.date: 10/18/2024 no-loc: [System.Text.Json, Newtonsoft.Json] zone_pivot_groups: dotnet-version dev_langs: @@ -17,7 +17,7 @@ ms.topic: how-to # How to serialize properties of derived classes with System.Text.Json -In this article, you will learn how to serialize properties of derived classes with the `System.Text.Json` namespace. +In this article, you learn how to serialize properties of derived classes with the `System.Text.Json` namespace. ## Serialize properties of derived classes @@ -148,7 +148,7 @@ The following example shows the JSON that results from the preceding code: Beginning with .NET 7, `System.Text.Json` supports polymorphic type hierarchy serialization and deserialization with attribute annotations. | Attribute | Description | -|--|--| +|-----------|-------------| | | When placed on a type declaration, indicates that the specified subtype should be opted into polymorphic serialization. It also exposes the ability to specify a type discriminator. | | | When placed on a type declaration, indicates that the type should be serialized polymorphically. It also exposes various options to configure polymorphic serialization and deserialization for that type. | @@ -240,7 +240,7 @@ Public Class WeatherForecastWithCity End Class ``` -With the added metadata, specifically, the type discriminator, the serializer can serialize and deserialize the payload as the `WeatherForecastWithCity` type from its base type `WeatherForecastBase`. Serialization will emit JSON along with the type discriminator metadata: +With the added metadata, specifically, the type discriminator, the serializer can serialize and deserialize the payload as the `WeatherForecastWithCity` type from its base type `WeatherForecastBase`. Serialization emits JSON along with the type discriminator metadata: ```csharp WeatherForecastBase weather = new WeatherForecastWithCity @@ -289,14 +289,23 @@ WeatherForecastBase value = JsonSerializer.Deserialize(json Console.WriteLine(value is WeatherForecastWithCity); // True ``` -> [!NOTE] -> The type discriminator must be placed at the start of the JSON object, grouped together with other metadata properties like `$id` and `$ref`. - ```vb Dim value As WeatherForecastBase = JsonSerializer.Deserialize(json) Console.WriteLine(value is WeatherForecastWithCity) // True ``` + +> [!NOTE] +> By default, the `$type` discriminator must be placed at the start of the JSON object, grouped together with other metadata properties like `$id` and `$ref`. If you're reading data off an external API that places the `$type` discriminator in the middle of the JSON object, set to `true`: +> +> ```csharp +> JsonSerializerOptions options = new() { AllowOutOfOrderMetadataProperties = true }; +> JsonSerializer.Deserialize("""{"Name":"Name","$type":"derived"}""", options); +> ``` +> +> Be careful when you enable this flag, as it might result in over-buffering (and out-of-memory failures) when performing streaming deserialization of very large JSON objects. + + ### Mix and match type discriminator formats Type discriminator identifiers are valid in either `string` or `int` forms, so the following is valid: diff --git a/docs/standard/serialization/system-text-json/preserve-references.md b/docs/standard/serialization/system-text-json/preserve-references.md index 08ef17474f4a1..60a7e8f4a0f0c 100644 --- a/docs/standard/serialization/system-text-json/preserve-references.md +++ b/docs/standard/serialization/system-text-json/preserve-references.md @@ -37,7 +37,7 @@ The following code illustrates use of the `Preserve` setting. This feature can't be used to preserve value types or immutable types. On deserialization, the instance of an immutable type is created after the entire payload is read. So it would be impossible to deserialize the same instance if a reference to it appears within the JSON payload. -For value types, immutable types, and arrays, no reference metadata is serialized. On deserialization, an exception is thrown if `$ref` or `$id` is found. However, value types ignore `$id` (and `$values` in the case of collections) to make it possible to deserialize payloads that were serialized by using Newtonsoft.Json. Newtonsoft.Json does serialize metadata for such types. +For value types, immutable types, and arrays, no reference metadata is serialized. On deserialization, an exception is thrown if `$ref` or `$id` is found. However, value types ignore `$id` (and `$values` in the case of collections) to make it possible to deserialize payloads that were serialized by using Newtonsoft.Json, which does serialize metadata for such types. To determine if objects are equal, System.Text.Json uses , which uses reference equality () instead of value equality () when comparing two object instances. @@ -47,7 +47,7 @@ The class defines the be ### Persist reference metadata across multiple serialization and deserialization calls -By default, reference data is only cached for each call to or . To persist references from one `Serialize`/`Deserialize` call to another one, root the instance in the call site of `Serialize`/`Deserialize`. The following code shows an example for this scenario: +By default, reference data is only cached for each call to or . To persist references from one `Serialize` or `Deserialize` call to another one, root the instance in the call site of `Serialize`/`Deserialize`. The following code shows an example for this scenario: * You have a list of `Employee` objects and you have to serialize each one individually. * You want to take advantage of the references saved in the resolver for the `ReferenceHandler`.