Class MessagePackSerializer

Namespace

Nerdbank.MessagePack

Assembly

Nerdbank.MessagePack.dll

Serializes .NET objects using the MessagePack format.

public record MessagePackSerializer : IEquatable<MessagePackSerializer>

Inheritance

object

MessagePackSerializer

Implements

IEquatable<MessagePackSerializer>

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Properties

InternStrings

Gets a value indicating whether to intern strings during deserialization.

public bool InternStrings { get; init; }

Property Value

bool

Remarks

String interning means that a string that appears multiple times (within a single deserialization or across many) in the msgpack data will be deserialized as the same string instance, reducing GC pressure.

When enabled, all deserialized are retained with a weak reference, allowing them to be garbage collected while also being reusable for future deserializations as long as they are in memory.

This feature has a positive impact on memory usage but may have a negative impact on performance due to searching through previously deserialized strings to find a match. If your application is performance sensitive, you should measure the impact of this feature on your application.

This feature is orthogonal and complementary to Nerdbank.MessagePack.ConverterCache.PreserveReferences. Preserving references impacts the serialized result and can hurt interoperability if the other party is not using the same feature. Preserving references also does not guarantee that equal strings will be reused because the original serialization may have had multiple string objects for the same value, so deserialization would produce the same result. Preserving references alone will never reuse strings across top-level deserialization operations either. Interning strings however, has no impact on the serialized result and is always safe to use. Interning strings will guarantee string objects are reused within and across deserialization operations so long as their values are equal. The combination of the two features will ensure the most compact msgpack, and will produce faster deserialization times than string interning alone. Combining the two features also activates special behavior to ensure that serialization only writes a string once and references that string later in that same serialization, even if the equal strings were unique objects.

LibraryExtensionTypeCodes

Gets the extension type codes to use for library-reserved extension types.

public LibraryReservedMessagePackExtensionTypeCode LibraryExtensionTypeCodes { get; init; }

Property Value

LibraryReservedMessagePackExtensionTypeCode

Remarks

This property may be used to reassign the extension type codes for library-provided extension types in order to avoid conflicts with other libraries the application is using.

MaxAsyncBuffer

Gets the maximum length of msgpack to buffer before beginning deserialization.

public int MaxAsyncBuffer { get; init; }

Property Value

int

May be set to any non-negative integer. The default value is 1MB and is subject to change.

Remarks

Larger values are more likely to lead to async buffering followed by synchronous deserialization, which is significantly faster than async deserialization. Smaller values are useful for limiting memory usage since deserialization can happen while pulling in more msgpack bytes, allowing release of the buffers containing earlier bytes to make room for subsequent ones.

This value has no impact once deserialization has begun. The msgpack structure to be deserialized and converters used during deserialization may result in buffering any amount of msgpack beyond this value.

MultiDimensionalArrayFormat

Gets the format to use when serializing multi-dimensional arrays.

public MultiDimensionalArrayFormat MultiDimensionalArrayFormat { get; init; }

Property Value

MultiDimensionalArrayFormat

PreserveReferences

Gets a value indicating whether to preserve reference equality when serializing objects.

public bool PreserveReferences { get; init; }

Property Value

bool

The default value is false.

Remarks

When false, if an object appears multiple times in a serialized object graph, it will be serialized at each location. This has two outcomes: redundant data leading to larger serialized payloads and the loss of reference equality when deserialized. This is the default behavior because it requires no msgpack extensions and is compatible with all msgpack readers.

When true, every object is serialized normally the first time it appears in the object graph. Each subsequent type the object appears in the object graph, it is serialized as a reference to the first occurrence. This reference requires between 3-6 bytes of overhead per reference instead of whatever the object's by-value representation would have required. Upon deserialization, all objects that were shared across the object graph will also be shared across the deserialized object graph. Of course there will not be reference equality between the original and deserialized objects, but the deserialized objects will have reference equality with each other. This option utilizes a proprietary msgpack extension and can only be deserialized by libraries that understand this extension. There is a small perf penalty for this feature, but depending on the object graph it may turn out to improve performance due to avoiding redundant serializations.

