TheWriteXValue methods inUtf8JsonWriter had documentation that incorrectly stated they write values "as an element of a JSON array". However, these methods can be used in various contexts, not just arrays:

• As array elements:[value1, value2, value3]
• As object property values:{"property": value}
• As standalone JSON values (e.g., in custom converters)

Example from the issue

The problem was evident in custom converters like this:

publicoverridevoidWrite(Utf8JsonWriterwriter,DateTimeOffsetdateTimeValue,JsonSerializerOptionsoptions)=>writer.WriteStringValue(dateTimeValue.ToString(// Not writing to an array!"MM/dd/yyyy",CultureInfo.InvariantCulture));

Changes made

Updated documentation for all affectedWriteXValue methods to remove the misleading "as an element of a JSON array" language:

• WriteStringValue (all overloads):DateTime,DateTimeOffset,Guid,ReadOnlySpan<byte>,ReadOnlySpan<char>,string,JsonEncodedText
• WriteBooleanValue
• WriteNullValue
• WriteNumberValue (all numeric types):Decimal,Double,Int32,Int64,Single,UInt32,UInt64
• WriteBase64StringValue

Before and after

Before:

<summary>Writes a string text value (as a JSON string) as an element of a JSON array.</summary>

After:

<summary>Writes a string text value (as a JSON string).</summary>

The documentation now accurately reflects that these methods write JSON values in any valid context, not just arrays.

Fixes#11360.

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Clickhere to start the survey.