Class JsonSerializer

Namespace

Nerdbank.Json

Assembly

Nerdbank.Json.dll

Serializes .NET values to JSON.

public record JsonSerializer : IEquatable<JsonSerializer>

Inheritance

object

JsonSerializer

Implements

IEquatable<JsonSerializer>

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

This type is immutable and thread-safe.

Synchronous serialization and deserialization failures are reported as JsonSerializationException. The original exception is available as the inner exception; cancellation and argument validation errors are not wrapped.

When targeting .NET Standard 2.0 or .NET Framework, some important methods are available only as extension methods, so make sure to have a using Nerdbank.Json; directive in your code file to see these.

Properties

AllowTrailingCommas

Gets a value indicating whether a trailing comma is permitted before the end of a JSON array or object during deserialization.

public bool AllowTrailingCommas { get; init; }

Property Value

bool

Remarks

The default value is false.

ComparerProvider

Gets the provider of IEqualityComparer<T> and IComparer<T> instances to use when instantiating collections that support them.

public IComparerProvider? ComparerProvider { get; init; }

Property Value

IComparerProvider

The default value is an instance of SecureComparerProvider, which provides hash collision resistance for improved security when deserializing untrusted data.

Remarks

This property may be cleared from its secure default for improved performance when deserializing trusted data.

ConverterFactories

Gets the runtime-registered converter factories that are consulted after Nerdbank.Json.JsonSerializerConfiguration.Converters and Nerdbank.Json.JsonSerializerConfiguration.ConverterTypes.

public IReadOnlyList<IJsonConverterFactory> ConverterFactories { get; init; }

Property Value

IReadOnlyList<IJsonConverterFactory>

ConverterTypes

Gets the runtime-registered converter types that take precedence after Nerdbank.Json.JsonSerializerConfiguration.Converters.

public JsonConverterTypeCollection ConverterTypes { get; init; }

Property Value

JsonConverterTypeCollection

Converters

Gets the runtime-registered converters that take precedence over built-in and shape-based converters.

public ConverterCollection Converters { get; init; }

Property Value

ConverterCollection

DeserializeDefaultValues

Gets the policy that determines how deserialization handles missing or null values.

public DeserializeDefaultValuesPolicy DeserializeDefaultValues { get; init; }

Property Value

DeserializeDefaultValuesPolicy

Remarks

The default value is Default.

DictionaryKeyNamingPolicy

Gets the transformation applied to dictionary keys during serialization and deserialization.

public JsonNamingPolicy? DictionaryKeyNamingPolicy { get; init; }

Property Value

JsonNamingPolicy

Remarks

The default value is null, which preserves dictionary keys as declared.

InternStrings

Gets a value indicating whether equal strings should share an instance during deserialization.

public bool InternStrings { get; init; }

Property Value

bool

Remarks

The default value is false. When enabled, strings with equal values within one deserialization operation are represented by the same string instance.

Interned strings are retained only for the operation's lifetime, so this setting does not retain strings across deserialization operations. It can reduce memory use when input repeats string values, at the cost of looking up each deserialized string in the operation's cache.

PreserveReferences

Gets the mode that preserves reference equality during serialization and deserialization.

public ReferencePreservationMode PreserveReferences { get; init; }

Property Value

ReferencePreservationMode

PropertyNameCaseInsensitive

Gets a value indicating whether JSON object property names are matched case-insensitively during deserialization.

public bool PropertyNameCaseInsensitive { get; init; }

Property Value

bool

Remarks

The default value is false.

PropertyNamingPolicy

Gets the transformation applied to object property names and enum value names during serialization and deserialization.

public JsonNamingPolicy? PropertyNamingPolicy { get; init; }

Property Value

JsonNamingPolicy

Remarks

The default value is CamelCase. Set this property to null to preserve declared property names and enum value names. Enum value names are transformed only when Nerdbank.Json.JsonSerializerConfiguration.SerializeEnumValuesByName is true.

ReadCommentHandling

Gets the policy for handling JSON comments during deserialization.

public JsonCommentHandling ReadCommentHandling { get; init; }

Property Value

JsonCommentHandling

Remarks

The default value is Disallow.

SerializeDefaultValues

Gets the policy that determines whether properties with default values are serialized.

public SerializeDefaultValuesPolicy SerializeDefaultValues { get; init; }

Property Value

SerializeDefaultValuesPolicy

Remarks

The default value is Always.

SerializeEnumValuesByName

Gets a value indicating whether enum values should be serialized by name rather than by numeric value when possible.

public bool SerializeEnumValuesByName { get; init; }

Property Value

bool

Remarks

The default value is false. When enabled, Nerdbank.Json.JsonSerializerConfiguration.PropertyNamingPolicy is applied to enum value names.

StartingContext

Gets the starting context to begin serializations and deserializations with.

public SerializationContext StartingContext { get; init; }

Property Value

SerializationContext

Unions

Gets the runtime union configuration that adds, replaces, extends, or disables shape-generated unions.

public JsonUnionConfiguration Unions { get; init; }

Property Value

JsonUnionConfiguration

The default value is Default.

WriteIndented

Gets a value indicating whether serialized JSON should be formatted with indentation and line breaks.

public bool WriteIndented { get; init; }

Property Value

bool

Remarks

The default value is false.

Methods

DeserializeArrayAsync<T>(PipeReader, ITypeShape<T>, CancellationToken)

Asynchronously streams the elements of a top-level JSON array, reading only enough to produce each element on demand.

public IAsyncEnumerable<T?> DeserializeArrayAsync<T>(PipeReader reader, ITypeShape<T> shape, CancellationToken cancellationToken = default)

Parameters

reader PipeReader

The pipe to read from. It is advanced but never completed by this method.

shape ITypeShape<T>

The shape of T.

cancellationToken CancellationToken

A cancellation token.

Returns

IAsyncEnumerable<T>

An asynchronous sequence of elements.

Type Parameters

T

The element type.

DeserializeArrayAsync<T>(PipeReader, CancellationToken)

Asynchronously streams the elements of a top-level JSON array, reading only enough to produce each element on demand.

public IAsyncEnumerable<T?> DeserializeArrayAsync<T>(PipeReader reader, CancellationToken cancellationToken = default) where T : IShapeable<T>

Parameters

reader PipeReader

The pipe to read from. It is advanced but never completed by this method.

cancellationToken CancellationToken

A cancellation token.

Returns

IAsyncEnumerable<T>

An asynchronous sequence of elements.

Type Parameters

T

The element type.

DeserializeArrayAsync<T>(Stream, ITypeShape<T>, CancellationToken)

Asynchronously streams the elements of a top-level JSON array from a stream.

public IAsyncEnumerable<T?> DeserializeArrayAsync<T>(Stream stream, ITypeShape<T> shape, CancellationToken cancellationToken = default)

Parameters

stream Stream

The stream to read from. It is read but not disposed or closed by this method.

shape ITypeShape<T>

The shape of T.

cancellationToken CancellationToken

A cancellation token.

Returns

IAsyncEnumerable<T>

An asynchronous sequence of elements.

Type Parameters

T

The element type.

DeserializeArrayAsync<T>(Stream, CancellationToken)

Asynchronously streams the elements of a top-level JSON array from a stream.

public IAsyncEnumerable<T?> DeserializeArrayAsync<T>(Stream stream, CancellationToken cancellationToken = default) where T : IShapeable<T>

Parameters

stream Stream

The stream to read from. It is read but not disposed or closed by this method.

cancellationToken CancellationToken

A cancellation token.

Returns

IAsyncEnumerable<T>

An asynchronous sequence of elements.

Type Parameters

T

The element type.

DeserializeArrayAtAsync<TElement>(PipeReader, JsonPath, ITypeShape<TElement>, MissingPathBehavior, CancellationToken)

Asynchronously streams the elements of a JSON array selected by a pre-parsed JsonPath inside an object or array envelope, parsing the preamble incrementally and draining the remainder of the envelope on completion.

public IAsyncEnumerable<TElement?> DeserializeArrayAtAsync<TElement>(PipeReader reader, JsonPath path, ITypeShape<TElement> elementShape, MissingPathBehavior missingBehavior = MissingPathBehavior.Throw, CancellationToken cancellationToken = default)

Parameters

reader PipeReader

The pipe to read from. It is advanced but never completed by this method.

path JsonPath

The pre-parsed path that selects the array. Names are the serialized (wire) names.

elementShape ITypeShape<TElement>

The shape of TElement.

missingBehavior MissingPathBehavior

Controls behavior when the path is not found.

cancellationToken CancellationToken

A cancellation token.