Reference cycles (where an object refers to itself or to another object that eventually refers back to it) are not supported in either mode. When this property is true, an exception will be thrown when a cycle is detected. When this property is false, a cycle will eventually result in a StackOverflowException being thrown.

PropertyNamingPolicy

Gets the transformation function to apply to property names before serializing them.

public MessagePackNamingPolicy? PropertyNamingPolicy { get; init; }

Property Value

MessagePackNamingPolicy

The default value is null, indicating that property names should be persisted exactly as they are declared in .NET.

SerializeDefaultValues

Gets a value indicating whether to serialize properties that are set to their default values.

public bool SerializeDefaultValues { get; init; }

Property Value

bool

The default value is false.

Remarks

By default, the serializer omits properties and fields that are set to their default values when serializing objects. This property can be used to override that behavior and serialize all properties and fields, regardless of their value.

This property currently only impacts objects serialized as maps (i.e. types that are not using KeyAttribute on their members), but this could be expanded to truncate value arrays as well.

Default values are assumed to be default(TPropertyType) except where overridden, as follows:

• Primary constructor default parameter values. e.g. record Person(int Age = 18)
• Properties or fields attributed with DefaultValueAttribute. e.g. [DefaultValue(18)] internal int Age { get; set; }

SerializeEnumValuesByName

Gets a value indicating whether enum values will be serialized by name rather than by their numeric value.

public bool SerializeEnumValuesByName { get; init; }

Property Value

bool

Remarks

Serializing by name is a best effort. Most enums do not define a name for every possible value, and flags enums may have complicated string representations when multiple named enum elements are combined to form a value. When a simple string cannot be constructed for a given value, the numeric form is used.

When deserializing enums by name, name matching is case insensitive unless the enum type defines multiple values with names that are only distinguished by case.

StartingContext

Gets the starting context to begin (de)serializations with.

public SerializationContext StartingContext { get; init; }

Property Value

SerializationContext

Methods

ConvertToJson(ref MessagePackReader, TextWriter)

Converts one MessagePack structure to a JSON stream.

public static void ConvertToJson(ref MessagePackReader reader, TextWriter jsonWriter)

Parameters

reader MessagePackReader

A reader of the msgpack stream.

jsonWriter TextWriter

The writer that will receive JSON text.

ConvertToJson(in ReadOnlySequence<byte>)

Converts a msgpack sequence into equivalent JSON.

public static string ConvertToJson(in ReadOnlySequence<byte> msgpack)

Parameters

msgpack ReadOnlySequence<byte>

The msgpack sequence.

Returns

string

The JSON.

Remarks

Not all valid msgpack can be converted to JSON. For example, msgpack maps with non-string keys cannot be represented in JSON. As such, this method is intended for debugging purposes rather than for production use.

ConvertToJson(ReadOnlyMemory<byte>)

Converts a msgpack sequence into equivalent JSON.

public static string ConvertToJson(ReadOnlyMemory<byte> msgpack)

Parameters

msgpack ReadOnlyMemory<byte>

The msgpack sequence.

Returns

string

The JSON.

Remarks

Not all valid msgpack can be converted to JSON. For example, msgpack maps with non-string keys cannot be represented in JSON. As such, this method is intended for debugging purposes rather than for production use.

CreateSerializationContext(ITypeShapeProvider, CancellationToken)

Creates a new serialization context that is ready to process a serialization job.

protected MessagePackSerializer.DisposableSerializationContext CreateSerializationContext(ITypeShapeProvider provider, CancellationToken cancellationToken = default)

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).

cancellationToken CancellationToken

A cancellation token for the operation.

Returns

MessagePackSerializer.DisposableSerializationContext

The serialization context.

Remarks

Callers should be sure to always call Dispose() when done with the context.

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

Deserializes a value from a PipeReader.

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

Parameters

reader PipeReader

The reader to deserialize from.

shape ITypeShape<T>

The shape of the type, as obtained from an ITypeShapeProvider.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask<T>

The deserialized value.

Type Parameters

T

The type of value to deserialize.

DeserializeAsync<T>(PipeReader, ITypeShapeProvider, CancellationToken)

Deserializes a value from a PipeReader.

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

Parameters

reader PipeReader

The reader to deserialize from.

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).

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask<T>

The deserialized value.

Type Parameters

T

