Class MsgPackSerializer

Namespace

ShapeShift.MsgPack

Assembly

ShapeShift.MsgPack.dll

Serializes PolyType-described object graphs as MessagePack.

public sealed record MsgPackSerializer : ShapeShiftSerializer<MsgPackEncoder, MsgPackDecoder>, IEquatable<ShapeShiftSerializer<MsgPackEncoder, MsgPackDecoder>>, IReferencePreservingSerializer<MsgPackEncoder, MsgPackDecoder>, IEquatable<MsgPackSerializer>

Inheritance

object

ShapeShiftSerializer<MsgPackEncoder, MsgPackDecoder>

MsgPackSerializer

Implements

IEquatable<ShapeShiftSerializer<MsgPackEncoder, MsgPackDecoder>>

IReferencePreservingSerializer<MsgPackEncoder, MsgPackDecoder>

IEquatable<MsgPackSerializer>

Inherited Members

ShapeShiftSerializer<MsgPackEncoder, MsgPackDecoder>.StartingContext

ShapeShiftSerializer<MsgPackEncoder, MsgPackDecoder>.InternStrings

ShapeShiftSerializer<MsgPackEncoder, MsgPackDecoder>.Converters

ShapeShiftSerializer<MsgPackEncoder, MsgPackDecoder>.ConverterFactories

ShapeShiftSerializer<MsgPackEncoder, MsgPackDecoder>.SerializeDefaultValues

ShapeShiftSerializer<MsgPackEncoder, MsgPackDecoder>.DeserializeDefaultValues

ShapeShiftSerializer<MsgPackEncoder, MsgPackDecoder>.SerializeEnumValuesByName

ShapeShiftSerializer<MsgPackEncoder, MsgPackDecoder>.PropertyNamingPolicy

ShapeShiftSerializer<MsgPackEncoder, MsgPackDecoder>.PreserveReferences

ShapeShiftSerializer<MsgPackEncoder, MsgPackDecoder>.WithReflectionConverterTypes(ConverterTypeCollection)

ShapeShiftSerializer<MsgPackEncoder, MsgPackDecoder>.GetContract(ITypeShape)

ShapeShiftSerializer<MsgPackEncoder, MsgPackDecoder>.GetContract<T>()

ShapeShiftSerializer<MsgPackEncoder, MsgPackDecoder>.GetContract<T, TProvider>()

ShapeShiftSerializer<MsgPackEncoder, MsgPackDecoder>.GetPath<TRoot, TValue>(Expression<Func<TRoot, TValue>>, ITypeShape<TRoot>)

ShapeShiftSerializer<MsgPackEncoder, MsgPackDecoder>.GetPath<TRoot, TValue>(Expression<Func<TRoot, TValue>>)

ShapeShiftSerializer<MsgPackEncoder, MsgPackDecoder>.GetPath<TRoot, TValue, TProvider>(Expression<Func<TRoot, TValue>>)

ShapeShiftSerializer<MsgPackEncoder, MsgPackDecoder>.Serialize<T>(ref MsgPackEncoder, in T, ITypeShape<T>, CancellationToken)

ShapeShiftSerializer<MsgPackEncoder, MsgPackDecoder>.Deserialize<T>(ref MsgPackDecoder, ITypeShape<T>, CancellationToken)

ShapeShiftSerializer<MsgPackEncoder, MsgPackDecoder>.TryDeserializeFragment<T>(ref MsgPackDecoder, ShapeShiftPath, ITypeShape<T>, out T, CancellationToken)

ShapeShiftSerializer<MsgPackEncoder, MsgPackDecoder>.DeserializeFragment<T>(ref MsgPackDecoder, ShapeShiftPath, ITypeShape<T>, CancellationToken)

ShapeShiftSerializer<MsgPackEncoder, MsgPackDecoder>.CreateSequenceReader<T>(ITypeShape<T>, CancellationToken)

ShapeShiftSerializer<MsgPackEncoder, MsgPackDecoder>.CreateDocumentReader<T>(ITypeShape<T>, CancellationToken)

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Constructors

MsgPackSerializer()

Initializes a new instance of the MsgPackSerializer class.

public MsgPackSerializer()

Properties

ConverterFactories

Gets an array of converter factories to consult when creating a converter for a given type.

public ImmutableArray<IShapeShiftConverterFactory<MsgPackEncoder, MsgPackDecoder>> ConverterFactories { get; init; }

Property Value

ImmutableArray<IShapeShiftConverterFactory<MsgPackEncoder, MsgPackDecoder>>

Remarks

Factories are the last resort for creating a custom converter, coming after ShapeShift.SerializerConfiguration<TEncoder, TDecoder>.Converters and ShapeShift.SerializerConfiguration<TEncoder, TDecoder>.ConverterTypes.

Methods

CreateDocumentReader<T>(CancellationToken)

Creates a reader that incrementally enumerates a sequence of whole top-level MessagePack values sharing one buffer.

public ShapeShiftDocumentReader<T, MsgPackEncoder, MsgPackDecoder> CreateDocumentReader<T>(CancellationToken cancellationToken = default) where T : IShapeable<T>

Parameters