Returns

IAsyncEnumerable<TElement>

An asynchronous sequence of elements.

Type Parameters

TElement

The element type.

DeserializeArrayAtAsync<TElement>(Stream, JsonPath, ITypeShape<TElement>, MissingPathBehavior, CancellationToken)

Asynchronously streams the elements of a JSON array selected by a pre-parsed JsonPath from a stream.

public IAsyncEnumerable<TElement?> DeserializeArrayAtAsync<TElement>(Stream stream, JsonPath path, ITypeShape<TElement> elementShape, MissingPathBehavior missingBehavior = MissingPathBehavior.Throw, CancellationToken cancellationToken = default)

Parameters

stream Stream

The stream to read from. It is read but not disposed or closed by this method.

path JsonPath

The pre-parsed path that selects the array.

elementShape ITypeShape<TElement>

The shape of TElement.

missingBehavior MissingPathBehavior

Controls behavior when the path is not found.

cancellationToken CancellationToken

A cancellation token.

Returns

IAsyncEnumerable<TElement>

An asynchronous sequence of elements.

Type Parameters

TElement

The element type.

DeserializeArrayAtAsync<TRoot, TElement>(PipeReader, Expression<Func<TRoot, IEnumerable<TElement>>>, MissingPathBehavior, CancellationToken)

Asynchronously streams the elements of a JSON array selected by a member-access expression inside an object or array envelope. The expression is parsed but never compiled, so this overload is NativeAOT-safe and can traverse intermediate union or custom-converter representations.

public IAsyncEnumerable<TElement?> DeserializeArrayAtAsync<TRoot, TElement>(PipeReader reader, Expression<Func<TRoot, IEnumerable<TElement>>> path, MissingPathBehavior missingBehavior = MissingPathBehavior.Throw, CancellationToken cancellationToken = default) where TRoot : IShapeable<TRoot>

Parameters

reader PipeReader

The pipe to read from. It is advanced but never completed by this method.

path Expression<Func<TRoot, IEnumerable<TElement>>>

An expression such as x => x.Items selecting an IEnumerable<T>.

missingBehavior MissingPathBehavior

Controls behavior when the path is not found.

cancellationToken CancellationToken

A cancellation token.

Returns

IAsyncEnumerable<TElement>

An asynchronous sequence of elements.

Type Parameters

TRoot

The root document type.

TElement

The element type.

DeserializeArrayAtAsync<TRoot, TElement>(PipeReader, Expression<Func<TRoot, IEnumerable<TElement>>>, ITypeShape<TRoot>, MissingPathBehavior, CancellationToken)

Asynchronously streams the elements of a JSON array selected by a member-access expression inside an object or array envelope. The expression is parsed but never compiled, so this overload is NativeAOT-safe and can traverse intermediate union or custom-converter representations.

public IAsyncEnumerable<TElement?> DeserializeArrayAtAsync<TRoot, TElement>(PipeReader reader, Expression<Func<TRoot, IEnumerable<TElement>>> path, ITypeShape<TRoot> rootShape, MissingPathBehavior missingBehavior = MissingPathBehavior.Throw, CancellationToken cancellationToken = default)

Parameters

reader PipeReader

The pipe to read from. It is advanced but never completed by this method.

path Expression<Func<TRoot, IEnumerable<TElement>>>

An expression such as x => x.Items selecting an IEnumerable<T>.

rootShape ITypeShape<TRoot>

The shape of TRoot.

missingBehavior MissingPathBehavior

Controls behavior when the path is not found.

cancellationToken CancellationToken

A cancellation token.

Returns

IAsyncEnumerable<TElement>

An asynchronous sequence of elements.

Type Parameters

TRoot

The root document type.

TElement

The element type.

DeserializeArrayAtAsync<TRoot, TElement>(Stream, Expression<Func<TRoot, IEnumerable<TElement>>>, MissingPathBehavior, CancellationToken)

Asynchronously streams the elements of a JSON array selected by a member-access expression from a stream.

public IAsyncEnumerable<TElement?> DeserializeArrayAtAsync<TRoot, TElement>(Stream stream, Expression<Func<TRoot, IEnumerable<TElement>>> path, MissingPathBehavior missingBehavior = MissingPathBehavior.Throw, CancellationToken cancellationToken = default) where TRoot : IShapeable<TRoot>

Parameters

stream Stream

The stream to read from. It is read but not disposed or closed by this method.

path Expression<Func<TRoot, IEnumerable<TElement>>>

An expression selecting an IEnumerable<T>.

missingBehavior MissingPathBehavior

Controls behavior when the path is not found.

cancellationToken CancellationToken

A cancellation token.

Returns

IAsyncEnumerable<TElement>

An asynchronous sequence of elements.

Type Parameters

TRoot

The root document type.

TElement

The element type.

DeserializeArrayAtAsync<TRoot, TElement>(Stream, Expression<Func<TRoot, IEnumerable<TElement>>>, ITypeShape<TRoot>, MissingPathBehavior, CancellationToken)

Asynchronously streams the elements of a JSON array selected by a member-access expression from a stream.

public IAsyncEnumerable<TElement?> DeserializeArrayAtAsync<TRoot, TElement>(Stream stream, Expression<Func<TRoot, IEnumerable<TElement>>> path, ITypeShape<TRoot> rootShape, MissingPathBehavior missingBehavior = MissingPathBehavior.Throw, CancellationToken cancellationToken = default)

Parameters

stream Stream

The stream to read from. It is read but not disposed or closed by this method.

path Expression<Func<TRoot, IEnumerable<TElement>>>

An expression selecting an IEnumerable<T>.

rootShape ITypeShape<TRoot>

The shape of TRoot.

missingBehavior MissingPathBehavior

Controls behavior when the path is not found.

cancellationToken CancellationToken

A cancellation token.

Returns

IAsyncEnumerable<TElement>

An asynchronous sequence of elements.

Type Parameters

TRoot

The root document type.

TElement

The element type.

DeserializeAsync<T>(PipeReader, ITypeShape<T>, SerializationContext)

Deserializes a value from UTF-8 JSON read incrementally from a PipeReader using a caller-supplied starting context.

public ValueTask<T?> DeserializeAsync<T>(PipeReader reader, ITypeShape<T> shape, SerializationContext startingContext)

Parameters

reader PipeReader

The pipe to read from. It is advanced but never completed by this method.

shape ITypeShape<T>

The type shape describing T.

startingContext SerializationContext

The context to start this operation with, used instead of StartingContext. Its CancellationToken cancels the operation.

Returns

ValueTask<T>

A task whose result is the deserialized value.

Type Parameters

T

The type to deserialize.

Remarks

Use this overload to supply per-call state to converters via this[object].

Exceptions

ArgumentException

Thrown if startingContext belongs to an operation already in progress.

FormatException

Thrown if unexpected trailing data follows the value.

DeserializeAsync<T>(PipeReader, ITypeShape<T>, CancellationToken)

Deserializes a value from UTF-8 JSON read incrementally from a PipeReader.

public ValueTask<T?> DeserializeAsync<T>(PipeReader reader, ITypeShape<T> shape, CancellationToken cancellationToken = default)

Parameters

reader PipeReader

The pipe to read from. It is advanced but never completed by this method.

shape ITypeShape<T>

The type shape describing T.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask<T>

A task whose result is the deserialized value.

Type Parameters

T

The type to deserialize.

Exceptions

FormatException

Thrown if unexpected trailing data follows the value.

DeserializeAsync<T>(PipeReader, CancellationToken)

Deserializes a value from UTF-8 JSON read incrementally from a PipeReader.

public ValueTask<T?> DeserializeAsync<T>(PipeReader reader, CancellationToken cancellationToken = default) where T : IShapeable<T>

Parameters

reader PipeReader

The pipe to read from. It is advanced but never completed by this method.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask<T>

A task whose result is the deserialized value.

Type Parameters

T

The type to deserialize.

Exceptions

FormatException

Thrown if unexpected trailing data follows the value.

DeserializeAsync<T>(Stream, ITypeShape<T>, CancellationToken)

Deserializes a value from UTF-8 JSON read incrementally from a Stream.

public ValueTask<T?> DeserializeAsync<T>(Stream stream, ITypeShape<T> shape, CancellationToken cancellationToken = default)

Parameters

stream Stream

The source stream. It is read but not disposed or closed by this method.

shape ITypeShape<T>

The type shape describing T.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask<T>

A task whose result is the deserialized value.

Type Parameters

T

The type to deserialize.

DeserializeAsync<T>(Stream, CancellationToken)