The type of value to deserialize.

DeserializeAsync<T>(PipeReader, CancellationToken)

Deserializes a value from a PipeReader.

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

Parameters

reader PipeReader

The reader to deserialize from.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask<T>

The deserialized value.

Type Parameters

T

The type of value to deserialize.

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

Deserializes a value from a Stream.

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

Parameters

stream Stream

The stream to deserialize from. If this stream contains more than one top-level msgpack structure, it may be positioned beyond its end after deserialization due to buffering.

shape ITypeShape<T>

The shape of the type, as obtained from an ITypeShapeProvider.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask<T>

The deserialized value.

Type Parameters

T

The type to be serialized.

DeserializeAsync<T>(Stream, ITypeShapeProvider, CancellationToken)

Deserializes a value from a Stream.

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

Parameters

stream Stream

The stream to deserialize from. If this stream contains more than one top-level msgpack structure, it may be positioned beyond its end after deserialization due to buffering.

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).

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask<T>

The deserialized value.

Type Parameters

T

The type to be serialized.

DeserializeAsync<T>(Stream, CancellationToken)

Deserializes a value from a Stream.

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

Parameters

stream Stream

The stream to deserialize from. If this stream contains more than one top-level msgpack structure, it may be positioned beyond its end after deserialization due to buffering.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask<T>

The deserialized value.

Type Parameters

T

The type to be serialized.

DeserializeAsync<T, TProvider>(PipeReader, CancellationToken)

Deserializes a value from a PipeReader.

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

Parameters

reader PipeReader

The reader to deserialize from.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask<T>

The deserialized value.

Type Parameters

T

The type of value to deserialize.

TProvider

DeserializeAsync<T, TProvider>(Stream, CancellationToken)

Deserializes a value from a Stream.

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

Parameters

stream Stream

The stream to deserialize from. If this stream contains more than one top-level msgpack structure, it may be positioned beyond its end after deserialization due to buffering.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask<T>

The deserialized value.

Type Parameters

T

The type to be serialized.

TProvider

DeserializeObject(ref MessagePackReader, ITypeShape, CancellationToken)

Deserializes an untyped value.

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

Parameters

reader MessagePackReader

The msgpack reader to deserialize from.

shape ITypeShape

The shape of the value to deserialize.

cancellationToken CancellationToken

A cancellation token.

Returns

object

The deserialized value.

Examples

See the SerializeObject(ref MessagePackWriter, object?, ITypeShape, CancellationToken) method for an example of using this method.

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

Deserializes a value.

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

Parameters

reader MessagePackReader

The msgpack reader to deserialize from.

shape ITypeShape<T>

The shape of T.

cancellationToken CancellationToken

A cancellation token.

Returns

T

The deserialized value.

Type Parameters

T

The type of value to deserialize.

Deserialize<T>(ref MessagePackReader, ITypeShapeProvider, CancellationToken)

Deserializes a value.

public T? Deserialize<T>(ref MessagePackReader reader, ITypeShapeProvider provider, CancellationToken cancellationToken = default)

Parameters

reader MessagePackReader

The msgpack reader to deserialize from.

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).

cancellationToken CancellationToken

A cancellation token.

Returns

T

The deserialized value.

Type Parameters

T

The type of value to deserialize.

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

Deserializes a value.

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 shape of T.

cancellationToken CancellationToken

A cancellation token.

Returns

T

The deserialized value.

Type Parameters

T

The type of value to deserialize.

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

Deserializes a value.

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

Parameters

buffer ReadOnlySequence<byte>

The msgpack to deserialize from.

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).

cancellationToken CancellationToken

A cancellation token.

Returns

T

The deserialized value.

Type Parameters

T

The type of value to deserialize.

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

Deserializes a value.

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

Parameters

bytes ReadOnlySequence<byte>

cancellationToken CancellationToken

A cancellation token.

Returns

T

The deserialized value.

Type Parameters

T

The type of value to deserialize.

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

Deserializes a value.

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

Parameters

stream Stream

The stream to deserialize from. If this stream contains more than one top-level msgpack structure, it may be positioned beyond its end after deserialization due to buffering.

shape ITypeShape<T>

The shape of T.

cancellationToken CancellationToken