cancellationToken CancellationToken

A cancellation token that applies throughout the lifetime of the reader.

Returns

ShapeShiftDocumentReader<T, MsgPackEncoder, MsgPackDecoder>

The reader. Callers should dispose of it (or use a using statement) when done.

Type Parameters

T

The type of each top-level value.

CreateDocumentReader<T, TProvider>(CancellationToken)

Creates a reader that incrementally enumerates a sequence of whole top-level MessagePack values sharing one buffer using a specified shape provider.

public ShapeShiftDocumentReader<T, MsgPackEncoder, MsgPackDecoder> CreateDocumentReader<T, TProvider>(CancellationToken cancellationToken = default) where TProvider : IShapeable<T>

Parameters

cancellationToken CancellationToken

A cancellation token that applies throughout the lifetime of the reader.

Returns

ShapeShiftDocumentReader<T, MsgPackEncoder, MsgPackDecoder>

The reader. Callers should dispose of it (or use a using statement) when done.

Type Parameters

T

The type of each top-level value.

TProvider

The type shape provider.

CreateSequenceReader<T>(CancellationToken)

Creates a reader that incrementally enumerates the elements of a MessagePack array, whether that array is the root of the document or is reached by first seeking into an enclosing document.

public ShapeShiftSequenceReader<T, MsgPackEncoder, MsgPackDecoder> CreateSequenceReader<T>(CancellationToken cancellationToken = default) where T : IShapeable<T>

Parameters

cancellationToken CancellationToken

A cancellation token that applies throughout the lifetime of the reader.

Returns

ShapeShiftSequenceReader<T, MsgPackEncoder, MsgPackDecoder>

The reader. Callers should dispose of it (or use a using statement) when done.

Type Parameters

T

The type of each element in the array.

CreateSequenceReader<T, TProvider>(CancellationToken)

Creates a reader that incrementally enumerates the elements of a MessagePack array using a specified shape provider, whether that array is the root of the document or is reached by first seeking into an enclosing document.

public ShapeShiftSequenceReader<T, MsgPackEncoder, MsgPackDecoder> CreateSequenceReader<T, TProvider>(CancellationToken cancellationToken = default) where TProvider : IShapeable<T>

Parameters

cancellationToken CancellationToken

A cancellation token that applies throughout the lifetime of the reader.

Returns

ShapeShiftSequenceReader<T, MsgPackEncoder, MsgPackDecoder>

The reader. Callers should dispose of it (or use a using statement) when done.

Type Parameters

T

The type of each element in the array.

TProvider

The type shape provider.

DeserializeAllAsync<T>(PipeReader, long, CancellationToken)

Asynchronously reads a sequence of whole top-level MessagePack values sharing one PipeReader, buffering only as much input as each value requires.

public IAsyncEnumerable<T?> DeserializeAllAsync<T>(PipeReader reader, long maxBufferedSize = 67108864, CancellationToken cancellationToken = default) where T : IShapeable<T>

Parameters

reader PipeReader

The source reader. This method does not complete it; the caller retains ownership.

maxBufferedSize long

The maximum number of bytes to buffer while searching for any single value, bounding memory use against a value that never completes (e.g. one truncated by a misbehaving sender, or a hostile/corrupt length header).

cancellationToken CancellationToken

A cancellation token that applies throughout the enumeration.

Returns

IAsyncEnumerable<T>

An async sequence of the values read, ending gracefully when the reader reaches its end.

Type Parameters

T

The type of each top-level value.

DeserializeAllAsync<T>(Stream, long, CancellationToken)

Asynchronously reads a sequence of whole top-level MessagePack values from a stream, buffering only as much input as each value requires.

public IAsyncEnumerable<T?> DeserializeAllAsync<T>(Stream stream, long maxBufferedSize = 67108864, CancellationToken cancellationToken = default) where T : IShapeable<T>

Parameters

stream Stream

The source stream. It is not closed or disposed by this method.

maxBufferedSize long

The maximum number of bytes to buffer while searching for any single value, bounding memory use against a value that never completes (e.g. one truncated by a misbehaving sender, or a hostile/corrupt length header).

cancellationToken CancellationToken

A cancellation token that applies throughout the enumeration.

Returns

IAsyncEnumerable<T>

An async sequence of the values read, ending gracefully when the stream reaches its end.

Type Parameters

T

The type of each top-level value.

DeserializeAllAsync<T, TProvider>(PipeReader, long, CancellationToken)

Asynchronously reads a sequence of whole top-level MessagePack values sharing one PipeReader using a specified shape provider, buffering only as much input as each value requires.

public IAsyncEnumerable<T?> DeserializeAllAsync<T, TProvider>(PipeReader reader, long maxBufferedSize = 67108864, CancellationToken cancellationToken = default) where TProvider : IShapeable<T>

Parameters

reader PipeReader

The source reader. This method does not complete it; the caller retains ownership.

maxBufferedSize long

The maximum number of bytes to buffer while searching for any single value, bounding memory use against a value that never completes (e.g. one truncated by a misbehaving sender, or a hostile/corrupt length header).

cancellationToken CancellationToken

A cancellation token that applies throughout the enumeration.

