Getting Started

Installation

Consume this library via its NuGet Package. Click on the badge to find its latest version and the instructions for consuming it that best apply to your project.

C# language version

When your project targets .NET Framework or .NET Standard 2.x, the C# language version may default to 7.3. C# 12 introduced support for generic attributes, which is a fundamental requirement PolyType, upon which Nerdbank.MessagePack is based. If you find generic attributes are not allowed in your C# code, change your .csproj file to include this snippet:

<PropertyGroup>
  <LangVersion>12</LangVersion>
</PropertyGroup>

Using the latest C# language version (even when targeting older runtimes like .NET Framework) is generally a Good Thing. C# automatically produces errors if you try to use certain newer language features that requires a newer runtime.

Usage

Given a type annotated with GenerateShapeAttribute like this:

[GenerateShape]
public partial record ARecord(string AString, bool ABoolean);

You can serialize and deserialize it like this:

.NET
.NET Standard

void Roundtrip()
{
    // Construct a value.
    var value = new ARecord("hello", true);

    // Create a serializer instance.
    MessagePackSerializer serializer = new();

    // Serialize the value to the buffer.
    byte[] msgpack = serializer.Serialize(value);

    // Deserialize it back.
    ARecord? deserialized = serializer.Deserialize<ARecord>(msgpack);
}

void Roundtrip()
{
    // Construct a value.
    var value = new ARecord("hello", true);

    // Create a serializer instance.
    MessagePackSerializer serializer = new();

    // Serialize the value to the buffer.
    byte[] msgpack = serializer.Serialize(value, Witness.ShapeProvider);

    // Deserialize it back.
    ARecord? deserialized = serializer.Deserialize<ARecord>(msgpack, Witness.ShapeProvider);
}

[GenerateShape<ARecord>]
internal partial class Witness;

Only the top-level types that you serialize need the attribute. All types that they reference will automatically have their 'shape' source generated as well so the whole object graph can be serialized.

If you need to directly serialize a type that isn't declared in your project and is not annotated with [GenerateShape], you can define another class in your own project to provide that shape. Learn more about witness classes.

Limitations

Not all types are suitable for serialization. I/O types (e.g. Steam) or types that are more about function that data (e.g. Task<T>, CancellationToken) are not suitable for serialization.

Typeless serialization is not supported. For security and trim-friendly reasons, the type of the object being deserialized must be known at compile time.

Reference cycles in the object graph are not supported. Reference equality preservation is an option that can be turned on.

Converting to JSON

It can sometimes be useful to understand what msgpack is actually being serialized. Msgpack being a binary format makes looking at the serialized buffer less than helpful for most folks.

You may use the ConvertToJson method to convert most msgpack buffers to JSON for human inspection.

It is important to note that not all msgpack is expressible as JSON. In particular the following limitations apply:

Msgpack maps allow for any type to serve as the key. JSON only supports strings. In such cases, the rendered JSON will emit the msgpack key as-is, and the result will be human-readable but not valid JSON.
Msgpack supports arbitrary binary extensions. In JSON this will be rendered as a base64-encoded string with an "msgpack extension {typecode} as base64: " prefix.
Msgpack supports binary blobs. In JSON this will be rendered as a base64-encoded string with an "msgpack binary as base64: " prefix.