Struct SerializationContext<TEncoder, TDecoder>

Namespace

ShapeShift

Assembly

ShapeShift.dll

public struct SerializationContext<TEncoder, TDecoder> where TEncoder : IEncoder, allows ref struct where TDecoder : IDecoder, allows ref struct

Type Parameters

TEncoder

TDecoder

Inherited Members

ValueType.Equals(object)

ValueType.GetHashCode()

ValueType.ToString()

object.Equals(object, object)

object.GetType()

object.ReferenceEquals(object, object)

Constructors

SerializationContext()

Initializes a new instance of the SerializationContext<TEncoder, TDecoder> 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 Write(ref TEncoder, in T?, SerializationContext<TEncoder, TDecoder>) or Read(ref TDecoder, SerializationContext<TEncoder, TDecoder>) 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<TEncoder, TDecoder> as a local variable, then reassign it to the serializer.

// The context is a struct, so change a local copy and reassign it to the serializer.
SerializationContext<JsonEncoder, JsonDecoder> context = serializer.StartingContext;
context[MoneyConverter.DefaultCurrencyKey] = "USD";
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.

MaxBinaryLength

Gets or sets the maximum number of bytes allowed in a binary value.

public int MaxBinaryLength { readonly get; set; }

Property Value

int

The default value is 64 MiB.

MaxCollectionLength

Gets or sets the maximum number of elements allowed in a collection during serialization or deserialization.

public int MaxCollectionLength { readonly get; set; }

Property Value

int

The default value is 1,000,000.

Remarks

This limit protects against payloads that attempt to allocate or populate unreasonably large collections.

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

MaxStringLength

Gets or sets the maximum number of characters allowed in a string.

public int MaxStringLength { readonly get; set; }

Property Value

int

The default value is 16,777,216.

TypeShapeProvider

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

public readonly ITypeShapeProvider? TypeShapeProvider { get; }

Property Value

ITypeShapeProvider

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

ShapeShiftSerializationException

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 ShapeShiftConverter<TEncoder, TDecoder> GetConverter(ITypeShape typeShape)

Parameters

typeShape ITypeShape

The shape of the type to be converted.

Returns

ShapeShiftConverter<TEncoder, TDecoder>

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 ShapeShiftConverter<TEncoder, TDecoder> GetConverter(Type type, ITypeShapeProvider? provider = null)

Parameters

type Type

The type to be converted.

provider ITypeShapeProvider

The shape provider for the type(s) to be serialized. This might be PolyType.ReflectionProvider.ReflectionTypeShapeProvider.Default to use reflection-based shapes. It might also be the value of the GeneratedTypeShapeProvider static property on a witness class (a class on which PolyType.GenerateShapeForAttribute<T> has been applied), although for source generated shapes, overloads that do not take an PolyType.ITypeShapeProvider offer better performance. It can also come from TypeShapeProvider. A null value will be filled in with TypeShapeProvider.

Returns

ShapeShiftConverter<TEncoder, TDecoder>

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 ShapeShiftConverter<T, TEncoder, TDecoder> GetConverter<T>() where T : IShapeable<T>

Returns

ShapeShiftConverter<T, TEncoder, TDecoder>

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 ShapeShiftConverter<T, TEncoder, TDecoder> GetConverter<T>(ITypeShapeProvider? provider)

Parameters

provider ITypeShapeProvider

The shape provider for the type(s) to be serialized. This might be PolyType.ReflectionProvider.ReflectionTypeShapeProvider.Default to use reflection-based shapes. It might also be the value of the GeneratedTypeShapeProvider static property on a witness class (a class on which PolyType.GenerateShapeForAttribute<T> has been applied), although for source generated shapes, overloads that do not take an PolyType.ITypeShapeProvider offer better performance. It can also come from TypeShapeProvider. A null value will be filled in with TypeShapeProvider.

Returns

ShapeShiftConverter<T, TEncoder, TDecoder>

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>(ITypeShape<T>)

Gets a converter for a given type shape.

public ShapeShiftConverter<T, TEncoder, TDecoder> GetConverter<T>(ITypeShape<T> typeShape)

Parameters

typeShape ITypeShape<T>

The shape of the type to be converted.

Returns

ShapeShiftConverter<T, TEncoder, TDecoder>

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 ShapeShiftConverter<T, TEncoder, TDecoder> GetConverter<T, TProvider>() where TProvider : IShapeable<T>

Returns

ShapeShiftConverter<T, TEncoder, TDecoder>

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.

ReportObjectConstructed(object?)

Shares the reference to an object as soon as it is constructed during deserialization.

public void ReportObjectConstructed(object? value)

Parameters

value object

The constructed object.

Remarks

This method should never be called with a boxed value type. The caller may use IsValueType to determine if the value is a value type and call this method only if this property is false.

Converters are not required to call this method, and there is no point in calling it just before the Read(ref TDecoder, SerializationContext<TEncoder, TDecoder>) method returns the object to its caller. But if such a method activates the object and is about to start deserializing its properties, calling this method first can help provide support for reference cycles that involve the object being deserialized.