You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* Update JsonSerializer docs for clarity.
* Add back an exception condition for deserializing from the
Utf8JsonReader.
* Fix parameter name in the remark for the reader overload.
Copy file name to clipboardExpand all lines: xml/System.Text.Json/JsonSerializer.xml
+62-22Lines changed: 62 additions & 22 deletions
Original file line number
Diff line number
Diff line change
@@ -46,7 +46,15 @@
46
46
<remarks>To be added.</remarks>
47
47
<exceptioncref="T:System.ArgumentNullException">
48
48
<paramrefname="returnType" /> is <seelangword="null" />.</exception>
49
-
<exceptioncref="T:System.Text.Json.JsonException">The JSON is invalid, <paramrefname="returnType" /> is not compatible with the JSON, or when there is remaining data in the Stream.</exception>
49
+
<exceptioncref="T:System.Text.Json.JsonException">The JSON is invalid.
50
+
51
+
-or-
52
+
53
+
<typeparamrefname="returnType" /> is not compatible with the JSON.
54
+
55
+
-or-
56
+
57
+
There is remaining data in the span beyond a single JSON value.</exception>
50
58
</Docs>
51
59
</Member>
52
60
<MemberMemberName="Deserialize">
@@ -86,7 +94,15 @@ UTF-8 methods since the implementation natively uses UTF-8.
86
94
</remarks>
87
95
<exceptioncref="T:System.ArgumentNullException">
88
96
<paramrefname="json" /> or <paramrefname="returnType" /> is <seelangword="null" />.</exception>
89
-
<exceptioncref="T:System.Text.Json.JsonException">The JSON is invalid, the <paramrefname="returnType" /> is not compatible with the JSON, or when there is remaining data in the Stream.</exception>
97
+
<exceptioncref="T:System.Text.Json.JsonException">The JSON is invalid.
98
+
99
+
-or-
100
+
101
+
<typeparamrefname="TValue" /> is not compatible with the JSON.
102
+
103
+
-or-
104
+
105
+
There is remaining data in the string beyond a single JSON value.</exception>
90
106
</Docs>
91
107
</Member>
92
108
<MemberMemberName="Deserialize">
@@ -109,7 +125,7 @@ UTF-8 methods since the implementation natively uses UTF-8.
<paramname="reader">The reader to read the JSON from.</param>
113
129
<paramname="returnType">The type of the object to convert to and return.</param>
114
130
<paramname="options">Options to control the serializer behavior during reading.</param>
115
131
<summary>Reads one JSON value (including objects or arrays) from the provided reader and converts it into an instance of a specified type.</summary>
@@ -131,7 +147,15 @@ The <xref:System.Text.Json.JsonReaderOptions> used to create the instance of the
131
147
</remarks>
132
148
<exceptioncref="T:System.ArgumentNullException">
133
149
<paramrefname="returnType" /> is <seelangword="null" />.</exception>
134
-
<exceptioncref="T:System.Text.Json.JsonException">The JSON is invalid, <paramrefname="returnType" /> is not compatible with the JSON, or a value could not be read from the reader.</exception>
150
+
<exceptioncref="T:System.Text.Json.JsonException">The JSON is invalid.
151
+
152
+
-or-
153
+
154
+
<typeparamrefname="returnType" /> is not compatible with the JSON.
155
+
156
+
-or-
157
+
158
+
A value could not be read from the reader.</exception>
135
159
<exceptioncref="T:System.ArgumentException">
136
160
<paramrefname="reader" /> is using unsupported options.</exception>
137
161
</Docs>
@@ -172,7 +196,7 @@ The <xref:System.Text.Json.JsonReaderOptions> used to create the instance of the
172
196
173
197
-or-
174
198
175
-
There is remaining data in the stream.</exception>
199
+
There is remaining data in the span beyond a single JSON value.</exception>
176
200
</Docs>
177
201
</Member>
178
202
<MemberMemberName="Deserialize<TValue>">
@@ -220,7 +244,7 @@ Using a <xref:System.String> is not as efficient as using the UTF-8 methods sinc
220
244
221
245
-or-
222
246
223
-
There is remaining data in the stream.</exception>
247
+
There is remaining data in the string beyond a single JSON value.</exception>
224
248
</Docs>
225
249
</Member>
226
250
<MemberMemberName="Deserialize<TValue>">
@@ -246,7 +270,7 @@ There is remaining data in the stream.</exception>
246
270
</Parameters>
247
271
<Docs>
248
272
<typeparamname="TValue">The target type of the JSON value.</typeparam>
249
-
<paramname="reader">The reader to read.</param>
273
+
<paramname="reader">The reader to read the JSON from.</param>
250
274
<paramname="options">Options to control serializer behavior during reading.</param>
251
275
<summary>Reads one JSON value (including objects or arrays) from the provided reader into an instance of the type specified by a generic type parameter.</summary>
252
276
<returns>A <typeparamrefname="TValue" /> representation of the JSON value.</returns>
@@ -273,7 +297,7 @@ The <xref:System.Text.Json.JsonReaderOptions> used to create the instance of the
273
297
274
298
-or-
275
299
276
-
There is remaining data in the stream.</exception>
300
+
A value could not be read from the reader.</exception>
<paramname="writer">The JSON writer to write to.</param>
419
443
<paramname="value">The value to convert and write.</param>
420
444
<paramname="inputType">The type of the <paramrefname="value" /> to convert.</param>
421
445
<paramname="options">Options to control serialization behavior.</param>
422
-
<summary>Writes one JSON value (including objects or arrays) of a specified type to the provided writer.</summary>
423
-
<remarks>To be added.</remarks>
446
+
<summary>Writes the JSON representation of the specified type to the provided writer.</summary>
447
+
<remarks>
448
+
<formattype="text/markdown"><![CDATA[
449
+
450
+
## Remarks
451
+
452
+
The <xref:System.Text.Json.JsonWriterOptions> used to create the instance of the <xref:System.Text.Json.Utf8JsonWriter> take precedence over the <xref:System.Text.Json.JsonSerializerOptions> when they conflict. Hence, <xref:System.Text.Json.JsonWriterOptions.Indented?displayProperty=nameWithType>, <xref:System.Text.Json.JsonWriterOptions.SkipValidation?displayProperty=nameWithType>, and <xref:System.Text.Json.JsonWriterOptions.Encoder?displayProperty=nameWithType> are used while writing.
453
+
454
+
]]></format>
455
+
</remarks>
424
456
</Docs>
425
457
</Member>
426
458
<MemberMemberName="Serialize<TValue>">
@@ -448,8 +480,8 @@ Using a <xref:System.String> is not as efficient as using UTF-8 encoding since t
448
480
<typeparamname="TValue">The type of the value to serialize.</typeparam>
449
481
<paramname="value">The value to convert.</param>
450
482
<paramname="options">Options to control serialization behavior.</param>
451
-
<summary>Converts the value of a type specified by a generic type parameter into a <seecref="T:System.String" />.</summary>
452
-
<returns>A string representation of the value.</returns>
483
+
<summary>Converts the value of a type specified by a generic type parameter into a JSON string.</summary>
484
+
<returns>A JSON string representation of the value.</returns>
453
485
<remarks>
454
486
<formattype="text/markdown"><![CDATA[
455
487
@@ -485,11 +517,19 @@ Using a <xref:System.String> is not as efficient as using UTF-8 encoding since t
485
517
</Parameters>
486
518
<Docs>
487
519
<typeparamname="TValue">The type of the value to serialize.</typeparam>
488
-
<paramname="writer">A JSON writer.</param>
520
+
<paramname="writer">A JSON writer to write to.</param>
489
521
<paramname="value">The value to convert and write.</param>
490
522
<paramname="options">Options to control serialization behavior.</param>
491
-
<summary>Writes one JSON value (including objects or arrays) of a type specified by a generic type parameter to the provided writer.</summary>
492
-
<remarks>To be added.</remarks>
523
+
<summary>Writes the JSON representation of a type specified by a generic type parameter to the provided writer.</summary>
524
+
<remarks>
525
+
<formattype="text/markdown"><![CDATA[
526
+
527
+
## Remarks
528
+
529
+
The <xref:System.Text.Json.JsonWriterOptions> used to create the instance of the <xref:System.Text.Json.Utf8JsonWriter> take precedence over the <xref:System.Text.Json.JsonSerializerOptions> when they conflict. Hence, <xref:System.Text.Json.JsonWriterOptions.Indented?displayProperty=nameWithType>, <xref:System.Text.Json.JsonWriterOptions.SkipValidation?displayProperty=nameWithType>, and <xref:System.Text.Json.JsonWriterOptions.Encoder?displayProperty=nameWithType> are used while writing.
530
+
531
+
]]></format>
532
+
</remarks>
493
533
</Docs>
494
534
</Member>
495
535
<MemberMemberName="SerializeAsync">
@@ -579,8 +619,8 @@ Using a <xref:System.String> is not as efficient as using UTF-8 encoding since t
579
619
<paramname="value">The value to convert.</param>
580
620
<paramname="inputType">The type of the <paramrefname="value" /> to convert.</param>
581
621
<paramname="options">Options to control the conversion behavior.</param>
582
-
<summary>Converts a value of the specified type into a UTF8-encoded byte array.</summary>
583
-
<returns>A UTF-8 representation of the value.</returns>
622
+
<summary>Converts a value of the specified type into a JSON string, encoded as UTF-8 bytes.</summary>
623
+
<returns>A JSON string representation of the value, encoded as UTF-8 bytes.</returns>
584
624
<remarks>To be added.</remarks>
585
625
</Docs>
586
626
</Member>
@@ -609,8 +649,8 @@ Using a <xref:System.String> is not as efficient as using UTF-8 encoding since t
609
649
<typeparamname="TValue">The type of the value.</typeparam>
610
650
<paramname="value">The value to convert.</param>
611
651
<paramname="options">Options to control the conversion behavior.</param>
612
-
<summary>Converts the value of a type specifed by a generic type parameter into a UTF8-encoded byte array.</summary>
613
-
<returns>A UTF-8 representation of the value.</returns>
652
+
<summary>Converts the value of a type specifed by a generic type parameter into a JSON string, encoded as UTF-8 bytes.</summary>
653
+
<returns>A JSON string representation of the value, encoded as UTF-8 bytes.</returns>
0 commit comments