MessagePack for C# (.NET Framework, .NET 8, Unity, Xamarin)

[!IMPORTANT] This README is for v3.x (current stable). v4.0.0-preview.1 is now available: more than twice the performance, stronger safety, and full Native AOT support, while staying feature- and wire-compatible with v3. Check out the v4 README and join the preview.

The extremely fast MessagePack serializer for C#. It is 10x faster than MsgPack-Cli and outperforms other C# serializers. MessagePack for C# also ships with built-in support for LZ4 compression - an extremely fast compression algorithm. Performance is important, particularly in applications like games, distributed computing, microservices, or data caches.

MessagePack has a compact binary size and a full set of general purpose expressive data types. Please have a look at the comparison with JSON, protobuf, ZeroFormatter section and learn why MessagePack C# is the fastest.

Table of Contents

• Installation
  • NuGet packages
  • Unity
  • Migration notes from v1.x
• Quick Start
• Analyzer
• Built-in supported types
• Object Serialization
• DataContract compatibility
• Serializing readonly/immutable object members (SerializationConstructor)
• Serialization Callback
• Union
• Dynamic (Untyped) Deserialization
• Object Type Serialization
• Typeless
• Security
• Performance
  • Deserialization Performance for different options
  • String interning
• LZ4 Compression
  • Attributions
• Comparison with protobuf, JSON, ZeroFormatter
• Hints to achieve maximum performance when using MessagePack for C#
  • Use indexed keys instead of string keys (Contractless)
  • Create own custom composite resolver
  • Use native resolvers
  • Be careful when copying buffers
  • Choosing compression
• Extensions
• Experimental Features
• High-Level API (MessagePackSerializer)
  • Multiple MessagePack structures on a single Stream
• Low-Level API (IMessagePackFormatter<T>)
• Primitive API (MessagePackWriter, MessagePackReader)
  • MessagePackReader
  • MessagePackWriter
• Main Extension Point (IFormatterResolver)
• MessagePackFormatterAttribute
• IgnoreFormatter
• Reserved Extension Types
• Unity support
• AOT Code Generation (support for Unity/Xamarin)
• RPC
  • MagicOnion
  • StreamJsonRpc
• How to build
• Author Info
• Code of Conduct & .NET Foundation notice

Installation

This library is distributed via NuGet. Special Unity support is available, too.

We target .NET Standard 2.0 with special optimizations for .NET 8+ and .NET Framework. The library code is pure C# (with Just-In-Time IL code generation on some platforms or AOT safe source generators).

NuGet packages

To install with NuGet, just install the MessagePack package:

Install-Package MessagePack

There are also a range of official and third party Extension Packages available (learn more in our extensions section):

Install-Package MessagePack.ReactiveProperty
Install-Package MessagePack.UnityShims
Install-Package MessagePack.AspNetCoreMvcFormatter

Unity

For Unity projects, please read the Unity Support section to install.

Migration notes from prior versions

Migrating from a prior major version of MessagePack to the latest? Check out these instructions.

Quick Start

Define the struct or class to be serialized and annotate it with a [MessagePackObject] attribute. Annotate members whose values should be serialized (fields as well as properties) with [Key] attributes.

[MessagePackObject]
public class MyClass
{
    // Key attributes take a serialization index (or string name)
    // The values must be unique and versioning has to be considered as well.
    // Keys are described in later sections in more detail.
    [Key(0)]
    public int Age { get; set; }

    [Key(1)]
    public string FirstName { get; set; }

    [Key(2)]
    public string LastName { get; set; }

    // All fields or properties that should not be serialized must be annotated with [IgnoreMember].
    [IgnoreMember]
    public string FullName { get { return FirstName + LastName; } }
}

Call MessagePackSerializer.Serialize<T>/Deserialize<T> to serialize/deserialize your object instance. You can use the ConvertToJson method to get a human readable representation of any MessagePack binary blob.

class Program
{
    static void Main(string[] args)
    {
        var mc = new MyClass
        {
            Age = 99,
            FirstName = "hoge",
            LastName = "huga",
        };

        // Call Serialize/Deserialize, that's all.
        byte[] bytes = MessagePackSerializer.Serialize(mc);
        MyClass mc2 = MessagePackSerializer.Deserialize<MyClass>(bytes);

        // You can dump MessagePack binary blobs to human readable json.
        // Using indexed keys (as opposed to string keys) will serialize to MessagePack arrays,
        // hence property names are not available.
        // [99,"hoge","huga"]
        var json = MessagePackSerializer.ConvertToJson(bytes);
        Console.WriteLine(json);
    }
}

By default, a MessagePackObject annotation is required. This can be made optional; see the Object Serialization section and the Formatter Resolver section for details.

Analyzer

The MessagePackAnalyzer package(includes in default) aids with:

1. Produces compiler warnings upon incorrect attribute use, member accessibility, and more.
2. Automating attributing of your serializable classes and members.
3. Optionally improving startup time through AOT formatter generation.

The first two of these features is demonstrated below:

Two assembly-level attributes exist to help with mixing in your own custom formatters with the automatically generated ones: - MessagePackKnownFormatterAttribute - Identifies classes that implement IMessagePackFormatter<T>. The T type argument will not produce an analyzer warning when T is used elsewhere in a serializable object. When using a source generated resolver, the resolver will refer to this formatter for the appropriate type(s). - MessagePackAssumedFormattableAttribute - Identifies types that are assumed to have an IMessagePackFormatter<T> somewhere, and that will be combined within an IFormatterResolver at runtime to ensure the specified type can be serialized. This attribute will suppress the analyzer warning from using that type although the type does not have a [MessagePackObject] attribute on it.

Built-in supported types

These types can serialize by default:

• Primitives (int, string, etc...), Enums, Nullable<>, Lazy<>
• TimeSpan, DateTime, DateTimeOffset, DateOnly (.NET 6+), TimeOnly (.NET 6+)
• Guid, Uri, Version, StringBuilder, decimal, Type
• BigInteger, Complex, Half (.NET 5+), Rune (.NET 5+), Int128 (.NET 7+), UInt128 (.NET 7+)
• Memory<byte>, ReadOnlyMemory<byte>, ReadOnlySequence<byte>
• System.Numerics.Vector2, Vector3, Vector4, Quaternion, Matrix3x2, Matrix4x4
• Array[], Array[,], Array[,,], Array[,,,], ArraySegment<>, BitArray
• KeyValuePair<,>, Tuple<,...>, ValueTuple<,...>
• ArrayList, Hashtable
• List<>, LinkedList<>, Queue<>, Stack<>, HashSet<>, ReadOnlyCollection<>, SortedList<,>
• IList<>, ICollection<>, IEnumerable<>, IReadOnlyCollection<>, IReadOnlyList<>
• Dictionary<,>, IDictionary<,>, SortedDictionary<,>, ILookup<,>, IGrouping<,>, ReadOnlyDictionary<,>, IReadOnlyDictionary<,>
• ObservableCollection<>, ReadOnlyObservableCollection<>
• ISet<>,
• ConcurrentBag<>, ConcurrentQueue<>, ConcurrentStack<>, ConcurrentDictionary<,>
• Immutable collections (ImmutableList<>, etc)
• Custom implementations of ICollection<> or IDictionary<,> with a parameterless constructor
• Custom implementations of IList or IDictionary with a parameterless constructor

You can add support for custom types, and there are some official/third-party extension packages for:

• ReactiveProperty
• for Unity (Vector3, Quaternion, etc...)
• F# (Record, FsList, Discrimi