Deserializes a value from UTF-8 JSON read incrementally from a Stream.

public ValueTask<T?> DeserializeAsync<T>(Stream stream, CancellationToken cancellationToken = default) where T : IShapeable<T>

Parameters

stream Stream

The source stream. It is read but not disposed or closed by this method.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask<T>

A task whose result is the deserialized value.

Type Parameters

T

The type to deserialize.

DeserializeAsync<T, TProvider>(PipeReader, CancellationToken)

Deserializes a value from UTF-8 JSON read incrementally from a PipeReader.

public ValueTask<T?> DeserializeAsync<T, TProvider>(PipeReader reader, CancellationToken cancellationToken = default) where TProvider : IShapeable<T>

Parameters

reader PipeReader

The pipe to read from. It is advanced but never completed by this method.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask<T>

A task whose result is the deserialized value.

Type Parameters

T

The type to deserialize.

TProvider

Exceptions

FormatException

Thrown if unexpected trailing data follows the value.

DeserializeAsync<T, TProvider>(Stream, CancellationToken)

Deserializes a value from UTF-8 JSON read incrementally from a Stream.

public ValueTask<T?> DeserializeAsync<T, TProvider>(Stream stream, CancellationToken cancellationToken = default) where TProvider : IShapeable<T>

Parameters

stream Stream

The source stream. It is read but not disposed or closed by this method.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask<T>

A task whose result is the deserialized value.

Type Parameters

T

The type to deserialize.

TProvider

DeserializeAt<TValue>(scoped in ReadOnlySequence<byte>, JsonPath, ITypeShape<TValue>, MissingPathBehavior, CancellationToken)

Deserializes only the value selected by a pre-parsed JsonPath from a possibly multi-segment UTF-8 buffer.

public TValue? DeserializeAt<TValue>(scoped in ReadOnlySequence<byte> utf8Json, JsonPath path, ITypeShape<TValue> targetShape, MissingPathBehavior missingBehavior = MissingPathBehavior.Throw, CancellationToken cancellationToken = default)

Parameters

utf8Json ReadOnlySequence<byte>

The UTF-8 JSON document, possibly spanning multiple buffer segments.

path JsonPath

The pre-parsed path that selects the value.

targetShape ITypeShape<TValue>

The shape of TValue.

missingBehavior MissingPathBehavior

Controls behavior when the path is not found.

cancellationToken CancellationToken

A cancellation token.

Returns

TValue

The deserialized value, or the default value when the path is missing and default behavior is selected.

Type Parameters

TValue

The type of the selected value.

DeserializeAt<TValue>(ReadOnlyMemory<byte>, JsonPath, ITypeShape<TValue>, MissingPathBehavior, CancellationToken)

Deserializes only the value selected by a pre-parsed JsonPath from a UTF-8 buffer.

public TValue? DeserializeAt<TValue>(ReadOnlyMemory<byte> utf8Json, JsonPath path, ITypeShape<TValue> targetShape, MissingPathBehavior missingBehavior = MissingPathBehavior.Throw, CancellationToken cancellationToken = default)

Parameters

utf8Json ReadOnlyMemory<byte>

The UTF-8 JSON document.

path JsonPath

The pre-parsed path that selects the value.

targetShape ITypeShape<TValue>

The shape of TValue.

missingBehavior MissingPathBehavior

Controls behavior when the path is not found.

cancellationToken CancellationToken

A cancellation token.

Returns

TValue

The deserialized value, or the default value when the path is missing and default behavior is selected.

Type Parameters

TValue

The type of the selected value.

DeserializeAt<TValue>(string, JsonPath, MissingPathBehavior, CancellationToken)

Deserializes only the value selected by a pre-parsed JsonPath, using the type's own shape.

public TValue? DeserializeAt<TValue>(string json, JsonPath path, MissingPathBehavior missingBehavior = MissingPathBehavior.Throw, CancellationToken cancellationToken = default) where TValue : IShapeable<TValue>

Parameters

json string

The JSON document.

path JsonPath

The pre-parsed path that selects the value.

missingBehavior MissingPathBehavior

Controls behavior when the path is not found.

cancellationToken CancellationToken

A cancellation token.

Returns

TValue

The deserialized value.

Type Parameters

TValue

The type of the selected value.

DeserializeAt<TValue>(string, JsonPath, ITypeShape<TValue>, MissingPathBehavior, CancellationToken)

Deserializes only the value selected by a pre-parsed JsonPath, skipping unrelated JSON.

public TValue? DeserializeAt<TValue>(string json, JsonPath path, ITypeShape<TValue> targetShape, MissingPathBehavior missingBehavior = MissingPathBehavior.Throw, CancellationToken cancellationToken = default)

Parameters

json string

The JSON document.

path JsonPath

The pre-parsed path that selects the value.

targetShape ITypeShape<TValue>

The shape of TValue.

missingBehavior MissingPathBehavior

Controls behavior when the path is not found.

cancellationToken CancellationToken

A cancellation token.

Returns

TValue

The deserialized value, or the default value if the path is missing and missingBehavior is ReturnDefault.

Type Parameters

TValue

The type of the selected value.

Remarks

The selected value is deserialized through the full converter graph, so naming policies, custom converters, and union envelopes remain correct for the target. Path segments navigate plain JSON objects and arrays; targeted deserialization is not supported when reference preservation is enabled.

DeserializeAt<TValue, TProvider>(string, JsonPath, MissingPathBehavior, CancellationToken)

Deserializes only the value selected by a pre-parsed JsonPath, using a witness type's shape.

public TValue? DeserializeAt<TValue, TProvider>(string json, JsonPath path, MissingPathBehavior missingBehavior = MissingPathBehavior.Throw, CancellationToken cancellationToken = default) where TProvider : IShapeable<TValue>

Parameters

json string

The JSON document.

path JsonPath

The pre-parsed path that selects the value.

missingBehavior MissingPathBehavior

Controls behavior when the path is not found.

cancellationToken CancellationToken

A cancellation token.

Returns

TValue

The deserialized value.

Type Parameters

TValue

The type of the selected value.

TProvider

A witness type that provides the shape for TValue.

DeserializeAt<TRoot, TValue>(string, Expression<Func<TRoot, TValue>>, MissingPathBehavior, CancellationToken)

Deserializes only the value selected by a member-access expression, using the root type's own shape.

public TValue? DeserializeAt<TRoot, TValue>(string json, Expression<Func<TRoot, TValue>> path, MissingPathBehavior missingBehavior = MissingPathBehavior.Throw, CancellationToken cancellationToken = default) where TRoot : IShapeable<TRoot>

Parameters

json string

The JSON document.

path Expression<Func<TRoot, TValue>>

An expression such as x => x.Items[3].Name that selects the value.

missingBehavior MissingPathBehavior

Controls behavior when the path is not found.

cancellationToken CancellationToken

A cancellation token.

Returns

TValue

The deserialized value.

Type Parameters

TRoot

The type of the root document.

TValue

The type of the selected value.

DeserializeAt<TRoot, TValue>(string, Expression<Func<TRoot, TValue>>, ITypeShape<TRoot>, MissingPathBehavior, CancellationToken)

Deserializes only the value selected by a member-access expression, skipping unrelated JSON.

public TValue? DeserializeAt<TRoot, TValue>(string json, Expression<Func<TRoot, TValue>> path, ITypeShape<TRoot> rootShape, MissingPathBehavior missingBehavior = MissingPathBehavior.Throw, CancellationToken cancellationToken = default)

Parameters

json string

The JSON document.

path Expression<Func<TRoot, TValue>>

An expression such as x => x.Items[3].Name that selects the value.

rootShape ITypeShape<TRoot>

The shape of TRoot.

missingBehavior MissingPathBehavior

Controls behavior when the path is not found.

cancellationToken CancellationToken

A cancellation token.

Returns

TValue

The deserialized value.

Type Parameters

TRoot

The type of the root document.

TValue

The type of the selected value.

Remarks

The expression is parsed but never compiled, so this overload is NativeAOT-safe. CLR member names are translated to serialized names using the configured naming policies. Array and dictionary indices must be compile-time constants; unsupported expressions are rejected before any JSON is read.

DeserializeJsonValue(scoped in ReadOnlySequence<byte>, CancellationToken)

Deserializes UTF-8 JSON, possibly spanning multiple segments, into the native JsonValue document object model.

public JsonValue? DeserializeJsonValue(scoped in ReadOnlySequence<byte> utf8Json, CancellationToken cancellationToken = default)

Parameters

utf8Json ReadOnlySequence<byte>

The UTF-8 JSON bytes, possibly spanning multiple segments.