Returns

IAsyncEnumerable<T>

An async sequence of the values read, ending gracefully when the reader reaches its end.

Type Parameters

T

The type of each top-level value.

TProvider

The type shape provider.

DeserializeAllAsync<T, TProvider>(Stream, long, CancellationToken)

Asynchronously reads a sequence of whole top-level MessagePack values from a stream using a specified shape provider, buffering only as much input as each value requires.

public IAsyncEnumerable<T?> DeserializeAllAsync<T, TProvider>(Stream stream, long maxBufferedSize = 67108864, CancellationToken cancellationToken = default) where TProvider : IShapeable<T>

Parameters

stream Stream

The source stream. It is not closed or disposed by this method.

maxBufferedSize long

The maximum number of bytes to buffer while searching for any single value, bounding memory use against a value that never completes (e.g. one truncated by a misbehaving sender, or a hostile/corrupt length header).

cancellationToken CancellationToken

A cancellation token that applies throughout the enumeration.

Returns

IAsyncEnumerable<T>

An async sequence of the values read, ending gracefully when the stream reaches its end.

Type Parameters

T

The type of each top-level value.

TProvider

The type shape provider.

DeserializeAllFramesAsync<T>(PipeReader, long, CancellationToken)

Asynchronously reads an endless sequence of length-prefixed frames from a PipeReader.

public IAsyncEnumerable<T?> DeserializeAllFramesAsync<T>(PipeReader reader, long maxFrameLength = 67108864, CancellationToken cancellationToken = default) where T : IShapeable<T>

Parameters

reader PipeReader

The source reader. This method does not complete it; the caller retains ownership.

maxFrameLength long

The largest frame this call will accept, checked against each length prefix before any of that frame is buffered.

cancellationToken CancellationToken

A cancellation token that applies throughout the enumeration.

Returns

IAsyncEnumerable<T>

An async sequence of the framed values, ending gracefully when the reader reaches its end between frames.

Type Parameters

T

The type of each framed value.

Exceptions

DecoderException

Thrown when the reader ends inside a frame, or a frame does not contain exactly one MessagePack value.

ShapeShiftSerializationException

Thrown when a frame declares a length greater than maxFrameLength.

DeserializeAllFramesAsync<T>(Stream, long, CancellationToken)

Asynchronously reads an endless sequence of length-prefixed frames from a stream.

public IAsyncEnumerable<T?> DeserializeAllFramesAsync<T>(Stream stream, long maxFrameLength = 67108864, CancellationToken cancellationToken = default) where T : IShapeable<T>

Parameters

stream Stream

The source stream. It is not closed or disposed by this method.

maxFrameLength long

The largest frame this call will accept, checked against each length prefix before any of that frame is buffered.

cancellationToken CancellationToken

A cancellation token that applies throughout the enumeration.

Returns

IAsyncEnumerable<T>

An async sequence of the framed values, ending gracefully when the stream reaches its end between frames.

Type Parameters

T

The type of each framed value.

Exceptions

DecoderException

Thrown when the stream ends inside a frame, or a frame does not contain exactly one MessagePack value.

ShapeShiftSerializationException

Thrown when a frame declares a length greater than maxFrameLength.

DeserializeAllFramesAsync<T, TProvider>(PipeReader, long, CancellationToken)

Asynchronously reads an endless sequence of length-prefixed frames from a PipeReader using a specified shape provider.

public IAsyncEnumerable<T?> DeserializeAllFramesAsync<T, TProvider>(PipeReader reader, long maxFrameLength = 67108864, CancellationToken cancellationToken = default) where TProvider : IShapeable<T>

Parameters

reader PipeReader

The source reader. This method does not complete it; the caller retains ownership.

maxFrameLength long

The largest frame this call will accept, checked against each length prefix before any of that frame is buffered.

cancellationToken CancellationToken

A cancellation token that applies throughout the enumeration.

Returns

IAsyncEnumerable<T>

An async sequence of the framed values, ending gracefully when the reader reaches its end between frames.

Type Parameters

T

The type of each framed value.

TProvider

The type shape provider.

Exceptions

DecoderException

Thrown when the reader ends inside a frame, or a frame does not contain exactly one MessagePack value.

ShapeShiftSerializationException

Thrown when a frame declares a length greater than maxFrameLength.

DeserializeAllFramesAsync<T, TProvider>(Stream, long, CancellationToken)

Asynchronously reads an endless sequence of length-prefixed frames from a stream using a specified shape provider.

public IAsyncEnumerable<T?> DeserializeAllFramesAsync<T, TProvider>(Stream stream, long maxFrameLength = 67108864, CancellationToken cancellationToken = default) where TProvider : IShapeable<T>

Parameters

stream Stream

The source stream. It is not closed or disposed by this method.

maxFrameLength long

The largest frame this call will accept, checked against each length prefix before any of that frame is buffered.

cancellationToken CancellationToken

A cancellation token that applies throughout the enumeration.

Returns

IAsyncEnumerable<T>

An async sequence of the framed values, ending gracefully when the stream reaches its end between frames.

Type Parameters

T

The type of each framed value.

TProvider

