Class JsonAsyncReader
- Namespace
- Nerdbank.Json
- Assembly
- Nerdbank.Json.dll
An incremental UTF-8 JSON reader that decodes from a PipeReader without buffering the entire document.
public sealed class JsonAsyncReader : IDisposable- Inheritance
-
JsonAsyncReader
- Implements
- Inherited Members
Remarks
This reader fetches bytes from the pipe on demand and frames one JSON value (or one structural token) at a time using Nerdbank.Json.JsonStructureScanner, so tokens that straddle buffer boundaries are handled correctly and memory use is bounded by the size of the largest single value being decoded rather than the whole document.
It is the asynchronous counterpart to JsonReader and is used when implementing the asynchronous virtual methods on JsonConverter<T>. The underlying PipeReader is never completed by this type; it is left positioned after the last consumed byte.
Constructors
JsonAsyncReader(PipeReader, bool, JsonCommentHandling)
Initializes a new instance of the JsonAsyncReader class.
public JsonAsyncReader(PipeReader pipeReader, bool allowTrailingCommas = false, JsonCommentHandling commentHandling = JsonCommentHandling.Disallow)Parameters
pipeReaderPipeReaderThe pipe to read UTF-8 JSON from. It is not completed by this reader.
allowTrailingCommasboolWhether trailing commas are tolerated in arrays and objects.
commentHandlingJsonCommentHandlingThe comment handling policy.
Properties
CancellationToken
Gets a cancellation token that applies to all reads from this reader.
public required CancellationToken CancellationToken { get; init; }Property Value
Methods
BufferNextValueAsync(SerializationContext)
Buffers the next complete JSON value from the pipe, fetching more bytes as needed.
public ValueTask BufferNextValueAsync(SerializationContext context)Parameters
contextSerializationContextThe serialization context.
Returns
- ValueTask
A task that completes when a full value is buffered.
CloseContainersAsync(int, SerializationContext)
Consumes the remainder of a given number of already-open JSON containers, discarding bytes as they are scanned, so that a partially-navigated envelope can be validated and drained without buffering it.
public ValueTask CloseContainersAsync(int openContainers, SerializationContext context)Parameters
openContainersintThe number of containers that were entered but not yet closed.
contextSerializationContextThe serialization context.
Returns
- ValueTask
A task that completes when the containers have been closed.
Exceptions
- FormatException
Thrown if the stream ends before the containers are closed.
CreateBufferedReader()
Creates a synchronous reader over the value most recently buffered by BufferNextValueAsync(SerializationContext).
public JsonReader CreateBufferedReader()Returns
- JsonReader
A synchronous reader.
Dispose()
Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.
public void Dispose()EnsureFullyConsumedAsync(SerializationContext)
Verifies that no significant data (other than whitespace and, when allowed, comments) follows the value already read.
public ValueTask EnsureFullyConsumedAsync(SerializationContext context)Parameters
contextSerializationContextThe serialization context.
Returns
- ValueTask
A task that completes when the check passes.
Exceptions
- FormatException
Thrown if trailing data is present.
PeekNextByteAcrossLinesAsync()
Peeks at the next significant byte, additionally reporting whether a line terminator was skipped on the way there. Used to enforce newline framing for newline-delimited JSON.
public ValueTask<(int Byte, bool SawLineTerminator)> PeekNextByteAcrossLinesAsync()Returns
- ValueTask<(int Byte, bool SawLineTerminator)>
The next significant byte (or
-1at end of stream) and whether a line break preceded it.
PeekNextByteAsync()
Peeks at the next significant (non-whitespace, non-comment) byte without consuming it.
public ValueTask<int> PeekNextByteAsync()Returns
ReadNameSeparatorAsync(SerializationContext)
Reads the name separator (colon).
public ValueTask ReadNameSeparatorAsync(SerializationContext context)Parameters
contextSerializationContextThe serialization context.
Returns
- ValueTask
A task representing the read.
ReadNumberTokenAsync(SerializationContext)
Reads a JSON number token (buffered, bounded by its own size) and returns its raw text.
public ValueTask<string> ReadNumberTokenAsync(SerializationContext context)Parameters
contextSerializationContextThe serialization context.
Returns
ReadPropertyNameAsync(SerializationContext)
Reads a JSON property name (a string) and the following name separator.
public ValueTask<string> ReadPropertyNameAsync(SerializationContext context)Parameters
contextSerializationContextThe serialization context.
Returns
ReadRawValueAsync(SerializationContext)
Reads the next JSON value and returns its raw JSON text. The value is buffered (bounded by its own size).
public ValueTask<string> ReadRawValueAsync(SerializationContext context)Parameters
contextSerializationContextThe serialization context.
Returns
ReadStartArrayAsync(SerializationContext)
Reads the start-of-array token.
public ValueTask ReadStartArrayAsync(SerializationContext context)Parameters
contextSerializationContextThe serialization context.
Returns
- ValueTask
A task representing the read.
ReadStartObjectAsync(SerializationContext)
Reads the start-of-object token.
public ValueTask ReadStartObjectAsync(SerializationContext context)Parameters
contextSerializationContextThe serialization context.
Returns
- ValueTask
A task representing the read.
ReadStringValueAsync(SerializationContext)
Reads a JSON string value (buffered, bounded by its own size) and returns the decoded string.
public ValueTask<string> ReadStringValueAsync(SerializationContext context)Parameters
contextSerializationContextThe serialization context.
Returns
ReadValueAsync<T>(JsonConverter<T>, SerializationContext)
Reads a value using the specified converter, streaming when the converter prefers asynchronous serialization.
public ValueTask<T?> ReadValueAsync<T>(JsonConverter<T> converter, SerializationContext context)Parameters
converterJsonConverter<T>The converter for the value.
contextSerializationContextThe serialization context.
Returns
- ValueTask<T>
The deserialized value.
Type Parameters
TThe value type.
ReadValueSeparatorAsync(SerializationContext)
Reads a value separator (comma).
public ValueTask ReadValueSeparatorAsync(SerializationContext context)Parameters
contextSerializationContextThe serialization context.
Returns
- ValueTask
A task representing the read.
ReturnReader(ref JsonReader)
Returns a synchronous reader previously obtained from this object, advancing this reader past the consumed bytes.
public void ReturnReader(ref JsonReader reader)Parameters
readerJsonReaderThe reader to return. It is reset to prevent reuse.
SkipValueAsync(SerializationContext)
Skips the next JSON value, discarding bytes as they are scanned so that a large skipped value does not need to be buffered in its entirety.
public ValueTask SkipValueAsync(SerializationContext context)Parameters
contextSerializationContextThe serialization context.
Returns
- ValueTask
A task that completes when the value has been skipped.
TryReadEndArrayAsync(SerializationContext)
Reads the end-of-array token if present. Honors trailing commas when enabled.
public ValueTask<bool> TryReadEndArrayAsync(SerializationContext context)Parameters
contextSerializationContextThe serialization context.
Returns
TryReadEndObjectAsync(SerializationContext)
Reads the end-of-object token if present. Honors trailing commas when enabled.
public ValueTask<bool> TryReadEndObjectAsync(SerializationContext context)Parameters
contextSerializationContextThe serialization context.
Returns
TryReadNullAsync(SerializationContext)
Reads and discards a leading null literal if present.
public ValueTask<bool> TryReadNullAsync(SerializationContext context)Parameters
contextSerializationContextThe serialization context.