cancellationToken CancellationToken

A cancellation token.

Returns

JsonValue

The parsed value.

DeserializeJsonValue(Stream, CancellationToken)

Deserializes UTF-8 JSON from a stream into the native JsonValue document object model.

public JsonValue? DeserializeJsonValue(Stream stream, CancellationToken cancellationToken = default)

Parameters

stream Stream

The stream. It is read but not disposed by this method.

cancellationToken CancellationToken

A cancellation token.

Returns

JsonValue

The parsed value.

DeserializeJsonValue(ReadOnlyMemory<byte>, CancellationToken)

Deserializes UTF-8 JSON into the native JsonValue document object model.

public JsonValue? DeserializeJsonValue(ReadOnlyMemory<byte> utf8Json, CancellationToken cancellationToken = default)

Parameters

utf8Json ReadOnlyMemory<byte>

The UTF-8 JSON bytes.

cancellationToken CancellationToken

A cancellation token.

Returns

JsonValue

The parsed value.

DeserializeJsonValue(string, CancellationToken)

Deserializes any JSON text into the native, dependency-free JsonValue document object model.

public JsonValue? DeserializeJsonValue(string json, CancellationToken cancellationToken = default)

Parameters

json string

The JSON text.

cancellationToken CancellationToken

A cancellation token.

Returns

JsonValue

The parsed value.

Remarks

This entry point does not require a static model or a generated shape, and it neither roots System.Text.Json nor uses reflection, so it keeps the default serializer trimming- and NativeAOT-safe.

DeserializeJsonValueAsync(PipeReader, CancellationToken)

Deserializes UTF-8 JSON from a PipeReader into the native JsonValue document object model, reading incrementally without buffering the whole document.

public ValueTask<JsonValue?> DeserializeJsonValueAsync(PipeReader reader, CancellationToken cancellationToken = default)

Parameters

reader PipeReader

The pipe. It is advanced but not completed by this method.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask<JsonValue>

The parsed value.

DeserializeJsonValueAsync(Stream, CancellationToken)

Deserializes JSON from a Stream into the native JsonValue document object model.

public ValueTask<JsonValue?> DeserializeJsonValueAsync(Stream stream, CancellationToken cancellationToken = default)

Parameters

stream Stream

The stream. It is read but not disposed by this method.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask<JsonValue>

The parsed value.

DeserializeNewlineDelimitedAsync<T>(PipeReader, ITypeShape<T>, CancellationToken)

Asynchronously streams the values of a newline-delimited JSON (NDJSON / JSON Lines) document, where each value is framed on its own line.

public IAsyncEnumerable<T?> DeserializeNewlineDelimitedAsync<T>(PipeReader reader, ITypeShape<T> shape, CancellationToken cancellationToken = default)

Parameters

reader PipeReader

The pipe to read from. It is advanced but never completed by this method.

shape ITypeShape<T>

The shape of T.

cancellationToken CancellationToken

A cancellation token.

Returns

IAsyncEnumerable<T>

An asynchronous sequence of values.

Type Parameters

T

The value type.

Exceptions

FormatException

Thrown if two values are not separated by a line terminator.

DeserializeNewlineDelimitedAsync<T>(PipeReader, CancellationToken)

Asynchronously streams the values of a newline-delimited JSON (NDJSON / JSON Lines) document, where each value is framed on its own line.

public IAsyncEnumerable<T?> DeserializeNewlineDelimitedAsync<T>(PipeReader reader, CancellationToken cancellationToken = default) where T : IShapeable<T>

Parameters

reader PipeReader

The pipe to read from. It is advanced but never completed by this method.

cancellationToken CancellationToken

A cancellation token.

Returns

IAsyncEnumerable<T>

An asynchronous sequence of values.

Type Parameters

T

The value type.

Exceptions

FormatException

Thrown if two values are not separated by a line terminator.

DeserializeNewlineDelimitedAsync<T>(Stream, ITypeShape<T>, CancellationToken)

Asynchronously streams the values of a newline-delimited JSON document from a stream.

public IAsyncEnumerable<T?> DeserializeNewlineDelimitedAsync<T>(Stream stream, ITypeShape<T> shape, CancellationToken cancellationToken = default)

Parameters

stream Stream

The stream to read from. It is read but not disposed or closed by this method.

shape ITypeShape<T>

The shape of T.

cancellationToken CancellationToken

A cancellation token.

Returns

IAsyncEnumerable<T>

An asynchronous sequence of values.

Type Parameters

T

The value type.

DeserializeNewlineDelimitedAsync<T>(Stream, CancellationToken)

Asynchronously streams the values of a newline-delimited JSON document from a stream.

public IAsyncEnumerable<T?> DeserializeNewlineDelimitedAsync<T>(Stream stream, CancellationToken cancellationToken = default) where T : IShapeable<T>

Parameters

stream Stream

The stream to read from. It is read but not disposed or closed by this method.

cancellationToken CancellationToken

A cancellation token.

Returns

IAsyncEnumerable<T>

An asynchronous sequence of values.

Type Parameters

T

The value type.

DeserializeObject(ref JsonReader, ITypeShape, SerializationContext)

Deserializes an untyped value from JSON using the specified type shape and a caller-supplied starting context.

public object? DeserializeObject(ref JsonReader reader, ITypeShape shape, SerializationContext startingContext)

Parameters

reader JsonReader

The reader to deserialize the value from.

shape ITypeShape

The type shape describing the structure of the value to deserialize.

startingContext SerializationContext

The context to start this operation with, used instead of StartingContext. Its CancellationToken cancels the operation.

Returns

object

The deserialized value, or null if the JSON represents a null value.

Exceptions

ArgumentException

Thrown if startingContext belongs to an operation already in progress.

DeserializeObject(ref JsonReader, ITypeShape, CancellationToken)

Deserializes an untyped value from JSON using the specified type shape.

public object? DeserializeObject(ref JsonReader reader, ITypeShape shape, CancellationToken cancellationToken = default)

Parameters

reader JsonReader

The reader to deserialize the value from.

shape ITypeShape

The type shape describing the structure of the value to deserialize.

cancellationToken CancellationToken

A token to cancel the operation.

Returns

object

The deserialized value, or null if the JSON represents a null value.

DeserializeObject(scoped in ReadOnlySequence<byte>, ITypeShape, CancellationToken)

Deserializes an untyped value from JSON using the specified type shape.

public object? DeserializeObject(scoped in ReadOnlySequence<byte> buffer, ITypeShape shape, CancellationToken cancellationToken = default)

Parameters

buffer ReadOnlySequence<byte>

The JSON to deserialize from.

shape ITypeShape

The type shape describing the structure of the value to deserialize.

cancellationToken CancellationToken

A token to cancel the operation.

Returns

object

The deserialized value, or null if the JSON represents a null value.

DeserializeObject(Stream, ITypeShape, CancellationToken)

Deserializes an untyped value from JSON using the specified type shape.

public object? DeserializeObject(Stream stream, ITypeShape shape, CancellationToken cancellationToken = default)

Parameters

stream Stream

The JSON stream.

shape ITypeShape

The type shape describing the structure of the value to deserialize.

cancellationToken CancellationToken

A token to cancel the operation.

Returns

object

The deserialized value, or null if the JSON represents a null value.

DeserializeObject(ReadOnlyMemory<byte>, ITypeShape, CancellationToken)

Deserializes an untyped value from JSON using the specified type shape.

public object? DeserializeObject(ReadOnlyMemory<byte> buffer, ITypeShape shape, CancellationToken cancellationToken = default)

Parameters

buffer ReadOnlyMemory<byte>

shape ITypeShape

The type shape describing the structure of the value to deserialize.

cancellationToken CancellationToken

A token to cancel the operation.

Returns

object

The deserialized value, or null if the JSON represents a null value.

DeserializeObject(string, ITypeShape, CancellationToken)

Deserializes an untyped value from JSON using the specified type shape.

public object? DeserializeObject(string json, ITypeShape shape, CancellationToken cancellationToken = default)

Parameters

json string

shape ITypeShape

The type shape describing the structure of the value to deserialize.

cancellationToken CancellationToken

A token to cancel the operation.

Returns

object

The deserialized value, or null if the JSON represents a null value.

Deserialize<T>(ref JsonReader, ITypeShape<T>, SerializationContext)

Deserializes a value from JSON using the specified type shape and a caller-supplied starting context.

public T? Deserialize<T>(ref JsonReader reader, ITypeShape<T> shape, SerializationContext startingContext)

Parameters

reader JsonReader

The reader to deserialize the value from.

