Class OptionalConverters
- Namespace
- Nerdbank.MessagePack
- Assembly
- Nerdbank.MessagePack.dll
Contains extension methods to add optional converters.
public static class OptionalConverters- Inheritance
-
OptionalConverters
- Inherited Members
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
WithAssumedDateTimeKind(MessagePackSerializer, DateTimeKind)
Configures the built-in DateTime converter to assume a specific DateTimeKind when serializing values that have a Unspecified kind.
public static MessagePackSerializer WithAssumedDateTimeKind(this MessagePackSerializer serializer, DateTimeKind kind)Parameters
serializerMessagePackSerializerThe serializer to add converters to.
kindDateTimeKind
Returns
- MessagePackSerializer
The modified serializer.
Remarks
By default, serializing a DateTime with an Unspecified kind throws an exception because the MessagePack format does not permit that kind of ambiguity. While an explicit DateTimeKind is always preferred, this method allows you to assume a specific DateTimeKind for such values.
Specifying Utc will cause unspecified values to be treated as UTC and therefore serialized without any adjustment. Specifying Local will cause unspecified values to be treated as local time and therefore adjusted to UTC time during serialization.
The serialized form will always be UTC (per the MessagePack encoding spec), and a deserialized DateTime will always have the DateTimeKind set to Utc.
Exceptions
- ArgumentException
Thrown if this method has already been called on the given
serializeror a custom DateTime converter has already been set.
WithDynamicObjectConverter(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 WithDynamicObjectConverter(this MessagePackSerializer serializer)Parameters
serializerMessagePackSerializerThe serializer to add converters to.
Returns
- MessagePackSerializer
The modified serializer.
Remarks
This converter is very similar to the one added by WithObjectConverter(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.
WithExpandoObjectConverter(MessagePackSerializer)
Adds a converter for ExpandoObject to the specified serializer.
public static MessagePackSerializer WithExpandoObjectConverter(this MessagePackSerializer serializer)Parameters
serializerMessagePackSerializerThe serializer to add converters to.
Returns
- MessagePackSerializer
The modified serializer.
Remarks
This can only serialize an ExpandoObject whose properties are values or objects whose runtime type has a shape available as provided by TypeShapeProvider.
This can deserialize any msgpack map.
Nested maps included in the deserialized graph will be deserialized as dictionaries that support C# dynamic access to their members,
similar to ExpandoObject but with read-only access.
Exceptions
- ArgumentException
Thrown if a converter for ExpandoObject has already been added.
WithGuidConverter(MessagePackSerializer, GuidStringFormat)
Adds a converter for Guid to the specified serializer that serializes GUIDs as strings.
public static MessagePackSerializer WithGuidConverter(this MessagePackSerializer serializer, OptionalConverters.GuidStringFormat format)Parameters
serializerMessagePackSerializerThe serializer to add converters to.
formatOptionalConverters.GuidStringFormatThe string format in which the Guid should be written. All string-based formats can read all other string-based formats.
Returns
- MessagePackSerializer
The modified serializer.
Remarks
By default, Guid values are serialized in a compact binary format. This method allows you to override that behavior to serialize them as strings instead. The Guid converter is optimized to avoid allocating strings during the conversion.
Exceptions
- ArgumentOutOfRangeException
Thrown if
formatis not one of the allowed values.- ArgumentException
Thrown if a converter for Guid has already been added.
WithHiFiDateTime(MessagePackSerializer)
Replaces the built-in DateTime converter that uses msgpack standard timestamp encoding with a proprietary converter that preserves Kind for DateTime values.
public static MessagePackSerializer WithHiFiDateTime(this MessagePackSerializer serializer)Parameters
serializerMessagePackSerializerThe existing MessagePackSerializer to configure. Cannot be null.
Returns
- MessagePackSerializer
A new MessagePackSerializer instance with high-fidelity DateTime support enabled.
Remarks
The msgpack encoding standard mandates that all timestamps are encoded as UTC. This means all deserialized DateTime values have their Kind set to Utc, and forces serialization to throw if Unspecified is encountered (unless WithAssumedDateTimeKind(MessagePackSerializer, DateTimeKind) is used).
With this method, DateTime values are serialized such that their Kind
is preserved.
When the Kind is Utc, the value is stored as a msgpack timestamp.
For other kinds, a msgpack array of two elements is used: [ticks, kind].
Note that serializing anything other than Utc values is not recommended both because it is not interoperable with other msgpack implementations and (more importantly) because the party that deserializes the value may not be in the same time zone (even if the user and machine is the same) and thus could end up with a different time interpretation than the one that was serialized.
- See Also
WithObjectConverter(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 WithObjectConverter(this MessagePackSerializer serializer)Parameters
serializerMessagePackSerializerThe 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. 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. Deserialized arrays will be typed as object arrays. This converter deserializes an entire msgpack structure using these primitives, since no type information is available to deserialize any sub-graph as a higher-level type.
To use object as the declared type for fields or properties used as or within a key of a dictionary or hash set, either the field or property must be read-only and be pre-initialized with a collection instance, or ComparerProvider must also be set to null or some other non-default provider that can hash object keys.
Exceptions
- ArgumentException
Thrown if a converter for object has already been added.
- See Also
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
serializerMessagePackSerializerThe serializer to add converters to.
Returns
- MessagePackSerializer
The modified serializer.
Exceptions
- ArgumentNullException
Thrown if
serializeris null.- ArgumentException
Thrown if a converter for any of these System.Text.Json types has already been added.