Struct SerializationContext

Namespace

Nerdbank.MessagePack

Assembly

Nerdbank.MessagePack.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.

MessagePackSerializer serializer = new()
{
    StartingContext = new SerializationContext
    {
        MaxDepth = 128,
    },
};

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

serializer = serializer with
{
    StartingContext = serializer.StartingContext with
    {
        MaxDepth = 256,
    },
};

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

Remarks

In WriteAsync(MessagePackAsyncWriter, T?, SerializationContext) or ReadAsync(MessagePackAsyncReader, SerializationContext) methods, this will tend to be equivalent to the cancellationToken parameter passed to those methods.

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.

SerializationContext context = serializer.StartingContext;
context["MyState"] = "IsValue";
serializer = serializer with
{
    StartingContext = context,
};

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 a MessagePackSerializationException being thrown from DepthStep().

TypeShapeProvider

Gets the type shape provider that applies to the serialization operation.

public readonly ITypeShapeProvider? TypeShapeProvider { get; }

Property Value

ITypeShapeProvider

UnflushedBytesThreshold

Gets a hint as to the number of bytes to write into the buffer before serialization will flush the output.

public int UnflushedBytesThreshold { readonly get; init; }

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 passing the context to nested (de)serializers.

Exceptions

MessagePackSerializationException

Thrown if the depth limit has been exceeded.

OperationCanceledException

Thrown if CancellationToken has been canceled.

GetConverter(ITypeShape)

Gets a converter for a given type shape.

public IMessagePackConverter GetConverter(ITypeShape shape)

Parameters

shape ITypeShape

The shape of the type to be converted.

Returns

IMessagePackConverter

The converter.

Remarks

This method is intended only for use by custom converters in order to delegate conversion of sub-values.

Exceptions

InvalidOperationException

Thrown if no serialization operation is in progress.

GetConverter(Type, ITypeShapeProvider?)

Gets a converter for a given type shape.

public IMessagePackConverter GetConverter(Type type, ITypeShapeProvider? provider)

Parameters

type Type

The type to be converted.

provider ITypeShapeProvider

The shape provider of T. This will typically be obtained by calling the ShapeProvider static property on a witness class (a class on which GenerateShapeAttribute<T> has been applied). It can also come from TypeShapeProvider. A null value will be filled in with TypeShapeProvider.

Returns

IMessagePackConverter

The converter.

Remarks

This method is intended only for use by custom converters in order to delegate conversion of sub-values.

Exceptions

InvalidOperationException

Thrown if no serialization operation is in progress.

GetConverter<T>()

Gets a converter for a specific type.

public MessagePackConverter<T> GetConverter<T>() where T : IShapeable<T>

Returns

MessagePackConverter<T>

The converter.

Type Parameters

T

The type to be converted.

Remarks

This method is intended only for use by custom converters in order to delegate conversion of sub-values.

Exceptions

InvalidOperationException

Thrown if no serialization operation is in progress.

GetConverter<T>(ITypeShapeProvider?)

Gets a converter for a specific type.

public MessagePackConverter<T> GetConverter<T>(ITypeShapeProvider? provider)

Parameters

provider ITypeShapeProvider

The shape provider of T. This will typically be obtained by calling the ShapeProvider static property on a witness class (a class on which GenerateShapeAttribute<T> has been applied). It can also come from TypeShapeProvider. A null value will be filled in with TypeShapeProvider.

Returns

MessagePackConverter<T>

The converter.

Type Parameters

T

The type to be converted.

Remarks

This method is intended only for use by custom converters in order to delegate conversion of sub-values.

Exceptions

InvalidOperationException

Thrown if no serialization operation is in progress.

GetConverter<T, TProvider>()

Gets a converter for a specific type.

public MessagePackConverter<T> GetConverter<T, TProvider>() where TProvider : IShapeable<T>

Returns

MessagePackConverter<T>

The converter.

Type Parameters

T

The type to be converted.

TProvider

The type that provides the shape of the type to be converted.

Remarks

This method is intended only for use by custom converters in order to delegate conversion of sub-values.

Exceptions

InvalidOperationException

Thrown if no serialization operation is in progress.