A cancellation token.

Returns

T

The deserialized value.

Type Parameters

T

The type of value to deserialize.

Remarks

The implementation of this method currently is to buffer the entire content of the stream into memory before deserializing. This is for simplicity and perf reasons. Callers should only provide streams that are known to be small enough to fit in memory and contain only msgpack content.

Deserialize<T>(Stream, ITypeShapeProvider, CancellationToken)

Deserializes a value.

public T? Deserialize<T>(Stream stream, ITypeShapeProvider provider, CancellationToken cancellationToken = default)

Parameters

stream Stream

The stream to deserialize from. If this stream contains more than one top-level msgpack structure, it may be positioned beyond its end after deserialization due to buffering.

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).

cancellationToken CancellationToken

A cancellation token.

Returns

T

The deserialized value.

Type Parameters

T

The type of value to deserialize.

Remarks

The implementation of this method currently is to buffer the entire content of the stream into memory before deserializing. This is for simplicity and perf reasons. Callers should only provide streams that are known to be small enough to fit in memory and contain only msgpack content.

Deserialize<T>(Stream, CancellationToken)

Deserializes a value.

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

Parameters

stream Stream

The stream to deserialize from. If this stream contains more than one top-level msgpack structure, it may be positioned beyond its end after deserialization due to buffering.

cancellationToken CancellationToken

A cancellation token.

Returns

T

The deserialized value.

Type Parameters

T

The type of value to deserialize.

Remarks

The implementation of this method currently is to buffer the entire content of the stream into memory before deserializing. This is for simplicity and perf reasons. Callers should only provide streams that are known to be small enough to fit in memory and contain only msgpack content.

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

Deserializes a value.

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 shape of T.

cancellationToken CancellationToken

A cancellation token.

Returns

T

The deserialized value.

Type Parameters

T

The type of value to deserialize.

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

Deserializes a value.

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

Parameters

buffer ReadOnlyMemory<byte>

The msgpack to deserialize from.

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).

cancellationToken CancellationToken

A cancellation token.

Returns

T

The deserialized value.

Type Parameters

T

The type of value to deserialize.

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

Deserializes a value.

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

Parameters

bytes ReadOnlyMemory<byte>

cancellationToken CancellationToken

A cancellation token.

Returns

T

The deserialized value.

Type Parameters

T

The type of value to deserialize.

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

Deserializes a value.

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

Parameters

bytes ReadOnlySequence<byte>

cancellationToken CancellationToken

A cancellation token.

Returns

T

The deserialized value.

Type Parameters

T

The type of value to deserialize.

TProvider

Deserialize<T, TProvider>(Stream, CancellationToken)

Deserializes a value.

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

Parameters

stream Stream

The stream to deserialize from. If this stream contains more than one top-level msgpack structure, it may be positioned beyond its end after deserialization due to buffering.

cancellationToken CancellationToken

A cancellation token.

Returns

T

The deserialized value.

Type Parameters

T

The type of value to deserialize.

TProvider

Remarks

The implementation of this method currently is to buffer the entire content of the stream into memory before deserializing. This is for simplicity and perf reasons. Callers should only provide streams that are known to be small enough to fit in memory and contain only msgpack content.

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

Deserializes a value.

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

Parameters

bytes ReadOnlyMemory<byte>

cancellationToken CancellationToken

A cancellation token.

Returns

T

The deserialized value.

Type Parameters

T

The type of value to deserialize.

TProvider

GetJsonSchema(ITypeShape)

Creates a JSON Schema that describes the msgpack serialization of the given type's shape.

public JsonObject GetJsonSchema(ITypeShape typeShape)

Parameters

typeShape ITypeShape

The shape of the type.

Returns

JsonObject

The JSON Schema document.

GetJsonSchema<T>()

Creates a JSON Schema that describes the msgpack serialization of the given type's shape.

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

Returns

JsonObject

The JSON Schema document.

Type Parameters

T

The self-describing type whose schema should be produced.

GetJsonSchema<T>(ITypeShapeProvider)

Creates a JSON Schema that describes the msgpack serialization of the given type's shape.

public JsonObject GetJsonSchema<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).

Returns

JsonObject

The JSON Schema document.

Type Parameters