The type shape provider.

Exceptions

DecoderException

Thrown when the stream ends inside a frame, or a frame does not contain exactly one MessagePack value.

ShapeShiftSerializationException

Thrown when a frame declares a length greater than maxFrameLength.

DeserializeAsync<T>(PipeReader, long, CancellationToken)

Asynchronously reads one MessagePack value from a PipeReader, buffering only as much input as that value requires.

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

Parameters

reader PipeReader

The source reader. This method does not complete it; the caller retains ownership.

maxBufferedSize long

The maximum number of bytes to buffer while searching for the value, bounding memory use against a value that never completes (e.g. one truncated by a misbehaving sender, or a hostile/corrupt length header).

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask<T>

The decoded value.

Type Parameters

T

The value type.

Exceptions

DecoderException

Thrown if the reader has no more values, or ends in the middle of one.

DeserializeAsync<T>(Stream, long, CancellationToken)

Asynchronously reads one MessagePack value from a stream, buffering only as much input as that value requires.

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

Parameters

stream Stream

The source stream. It is not closed or disposed by this method.

maxBufferedSize long

The maximum number of bytes to buffer while searching for the value, bounding memory use against a value that never completes (e.g. one truncated by a misbehaving sender, or a hostile/corrupt length header).

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask<T>

The decoded value.

Type Parameters

T

The value type.

Exceptions

DecoderException

Thrown if the stream has no more values, or ends in the middle of one.

DeserializeAsync<T, TProvider>(PipeReader, long, CancellationToken)

Asynchronously reads one MessagePack value from a PipeReader using a specified shape provider, buffering only as much input as that value requires.

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

Parameters

reader PipeReader

The source reader. This method does not complete it; the caller retains ownership.

maxBufferedSize long

The maximum number of bytes to buffer while searching for the value, bounding memory use against a value that never completes (e.g. one truncated by a misbehaving sender, or a hostile/corrupt length header).

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask<T>

The decoded value.

Type Parameters

T

The value type.

TProvider

The type shape provider.

Exceptions

DecoderException

Thrown if the reader has no more values, or ends in the middle of one.

DeserializeAsync<T, TProvider>(Stream, long, CancellationToken)

Asynchronously reads one MessagePack value from a stream using a specified shape provider, buffering only as much input as that value requires.

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

Parameters

stream Stream

The source stream. It is not closed or disposed by this method.

maxBufferedSize long

The maximum number of bytes to buffer while searching for the value, bounding memory use against a value that never completes (e.g. one truncated by a misbehaving sender, or a hostile/corrupt length header).

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask<T>

The decoded value.

Type Parameters

T

The value type.

TProvider

The type shape provider.

Exceptions

DecoderException

Thrown if the stream has no more values, or ends in the middle of one.

DeserializeFragment<T>(ReadOnlySpan<byte>, ShapeShiftPath, CancellationToken)

Deserializes the value found at a given ShapeShiftPath within a MessagePack buffer, skipping over everything else without fully parsing or buffering it.

public T? DeserializeFragment<T>(ReadOnlySpan<byte> messagePack, ShapeShiftPath path, CancellationToken cancellationToken = default) where T : IShapeable<T>

Parameters

messagePack ReadOnlySpan<byte>

The encoded bytes.

path ShapeShiftPath

The location of the value to deserialize.

cancellationToken CancellationToken

A cancellation token.

Returns

T

The deserialized value.

Type Parameters

T

The value type.

Exceptions

ShapeShiftSerializationException

Thrown when path could not be found.

DeserializeFragment<T, TProvider>(ReadOnlySpan<byte>, ShapeShiftPath, CancellationToken)

Deserializes the value found at a given ShapeShiftPath within a MessagePack buffer using a specified shape provider, skipping over everything else without fully parsing or buffering it.

public T? DeserializeFragment<T, TProvider>(ReadOnlySpan<byte> messagePack, ShapeShiftPath path, CancellationToken cancellationToken = default) where TProvider : IShapeable<T>

Parameters

messagePack ReadOnlySpan<byte>

The encoded bytes.

path ShapeShiftPath

The location of the value to deserialize.

cancellationToken CancellationToken

A cancellation token.

Returns

T

The deserialized value.

Type Parameters

T

The value type.

TProvider

The type shape provider.

Exceptions

ShapeShiftSerializationException

Thrown when path could not be found.

DeserializeFrameAsync<T>(PipeReader, long, CancellationToken)

Asynchronously reads one length-prefixed frame from a PipeReader and deserializes the single MessagePack value it contains.

public ValueTask<T?> DeserializeFrameAsync<T>(PipeReader reader, long maxFrameLength = 67108864, CancellationToken cancellationToken = default) where T : IShapeable<T>

Parameters

reader PipeReader

The source reader. This method does not complete it; the caller retains ownership.

maxFrameLength long

The largest frame this call will accept, checked against the length prefix before any of the frame is buffered.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask<T>

The decoded value.

Type Parameters

T

The value type.

Exceptions

DecoderException

Thrown when the reader has no more frames, ends inside one, or a frame does not contain exactly one MessagePack value.

ShapeShiftSerializationException

