Utf8JsonWriter WriteXValue methods assume an array is being written to

[Reprevise]

The documentation of the WriteXValue methods assumes you're calling the method to append a value to a JSON array when there other usecases, for example when writing converters (see here).

namespace SystemTextJsonSamples
{
    public class DateTimeOffsetJsonConverter : JsonConverter<DateTimeOffset>
    {
        public override DateTimeOffset Read(
            ref Utf8JsonReader reader,
            Type typeToConvert,
            JsonSerializerOptions options) =>
                DateTimeOffset.ParseExact(reader.GetString()!,
                    "MM/dd/yyyy", CultureInfo.InvariantCulture);

        public override void Write(
            Utf8JsonWriter writer,
            DateTimeOffset dateTimeValue,
            JsonSerializerOptions options) =>
                writer.WriteStringValue(dateTimeValue.ToString( // Call to WriteStringValue
                    "MM/dd/yyyy", CultureInfo.InvariantCulture));
    }
}

Documentation for WriteStringValue:

Writes a string text value (as a JSON string) as an element of a JSON array.

There's also a method call to SetFlagToAddListSeparatorBeforeNextItem() inside the WriteStringValue(ReadOnlySpan<char> value) method.

[dotnet-policy-service]

Tagging subscribers to this area: @dotnet/area-system-text-json, @gregsdennis
See info in area-owners.md if you want to be subscribed.

[eiriktsarpalis]

Thanks, this is clearly incorrect and should be fixed. The methods can be used to write a value in any context.

[Reprevise]

What about the call to SetFlagToAddListSeparatorBeforeNextItem() inside WriteStringValue(ReadOnlySpan<char>)? It seems like this method was intended to be for writing values to arrays. Though this hasn't broken anything (as far as its known).

[eiriktsarpalis]

That's just implementation detail, setting a flag that is invariant when writing in non-array contexts.