Class OptionalConverters

Namespace

Nerdbank.MessagePack

Assembly

Nerdbank.MessagePack.dll

Contains extension methods to add optional converters.

public static class OptionalConverters

Inheritance

object

OptionalConverters

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

The library comes with many converters. Some are not enabled by default to avoid unnecessary dependencies and to keep a trimmed application size small when it doesn't require them. The extension methods in this class can be used to turn these optional converters on.

Methods

WithExpandoObjectConverter(MessagePackSerializer)

Adds a converter for ExpandoObject to the specified serializer.

public static MessagePackSerializer WithExpandoObjectConverter(this MessagePackSerializer serializer)

Parameters

serializer MessagePackSerializer

The serializer to add converters to.

Returns

MessagePackSerializer

The modified serializer.

Remarks

This can deserialize anything, but can only serialize object graphs for which every runtime type has a shape available as provided by TypeShapeProvider.

Exceptions

ArgumentException

Thrown if a converter for ExpandoObject has already been added.

WithGuidConverter(MessagePackSerializer, GuidFormat)

Adds a converter for Guid to the specified serializer.

public static MessagePackSerializer WithGuidConverter(this MessagePackSerializer serializer, OptionalConverters.GuidFormat format = GuidFormat.BinaryLittleEndian)

Parameters

serializer MessagePackSerializer

The serializer to add converters to.

format OptionalConverters.GuidFormat

The format in which the Guid should be written.

Returns

MessagePackSerializer

The modified serializer.

Remarks

The Guid converter is optimized to avoid allocating strings during the conversion.

Exceptions

ArgumentOutOfRangeException

Thrown if format is not one of the allowed values.

ArgumentException

Thrown if a converter for Guid has already been added.

WithObjectDynamicConverter(MessagePackSerializer)

Adds a converter to the specified serializer that can write objects with a declared type of object based on their runtime type (provided a type shape is available for the runtime type), and can deserialize them based on their msgpack token types into primitives, dictionaries and arrays.

public static MessagePackSerializer WithObjectDynamicConverter(this MessagePackSerializer serializer)

Parameters

serializer MessagePackSerializer

The serializer to add converters to.

Returns

MessagePackSerializer

The modified serializer.

Remarks

This converter is very similar to the one added by WithObjectPrimitiveConverter(MessagePackSerializer), except that the deserialized result can be used with the C# dynamic keyword where the content of maps can also be accessed using string keys as if they were properties.

Exceptions

ArgumentException

Thrown if a converter for object has already been added.

WithObjectPrimitiveConverter(MessagePackSerializer)

Adds a converter to the specified serializer that can write objects with a declared type of object based on their runtime type (provided a type shape is available for the runtime type), and can deserialize them based on their msgpack token types into primitives, dictionaries and arrays.

public static MessagePackSerializer WithObjectPrimitiveConverter(this MessagePackSerializer serializer)

Parameters

serializer MessagePackSerializer

The serializer to add converters to.

Returns

MessagePackSerializer

The modified serializer.

Remarks

This converter is not included by default because untyped serialization is not generally desirable. But it is offered as a converter that may be added to Converters in order to enable limited untyped serialization.

Maps are deserialized as objects that implement IReadOnlyDictionary<TKey, TValue> where the key is object and the value is a nullable object.

Exceptions

ArgumentException

Thrown if a converter for object has already been added.

WithSystemTextJsonConverters(MessagePackSerializer)

Adds converters for common System.Text.Json types, including: JsonNode, JsonElement, and JsonDocument to the specified serializer.

public static MessagePackSerializer WithSystemTextJsonConverters(this MessagePackSerializer serializer)

Parameters

serializer MessagePackSerializer

The serializer to add converters to.

Returns

MessagePackSerializer

The modified serializer.

Exceptions

ArgumentNullException

Thrown if serializer is null.

ArgumentException

Thrown if a converter for any of these System.Text.Json types has already been added.