Thrown when a frame declares a length greater than maxFrameLength.

DeserializeFrameAsync<T>(Stream, long, CancellationToken)

Asynchronously reads one length-prefixed frame from a stream and deserializes the single MessagePack value it contains.

public ValueTask<T?> DeserializeFrameAsync<T>(Stream stream, long maxFrameLength = 67108864, CancellationToken cancellationToken = default) where T : IShapeable<T>

Parameters

stream Stream

The source stream. It is not closed or disposed by this method.

maxFrameLength long

The largest frame this call will accept, checked against the length prefix before any of the frame is buffered.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask<T>

The decoded value.

Type Parameters

T

The value type.

Exceptions

DecoderException

Thrown when the stream has no more frames, ends inside one, or a frame does not contain exactly one MessagePack value.

ShapeShiftSerializationException

Thrown when a frame declares a length greater than maxFrameLength.

DeserializeFrameAsync<T, TProvider>(PipeReader, long, CancellationToken)

Asynchronously reads one length-prefixed frame from a PipeReader using a specified shape provider, and deserializes the single MessagePack value it contains.

public ValueTask<T?> DeserializeFrameAsync<T, TProvider>(PipeReader reader, long maxFrameLength = 67108864, CancellationToken cancellationToken = default) where TProvider : IShapeable<T>

Parameters

reader PipeReader

The source reader. This method does not complete it; the caller retains ownership.

maxFrameLength long

The largest frame this call will accept, checked against the length prefix before any of the frame is buffered.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask<T>

The decoded value.

Type Parameters

T

The value type.

TProvider

The type shape provider.

Exceptions

DecoderException

Thrown when the reader has no more frames, ends inside one, or a frame does not contain exactly one MessagePack value.

ShapeShiftSerializationException

Thrown when a frame declares a length greater than maxFrameLength.

DeserializeFrameAsync<T, TProvider>(Stream, long, CancellationToken)

Asynchronously reads one length-prefixed frame from a stream using a specified shape provider, and deserializes the single MessagePack value it contains.

public ValueTask<T?> DeserializeFrameAsync<T, TProvider>(Stream stream, long maxFrameLength = 67108864, CancellationToken cancellationToken = default) where TProvider : IShapeable<T>

Parameters

stream Stream

The source stream. It is not closed or disposed by this method.

maxFrameLength long

The largest frame this call will accept, checked against the length prefix before any of the frame is buffered.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask<T>

The decoded value.

Type Parameters

T

The value type.

TProvider

The type shape provider.

Exceptions

DecoderException

Thrown when the stream has no more frames, ends inside one, or a frame does not contain exactly one MessagePack value.

ShapeShiftSerializationException

Thrown when a frame declares a length greater than maxFrameLength.

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

Deserializes a value from a potentially segmented MessagePack sequence.

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

Parameters

messagePack ReadOnlySequence<byte>

The encoded bytes.

cancellationToken CancellationToken

A cancellation token.

Returns

T

The decoded value.

Type Parameters

T

The value type.

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

Deserializes a value from MessagePack.

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

Parameters

messagePack ReadOnlySpan<byte>

The encoded bytes.

cancellationToken CancellationToken

A cancellation token.

Returns

T

The decoded value.

Type Parameters

T

The value type.

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

Deserializes a value from a potentially segmented MessagePack sequence using a specified shape provider.

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

Parameters

messagePack ReadOnlySequence<byte>

The encoded bytes.

cancellationToken CancellationToken

A cancellation token.

Returns

T

The decoded value.

Type Parameters

T

The value type.

TProvider

The type shape provider.

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

Deserializes a value using a specified shape provider.

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

Parameters

messagePack ReadOnlySpan<byte>

The encoded bytes.

cancellationToken CancellationToken

A cancellation token.

Returns

T

The decoded value.

Type Parameters

T

The value type.

TProvider

The type shape provider.

SerializeAllAsync<T>(PipeWriter, IAsyncEnumerable<T?>, CancellationToken)

Asynchronously writes a sequence of MessagePack values, one after another, to a PipeWriter.

public ValueTask SerializeAllAsync<T>(PipeWriter writer, IAsyncEnumerable<T?> values, CancellationToken cancellationToken = default) where T : IShapeable<T>

Parameters

writer PipeWriter

The destination writer. This method flushes it but does not complete it.

values IAsyncEnumerable<T>

The values to write. The sequence may be endless; this method writes until it ends or the operation is canceled.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask

A task that represents the operation.

Type Parameters

T

The value type.

SerializeAllAsync<T>(PipeWriter, IEnumerable<T?>, CancellationToken)

Asynchronously writes a sequence of MessagePack values, one after another, to a PipeWriter.

public ValueTask SerializeAllAsync<T>(PipeWriter writer, IEnumerable<T?> values, CancellationToken cancellationToken = default) where T : IShapeable<T>

Parameters

writer PipeWriter

The destination writer. This method flushes it but does not complete it.

values IEnumerable<T>

The values to write.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask

A task that represents the operation.

Type Parameters

T

The value type.

SerializeAllAsync<T>(Stream, IAsyncEnumerable<T?>, CancellationToken)