T

The type whose schema should be produced.

GetJsonSchema<T, TProvider>()

Creates a JSON Schema that describes the msgpack serialization of the given type's shape.

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

Returns

JsonObject

The JSON Schema document.

Type Parameters

T

The type whose schema should be produced.

TProvider

The witness type that provides the shape for T.

RegisterConverter<T>(MessagePackConverter<T>)

Registers a converter for use with this serializer.

public void RegisterConverter<T>(MessagePackConverter<T> converter)

Parameters

converter MessagePackConverter<T>

The converter.

Type Parameters

T

The convertible type.

Remarks

If a converter for the data type has already been cached, the new value takes its place. Custom converters should be registered before serializing anything on this instance of MessagePackSerializer.

RegisterKnownSubTypes<TBase>(KnownSubTypeMapping<TBase>)

Registers a known sub-type mapping for a base type.

public void RegisterKnownSubTypes<TBase>(KnownSubTypeMapping<TBase> mapping)

Parameters

mapping KnownSubTypeMapping<TBase>

The mapping.

Type Parameters

TBase

The base type or interface that all sub-types derive from or implement.

Remarks

This method provides a runtime dynamic alternative to the otherwise simpler but static KnownSubTypeAttribute, enabling scenarios such as sub-types that are not known at compile time.

This is also the only way to force the serialized schema to support sub-types in the future when no sub-types are defined yet, such that they can be added later without a schema-breaking change.

A mapping provided for a given TBase will completely replace any mapping from KnownSubTypeAttribute attributes that may be applied to that same TBase.

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

Serializes a value using the given PipeWriter.

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

Parameters

writer PipeWriter

The writer to use.

value T

The value to serialize.

shape ITypeShape<T>

The shape of the type, as obtained from an ITypeShapeProvider.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask

A task that tracks the async serialization.

Type Parameters

T

The type to be serialized.

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

Serializes a value using the given PipeWriter.

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

Parameters

writer PipeWriter

The writer to use.

value T

The value to serialize.

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).

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask

A task that tracks the async serialization.

Type Parameters

T

The type to be serialized.

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

Serializes a value using the given PipeWriter.

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

Parameters

writer PipeWriter

The writer to use.

value T

The value to serialize.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask

A task that tracks the async serialization.

Type Parameters

T

The type to be serialized.

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

Serializes a value to a Stream.

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

Parameters

stream Stream

The stream to write to.

value T

The value to serialize.

shape ITypeShape<T>

The shape of the type, as obtained from an ITypeShapeProvider.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask

A task that tracks the async serialization.

Type Parameters

T

The type to be serialized.

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

Serializes a value to a Stream.

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

Parameters

stream Stream

The stream to write to.

value T

The value to serialize.

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).

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask

A task that tracks the async serialization.

Type Parameters

T

The type to be serialized.

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

Serializes a value to a Stream.

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

Parameters

stream Stream

The stream to write to.

value T

The value to serialize.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask

A task that tracks the async serialization.

Type Parameters

T

The type to be serialized.

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

Serializes a value using the given PipeWriter.

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

Parameters

writer PipeWriter

The writer to use.

value T

The value to serialize.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask

A task that tracks the async serialization.

Type Parameters

T

The type to be serialized.

TProvider

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

Serializes a value to a Stream.

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

Parameters

stream Stream

The stream to write to.

value T

The value to serialize.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask

A task that tracks the async serialization.

Type Parameters

T

The type to be serialized.

TProvider

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

Serializes an untyped value.

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

Parameters

writer MessagePackWriter

The msgpack writer to use.

value object

The value to serialize.

shape ITypeShape

The shape of the value to serialize.

cancellationToken CancellationToken

A cancellation token.

Examples

The following snippet demonstrates a way to use this method.

