dotnet / dotnet/dotnet-api-docs

Utf8JsonReader Docs Do Not Include Buffer Requirements, Missing Examples for Partial Reads

Open
#3,831 1 comment 1 reaction 0 assignees View on GitHub
area-System.Text.Json doc-enhancement Pri3
Dominant language
C#
Stars
949
Forks
1.7k
Avg merge
3d 27m
Merged PRs (30d)
49

Description

The current [JsonReader docs ](https://docs.microsoft.com/en-us/dotnet/api/system.text.json.utf8jsonreader?view=netcore-3.1) and the [example page](https://docs.microsoft.com/en-us/dotnet/standard/serialization/system-text-json-how-to?view=netcore-3.1#use-utf8jsonreader) only cover how to use the reader when the entire document is loaded, but do not cover partial reads.

This can lead to confusion as the reader has specific requirements that are not documented (the buffer must be larger than the largest whitespace or token or the reader will fail, bytes not consumed by a read must be coped to the front of the buffer on the next read by the caller, etc). See [this issue ](https://github.com/dotnet/runtime/issues/2265) for an example.

I think part of the problem is, at first glance, Utf8JsonReader seems to have similar methods and structure to other streaming parsers, like Json.Net's JsonReader and the built in XmlReader (where the user calls Read for valid tokens). And while it does operate similarly if the full document is loaded, it has completely different semantics for partial reads.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.