Asynchronously writes a sequence of MessagePack values, one after another, to a stream.

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

Parameters

stream Stream

The destination stream. It is not closed or disposed by this method.

values IAsyncEnumerable<T>

The values to write. The sequence may be endless; this method writes until it ends or the operation is canceled.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask

A task that represents the operation.

Type Parameters

T

The value type.

SerializeAllAsync<T>(Stream, IEnumerable<T?>, CancellationToken)

Asynchronously writes a sequence of MessagePack values, one after another, to a stream.

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

Parameters

stream Stream

The destination stream. It is not closed or disposed by this method.

values IEnumerable<T>

The values to write.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask

A task that represents the operation.

Type Parameters

T

The value type.

SerializeAllAsync<T, TProvider>(PipeWriter, IAsyncEnumerable<T?>, CancellationToken)

Asynchronously writes a sequence of MessagePack values, one after another, to a PipeWriter using a specified shape provider.

public ValueTask SerializeAllAsync<T, TProvider>(PipeWriter writer, IAsyncEnumerable<T?> values, CancellationToken cancellationToken = default) where TProvider : IShapeable<T>

Parameters

writer PipeWriter

The destination writer. This method flushes it but does not complete it.

values IAsyncEnumerable<T>

The values to write. The sequence may be endless; this method writes until it ends or the operation is canceled.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask

A task that represents the operation.

Type Parameters

T

The value type.

TProvider

The type shape provider.

Remarks

Each value is converted synchronously and then flushed, so a slow consumer applies backpressure to the producer between values rather than accumulating an unbounded buffer.

SerializeAllAsync<T, TProvider>(PipeWriter, IEnumerable<T?>, CancellationToken)

Asynchronously writes a sequence of MessagePack values, one after another, to a PipeWriter using a specified shape provider.

public ValueTask SerializeAllAsync<T, TProvider>(PipeWriter writer, IEnumerable<T?> values, CancellationToken cancellationToken = default) where TProvider : IShapeable<T>

Parameters

writer PipeWriter

The destination writer. This method flushes it but does not complete it.

values IEnumerable<T>

The values to write.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask

A task that represents the operation.

Type Parameters

T

The value type.

TProvider

The type shape provider.

Remarks

Each value is converted synchronously and then flushed, so a slow consumer applies backpressure to the producer between values rather than accumulating an unbounded buffer.

SerializeAllAsync<T, TProvider>(Stream, IAsyncEnumerable<T?>, CancellationToken)

Asynchronously writes a sequence of MessagePack values, one after another, to a stream using a specified shape provider.

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

Parameters

stream Stream

The destination stream. It is not closed or disposed by this method.

values IAsyncEnumerable<T>

The values to write. The sequence may be endless; this method writes until it ends or the operation is canceled.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask

A task that represents the operation.

Type Parameters

T

The value type.

TProvider

The type shape provider.

SerializeAllAsync<T, TProvider>(Stream, IEnumerable<T?>, CancellationToken)

Asynchronously writes a sequence of MessagePack values, one after another, to a stream using a specified shape provider.

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

Parameters

stream Stream

The destination stream. It is not closed or disposed by this method.

values IEnumerable<T>

The values to write.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask

A task that represents the operation.

Type Parameters

T

The value type.

TProvider

The type shape provider.

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

Asynchronously writes one MessagePack value to a PipeWriter.

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

Parameters

writer PipeWriter

The destination writer. This method flushes it but does not complete it.

value T

The value to serialize.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask

A task that represents the operation.

Type Parameters

T

The value type.

Remarks

The value is converted synchronously (as with any other synchronous Serialize overload); only the flush to writer is asynchronous.

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

Asynchronously writes one MessagePack value to a stream.

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

Parameters

stream Stream

The destination stream. It is not closed or disposed by this method.

value T

The value to serialize.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask

A task that represents the operation.

Type Parameters

T

The value type.

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

Asynchronously writes one MessagePack value to a PipeWriter using a specified shape provider.

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

Parameters

writer PipeWriter

The destination writer. This method flushes it but does not complete it.

value T

The value to serialize.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask

A task that represents the operation.

Type Parameters

T

The value type.

TProvider

The type shape provider.

Remarks

The value is converted synchronously (as with any other synchronous Serialize overload); only the flush to writer is asynchronous.

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

Asynchronously writes one MessagePack value to a stream using a specified shape provider.

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

Parameters

stream Stream

The destination stream. It is not closed or disposed by this method.

value T

The value to serialize.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask

A task that represents the operation.

Type Parameters

T

The value type.

TProvider

The type shape provider.

SerializeFrameAsync<T>(PipeWriter, T?, CancellationToken)

Asynchronously writes one MessagePack value to a PipeWriter inside a length-prefixed frame.

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

Parameters

writer PipeWriter

The destination writer. This method flushes it but does not complete it.

value T

The value to serialize.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask

A task that represents the operation.

Type Parameters

T

The value type.

Remarks

See MsgPackFraming for the frame format and when framing is worth its four bytes.

SerializeFrameAsync<T>(Stream, T?, CancellationToken)

