From 6599488ce05d1272acc96625e738499d345d3ab8 Mon Sep 17 00:00:00 2001 From: carlossanlop Date: Tue, 26 May 2020 11:36:44 -0700 Subject: [PATCH 1/4] Automatically port System.Text.Json 5.0 documentation --- .../JsonConstructorAttribute.xml | 4 +- .../JsonIgnoreAttribute.xml | 12 ++++- .../JsonIgnoreCondition.xml | 11 ++-- .../JsonIncludeAttribute.xml | 14 +++-- .../ReferenceHandling.xml | 52 +++++++++++++++++-- .../JsonElement+ArrayEnumerator.xml | 10 +++- .../JsonElement+ObjectEnumerator.xml | 10 +++- .../JsonSerializerOptions.xml | 6 +-- 8 files changed, 98 insertions(+), 21 deletions(-) diff --git a/xml/System.Text.Json.Serialization/JsonConstructorAttribute.xml b/xml/System.Text.Json.Serialization/JsonConstructorAttribute.xml index 8696e94b445..1a1dc13ee98 100644 --- a/xml/System.Text.Json.Serialization/JsonConstructorAttribute.xml +++ b/xml/System.Text.Json.Serialization/JsonConstructorAttribute.xml @@ -19,7 +19,7 @@ - To be added. + When placed on a constructor, indicates that the constructor should be used to create instances of the type on deserialization. To be added. @@ -36,7 +36,7 @@ - To be added. + Initializes a new instance of . To be added. diff --git a/xml/System.Text.Json.Serialization/JsonIgnoreAttribute.xml b/xml/System.Text.Json.Serialization/JsonIgnoreAttribute.xml index e4b2381e591..c9f9b89f2e6 100644 --- a/xml/System.Text.Json.Serialization/JsonIgnoreAttribute.xml +++ b/xml/System.Text.Json.Serialization/JsonIgnoreAttribute.xml @@ -68,9 +68,17 @@ For more information, see [How to serialize and deserialize JSON](/dotnet/standa System.Text.Json.Serialization.JsonIgnoreCondition - To be added. + Specifies the condition that must be met before a property will be ignored. To be added. - To be added. + + . + + ]]> + diff --git a/xml/System.Text.Json.Serialization/JsonIgnoreCondition.xml b/xml/System.Text.Json.Serialization/JsonIgnoreCondition.xml index 6eb66310d69..e83b8fd0af6 100644 --- a/xml/System.Text.Json.Serialization/JsonIgnoreCondition.xml +++ b/xml/System.Text.Json.Serialization/JsonIgnoreCondition.xml @@ -13,7 +13,7 @@ System.Enum - To be added. + Controls how the ignores properties on serialization and deserialization. To be added. @@ -34,7 +34,8 @@ 0 - To be added. + Property will always be ignored. + To be added. @@ -54,7 +55,8 @@ 2 - To be added. + Property will always be serialized and deserialized, regardless of configuration. + To be added. @@ -74,7 +76,8 @@ 1 - To be added. + Property will only be ignored if it is . + To be added. diff --git a/xml/System.Text.Json.Serialization/JsonIncludeAttribute.xml b/xml/System.Text.Json.Serialization/JsonIncludeAttribute.xml index d54af630e2a..86723fc4fb4 100644 --- a/xml/System.Text.Json.Serialization/JsonIncludeAttribute.xml +++ b/xml/System.Text.Json.Serialization/JsonIncludeAttribute.xml @@ -19,8 +19,16 @@ - To be added. - To be added. + Indicates that the member should be included for serialization and deserialization. + + + @@ -36,7 +44,7 @@ - To be added. + Initializes a new instance of . To be added. diff --git a/xml/System.Text.Json.Serialization/ReferenceHandling.xml b/xml/System.Text.Json.Serialization/ReferenceHandling.xml index 1c6a8402e78..b92129c5b20 100644 --- a/xml/System.Text.Json.Serialization/ReferenceHandling.xml +++ b/xml/System.Text.Json.Serialization/ReferenceHandling.xml @@ -14,7 +14,7 @@ - To be added. + This class defines how the deals with references on serialization and deserialization. To be added. @@ -34,9 +34,22 @@ System.Text.Json.Serialization.ReferenceHandling - To be added. + Serialization does not support objects with cycles and does not preserve duplicate references. Metadata properties will not be written when serializing reference types and will be treated as regular properties on deserialize. To be added. - To be added. + + if an object contains a cycle. + * On Deserialize: + Metadata properties (`$id`, `$values`, and `$ref`) will not be consumed and therefore will be treated as regular JSON properties. + The metadata properties can map to a real property on the returned object if the property names match, or will be added to the overflow dictionary, if one exists; otherwise, they are ignored. + + ]]> + @@ -55,9 +68,38 @@ System.Text.Json.Serialization.ReferenceHandling - To be added. + Metadata properties will be honored when deserializing JSON objects and arrays into reference types and written when serializing reference types. This is necessary to create round-trippable JSON from objects that contain cycles or duplicate references. To be added. - To be added. + + is used to determine whether objects are identical. + When an object is identical to a previously serialized one, a pointer (`$ref`) to the identifier (`$id`) of such object is written instead. + No metadata properties are written for value types. + * On Deserialize: + The metadata properties within the JSON that are used to preserve duplicated references and cycles will be honored as long as they are well-formed**. + For JSON objects that don't contain any metadata properties, the deserialization behavior is identical to . + For value types: + * The `$id` metadata property is ignored. + * A is thrown if a `$ref` metadata property is found within the JSON object. + * For enumerable value types, the `$values` metadata property is ignored. + ** For the metadata properties within the JSON to be considered well-formed, they must follow these rules: + 1) The `$id` metadata property must be the first property in the JSON object. + 2) A JSON object that contains a `$ref` metadata property must not contain any other properties. + 3) The value of the `$ref` metadata property must refer to an `$id` that has appeared earlier in the JSON. + 4) The value of the `$id` and `$ref` metadata properties must be a JSON string. + 5) For enumerable types, such as , the JSON array must be nested within a JSON object containing an `$id` and `$values` metadata property, in that order. + 6) For enumerable types, the `$values` metadata property must be a JSON array. + 7) The `$values` metadata property is only valid when referring to enumerable types. + If the JSON is not well-formed, a is thrown. + + ]]> + diff --git a/xml/System.Text.Json/JsonElement+ArrayEnumerator.xml b/xml/System.Text.Json/JsonElement+ArrayEnumerator.xml index a9e1bdbe859..34d4d068d52 100644 --- a/xml/System.Text.Json/JsonElement+ArrayEnumerator.xml +++ b/xml/System.Text.Json/JsonElement+ArrayEnumerator.xml @@ -259,7 +259,15 @@ This member is an explicit interface member implementation. It can be used only Gets the element in the collection at the current position of the enumerator. The element in the collection at the current position of the enumerator. - To be added. + + instance is cast to an interface. + + ]]> + diff --git a/xml/System.Text.Json/JsonElement+ObjectEnumerator.xml b/xml/System.Text.Json/JsonElement+ObjectEnumerator.xml index 7a9a249fab1..3f6ba3b5b92 100644 --- a/xml/System.Text.Json/JsonElement+ObjectEnumerator.xml +++ b/xml/System.Text.Json/JsonElement+ObjectEnumerator.xml @@ -263,7 +263,15 @@ This member is an explicit interface member implementation. It can be used only Gets the element in the collection at the current position of the enumerator. The element in the collection at the current position of the enumerator. - To be added. + + instance is cast to an interface. + + ]]> + diff --git a/xml/System.Text.Json/JsonSerializerOptions.xml b/xml/System.Text.Json/JsonSerializerOptions.xml index ccc6fb1b61b..c92e19ae977 100644 --- a/xml/System.Text.Json/JsonSerializerOptions.xml +++ b/xml/System.Text.Json/JsonSerializerOptions.xml @@ -63,8 +63,8 @@ For more information, see [How to serialize and deserialize JSON](/dotnet/standa - To be added. - To be added. + The instance to copy options from. + Copies the options from a instance to a new instance. To be added. @@ -504,7 +504,7 @@ For more information, see [How to serialize and deserialize JSON](/dotnet/standa System.Text.Json.Serialization.ReferenceHandling - To be added. + Defines how references are treated when reading and writing JSON, this is convenient to deal with circularity. To be added. To be added. From 93f1dd8303edd25613a2955ae532cf2697158be9 Mon Sep 17 00:00:00 2001 From: carlossanlop Date: Tue, 26 May 2020 13:05:43 -0700 Subject: [PATCH 2/4] Auto ported exceptions --- xml/System.Text.Json/JsonSerializer.xml | 2 ++ .../JsonSerializerOptions.xml | 2 ++ xml/System.Text.Json/Utf8JsonReader.xml | 22 ++++++++++++++++--- 3 files changed, 23 insertions(+), 3 deletions(-) diff --git a/xml/System.Text.Json/JsonSerializer.xml b/xml/System.Text.Json/JsonSerializer.xml index da988b5ecc1..228f38172b0 100644 --- a/xml/System.Text.Json/JsonSerializer.xml +++ b/xml/System.Text.Json/JsonSerializer.xml @@ -456,6 +456,8 @@ For more information, see [How to serialize and deserialize JSON](/dotnet/standa There is remaining data in the stream. There is no compatible for or its serializable members. + + is . diff --git a/xml/System.Text.Json/JsonSerializerOptions.xml b/xml/System.Text.Json/JsonSerializerOptions.xml index c92e19ae977..9042b29afb9 100644 --- a/xml/System.Text.Json/JsonSerializerOptions.xml +++ b/xml/System.Text.Json/JsonSerializerOptions.xml @@ -66,6 +66,8 @@ For more information, see [How to serialize and deserialize JSON](/dotnet/standa The instance to copy options from. Copies the options from a instance to a new instance. To be added. + + is . diff --git a/xml/System.Text.Json/Utf8JsonReader.xml b/xml/System.Text.Json/Utf8JsonReader.xml index bea63343a98..e1f213efed4 100644 --- a/xml/System.Text.Json/Utf8JsonReader.xml +++ b/xml/System.Text.Json/Utf8JsonReader.xml @@ -349,7 +349,15 @@ The JSON token value represents a number less than The type of the JSON token is not a . - The value is not encoded as Base64 text, so it can't be decoded to bytes. + The value is not encoded as Base64 text, so it can't be decoded to bytes. + +-or- + +The value contains invalid/more than two padding characters. + +-or- + +The value is incomplete. That is, the JSON string length is not a multiple of 4. @@ -414,7 +422,11 @@ This method only creates a representation of JSON strings -or- -The entire UTF-8 encoded token value cannot be parsed to a value. +The entire UTF-8 encoded token value cannot be parsed to a value. + +-or- + +The JSON token value is of an unsupported format. Only a subset of ISO 8601 formats are supported. @@ -453,7 +465,11 @@ This method only creates a representation of JSON s -or- -The entire UTF-8 encoded token value cannot be parsed to a value. +The entire UTF-8 encoded token value cannot be parsed to a value. + +-or- + +The JSON token value is of an unsupported format. Only a subset of ISO 8601 formats are supported. From bea6f8fde7fd1f56b725cb10bb2a6f6cf8543f71 Mon Sep 17 00:00:00 2001 From: Carlos Sanchez Lopez <1175054+carlossanlop@users.noreply.github.com> Date: Tue, 23 Jun 2020 11:42:05 -0700 Subject: [PATCH 3/4] Apply suggestions from code review Co-authored-by: Tom Dykstra --- .../ReferenceHandling.xml | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/xml/System.Text.Json.Serialization/ReferenceHandling.xml b/xml/System.Text.Json.Serialization/ReferenceHandling.xml index b92129c5b20..8564f22393e 100644 --- a/xml/System.Text.Json.Serialization/ReferenceHandling.xml +++ b/xml/System.Text.Json.Serialization/ReferenceHandling.xml @@ -84,11 +84,14 @@ * On Deserialize: The metadata properties within the JSON that are used to preserve duplicated references and cycles will be honored as long as they are well-formed**. For JSON objects that don't contain any metadata properties, the deserialization behavior is identical to . - For value types: - * The `$id` metadata property is ignored. - * A is thrown if a `$ref` metadata property is found within the JSON object. - * For enumerable value types, the `$values` metadata property is ignored. - ** For the metadata properties within the JSON to be considered well-formed, they must follow these rules: + + For value types: + + * The `$id` metadata property is ignored. + * A is thrown if a `$ref` metadata property is found within the JSON object. + * For enumerable value types, the `$values` metadata property is ignored. + + For the metadata properties within the JSON to be considered well-formed, they must follow these rules: 1) The `$id` metadata property must be the first property in the JSON object. 2) A JSON object that contains a `$ref` metadata property must not contain any other properties. 3) The value of the `$ref` metadata property must refer to an `$id` that has appeared earlier in the JSON. @@ -96,7 +99,8 @@ 5) For enumerable types, such as , the JSON array must be nested within a JSON object containing an `$id` and `$values` metadata property, in that order. 6) For enumerable types, the `$values` metadata property must be a JSON array. 7) The `$values` metadata property is only valid when referring to enumerable types. - If the JSON is not well-formed, a is thrown. + + If the JSON is not well-formed, a is thrown. ]]> From 5724b4dced8fba90f49e63c08c9056d6ea18e401 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Mon, 3 Aug 2020 14:34:48 -0700 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: David Cantu Co-authored-by: Layomi Akinrinade --- .../JsonIncludeAttribute.xml | 3 ++- .../ReferenceHandling.xml | 26 +++++++++---------- .../JsonSerializerOptions.xml | 6 ++--- xml/System.Text.Json/Utf8JsonReader.xml | 6 ++--- 4 files changed, 21 insertions(+), 20 deletions(-) diff --git a/xml/System.Text.Json.Serialization/JsonIncludeAttribute.xml b/xml/System.Text.Json.Serialization/JsonIncludeAttribute.xml index 86723fc4fb4..ca04683d658 100644 --- a/xml/System.Text.Json.Serialization/JsonIncludeAttribute.xml +++ b/xml/System.Text.Json.Serialization/JsonIncludeAttribute.xml @@ -25,10 +25,11 @@ ## Remarks -When applied to a property, indicates that non-public getters and setters can be used for serialization and deserialization. +When applied to a property, indicates that non-public getters and setters can be used for serialization and deserialization. Non-public properties are not supported. ]]> + The attribute is applied to a non-public property. diff --git a/xml/System.Text.Json.Serialization/ReferenceHandling.xml b/xml/System.Text.Json.Serialization/ReferenceHandling.xml index 8564f22393e..3ccc6db94e8 100644 --- a/xml/System.Text.Json.Serialization/ReferenceHandling.xml +++ b/xml/System.Text.Json.Serialization/ReferenceHandling.xml @@ -14,7 +14,7 @@ - This class defines how the deals with references on serialization and deserialization. + Defines how the deals with references during serialization and deserialization. To be added. @@ -45,8 +45,8 @@ Treats duplicate object references as if they were unique and writes all their properties. The serializer throws a if an object contains a cycle. * On Deserialize: - Metadata properties (`$id`, `$values`, and `$ref`) will not be consumed and therefore will be treated as regular JSON properties. - The metadata properties can map to a real property on the returned object if the property names match, or will be added to the overflow dictionary, if one exists; otherwise, they are ignored. + Metadata properties (`$id`, `$values`, and `$ref`) are not consumed and, therefore, are treated as regular JSON properties. + The metadata properties can map to a real property on the returned object if the property names match. Or, if the overflow dictionary exists, the metadata properties are added to it. Otherwise, the metadata properties are ignored. ]]> @@ -77,12 +77,12 @@ * On Serialize: When writing complex reference types, the serializer also writes metadata properties (`$id`, `$values`, and `$ref`) within them. - The output JSON will contain an extra `$id` property for every object, and for every enumerable type the JSON array emitted will be nested within a JSON object containing an `$id` and `$values` property. + The output JSON will contain an extra `$id` property for every object. For every enumerable type, the JSON array emitted will be nested within a JSON object containing an `$id` and `$values` property. is used to determine whether objects are identical. When an object is identical to a previously serialized one, a pointer (`$ref`) to the identifier (`$id`) of such object is written instead. No metadata properties are written for value types. * On Deserialize: - The metadata properties within the JSON that are used to preserve duplicated references and cycles will be honored as long as they are well-formed**. + The metadata properties within the JSON that are used to preserve duplicated references, and cycles will be honored as long as they are well-formed**. For JSON objects that don't contain any metadata properties, the deserialization behavior is identical to . For value types: @@ -92,18 +92,18 @@ * For enumerable value types, the `$values` metadata property is ignored. For the metadata properties within the JSON to be considered well-formed, they must follow these rules: - 1) The `$id` metadata property must be the first property in the JSON object. - 2) A JSON object that contains a `$ref` metadata property must not contain any other properties. - 3) The value of the `$ref` metadata property must refer to an `$id` that has appeared earlier in the JSON. - 4) The value of the `$id` and `$ref` metadata properties must be a JSON string. - 5) For enumerable types, such as , the JSON array must be nested within a JSON object containing an `$id` and `$values` metadata property, in that order. - 6) For enumerable types, the `$values` metadata property must be a JSON array. - 7) The `$values` metadata property is only valid when referring to enumerable types. + - The `$id` metadata property must be the first property in the JSON object. + - A JSON object that contains a `$ref` metadata property must not contain any other properties. + - The value of the `$ref` metadata property must refer to an `$id` that has appeared earlier in the JSON. + - The value of the `$id` and `$ref` metadata properties must be a JSON string. + - For enumerable types, such as , the JSON array must be nested within a JSON object containing an `$id` and `$values` metadata property, in that order. + - For enumerable types, the `$values` metadata property must be a JSON array. + - The `$values` metadata property is only valid when referring to enumerable types. - If the JSON is not well-formed, a is thrown. ]]> + The JSON is not well formed. diff --git a/xml/System.Text.Json/JsonSerializerOptions.xml b/xml/System.Text.Json/JsonSerializerOptions.xml index 9042b29afb9..3a694761dcf 100644 --- a/xml/System.Text.Json/JsonSerializerOptions.xml +++ b/xml/System.Text.Json/JsonSerializerOptions.xml @@ -63,7 +63,7 @@ For more information, see [How to serialize and deserialize JSON](/dotnet/standa - The instance to copy options from. + The options instance to copy options from. Copies the options from a instance to a new instance. To be added. @@ -506,9 +506,9 @@ For more information, see [How to serialize and deserialize JSON](/dotnet/standa System.Text.Json.Serialization.ReferenceHandling - Defines how references are treated when reading and writing JSON, this is convenient to deal with circularity. + Configures how object references are handled when reading and writing JSON. To be added. - To be added. + This option provides a convenient way to deal with circularity in object graphs. diff --git a/xml/System.Text.Json/Utf8JsonReader.xml b/xml/System.Text.Json/Utf8JsonReader.xml index e1f213efed4..fc3d3989157 100644 --- a/xml/System.Text.Json/Utf8JsonReader.xml +++ b/xml/System.Text.Json/Utf8JsonReader.xml @@ -353,7 +353,7 @@ The JSON token value represents a number less than +The JSON token value is of an unsupported format. @@ -469,7 +469,7 @@ The entire UTF-8 encoded token value cannot be parsed to a