Struct SerializationContext

Namespace

Nerdbank.Json

Assembly

Nerdbank.Json.dll

Context that flows through the serialization process.

public record struct SerializationContext : IEquatable<SerializationContext>

Implements

IEquatable<SerializationContext>

Inherited Members

ValueType.Equals(object)

ValueType.GetHashCode()

ValueType.ToString()

object.Equals(object, object)

object.GetType()

object.ReferenceEquals(object, object)

Examples

The default values on this struct may be changed and the modified struct applied to StartingContext in order to serialize with the updated settings.

To modify the starting context on an existing serializer, you can use the with keyword to create a new serializer with the updated context.

To use a context for just one operation, pass it to a (de)serialization overload that accepts a SerializationContext.

Constructors

SerializationContext()

Initializes a new instance of the SerializationContext struct.

public SerializationContext()

Properties

CancellationToken

Gets a cancellation token that can be used to cancel the serialization operation.

public CancellationToken CancellationToken { readonly get; init; }

Property Value

CancellationToken

this[object]

Gets or sets special state to be exposed to converters during serialization.

public object? this[object key] { get; set; }

Parameters

key object

Any object that can act as a key in a dictionary.

Property Value

object

The value stored under the specified key, or null if no value has been stored under that key.

Examples

To add, modify or remove a key in this state as applied to a StartingContext, capture and change the SerializationContext as a local variable, then reassign it to the serializer.

To supply state for just one operation, capture and change the SerializationContext as a local variable, then pass it to an overload such as Serialize<T>(ref JsonWriter, in T?, ITypeShape<T>, SerializationContext).

Remarks

A key-value pair is removed from the underlying dictionary by assigning a value of null for a given key.

Strings can serve as convenient keys, but may collide with the same string used by another part of the data model for another purpose. Make your strings sufficiently unique to avoid collisions, or use a static readonly object MyKey = new object() field that you expose such that all interested parties can access the object for a key that is guaranteed to be unique.

MaxDepth

Gets or sets the remaining depth of the object graph to serialize or deserialize.

public int MaxDepth { readonly get; set; }

Property Value

int

The default value is 64.

Remarks

Exceeding this depth will result in an InvalidOperationException being thrown from DepthStep().

Security

Gets or sets the security settings to apply to (de)serialization.

public SecuritySettings Security { readonly get; set; }

Property Value

SecuritySettings

The default value is UntrustedData.

UnflushedBytesThreshold

Gets or sets the number of uncommitted bytes that may accumulate in an asynchronous writer's buffer before a flush to the underlying PipeWriter is triggered.

public int UnflushedBytesThreshold { readonly get; set; }

Property Value

int

The default value is 64KB.

Methods

DepthStep()

Decrements the depth remaining and checks the cancellation token.

public void DepthStep()

Remarks

Converters that (de)serialize nested objects should invoke this once before delegating to nested converters.

Exceptions

InvalidOperationException

Thrown if the depth limit has been exceeded.

OperationCanceledException

Thrown if CancellationToken has been canceled.

GetConverter(ITypeShape)

Gets a converter for a specific type shape.

public JsonConverter GetConverter(ITypeShape shape)

Parameters

shape ITypeShape

The type shape describing the type.

Returns

JsonConverter

The converter.

GetConverter<T>(ITypeShape<T>)

Gets a converter for a specific type shape.

public JsonConverter<T> GetConverter<T>(ITypeShape<T> shape)

Parameters

shape ITypeShape<T>

The type shape describing the type.

Returns

JsonConverter<T>

The converter.

Type Parameters

T

The type to convert.