shape ITypeShape<T>

The type shape describing the structure of T.

startingContext SerializationContext

The context to start this operation with, used instead of StartingContext. Its CancellationToken cancels the operation.

Returns

T

The deserialized value, or null if the JSON represents a null value.

Type Parameters

T

The type of value to deserialize.

Remarks

Use this overload to supply per-call state to converters via this[object].

Exceptions

ArgumentException

Thrown if startingContext belongs to an operation already in progress.

Deserialize<T>(ref JsonReader, ITypeShape<T>, CancellationToken)

Deserializes a value from JSON using the specified type shape.

public T? Deserialize<T>(ref JsonReader reader, ITypeShape<T> shape, CancellationToken cancellationToken = default)

Parameters

reader JsonReader

The reader to deserialize the value from.

shape ITypeShape<T>

The type shape describing the structure of T.

cancellationToken CancellationToken

A token to cancel the operation.

Returns

T

The deserialized value, or null if the JSON represents a null value.

Type Parameters

T

The type of value to deserialize.

Deserialize<T>(ref JsonReader, CancellationToken)

Deserializes a value from JSON using the specified type shape.

[ExcludeFromCodeCoverage]
public T? Deserialize<T>(ref JsonReader reader, CancellationToken cancellationToken = default) where T : IShapeable<T>

Parameters

reader JsonReader

The reader to deserialize the value from.

cancellationToken CancellationToken

A token to cancel the operation.

Returns

T

The deserialized value, or null if the JSON represents a null value.

Type Parameters

T

The type of value to deserialize.

Deserialize<T>(scoped in ReadOnlySequence<byte>, ITypeShape<T>, CancellationToken)

Deserializes a value from JSON using the specified type shape.

public T? Deserialize<T>(scoped in ReadOnlySequence<byte> buffer, ITypeShape<T> shape, CancellationToken cancellationToken = default)

Parameters

buffer ReadOnlySequence<byte>

The msgpack to deserialize from.

shape ITypeShape<T>

The type shape describing the structure of T.

cancellationToken CancellationToken

A token to cancel the operation.

Returns

T

The deserialized value, or null if the JSON represents a null value.

Type Parameters

T

The type of value to deserialize.

Deserialize<T>(scoped in ReadOnlySequence<byte>, CancellationToken)

Deserializes a value from JSON using the specified type shape.

[ExcludeFromCodeCoverage]
public T? Deserialize<T>(scoped in ReadOnlySequence<byte> bytes, CancellationToken cancellationToken = default) where T : IShapeable<T>

Parameters

bytes ReadOnlySequence<byte>

cancellationToken CancellationToken

A token to cancel the operation.

Returns

T

The deserialized value, or null if the JSON represents a null value.

Type Parameters

T

The type of value to deserialize.

Deserialize<T>(Stream, ITypeShape<T>, CancellationToken)

Deserializes UTF-8 JSON from a stream.

public T? Deserialize<T>(Stream stream, ITypeShape<T> shape, CancellationToken cancellationToken = default)

Parameters

stream Stream

The JSON stream.

shape ITypeShape<T>

The type shape describing T.

cancellationToken CancellationToken

A cancellation token.

Returns

T

The deserialized value.

Type Parameters

T

The type to deserialize.

Deserialize<T>(Stream, CancellationToken)

Deserializes UTF-8 JSON from a stream.

[ExcludeFromCodeCoverage]
public T? Deserialize<T>(Stream stream, CancellationToken cancellationToken = default) where T : IShapeable<T>

Parameters

stream Stream

The JSON stream.

cancellationToken CancellationToken

A cancellation token.

Returns

T

The deserialized value.

Type Parameters

T

The type to deserialize.

Deserialize<T>(ReadOnlyMemory<byte>, ITypeShape<T>, CancellationToken)

Deserializes a value from JSON using the specified type shape.

public T? Deserialize<T>(ReadOnlyMemory<byte> buffer, ITypeShape<T> shape, CancellationToken cancellationToken = default)

Parameters

buffer ReadOnlyMemory<byte>

The msgpack to deserialize from.

shape ITypeShape<T>

The type shape describing the structure of T.

cancellationToken CancellationToken

A token to cancel the operation.

Returns

T

The deserialized value, or null if the JSON represents a null value.

Type Parameters

T

The type of value to deserialize.

Deserialize<T>(ReadOnlyMemory<byte>, CancellationToken)

Deserializes a value from JSON using the specified type shape.

[ExcludeFromCodeCoverage]
public T? Deserialize<T>(ReadOnlyMemory<byte> bytes, CancellationToken cancellationToken = default) where T : IShapeable<T>

Parameters

bytes ReadOnlyMemory<byte>

cancellationToken CancellationToken

A token to cancel the operation.

Returns

T

The deserialized value, or null if the JSON represents a null value.

Type Parameters

T

The type of value to deserialize.

Deserialize<T>(string, ITypeShape<T>, CancellationToken)

Deserializes JSON text.

public T? Deserialize<T>(string json, ITypeShape<T> shape, CancellationToken cancellationToken = default)

Parameters

json string

The JSON text.

shape ITypeShape<T>

The type shape describing T.

cancellationToken CancellationToken

A cancellation token.

Returns

T

The deserialized value.

Type Parameters

T

The type to deserialize.

Deserialize<T>(string, CancellationToken)

Deserializes JSON text.

[ExcludeFromCodeCoverage]
public T? Deserialize<T>(string json, CancellationToken cancellationToken = default) where T : IShapeable<T>

Parameters

json string

The JSON text.

cancellationToken CancellationToken

A cancellation token.

Returns

T

The deserialized value.

Type Parameters

T

The type to deserialize.

Deserialize<T, TProvider>(ref JsonReader, CancellationToken)

Deserializes a value from JSON using the specified type shape.

[ExcludeFromCodeCoverage]
public T? Deserialize<T, TProvider>(ref JsonReader reader, CancellationToken cancellationToken = default) where TProvider : IShapeable<T>

Parameters

reader JsonReader

The reader to deserialize the value from.

cancellationToken CancellationToken

A token to cancel the operation.

Returns

T

The deserialized value, or null if the JSON represents a null value.

Type Parameters

T

The type of value to deserialize.

TProvider

Deserialize<T, TProvider>(scoped in ReadOnlySequence<byte>, CancellationToken)

Deserializes a value from JSON using the specified type shape.

[ExcludeFromCodeCoverage]
public T? Deserialize<T, TProvider>(scoped in ReadOnlySequence<byte> bytes, CancellationToken cancellationToken = default) where TProvider : IShapeable<T>

Parameters

bytes ReadOnlySequence<byte>

cancellationToken CancellationToken

A token to cancel the operation.

Returns

T

The deserialized value, or null if the JSON represents a null value.

Type Parameters

T

The type of value to deserialize.

TProvider

Deserialize<T, TProvider>(Stream, CancellationToken)

Deserializes UTF-8 JSON from a stream.

[ExcludeFromCodeCoverage]
public T? Deserialize<T, TProvider>(Stream stream, CancellationToken cancellationToken = default) where TProvider : IShapeable<T>

Parameters

stream Stream

The JSON stream.

cancellationToken CancellationToken

A cancellation token.

Returns

T

The deserialized value.

Type Parameters

T

The type to deserialize.

TProvider

Deserialize<T, TProvider>(ReadOnlyMemory<byte>, CancellationToken)

Deserializes a value from JSON using the specified type shape.

[ExcludeFromCodeCoverage]
public T? Deserialize<T, TProvider>(ReadOnlyMemory<byte> bytes, CancellationToken cancellationToken = default) where TProvider : IShapeable<T>

Parameters

bytes ReadOnlyMemory<byte>

cancellationToken CancellationToken

A token to cancel the operation.

Returns

T

The deserialized value, or null if the JSON represents a null value.

Type Parameters

T

The type of value to deserialize.

TProvider

Deserialize<T, TProvider>(string, CancellationToken)

Deserializes JSON text.

[ExcludeFromCodeCoverage]
public T? Deserialize<T, TProvider>(string json, CancellationToken cancellationToken = default) where TProvider : IShapeable<T>

Parameters

json string

The JSON text.

cancellationToken CancellationToken

A cancellation token.

Returns

T

The deserialized value.

Type Parameters

T

The type to deserialize.

TProvider

GetJsonSchema(ITypeShape)

Produces a JSON Schema (draft 2020-12 by default) document that describes how this serializer represents the given type.

public string GetJsonSchema(ITypeShape typeShape)

Parameters

typeShape ITypeShape

The shape of the type.

Returns

string

The JSON Schema document as a JSON string.

