Skip to content

Merge main into live #10255

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Aug 15, 2024
Merged

Merge main into live #10255

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
edf97c4
Remove porting tool artifacts and cross-reference the new JSO.Respect…
eiriktsarpalis Aug 14, 2024
5f7bd6d
Expand on `RespectNullableAnnotations` semantics.
eiriktsarpalis Aug 14, 2024
1df4aa4
Update xml/System.Text.Json/JsonSerializerOptions.xml
eiriktsarpalis Aug 14, 2024
dbe550b
Update xml/System.Text.Json/JsonSerializerOptions.xml
eiriktsarpalis Aug 14, 2024
423f632
Update xml/System.Text.Json/JsonSerializerOptions.xml
eiriktsarpalis Aug 14, 2024
c3d181e
Merge pull request #10250 from eiriktsarpalis/stj-respectflags-improve
eiriktsarpalis Aug 14, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 37 additions & 15 deletions xml/System.Text.Json/JsonSerializerOptions.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1162,19 +1162,34 @@ Use <xref:System.Text.Json.Serialization.ReferenceHandler.Preserve> to enable un
<summary>Gets or sets a value that indicates whether nullability annotations should be respected during serialization and deserialization.</summary>
<value>To be added.</value>
<remarks>
<para>Nullability annotations are resolved from the properties, fields and constructor parameters</para>
<para>that are used by the serializer. This includes annotations stemming from attributes such as</para>
<para>
<see cref="T:System.Diagnostics.CodeAnalysis.NotNullAttribute" />, <see cref="T:System.Diagnostics.CodeAnalysis.MaybeNullAttribute" />,</para>
Configures the serializer to throw an exception when trying to serialize a <see langword="null" /> value from a non-nullable property getter,
or when deserializing a <see langword="null" /> 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
<see cref="T:System.Diagnostics.CodeAnalysis.NotNullAttribute" />, <see cref="T:System.Diagnostics.CodeAnalysis.MaybeNullAttribute" />,
<see cref="T:System.Diagnostics.CodeAnalysis.AllowNullAttribute" /> and <see cref="T:System.Diagnostics.CodeAnalysis.DisallowNullAttribute" />.
</para>
<para>
<see cref="T:System.Diagnostics.CodeAnalysis.AllowNullAttribute" /> and <see cref="T:System.Diagnostics.CodeAnalysis.DisallowNullAttribute" />.</para>
<para>Due to restrictions in how nullable reference types are represented at run time,</para>
<para>this setting only governs nullability annotations of non-generic properties and fields.</para>
<para>It cannot be used to enforce nullability annotations of root-level types or generic parameters.</para>
<para>The default setting for this property can be toggled application-wide using the</para>
<para>"System.Text.Json.Serialization.RespectNullableAnnotationsDefault" feature switch.</para>
Due to restrictions in how nullable reference types are represented at run time,
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.
</para>
<para>
Nullability validation functions independently of required-ness validation,
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 <see langword="required" /> keyword,
the <see cref="P:System.Text.Json.Serialization.JsonRequiredAttribute" /> attribute,
or the <see cref="P:System.Text.Json.JsonSerializerOptions.RespectRequiredConstructorParameters" /> property.
</para>
<para>
It is recommended that new applications always set this property to <see langword="true" />,
in combination with the closely related <see cref="P:System.Text.Json.JsonSerializerOptions.RespectRequiredConstructorParameters" /> property.
</para>
</remarks>
<exception cref="T:System.InvalidOperationException">Thrown if this property is set after serialization or deserialization has occurred.</exception>
<exception cref="T:System.InvalidOperationException">This property is set after serialization or deserialization has occurred.</exception>
</Docs>
</Member>
<Member MemberName="RespectRequiredConstructorParameters">
Expand All @@ -1196,12 +1211,19 @@ Use <xref:System.Text.Json.Serialization.ReferenceHandler.Preserve> to enable un
<summary>Gets or sets a value that indicates whether non-optional constructor parameters should be specified during deserialization.</summary>
<value>To be added.</value>
<remarks>
<para>For historical reasons constructor-based deserialization treats all constructor parameters as optional by default.</para>
<para>This flag allows users to toggle that behavior as necessary for each <see cref="T:System.Text.Json.JsonSerializerOptions" /> instance.</para>
<para>The default setting for this property can be toggled application-wide using the</para>
<para>"System.Text.Json.Serialization.RespectRequiredConstructorParametersDefault" feature switch.</para>
<para>
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 <see cref="T:System.Text.Json.JsonSerializerOptions" /> instance.
The default setting for this property can be toggled application-wide using the
"System.Text.Json.Serialization.RespectRequiredConstructorParametersDefault" feature switch.
</para>
<para>
It is recommended that new applications always set this property to <see langword="true" />,
in combination with the closely related <see cref="P:System.Text.Json.JsonSerializerOptions.RespectNullableAnnotations" /> property.
</para>
</remarks>
<exception cref="T:System.InvalidOperationException">Thrown if this property is set after serialization or deserialization has occurred.</exception>
<exception cref="T:System.InvalidOperationException">This property is set after serialization or deserialization has occurred.</exception>
</Docs>
</Member>
<Member MemberName="TryGetTypeInfo">
Expand Down