Asynchronously writes one MessagePack value to a stream inside a length-prefixed frame.

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

Parameters

stream Stream

The destination stream. It is not closed or disposed by this method.

value T

The value to serialize.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask

A task that represents the operation.

Type Parameters

T

The value type.

Remarks

See MsgPackFraming for the frame format and when framing is worth its four bytes.

SerializeFrameAsync<T, TProvider>(PipeWriter, T?, CancellationToken)

Asynchronously writes one MessagePack value to a PipeWriter inside a length-prefixed frame using a specified shape provider.

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

Parameters

writer PipeWriter

The destination writer. This method flushes it but does not complete it.

value T

The value to serialize.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask

A task that represents the operation.

Type Parameters

T

The value type.

TProvider

The type shape provider.

Remarks

See MsgPackFraming for the frame format and when framing is worth its four bytes.

SerializeFrameAsync<T, TProvider>(Stream, T?, CancellationToken)

Asynchronously writes one MessagePack value to a stream inside a length-prefixed frame using a specified shape provider.

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

Parameters

stream Stream

The destination stream. It is not closed or disposed by this method.

value T

The value to serialize.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask

A task that represents the operation.

Type Parameters

T

The value type.

TProvider

The type shape provider.

Remarks

See MsgPackFraming for the frame format and when framing is worth its four bytes.

Serialize<T>(in T?, CancellationToken)

Serializes a value to MessagePack.

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

The encoded bytes.

Type Parameters

T

The value type.

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

Serializes a value into a caller-owned buffer.

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

Parameters

output IBufferWriter<byte>

The destination.

value T

The value to serialize.

cancellationToken CancellationToken

A cancellation token.

Type Parameters

T

The value type.

TProvider

The type shape provider.

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

Serializes a value using a specified shape provider.

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

The encoded bytes.

Type Parameters

T

The value type.

TProvider

The type shape provider.

TryDeserializeFragmentAsync<T>(PipeReader, ShapeShiftPath, long, CancellationToken)

Asynchronously reads one top-level MessagePack value from a PipeReader and deserializes only the fragment found at a given ShapeShiftPath within it.

public ValueTask<(bool Found, T? Value)> TryDeserializeFragmentAsync<T>(PipeReader reader, ShapeShiftPath path, long maxBufferedSize = 67108864, CancellationToken cancellationToken = default) where T : IShapeable<T>

Parameters

reader PipeReader

The source reader. This method does not complete it; the caller retains ownership.

path ShapeShiftPath

The location, within the next top-level value, of the value to deserialize.

maxBufferedSize long

The maximum number of bytes to buffer while searching for the enclosing top-level value's end, bounding memory use against a value that never completes.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask<(bool HasValue, T Value)>

A tuple whose Found is true and whose Value is the deserialized fragment, or whose Found is false because the path is not present in the value that was read.

Type Parameters

T

The type to deserialize the fragment as.

Remarks

The enclosing value's bytes are buffered (a value's extent cannot be known before its framing has been walked), but they are never copied into one contiguous buffer: the path is walked directly over the pipe's own segments, and everything that is not on the path is stepped over rather than parsed.

Exceptions

DecoderException

Thrown when the reader has no more values, or ends in the middle of one.

TryDeserializeFragmentAsync<T>(Stream, ShapeShiftPath, long, CancellationToken)

Asynchronously reads one top-level MessagePack value from a stream and deserializes only the fragment found at a given ShapeShiftPath within it.

public ValueTask<(bool Found, T? Value)> TryDeserializeFragmentAsync<T>(Stream stream, ShapeShiftPath path, long maxBufferedSize = 67108864, CancellationToken cancellationToken = default) where T : IShapeable<T>

Parameters

stream Stream

The source stream. It is not closed or disposed by this method.

path ShapeShiftPath

The location, within the next top-level value, of the value to deserialize.

maxBufferedSize long

The maximum number of bytes to buffer while searching for the enclosing top-level value's end, bounding memory use against a value that never completes.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask<(bool HasValue, T Value)>

A tuple whose Found is true and whose Value is the deserialized fragment, or whose Found is false because the path is not present in the value that was read.

Type Parameters

T

The type to deserialize the fragment as.

Exceptions

DecoderException

Thrown when the stream has no more values, or ends in the middle of one.

TryDeserializeFragmentAsync<T, TProvider>(PipeReader, ShapeShiftPath, long, CancellationToken)

Asynchronously reads one top-level MessagePack value from a PipeReader using a specified shape provider, and deserializes only the fragment found at a given ShapeShiftPath within it.

public ValueTask<(bool Found, T? Value)> TryDeserializeFragmentAsync<T, TProvider>(PipeReader reader, ShapeShiftPath path, long maxBufferedSize = 67108864, CancellationToken cancellationToken = default) where TProvider : IShapeable<T>

Parameters

reader PipeReader

The source reader. This method does not complete it; the caller retains ownership.

path ShapeShiftPath

The location, within the next top-level value, of the value to deserialize.

maxBufferedSize long

The maximum number of bytes to buffer while searching for the enclosing top-level value's end, bounding memory use against a value that never completes.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask<(bool HasValue, T Value)>