Remarks

The schema reflects the effective configuration, including the property naming policy, enum-by-name serialization, reference preservation, and runtime union configuration. Custom converters that do not override GetJsonSchema(JsonSchemaContext, ITypeShape) produce a permissive schema annotated with a conspicuous comment rather than false precision.

GetJsonSchema(ITypeShape, JsonSchemaOptions)

Produces a JSON Schema document that describes how this serializer represents the given type.

public string GetJsonSchema(ITypeShape typeShape, JsonSchemaOptions options)

Parameters

typeShape ITypeShape

The shape of the type.

options JsonSchemaOptions

The schema generation options.

Returns

string

The JSON Schema document as a JSON string.

Exceptions

ArgumentOutOfRangeException

The requested dialect is not supported.

GetJsonSchema<T>()

Produces a JSON Schema (draft 2020-12 by default) document that describes how this serializer represents the given type.

public string GetJsonSchema<T>() where T : IShapeable<T>

Returns

string

The JSON Schema document as a JSON string.

Type Parameters

T

The type to describe.

Remarks

The schema reflects the effective configuration, including the property naming policy, enum-by-name serialization, reference preservation, and runtime union configuration. Custom converters that do not override GetJsonSchema(JsonSchemaContext, ITypeShape) produce a permissive schema annotated with a conspicuous comment rather than false precision.

GetJsonSchema<T>(JsonSchemaOptions)

Produces a JSON Schema document using the specified options.

public string GetJsonSchema<T>(JsonSchemaOptions options) where T : IShapeable<T>

Parameters

options JsonSchemaOptions

The schema generation options.

Returns

string

The JSON Schema document as a JSON string.

Type Parameters

T

The type to describe.

GetJsonSchema<T>(ITypeShape<T>)

Produces a JSON Schema (draft 2020-12 by default) document that describes how this serializer represents the given type.

public string GetJsonSchema<T>(ITypeShape<T> shape)

Parameters

shape ITypeShape<T>

The shape of the type.

Returns

string

The JSON Schema document as a JSON string.

Type Parameters

T

The type to describe.

Remarks

The schema reflects the effective configuration, including the property naming policy, enum-by-name serialization, reference preservation, and runtime union configuration. Custom converters that do not override GetJsonSchema(JsonSchemaContext, ITypeShape) produce a permissive schema annotated with a conspicuous comment rather than false precision.

GetJsonSchema<T>(ITypeShape<T>, JsonSchemaOptions)

Produces a JSON Schema document that describes how this serializer represents the given type.

public string GetJsonSchema<T>(ITypeShape<T> shape, JsonSchemaOptions options)

Parameters

shape ITypeShape<T>

The shape of the type.

options JsonSchemaOptions

The schema generation options.

Returns

string

The JSON Schema document as a JSON string.

Type Parameters

T

The type to describe.

Exceptions

ArgumentOutOfRangeException

The requested dialect is not supported.

GetJsonSchema<T, TProvider>()

Produces a JSON Schema document that describes how this serializer represents T, using a witness type for the shape.

public string GetJsonSchema<T, TProvider>() where TProvider : IShapeable<T>

Returns

string

The JSON Schema document as a JSON string.

Type Parameters

T

The type to describe.

TProvider

A witness type that provides the shape for T.

GetJsonSchema<T, TProvider>(JsonSchemaOptions)

Produces a JSON Schema document using the specified options and witness type.

public string GetJsonSchema<T, TProvider>(JsonSchemaOptions options) where TProvider : IShapeable<T>

Parameters

options JsonSchemaOptions

The schema generation options.

Returns

string

The JSON Schema document as a JSON string.

Type Parameters

T

The type to describe.

TProvider

A witness type that provides the shape for T.

SerializeArrayAsync<T>(PipeWriter, IAsyncEnumerable<T>, ITypeShape<T>, CancellationToken)

Asynchronously serializes an IAsyncEnumerable<T> as a top-level JSON array, writing elements as they are produced with bounded memory and backpressure.

public ValueTask SerializeArrayAsync<T>(PipeWriter writer, IAsyncEnumerable<T> values, ITypeShape<T> shape, CancellationToken cancellationToken = default)

Parameters

writer PipeWriter

The pipe to write to. It is flushed but never completed by this method.

values IAsyncEnumerable<T>

The asynchronous source of elements.

shape ITypeShape<T>

The shape of T.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask

A task tracking the serialization.

Type Parameters

T

The element type.

SerializeArrayAsync<T>(PipeWriter, IAsyncEnumerable<T>, CancellationToken)

Asynchronously serializes an IAsyncEnumerable<T> as a top-level JSON array, writing elements as they are produced with bounded memory and backpressure.

public ValueTask SerializeArrayAsync<T>(PipeWriter writer, IAsyncEnumerable<T> values, CancellationToken cancellationToken = default) where T : IShapeable<T>

Parameters

writer PipeWriter

The pipe to write to. It is flushed but never completed by this method.

values IAsyncEnumerable<T>

The asynchronous source of elements.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask

A task tracking the serialization.

Type Parameters

T

The element type.

SerializeArrayAsync<T>(Stream, IAsyncEnumerable<T>, ITypeShape<T>, CancellationToken)

Asynchronously serializes an IAsyncEnumerable<T> as a top-level JSON array to a stream.

public ValueTask SerializeArrayAsync<T>(Stream stream, IAsyncEnumerable<T> values, ITypeShape<T> shape, CancellationToken cancellationToken = default)

Parameters

stream Stream

The stream to write to. It is flushed but not disposed or closed by this method.

values IAsyncEnumerable<T>

The asynchronous source of elements.

shape ITypeShape<T>

The shape of T.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask

A task tracking the serialization.

Type Parameters

T

The element type.

SerializeArrayAsync<T>(Stream, IAsyncEnumerable<T>, CancellationToken)

Asynchronously serializes an IAsyncEnumerable<T> as a top-level JSON array to a stream.

public ValueTask SerializeArrayAsync<T>(Stream stream, IAsyncEnumerable<T> values, CancellationToken cancellationToken = default) where T : IShapeable<T>

Parameters

stream Stream

The stream to write to. It is flushed but not disposed or closed by this method.

values IAsyncEnumerable<T>

The asynchronous source of elements.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask

A task tracking the serialization.

Type Parameters

T

The element type.

SerializeAsync<T>(PipeWriter, T?, ITypeShape<T>, SerializationContext)

Serializes a value as UTF-8 JSON to a PipeWriter incrementally using a caller-supplied starting context, flushing periodically so large graphs are written with bounded memory and backpressure.

public ValueTask SerializeAsync<T>(PipeWriter writer, T? value, ITypeShape<T> shape, SerializationContext startingContext)

Parameters

writer PipeWriter

The pipe to write to. It is flushed but never completed by this method.

value T

The value to serialize.

shape ITypeShape<T>

The type shape describing T.

startingContext SerializationContext

The context to start this operation with, used instead of StartingContext. Its CancellationToken cancels the operation.

Returns

ValueTask

A task tracking the asynchronous serialization.

Type Parameters

T

The type of value to serialize.

Remarks

Use this overload to supply per-call state to converters via this[object].

Exceptions

ArgumentException

Thrown if startingContext belongs to an operation already in progress.

SerializeAsync<T>(PipeWriter, T?, ITypeShape<T>, CancellationToken)

Serializes a value as UTF-8 JSON to a PipeWriter incrementally, flushing periodically so large graphs are written with bounded memory and backpressure.

public ValueTask SerializeAsync<T>(PipeWriter writer, T? value, ITypeShape<T> shape, CancellationToken cancellationToken = default)

Parameters

writer PipeWriter

The pipe to write to. It is flushed but never completed by this method.

value T

The value to serialize.

shape ITypeShape<T>

The type shape describing T.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask

A task tracking the asynchronous serialization.

Type Parameters

T

The type of value to serialize.

SerializeAsync<T>(PipeWriter, T?, CancellationToken)

Serializes a value as UTF-8 JSON to a PipeWriter incrementally, flushing periodically so large graphs are written with bounded memory and backpressure.

public ValueTask SerializeAsync<T>(PipeWriter writer, T? value, CancellationToken cancellationToken = default) where T : IShapeable<T>

Parameters

writer PipeWriter

The pipe to write to. It is flushed but never completed by this method.

value T

The value to serialize.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask

A task tracking the asynchronous serialization.

Type Parameters

T

The type of value to serialize.

SerializeAsync<T>(Stream, T?, ITypeShape<T>, CancellationToken)

Serializes a value as UTF-8 JSON to a Stream incrementally.

