Class JsonConverter

Namespace

Nerdbank.Json

Assembly

Nerdbank.Json.dll

Base type for JSON converters.

public abstract class JsonConverter

Inheritance

object

JsonConverter

Derived

JsonConverter<T>

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Properties

PreferAsyncSerialization

Gets a value indicating whether this converter's asynchronous methods should be preferred over its synchronous methods when a graph is being (de)serialized asynchronously.

public virtual bool PreferAsyncSerialization { get; }

Property Value

bool

Remarks

The default is false, which means the default asynchronous methods buffer a whole value and delegate to the synchronous methods. Converters that may (de)serialize very large values should override the asynchronous methods, set this to true, and stream fragments so that memory use stays bounded.

Methods

GetJsonSchema(JsonSchemaContext, ITypeShape)

Produces a JSON Schema fragment that describes how this converter represents its value, or null if this converter cannot describe its representation.

public virtual JsonSchema? GetJsonSchema(JsonSchemaContext context, ITypeShape typeShape)

Parameters

context JsonSchemaContext

The schema-generation context, which resolves nested schemas and shared definitions.

typeShape ITypeShape

The shape of the type this converter handles.

Returns

JsonSchema

A schema fragment, or null to indicate the representation is undocumented. When null is returned, the exporter emits a permissive schema annotated with a conspicuous comment rather than pretending to know the representation.

TryNavigate(ref JsonReader, in JsonNavigationSegment, JsonNavigationOptions)

Advances the reader from this converter's value to the child value selected by a targeted-deserialization segment.

public virtual bool TryNavigate(ref JsonReader reader, in JsonNavigationSegment segment, JsonNavigationOptions options)

Parameters

reader JsonReader

The reader positioned at this converter's JSON value.

segment JsonNavigationSegment

The member or index to navigate into.

options JsonNavigationOptions

The navigation options (name comparer and case sensitivity).

Returns

bool

true with the reader positioned at the selected child value; otherwise false when the child is absent (a missing path).

Remarks

The default implementation navigates a self-describing JSON object or array using raw token skipping. Converters whose representation is not a plain object or array (such as unions that emit a [discriminator, payload] envelope, or custom converters that remap members) should override this method to translate the segment into a navigation over their representation, typically by delegating to the converter of the underlying value.

TryNavigateAsync(JsonAsyncReader, JsonNavigationSegment, JsonNavigationOptions, SerializationContext)

Asynchronously advances the reader from this converter's value toward the child selected by a targeted-navigation segment, without buffering the enclosing document.

public virtual ValueTask<int> TryNavigateAsync(JsonAsyncReader reader, JsonNavigationSegment segment, JsonNavigationOptions options, SerializationContext context)

Parameters

reader JsonAsyncReader

The asynchronous reader positioned at this converter's JSON value.

segment JsonNavigationSegment

The member or index to navigate into.

options JsonNavigationOptions

The navigation options (name comparer and case sensitivity).

context SerializationContext

The serialization context.

Returns

ValueTask<int>

A task whose result is the number of JSON containers this converter left open on the path to the selected child (so the caller can later consume them), or a negative value when the child is absent (a missing path).

Remarks

The default implementation navigates a self-describing JSON object or array using the asynchronous reader. Converters whose representation is a union envelope or a custom shape should override this method to translate the segment into a navigation over their representation, typically by delegating to the converter of the underlying value and adding the number of containers they themselves opened.