A tuple whose Found is true and whose Value is the deserialized fragment, or whose Found is false because the path is not present in the value that was read.

Type Parameters

T

The type to deserialize the fragment as.

TProvider

The type shape provider.

Remarks

The enclosing value's bytes are buffered (a value's extent cannot be known before its framing has been walked), but they are never copied into one contiguous buffer: the path is walked directly over the pipe's own segments, and everything that is not on the path is stepped over rather than parsed.

Exceptions

DecoderException

Thrown when the reader has no more values, or ends in the middle of one.

TryDeserializeFragmentAsync<T, TProvider>(Stream, ShapeShiftPath, long, CancellationToken)

Asynchronously reads one top-level MessagePack value from a stream using a specified shape provider, and deserializes only the fragment found at a given ShapeShiftPath within it.

public ValueTask<(bool Found, T? Value)> TryDeserializeFragmentAsync<T, TProvider>(Stream stream, ShapeShiftPath path, long maxBufferedSize = 67108864, CancellationToken cancellationToken = default) where TProvider : IShapeable<T>

Parameters

stream Stream

The source stream. It is not closed or disposed by this method.

path ShapeShiftPath

The location, within the next top-level value, of the value to deserialize.

maxBufferedSize long

The maximum number of bytes to buffer while searching for the enclosing top-level value's end, bounding memory use against a value that never completes.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask<(bool HasValue, T Value)>

A tuple whose Found is true and whose Value is the deserialized fragment, or whose Found is false because the path is not present in the value that was read.

Type Parameters

T

The type to deserialize the fragment as.

TProvider

The type shape provider.

Exceptions

DecoderException

Thrown when the stream has no more values, or ends in the middle of one.

TryDeserializeFragment<T>(in ReadOnlySequence<byte>, ShapeShiftPath, out T?, CancellationToken)

Attempts to deserialize the value found at a given ShapeShiftPath within a potentially segmented MessagePack sequence, skipping over everything else without fully parsing or buffering it.

public bool TryDeserializeFragment<T>(in ReadOnlySequence<byte> messagePack, ShapeShiftPath path, out T? value, CancellationToken cancellationToken = default) where T : IShapeable<T>

Parameters

messagePack ReadOnlySequence<byte>

The encoded bytes.

path ShapeShiftPath

The location of the value to deserialize.

value T

Receives the deserialized value if this method returns true; otherwise default.

cancellationToken CancellationToken

A cancellation token.

Returns

bool

true if path was found; false otherwise.

Type Parameters

T

The value type.

TryDeserializeFragment<T>(ReadOnlySpan<byte>, ShapeShiftPath, out T?, CancellationToken)

Attempts to deserialize the value found at a given ShapeShiftPath within a MessagePack buffer, skipping over everything else without fully parsing or buffering it.

public bool TryDeserializeFragment<T>(ReadOnlySpan<byte> messagePack, ShapeShiftPath path, out T? value, CancellationToken cancellationToken = default) where T : IShapeable<T>

Parameters

messagePack ReadOnlySpan<byte>

The encoded bytes.

path ShapeShiftPath

The location of the value to deserialize.

value T

Receives the deserialized value if this method returns true; otherwise default.

cancellationToken CancellationToken

A cancellation token.

Returns

bool

true if path was found; false otherwise.

Type Parameters

T

The value type.

TryDeserializeFragment<T, TProvider>(in ReadOnlySequence<byte>, ShapeShiftPath, out T?, CancellationToken)

Attempts to deserialize the value found at a given ShapeShiftPath within a potentially segmented MessagePack sequence using a specified shape provider, skipping over everything else without fully parsing or buffering it.

public bool TryDeserializeFragment<T, TProvider>(in ReadOnlySequence<byte> messagePack, ShapeShiftPath path, out T? value, CancellationToken cancellationToken = default) where TProvider : IShapeable<T>

Parameters

messagePack ReadOnlySequence<byte>

The encoded bytes.

path ShapeShiftPath

The location of the value to deserialize.

value T

Receives the deserialized value if this method returns true; otherwise default.

cancellationToken CancellationToken

A cancellation token.

Returns

bool

true if path was found; false otherwise.

Type Parameters

T

The value type.

TProvider

The type shape provider.

TryDeserializeFragment<T, TProvider>(ReadOnlySpan<byte>, ShapeShiftPath, out T?, CancellationToken)

Attempts to deserialize the value found at a given ShapeShiftPath within a MessagePack buffer using a specified shape provider, skipping over everything else without fully parsing or buffering it.

public bool TryDeserializeFragment<T, TProvider>(ReadOnlySpan<byte> messagePack, ShapeShiftPath path, out T? value, CancellationToken cancellationToken = default) where TProvider : IShapeable<T>

Parameters

messagePack ReadOnlySpan<byte>

The encoded bytes.

path ShapeShiftPath

The location of the value to deserialize.

value T

Receives the deserialized value if this method returns true; otherwise default.

cancellationToken CancellationToken

A cancellation token.

Returns

bool

true if path was found; false otherwise.

Type Parameters

T

The value type.

TProvider

The type shape provider.