Class MessagePackConverter<T>

Namespace

Nerdbank.MessagePack

Assembly

Nerdbank.MessagePack.dll

An interface for all message pack converters.

public abstract class MessagePackConverter<T> : IMessagePackConverter

Type Parameters

T

The data type that can be converted by this object.

Inheritance

object

MessagePackConverter<T>

Implements

IMessagePackConverter

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

Authors of derived types should review this documentation for important guidance on implementing a converter.

Key points to remember about each Write(ref MessagePackWriter, in T?, SerializationContext) or Read(ref MessagePackReader, SerializationContext) method (or their async equivalents):

• Read or write exactly one msgpack structure. Use an array or map header for multiple values.
• Call DepthStep() before any significant work.
• Delegate serialization of sub-values to a converter obtained using GetConverter<T>(ITypeShapeProvider?) rather than making a top-level call back to MessagePackSerializer.

Implementations are encouraged to override GetJsonSchema(JsonSchemaContext, ITypeShape) in order to support GetJsonSchema(ITypeShape).

Properties

PreferAsyncSerialization

Gets a value indicating whether callers should prefer the async methods on this object.

public virtual bool PreferAsyncSerialization { get; }

Property Value

bool

Unless overridden in a derived converter, this value is always false.

Remarks

Derived types that override the WriteAsync(MessagePackAsyncWriter, object?, SerializationContext) and/or ReadAsync(MessagePackAsyncReader, SerializationContext) methods should also override this property and have it return true.

Methods

ApplyJsonSchemaNullability(JsonObject)

Transforms a JSON schema to include "null" as a possible value for the schema.

protected static JsonObject ApplyJsonSchemaNullability(JsonObject schema)

Parameters

schema JsonObject

The schema to transform. This value may be mutated.

Returns

JsonObject

The result of the transformation, which may be a different root object than given in schema.

Remarks

This is provided as a helper function for GetJsonSchema(JsonSchemaContext, ITypeShape) implementations.

CreateJsonValue(object?)

Wraps a boxed primitive as a JsonValue.

protected static JsonValue? CreateJsonValue(object? value)

Parameters

value object

The boxed primitive to wrap as a JsonValue. Only certain primitives are supported (roughly those supported by non-generic overloads of JsonValue.Create.

Returns

JsonValue

The JsonValue, or null if value is null because JsonValue does not represent null.

Remarks

This is provided as a helper function for GetJsonSchema(JsonSchemaContext, ITypeShape) implementations.

Exceptions

NotSupportedException

Thrown if value is of a type that cannot be wrapped as a simple JSON value.

CreateMsgPackBinarySchema(string?)

Creates a JSON schema fragment that provides a cursory description of a MessagePack binary blob.

protected static JsonObject CreateMsgPackBinarySchema(string? description = null)

Parameters

description string

An optional description to include with the schema.

Returns

JsonObject

A JSON schema fragment.

Remarks

This is provided as a helper function for GetJsonSchema(JsonSchemaContext, ITypeShape) implementations.

CreateMsgPackExtensionSchema(sbyte)

Creates a JSON schema fragment that provides a cursory description of a MessagePack extension.

protected static JsonObject CreateMsgPackExtensionSchema(sbyte extensionCode)

Parameters

extensionCode sbyte

The extension code used.

Returns

JsonObject

A JSON schema fragment.

Remarks

This is provided as a helper function for GetJsonSchema(JsonSchemaContext, ITypeShape) implementations.

CreateUndocumentedSchema(Type)

Creates a JSON schema fragment that describes a type that has no documented schema.

protected static JsonObject CreateUndocumentedSchema(Type undocumentingConverter)

Parameters

undocumentingConverter Type

The converter that has not provided a schema.

Returns

JsonObject

The JSON schema fragment that permits anything and explains why.

Remarks

This is provided as a helper function for GetJsonSchema(JsonSchemaContext, ITypeShape) implementations.

GetJsonSchema(JsonSchemaContext, ITypeShape)

Gets the JSON schema that resembles the data structure that this converter can serialize and deserialize.

public virtual JsonObject? GetJsonSchema(JsonSchemaContext context, ITypeShape typeShape)

Parameters

context JsonSchemaContext

A means to obtain schema fragments for inclusion when your converter delegates to other converters.

typeShape ITypeShape

The shape of the type T, in case it provides useful metadata for constructing the schema.

Returns

JsonObject

The fragment of JSON schema that describes the value written by this converter, or null if this method has not been overridden.

Remarks

Implementations should return a new instance of JsonObject that represents the JSON schema fragment for every caller. A shared instance may be used to call DeepClone() and the result returned.

The type property should not include "null" on account of the converted type being a reference type. It is the consumer of the object that will determine whether null is an acceptable value of the object.

Custom converters that do not override this method will lead to a JSON schema that does not describe the written data, and allows any data as input.

If the converter delegates to other converters, the schemas for those sub-values can be obtained for inclusion in the returned schema by calling GetJsonSchema(ITypeShape) on the context.

See Also

CreateMsgPackExtensionSchema(sbyte)

CreateJsonValue(object?)

ApplyJsonSchemaNullability(JsonObject)

Read(ref MessagePackReader, SerializationContext)

Deserializes an instance of T.

public abstract T? Read(ref MessagePackReader reader, SerializationContext context)

Parameters

reader MessagePackReader

The reader to use.

context SerializationContext

Context for the deserialization.

Returns

T

The deserialized value.

ReadAsync(MessagePackAsyncReader, SerializationContext)

Deserializes an instance of T.

public virtual ValueTask<T?> ReadAsync(MessagePackAsyncReader reader, SerializationContext context)

Parameters

reader MessagePackAsyncReader

The reader to use.

context SerializationContext

Context for the deserialization.

Returns

ValueTask<T>

The deserialized value.

Remarks

The default implementation delegates to Read(ref MessagePackReader, SerializationContext) after ensuring there is sufficient buffer to read the next structure.

Derived classes should only override this method if they may read a lot of data. They should do so with the intent to be able to read some data then asynchronously wait for data before reading more in order to reduce the amount of memory required to buffer.

Write(ref MessagePackWriter, in T?, SerializationContext)

Serializes an instance of T.

public abstract void Write(ref MessagePackWriter writer, in T? value, SerializationContext context)

Parameters

writer MessagePackWriter

The writer to use.

value T

The value to serialize.

context SerializationContext

Context for the serialization.

Remarks

Implementations of this method should not flush the writer.

WriteAsync(MessagePackAsyncWriter, T?, SerializationContext)

Serializes an instance of T.

public virtual ValueTask WriteAsync(MessagePackAsyncWriter writer, T? value, SerializationContext context)

Parameters

writer MessagePackAsyncWriter

The writer to use.

value T

The value to serialize.

context SerializationContext

Context for the serialization.

Returns

ValueTask

A task that tracks the async serialization.

Remarks

The default implementation delegates to Write(ref MessagePackWriter, in T?, SerializationContext) and then flushes the data to the pipe if the buffers are getting relatively full.

Derived classes should only override this method if they may write a lot of data. They should do so with the intent of writing fragments of data at a time and periodically call FlushIfAppropriateAsync(SerializationContext) in order to keep the size of memory buffers from growing too much.