Skip to content

Automatically port System.Text.Json.JsonSerializerOptions #2879

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 7 commits into from
Aug 7, 2019
Merged

Automatically port System.Text.Json.JsonSerializerOptions #2879

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
9afd0c0
Automatically port System.Text.Json.JsonSerializerOptions
carlossanlop Jul 30, 2019
0c38556
Edited content
Jul 31, 2019
01ded37
Overlooked 3 changes
Jul 31, 2019
8c22357
suggestions by Jozkee
carlossanlop Aug 1, 2019
b85aa1f
missing values
carlossanlop Aug 1, 2019
8f76aa6
bytes
carlossanlop Aug 6, 2019
1af32cf
suggestions by ahsonkhan
carlossanlop Aug 7, 2019
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
178 changes: 140 additions & 38 deletions xml/System.Text.Json/JsonSerializerOptions.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@
</Base>
<Interfaces />
<Docs>
<summary>To be added.</summary>
<summary>Provides options to be used with <see cref="T:System.Text.Json.JsonSerializer" />.</summary>
<remarks>To be added.</remarks>
</Docs>
<Members>
Expand All @@ -31,7 +31,7 @@
</AssemblyInfo>
<Parameters />
<Docs>
<summary>To be added.</summary>
<summary>Initializes a new instance of the <see cref="T:System.Text.Json.JsonSerializerOptions" /> class.</summary>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand All @@ -51,9 +51,18 @@
<ReturnType>System.Boolean</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<value>To be added.</value>
<remarks>To be added.</remarks>
<summary>Get or sets a value that indicates whether an extra comma at the end of a list of JSON values in an object or array is allowed (and ignored) within the JSON payload being deserialized.</summary>
<value><see langword="true" /> if an extra comma at the end of a list of JSON values in an object or array is allowed (and ignored); <see langword="false" /> otherwise.</value>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks

By default, `AllowTrailingCommas` is set to `false`, and a <exception cref="T:System.Text.Json.JsonException> is thrown if a trailing comma is encountered.

]]></format>
</remarks>
<exception cref="T:System.InvalidOperationException">This property was set after serialization or deserialization has occurred.</exception>
</Docs>
</Member>
<Member MemberName="Converters">
Expand All @@ -72,9 +81,17 @@
<ReturnType>System.Collections.Generic.IList&lt;System.Text.Json.Serialization.JsonConverter&gt;</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<value>To be added.</value>
<remarks>To be added.</remarks>
<summary>Gets the list of user-defined converters that were registered.</summary>
<value>The list of custom converters.</value>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks

Once serialization or deserialization occurs, the list cannot be modified.
Copy link
Contributor

@ahsonkhan ahsonkhan Aug 8, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It should state, "should not be modified", not cannot. There is nothing preventing the caller from modifying the list. The changes just won't be reflected when (de)serializing.

cc @steveharter

Copy link
Contributor

@steveharter steveharter Aug 8, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The caller cannot modify the list. They will get an InvalidOperationException.

Copy link
Contributor

@ahsonkhan ahsonkhan Aug 8, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Really? Interesting. We should document the exception then, no? Similar to other properties:
https://docs.microsoft.com/en-us/dotnet/api/system.text.json.jsonserializeroptions.allowtrailingcommas?view=netcore-3.0#exceptions

Verified, yep.

[Fact]
public static void ConverterWithCallback()
{
    const string json = @"{""Name"":""MyName""}";

    var options = new JsonSerializerOptions();
    options.Converters.Add(new CustomerCallbackConverter());

    Customer customer = JsonSerializer.Deserialize<Customer>(json, options);
    Assert.Equal("MyNameHello!", customer.Name);

    // Throws System.InvalidOperationException : Serializer options cannot be changed once serialization or deserialization has occurred.
    options.Converters.Add(new CustomerCallbackConverter());
}


]]></format>
</remarks>
</Docs>
</Member>
<Member MemberName="DefaultBufferSize">
Expand All @@ -93,9 +110,19 @@
<ReturnType>System.Int32</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<value>To be added.</value>
<remarks>To be added.</remarks>
<summary>Gets or sets the default buffer size, in bytes, to use when creating temporary buffers.</summary>
<value>The default buffer size in bytes.</value>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks

The default buffer size, in bytes, is 16384.

]]></format>
</remarks>
<exception cref="T:System.ArgumentException">The buffer size is less than 1.</exception>
<exception cref="T:System.InvalidOperationException">This property was set after serialization or deserialization has occurred.</exception>
</Docs>
</Member>
<Member MemberName="DictionaryKeyPolicy">
Expand All @@ -114,9 +141,21 @@
<ReturnType>System.Text.Json.JsonNamingPolicy</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<value>To be added.</value>
<remarks>To be added.</remarks>
<summary>Gets or sets the policy used to convert a <see cref="T:System.Collections.IDictionary" /> key's name to another format, such as camel-casing.</summary>
<value>The policy used to convert a <see cref="T:System.Collections.IDictionary" /> key's name to another format.</value>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks

This property can be set to <xref:System.Text.Json.JsonNamingPolicy.CamelCase?displayProperty=nameWithType> to specify a camel-casing policy.

This property can be set to <xref:System.Text.Json.JsonNamingPolicy.CamelCase> to specify a camel-casing policy.
Copy link
Contributor

@ahsonkhan ahsonkhan Aug 8, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This remark got duplicated with the latest change.


It is not used when deserializing.

]]></format>
</remarks>
</Docs>
</Member>
<Member MemberName="GetConverter">
Expand All @@ -138,9 +177,9 @@
<Parameter Name="typeToConvert" Type="System.Type" />
</Parameters>
<Docs>
<param name="typeToConvert">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<param name="typeToConvert">The type to return a converter for.</param>
<summary>Returns the converter for the specified type.</summary>
<returns>The first converter that supports the given type, or <see langword="null" /> if there is no converter.</returns>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand All @@ -160,9 +199,10 @@
<ReturnType>System.Boolean</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<value>To be added.</value>
<summary>Gets or sets a value that determines whether <see langword="null" /> values are ignored during serialization and deserialization. The default value is <see langword="false" />.</summary>
Copy link
Contributor

@ahsonkhan ahsonkhan Aug 8, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why do we have "the default value" specified in the summary text in some cases, but in remarks in others. Worth being consistent and moving them all to the remarks?

<value><see langword="true" /> to ignore null values during serialization and deserialization; otherwise, see langword="false" />.</value>
Copy link
Contributor

@ahsonkhan ahsonkhan Aug 8, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is missing a start tag

Suggested change
<value><see langword="true" /> to ignore null values during serialization and deserialization; otherwise, see langword="false" />.</value>
<value><see langword="true" /> to ignore null values during serialization and deserialization; otherwise, <see langword="false" />.</value>

<remarks>To be added.</remarks>
<exception cref="T:System.InvalidOperationException">This property was set after serialization or deserialization has occurred.</exception>
</Docs>
</Member>
<Member MemberName="IgnoreReadOnlyProperties">
Expand All @@ -181,9 +221,20 @@
<ReturnType>System.Boolean</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<value>To be added.</value>
<remarks>To be added.</remarks>
<summary>Gets a value that determines whether read-only properties are ignored during serialization. The default value is <see langword="false" />.</summary>
<value><see langword="true" /> to ignore read-only properties during serialization; otherwise, <see langword="false" />.</value>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks

A property is read-only if it contains a public getter but not a public setter.

Read-only properties are not deserialized regardless of this setting.

]]></format>
</remarks>
<exception cref="T:System.InvalidOperationException">This property was set after serialization or deserialization has occurred.</exception>
</Docs>
</Member>
<Member MemberName="MaxDepth">
Expand All @@ -202,9 +253,19 @@
<ReturnType>System.Int32</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<value>To be added.</value>
<remarks>To be added.</remarks>
<summary>Gets or sets the maximum depth allowed when serializing or deserializing JSON, with the default value of 0 indicating a maximum depth of 64.</summary>
<value>The maximum depth allowed when serializing or deserializing JSON.</value>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks

Going past this depth will throw a <exception cref="T:System.Text.Json.JsonException>.

]]></format>
</remarks>
<exception cref="T:System.InvalidOperationException">This property was set after serialization or deserialization has occurred.</exception>
<exception cref="T:System.ArgumentOutOfRangeException">The max depth is set to a negative value.</exception>
</Docs>
</Member>
<Member MemberName="PropertyNameCaseInsensitive">
Expand All @@ -223,9 +284,17 @@
<ReturnType>System.Boolean</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<value>To be added.</value>
<remarks>To be added.</remarks>
<summary>Gets or sets a value that determines whether a property's name uses a case-insensitive comparison during deserialization. The default value is <see langword="false" />.</summary>
<value><see langword="true" /> to compare property names using case-insensitive comparison; otherwise, <see langword="false" />.</value>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks

There is a performance cost associated with case-insensitie comparison (that is, when `PropertyNameCaseInsensitive` is `true`).
Copy link
Contributor

@ahsonkhan ahsonkhan Aug 8, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
There is a performance cost associated with case-insensitie comparison (that is, when `PropertyNameCaseInsensitive` is `true`).
There is a performance cost associated with case-insensitive comparison (that is, when `PropertyNameCaseInsensitive` is `true`).


]]></format>
</remarks>
</Docs>
</Member>
<Member MemberName="PropertyNamingPolicy">
Expand All @@ -244,9 +313,21 @@
<ReturnType>System.Text.Json.JsonNamingPolicy</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<value>To be added.</value>
<remarks>To be added.</remarks>
<summary>Gets or sets a value that specifies the policy used to convert a property's name on an object to another format, such as camel-casing. </summary>
<value>One of the enum values from <see cref="T:System.Text.Json.JsonNamingPolicy" />.</value>
Copy link
Contributor

@ahsonkhan ahsonkhan Aug 8, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

JsonNamingPolicy is not an enum.

Suggested change
<value>One of the enum values from <see cref="T:System.Text.Json.JsonNamingPolicy" />.</value>
<value>An instance of a <see cref="T:System.Text.Json.JsonNamingPolicy" />.</value>

<remarks>
<format type="text/markdown"><![CDATA[

## Remarks

The resulting property name is expected to match the JSON payload during deserialization, and will be used when writing the property name during serialization.

The policy is not used for properties that have a <xref:System.Text.Json.Serialization.JsonPropertyNameAttribute> applied.

This property can be set to <xref:System.Text.Json.JsonNamingPolicy.CamelCase?displayProperty=nameWithType> to specify a camel-casing policy.

]]></format>
</remarks>
</Docs>
</Member>
<Member MemberName="ReadCommentHandling">
Expand All @@ -265,9 +346,19 @@
<ReturnType>System.Text.Json.JsonCommentHandling</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<value>To be added.</value>
<remarks>To be added.</remarks>
<summary>Gets or sets a value that defines how comments are handled during deserialization.</summary>
<value>A value that indicates whether comments are allowed, disallowed, or skipped.</value>
Copy link
Contributor

@ahsonkhan ahsonkhan Aug 8, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The enum value JsonCommentHandling.Allow isn't supported here.

Suggested change
<value>A value that indicates whether comments are allowed, disallowed, or skipped.</value>
<value>A value that indicates whether comments are disallowed or ignored.</value>

<remarks>
<format type="text/markdown"><![CDATA[

## Remarks

By default, a <exception cref="T:System.Text.Json.JsonException> is thrown if a comment is encountered.

]]></format>
</remarks>
<exception cref="T:System.InvalidOperationException">This property was set after serialization or deserialization has occurred.</exception>
<exception cref="T:System.ArgumentOutOfRangeException">The comment handling enum is set to a value that is not supported (or not within the <see cref="T:System.Text.Json.JsonCommentHandling" /> enum range).</exception>
</Docs>
</Member>
<Member MemberName="WriteIndented">
Expand All @@ -286,10 +377,21 @@
<ReturnType>System.Boolean</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<value>To be added.</value>
<remarks>To be added.</remarks>
<summary>Gets or sets a value that defines whether JSON should use pretty printing. By default, JSON is serialized without any extra white space.</summary>
Copy link
Contributor

@ahsonkhan ahsonkhan Aug 8, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"JSON using pretty printing" doesn't make sense.

Suggested change
<summary>Gets or sets a value that defines whether JSON should use pretty printing. By default, JSON is serialized without any extra white space.</summary>
<summary>Gets or sets a value that defines whether JSON should be written pretty printed. By default, JSON is serialized without any extra white space.</summary>

<value><see langword="true"/> if JSON should pretty print on serialization; otherwise, <see langword="false"/>. The default is <see langword="false"/>.</value>
<remarks>
<format type="text/markdown"><![CDATA[

Pretty printing includes:

- Indenting nested JSON tokens.
- Adding new lines
Copy link
Contributor

@ahsonkhan ahsonkhan Aug 8, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- Adding new lines
- Adding new lines between between consecutive JSON object or array elements.

- Adding white space between property names and values.

]]></format>
</remarks>
<exception cref="T:System.InvalidOperationException">This property was set after serialization or deserialization has occurred.</exception>
</Docs>
</Member>
</Members>
</Type>
</Type>