From edf97c4a0f3f5493dccf193e637556e3e01fde7d Mon Sep 17 00:00:00 2001 From: Eirik Tsarpalis Date: Wed, 14 Aug 2024 16:30:12 +0100 Subject: [PATCH 1/5] Remove porting tool artifacts and cross-reference the new JSO.Respect* properties. --- .../JsonSerializerOptions.xml | 39 ++++++++++++------- 1 file changed, 26 insertions(+), 13 deletions(-) diff --git a/xml/System.Text.Json/JsonSerializerOptions.xml b/xml/System.Text.Json/JsonSerializerOptions.xml index 0ea4a3be74a..92b74000c8d 100644 --- a/xml/System.Text.Json/JsonSerializerOptions.xml +++ b/xml/System.Text.Json/JsonSerializerOptions.xml @@ -1162,17 +1162,23 @@ Use to enable un Gets or sets a value that indicates whether nullability annotations should be respected during serialization and deserialization. To be added. - Nullability annotations are resolved from the properties, fields and constructor parameters - that are used by the serializer. This includes annotations stemming from attributes such as - , , + Nullability annotations are resolved from the properties, fields and constructor parameters + that are used by the serializer. This includes annotations stemming from attributes such as + , , + and . + - and . - Due to restrictions in how nullable reference types are represented at run time, - this setting only governs nullability annotations of non-generic properties and fields. - It cannot be used to enforce nullability annotations of root-level types or generic parameters. - The default setting for this property can be toggled application-wide using the - "System.Text.Json.Serialization.RespectNullableAnnotationsDefault" feature switch. + Due to restrictions in how nullable reference types are represented at run time, + this setting only governs nullability annotations of non-generic properties and fields. + It cannot be used to enforce nullability annotations of root-level types, collection elements, or generic parameters. + The default setting for this property can be toggled application-wide using the + "System.Text.Json.Serialization.RespectNullableAnnotationsDefault" feature switch. + + + It is recommended that new applications always set this property to , + in combination with the closely related property. + Thrown if this property is set after serialization or deserialization has occurred. @@ -1196,10 +1202,17 @@ Use to enable un Gets or sets a value that indicates whether non-optional constructor parameters should be specified during deserialization. To be added. - For historical reasons constructor-based deserialization treats all constructor parameters as optional by default. - This flag allows users to toggle that behavior as necessary for each instance. - The default setting for this property can be toggled application-wide using the - "System.Text.Json.Serialization.RespectRequiredConstructorParametersDefault" feature switch. + + For historical reasons constructor-based deserialization treats all constructor parameters as optional by default, + filling missing parameters with default values when they are not present in the JSON payload. + This flag allows users to toggle that behavior as necessary for each instance. + The default setting for this property can be toggled application-wide using the + "System.Text.Json.Serialization.RespectRequiredConstructorParametersDefault" feature switch. + + + It is recommended that new applications always set this property to , + in combination with the closely related property. + Thrown if this property is set after serialization or deserialization has occurred. From 5f7bd6dc04110f145bc444761898f01249049a76 Mon Sep 17 00:00:00 2001 From: Eirik Tsarpalis Date: Wed, 14 Aug 2024 18:37:18 +0100 Subject: [PATCH 2/5] Expand on `RespectNullableAnnotations` semantics. --- xml/System.Text.Json/JsonSerializerOptions.xml | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/xml/System.Text.Json/JsonSerializerOptions.xml b/xml/System.Text.Json/JsonSerializerOptions.xml index 92b74000c8d..efda4183f82 100644 --- a/xml/System.Text.Json/JsonSerializerOptions.xml +++ b/xml/System.Text.Json/JsonSerializerOptions.xml @@ -1163,18 +1163,27 @@ Use to enable un To be added. - Nullability annotations are resolved from the properties, fields and constructor parameters + Configures the serializer to throw an exception when trying to serialize a value from a non-nullable property getter, + or when deserializing a value into a non-nullable property setter or constructor parameter. + Nullability annotations are resolved from the properties, fields, and constructor parameters that are used by the serializer. This includes annotations stemming from attributes such as , , and . Due to restrictions in how nullable reference types are represented at run time, - this setting only governs nullability annotations of non-generic properties and fields. + this setting only governs nullability annotations of non-generic properties, fields, and constructor parameters. It cannot be used to enforce nullability annotations of root-level types, collection elements, or generic parameters. The default setting for this property can be toggled application-wide using the "System.Text.Json.Serialization.RespectNullableAnnotationsDefault" feature switch. + + Nullability validation functions independently of required-ness validation, + that is to say the setting has no effect in scenaria where the payload is missing a required property. + This can be configured independently using the keyword, + the attribute, + or the property. + It is recommended that new applications always set this property to , in combination with the closely related property. From 1df4aa41d75742cf55892030487c9cb98ed23057 Mon Sep 17 00:00:00 2001 From: Eirik Tsarpalis Date: Wed, 14 Aug 2024 18:42:08 +0100 Subject: [PATCH 3/5] Update xml/System.Text.Json/JsonSerializerOptions.xml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Carlos Sánchez López <1175054+carlossanlop@users.noreply.github.com> --- xml/System.Text.Json/JsonSerializerOptions.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/xml/System.Text.Json/JsonSerializerOptions.xml b/xml/System.Text.Json/JsonSerializerOptions.xml index efda4183f82..1b54809304b 100644 --- a/xml/System.Text.Json/JsonSerializerOptions.xml +++ b/xml/System.Text.Json/JsonSerializerOptions.xml @@ -1179,7 +1179,7 @@ Use to enable un Nullability validation functions independently of required-ness validation, - that is to say the setting has no effect in scenaria where the payload is missing a required property. + that is to say the setting has no effect in scenarios where the payload is missing a required property. This can be configured independently using the keyword, the attribute, or the property. From dbe550b10e165ff685748eddb03a822e6c6c3f69 Mon Sep 17 00:00:00 2001 From: Eirik Tsarpalis Date: Wed, 14 Aug 2024 18:46:22 +0100 Subject: [PATCH 4/5] Update xml/System.Text.Json/JsonSerializerOptions.xml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Carlos Sánchez López <1175054+carlossanlop@users.noreply.github.com> --- xml/System.Text.Json/JsonSerializerOptions.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/xml/System.Text.Json/JsonSerializerOptions.xml b/xml/System.Text.Json/JsonSerializerOptions.xml index 1b54809304b..442940ebfb4 100644 --- a/xml/System.Text.Json/JsonSerializerOptions.xml +++ b/xml/System.Text.Json/JsonSerializerOptions.xml @@ -1189,7 +1189,7 @@ Use to enable un in combination with the closely related property. - Thrown if this property is set after serialization or deserialization has occurred. + This property is set after serialization or deserialization has occurred. From 423f632c1148e00431d391a3a16aaeff279a5eea Mon Sep 17 00:00:00 2001 From: Eirik Tsarpalis Date: Wed, 14 Aug 2024 18:46:33 +0100 Subject: [PATCH 5/5] Update xml/System.Text.Json/JsonSerializerOptions.xml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Carlos Sánchez López <1175054+carlossanlop@users.noreply.github.com> --- xml/System.Text.Json/JsonSerializerOptions.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/xml/System.Text.Json/JsonSerializerOptions.xml b/xml/System.Text.Json/JsonSerializerOptions.xml index 442940ebfb4..e6be2736252 100644 --- a/xml/System.Text.Json/JsonSerializerOptions.xml +++ b/xml/System.Text.Json/JsonSerializerOptions.xml @@ -1223,7 +1223,7 @@ Use to enable un in combination with the closely related property. - Thrown if this property is set after serialization or deserialization has occurred. + This property is set after serialization or deserialization has occurred.