public ValueTask SerializeAsync<T>(Stream stream, T? value, ITypeShape<T> shape, CancellationToken cancellationToken = default)

Parameters

stream Stream

The destination stream. It is flushed but not disposed or closed by this method.

value T

The value to serialize.

shape ITypeShape<T>

The type shape describing T.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask

A task tracking the asynchronous serialization.

Type Parameters

T

The type of value to serialize.

SerializeAsync<T>(Stream, T?, CancellationToken)

Serializes a value as UTF-8 JSON to a Stream incrementally.

public ValueTask SerializeAsync<T>(Stream stream, T? value, CancellationToken cancellationToken = default) where T : IShapeable<T>

Parameters

stream Stream

The destination stream. It is flushed but not disposed or closed by this method.

value T

The value to serialize.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask

A task tracking the asynchronous serialization.

Type Parameters

T

The type of value to serialize.

SerializeAsync<T, TProvider>(PipeWriter, T?, CancellationToken)

Serializes a value as UTF-8 JSON to a PipeWriter incrementally, flushing periodically so large graphs are written with bounded memory and backpressure.

public ValueTask SerializeAsync<T, TProvider>(PipeWriter writer, T? value, CancellationToken cancellationToken = default) where TProvider : IShapeable<T>

Parameters

writer PipeWriter

The pipe to write to. It is flushed but never completed by this method.

value T

The value to serialize.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask

A task tracking the asynchronous serialization.

Type Parameters

T

The type of value to serialize.

TProvider

SerializeAsync<T, TProvider>(Stream, T?, CancellationToken)

Serializes a value as UTF-8 JSON to a Stream incrementally.

public ValueTask SerializeAsync<T, TProvider>(Stream stream, T? value, CancellationToken cancellationToken = default) where TProvider : IShapeable<T>

Parameters

stream Stream

The destination stream. It is flushed but not disposed or closed by this method.

value T

The value to serialize.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask

A task tracking the asynchronous serialization.

Type Parameters

T

The type of value to serialize.

TProvider

SerializeJsonValue(JsonValue?, CancellationToken)

Serializes a JsonValue to JSON text.

public string SerializeJsonValue(JsonValue? value, CancellationToken cancellationToken = default)

Parameters

value JsonValue

The value to serialize.

cancellationToken CancellationToken

A cancellation token.

Returns

string

The serialized JSON text.

SerializeJsonValue(IBufferWriter<byte>, JsonValue?, CancellationToken)

Serializes a JsonValue as UTF-8 JSON to a buffer.

public void SerializeJsonValue(IBufferWriter<byte> writer, JsonValue? value, CancellationToken cancellationToken = default)

Parameters

writer IBufferWriter<byte>

The destination buffer.

value JsonValue

The value to serialize.

cancellationToken CancellationToken

A cancellation token.

SerializeJsonValue(Stream, JsonValue?, CancellationToken)

Serializes a JsonValue as UTF-8 JSON to a stream.

public void SerializeJsonValue(Stream stream, JsonValue? value, CancellationToken cancellationToken = default)

Parameters

stream Stream

The destination stream. It is flushed but not disposed by this method.

value JsonValue

The value to serialize.

cancellationToken CancellationToken

A cancellation token.

SerializeJsonValueAsync(PipeWriter, JsonValue?, CancellationToken)

Serializes a JsonValue as UTF-8 JSON to a PipeWriter incrementally.

public ValueTask SerializeJsonValueAsync(PipeWriter writer, JsonValue? value, CancellationToken cancellationToken = default)

Parameters

writer PipeWriter

The pipe. It is flushed but not completed by this method.

value JsonValue

The value to serialize.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask

A task tracking the serialization.

SerializeJsonValueAsync(Stream, JsonValue?, CancellationToken)

Serializes a JsonValue document object model to a Stream.

public ValueTask SerializeJsonValueAsync(Stream stream, JsonValue? value, CancellationToken cancellationToken = default)

Parameters

stream Stream

The destination stream. It is flushed but not disposed by this method.

value JsonValue

The value to serialize.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask

A task that completes when serialization finishes.

SerializeNewlineDelimitedAsync<T>(PipeWriter, IAsyncEnumerable<T>, ITypeShape<T>, CancellationToken)

Asynchronously serializes an IAsyncEnumerable<T> as newline-delimited JSON (one value per line).

public ValueTask SerializeNewlineDelimitedAsync<T>(PipeWriter writer, IAsyncEnumerable<T> values, ITypeShape<T> shape, CancellationToken cancellationToken = default)

Parameters

writer PipeWriter

The pipe to write to. It is flushed but never completed by this method.

values IAsyncEnumerable<T>

The asynchronous source of values.

shape ITypeShape<T>

The shape of T.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask

A task tracking the serialization.

Type Parameters

T

The value type.

SerializeNewlineDelimitedAsync<T>(PipeWriter, IAsyncEnumerable<T>, CancellationToken)

Asynchronously serializes an IAsyncEnumerable<T> as newline-delimited JSON (one value per line).

public ValueTask SerializeNewlineDelimitedAsync<T>(PipeWriter writer, IAsyncEnumerable<T> values, CancellationToken cancellationToken = default) where T : IShapeable<T>

Parameters

writer PipeWriter

The pipe to write to. It is flushed but never completed by this method.

values IAsyncEnumerable<T>

The asynchronous source of values.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask

A task tracking the serialization.

Type Parameters

T

The value type.

SerializeNewlineDelimitedAsync<T>(Stream, IAsyncEnumerable<T>, ITypeShape<T>, CancellationToken)

Asynchronously serializes an IAsyncEnumerable<T> as newline-delimited JSON to a stream.

public ValueTask SerializeNewlineDelimitedAsync<T>(Stream stream, IAsyncEnumerable<T> values, ITypeShape<T> shape, CancellationToken cancellationToken = default)

Parameters

stream Stream

The stream to write to. It is flushed but not disposed or closed by this method.

values IAsyncEnumerable<T>

The asynchronous source of values.

shape ITypeShape<T>

The shape of T.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask

A task tracking the serialization.

Type Parameters

T

The value type.

SerializeNewlineDelimitedAsync<T>(Stream, IAsyncEnumerable<T>, CancellationToken)

Asynchronously serializes an IAsyncEnumerable<T> as newline-delimited JSON to a stream.

public ValueTask SerializeNewlineDelimitedAsync<T>(Stream stream, IAsyncEnumerable<T> values, CancellationToken cancellationToken = default) where T : IShapeable<T>

Parameters

stream Stream

The stream to write to. It is flushed but not disposed or closed by this method.

values IAsyncEnumerable<T>

The asynchronous source of values.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask

A task tracking the serialization.

Type Parameters

T

The value type.

SerializeObject(ref JsonWriter, object?, ITypeShape, SerializationContext)

Serializes an untyped value to JSON using the specified type shape and a caller-supplied starting context.

public void SerializeObject(ref JsonWriter writer, object? value, ITypeShape shape, SerializationContext startingContext)

Parameters

writer JsonWriter

The writer to serialize the value into.

value object

The value to serialize.

shape ITypeShape

The type shape describing the structure of value.

startingContext SerializationContext

The context to start this operation with, used instead of StartingContext. Its CancellationToken cancels the operation.

Exceptions

ArgumentException

Thrown if startingContext belongs to an operation already in progress.

SerializeObject(ref JsonWriter, object?, ITypeShape, CancellationToken)

Serializes an untyped value to JSON using the specified type shape.

public void SerializeObject(ref JsonWriter writer, object? value, ITypeShape shape, CancellationToken cancellationToken = default)

Parameters

writer JsonWriter

The writer to serialize the value into.

value object

The value to serialize.

shape ITypeShape

The type shape describing the structure of value.

cancellationToken CancellationToken

A token to cancel the operation.

SerializeObject(IBufferWriter<byte>, object?, ITypeShape, CancellationToken)

Serializes an untyped value to JSON using the specified type shape.

public void SerializeObject(IBufferWriter<byte> writer, object? value, ITypeShape shape, CancellationToken cancellationToken = default)

Parameters

writer IBufferWriter<byte>

The writer to serialize the value into.

value object

The value to serialize.

shape ITypeShape

The type shape describing the structure of value.

cancellationToken CancellationToken

A token to cancel the operation.

SerializeObject(Stream, object?, ITypeShape, CancellationToken)

Serializes an untyped value to JSON using the specified type shape.

public void SerializeObject(Stream stream, object? value, ITypeShape shape, CancellationToken cancellationToken = default)

Parameters

stream Stream