// Possible implementations of ITypeShapeProvider instances.
static readonly ITypeShapeProvider ReflectionBased = ReflectionTypeShapeProvider.Default;
static readonly ITypeShapeProvider SourceGenerated = Witness.ShapeProvider;
object TypelessSerializeRoundtrip(object value, ITypeShapeProvider provider)
{
// Acquire the type's shape. For this sample, we'll use the runtime type of the object.
ITypeShape shape = provider.GetShape(value.GetType()) ?? throw new ArgumentException("No shape available for runtime type", nameof(provider));
MessagePackSerializer serializer = new();
Sequence<byte> sequence = new();

// Serialize the object.
MessagePackWriter writer = new(sequence);
serializer.SerializeObject(ref writer, value, shape);
writer.Flush();

// Deserialize the object.
MessagePackReader reader = new(sequence);
return serializer.DeserializeObject(ref reader, shape)!;

}
[GenerateShape<Fruit>]
partial class Witness;
[GenerateShape]
internal partial record Fruit(int Seeds);

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

Serializes a value.

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

Parameters

writer MessagePackWriter

The msgpack writer to use.

value T

The value to serialize.

shape ITypeShape<T>

The shape of T.

cancellationToken CancellationToken

A cancellation token.

Type Parameters

T

The type to be serialized.

Serialize<T>(ref MessagePackWriter, in T?, ITypeShapeProvider, CancellationToken)

Serializes a value.

public void Serialize<T>(ref MessagePackWriter writer, in T? value, ITypeShapeProvider provider, CancellationToken cancellationToken = default)

Parameters

writer MessagePackWriter

The msgpack writer to use.

value T

The value to serialize.

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).

cancellationToken CancellationToken

A cancellation token.

Type Parameters

T

The type to be serialized.

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

Serializes a value.

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

Parameters

writer IBufferWriter<byte>

The msgpack writer to use.

value T

The value to serialize.

shape ITypeShape<T>

The shape of T.

cancellationToken CancellationToken

A cancellation token.

Type Parameters

T

The type to be serialized.

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

Serializes a value.

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

Parameters

writer IBufferWriter<byte>

The msgpack writer to use.

value T

The value to serialize.

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).

cancellationToken CancellationToken

A cancellation token.

Type Parameters

T

The type to be serialized.

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

Serializes a value.

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

Parameters

writer IBufferWriter<byte>

The msgpack writer to use.

value T

The value to serialize.

cancellationToken CancellationToken

A cancellation token.

Type Parameters

T

The type to be serialized.

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

Serializes a value.

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

Parameters

stream Stream

The stream to write to.

value T

The value to serialize.

shape ITypeShape<T>

The shape of T.

cancellationToken CancellationToken

A cancellation token.

Type Parameters

T

The type to be serialized.

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

Serializes a value.

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

Parameters

stream Stream

The stream to write to.

value T

The value to serialize.

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).

cancellationToken CancellationToken

A cancellation token.

Type Parameters

T

The type to be serialized.

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

Serializes a value.

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

Parameters

stream Stream

The stream to write to.

value T

The value to serialize.

cancellationToken CancellationToken

A cancellation token.

Type Parameters

T

The type to be serialized.

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

Serializes a value.

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

Parameters

value T

The value to serialize.

shape ITypeShape<T>

The shape of T.

cancellationToken CancellationToken

A cancellation token.

Returns

byte[]

A byte array containing the serialized msgpack.

Type Parameters

T

The type to be serialized.

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

Serializes a value.

public byte[] Serialize<T>(in T? value, ITypeShapeProvider provider, CancellationToken cancellationToken = default)

Parameters

value T

The value to serialize.

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).

cancellationToken CancellationToken

A cancellation token.

Returns

byte[]

A byte array containing the serialized msgpack.

Type Parameters

T

The type to be serialized.

Serialize<T>(in T?, CancellationToken)

Serializes a value.

public byte[] 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

byte[]

A byte array containing the serialized msgpack.

Type Parameters

T

The type to be serialized.

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

Serializes a value.

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

Parameters

writer IBufferWriter<byte>

The msgpack writer to use.

value T

The value to serialize.

cancellationToken CancellationToken

A cancellation token.

Type Parameters

T

The type to be serialized.

TProvider

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

Serializes a value.

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

Parameters

stream Stream

The stream to write to.

value T

The value to serialize.

cancellationToken CancellationToken

A cancellation token.

Type Parameters

T

The type to be serialized.

TProvider

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

Serializes a value.

public byte[] 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

byte[]

A byte array containing the serialized msgpack.

Type Parameters

T

The type to be serialized.

TProvider