The destination stream.

value object

The value to serialize.

shape ITypeShape

The type shape describing the structure of value.

cancellationToken CancellationToken

A token to cancel the operation.

SerializeObject(object?, ITypeShape, CancellationToken)

Serializes an untyped value to JSON using the specified type shape.

public string SerializeObject(object? value, ITypeShape shape, CancellationToken cancellationToken = default)

Parameters

value object

The value to serialize.

shape ITypeShape

The type shape describing the structure of value.

cancellationToken CancellationToken

A token to cancel the operation.

Returns

string

The serialized JSON text.

Serialize<T>(ref JsonWriter, in T?, ITypeShape<T>, SerializationContext)

Serializes a value to JSON using the specified type shape and a caller-supplied starting context.

public void Serialize<T>(ref JsonWriter writer, in T? value, ITypeShape<T> shape, SerializationContext startingContext)

Parameters

writer JsonWriter

The writer to serialize the value into.

value T

The value to serialize.

shape ITypeShape<T>

The type shape describing the structure of T.

startingContext SerializationContext

The context to start this operation with, used instead of StartingContext. Its CancellationToken cancels the operation.

Type Parameters

T

The type of value to serialize.

Remarks

Use this overload to supply per-call state to converters via this[object].

Exceptions

ArgumentException

Thrown if startingContext belongs to an operation already in progress.

Serialize<T>(ref JsonWriter, in T?, ITypeShape<T>, CancellationToken)

Serializes a value to JSON using the specified type shape.

public void Serialize<T>(ref JsonWriter writer, in T? value, ITypeShape<T> shape, CancellationToken cancellationToken = default)

Parameters

writer JsonWriter

The writer to serialize the value into.

value T

The value to serialize.

shape ITypeShape<T>

The type shape describing the structure of T.

cancellationToken CancellationToken

A token to cancel the operation.

Type Parameters

T

The type of value to serialize.

Serialize<T>(ref JsonWriter, in T?, CancellationToken)

Serializes a value to JSON using the specified type shape.

[ExcludeFromCodeCoverage]
public void Serialize<T>(ref JsonWriter writer, in T? value, CancellationToken cancellationToken = default) where T : IShapeable<T>

Parameters

writer JsonWriter

The writer to serialize the value into.

value T

The value to serialize.

cancellationToken CancellationToken

A token to cancel the operation.

Type Parameters

T

The type of value to serialize.

Serialize<T>(IBufferWriter<byte>, in T?, ITypeShape<T>, CancellationToken)

Serializes a value as UTF-8 JSON to a byte buffer.

public void Serialize<T>(IBufferWriter<byte> writer, in T? value, ITypeShape<T> shape, CancellationToken cancellationToken = default)

Parameters

writer IBufferWriter<byte>

The destination buffer.

value T

The value to serialize.

shape ITypeShape<T>

The type shape describing T.

cancellationToken CancellationToken

A cancellation token.

Type Parameters

T

The type of value to serialize.

Serialize<T>(IBufferWriter<byte>, in T?, CancellationToken)

Serializes a value as UTF-8 JSON to a byte buffer.

[ExcludeFromCodeCoverage]
public void Serialize<T>(IBufferWriter<byte> writer, in T? value, CancellationToken cancellationToken = default) where T : IShapeable<T>

Parameters

writer IBufferWriter<byte>

The destination buffer.

value T

The value to serialize.

cancellationToken CancellationToken

A cancellation token.

Type Parameters

T

The type of value to serialize.

Serialize<T>(Stream, in T?, ITypeShape<T>, CancellationToken)

Serializes a value as UTF-8 JSON to a stream.

public void Serialize<T>(Stream stream, in T? value, ITypeShape<T> shape, CancellationToken cancellationToken = default)

Parameters

stream Stream

The destination stream.

value T

The value to serialize.

shape ITypeShape<T>

The type shape describing T.

cancellationToken CancellationToken

A cancellation token.

Type Parameters

T

The type of value to serialize.

Serialize<T>(Stream, in T?, CancellationToken)

Serializes a value as UTF-8 JSON to a stream.

[ExcludeFromCodeCoverage]
public void Serialize<T>(Stream stream, in T? value, CancellationToken cancellationToken = default) where T : IShapeable<T>

Parameters

stream Stream

The destination stream.

value T

The value to serialize.

cancellationToken CancellationToken

A cancellation token.

Type Parameters

T

The type of value to serialize.

Serialize<T>(in T?, ITypeShape<T>, CancellationToken)

Serializes a value to JSON text.

public string Serialize<T>(in T? value, ITypeShape<T> shape, CancellationToken cancellationToken = default)

Parameters

value T

The value to serialize.

shape ITypeShape<T>

The type shape describing T.

cancellationToken CancellationToken

A cancellation token.

Returns

string

The serialized JSON text.

Type Parameters

T

The type of value to serialize.

Serialize<T>(in T?, CancellationToken)

Serializes a value to JSON text.

[ExcludeFromCodeCoverage]
public string Serialize<T>(in T? value, CancellationToken cancellationToken = default) where T : IShapeable<T>

Parameters

value T

The value to serialize.

cancellationToken CancellationToken

A cancellation token.

Returns

string

The serialized JSON text.

Type Parameters

T

The type of value to serialize.

Serialize<T, TProvider>(ref JsonWriter, in T?, CancellationToken)

Serializes a value to JSON using the specified type shape.

[ExcludeFromCodeCoverage]
public void Serialize<T, TProvider>(ref JsonWriter writer, in T? value, CancellationToken cancellationToken = default) where TProvider : IShapeable<T>

Parameters

writer JsonWriter

The writer to serialize the value into.

value T

The value to serialize.

cancellationToken CancellationToken

A token to cancel the operation.

Type Parameters

T

The type of value to serialize.

TProvider

Serialize<T, TProvider>(IBufferWriter<byte>, in T?, CancellationToken)

Serializes a value as UTF-8 JSON to a byte buffer.

[ExcludeFromCodeCoverage]
public void Serialize<T, TProvider>(IBufferWriter<byte> writer, in T? value, CancellationToken cancellationToken = default) where TProvider : IShapeable<T>

Parameters

writer IBufferWriter<byte>

The destination buffer.

value T

The value to serialize.

cancellationToken CancellationToken

A cancellation token.

Type Parameters

T

The type of value to serialize.

TProvider

Serialize<T, TProvider>(Stream, in T?, CancellationToken)

Serializes a value as UTF-8 JSON to a stream.

[ExcludeFromCodeCoverage]
public void Serialize<T, TProvider>(Stream stream, in T? value, CancellationToken cancellationToken = default) where TProvider : IShapeable<T>

Parameters

stream Stream

The destination stream.

value T

The value to serialize.

cancellationToken CancellationToken

A cancellation token.

Type Parameters

T

The type of value to serialize.

TProvider

Serialize<T, TProvider>(in T?, CancellationToken)

Serializes a value to JSON text.

[ExcludeFromCodeCoverage]
public string Serialize<T, TProvider>(in T? value, CancellationToken cancellationToken = default) where TProvider : IShapeable<T>

Parameters

value T

The value to serialize.

cancellationToken CancellationToken

A cancellation token.

Returns

string

The serialized JSON text.

Type Parameters

T

The type of value to serialize.

TProvider

WithSystemTextJsonConverters()

Creates a copy of this serializer with opt-in converters registered for the JsonElement, JsonNode, and JsonDocument types.

public JsonSerializer WithSystemTextJsonConverters()

Returns

JsonSerializer

A new JsonSerializer instance with the System.Text.Json interop converters registered.

Remarks

These converters bridge to System.Text.Json by round-tripping raw JSON text, so they add no reflection. However, calling this method roots the System.Text.Json assembly. Because the converters are registered only when you call this method, the default serializer keeps System.Text.Json trimmable and out of the NativeAOT closure.

WithUntypedConverters()

Creates a copy of this serializer with opt-in converters registered for untyped JSON: the CLR object and ExpandoObject types, along with the native JsonValue document object model when it appears as a member of another shaped type.

public JsonSerializer WithUntypedConverters()

Returns

JsonSerializer

A new JsonSerializer instance with the untyped converters registered.

Remarks

These converters use no reflection and root no additional dependencies. Because they are registered only when you call this method, the default serializer remains trimming- and NativeAOT-safe and never discovers arbitrary CLR types.

A non-null value typed as object deserializes to a boxed JsonValue, while a JSON null deserializes to C# null. Serializing an object requires a JsonValue or a boxed JSON primitive; any other CLR type throws a NotSupportedException that guides you to use a generated type shape instead.