BinaryPack is a binary serialization library inspired by MessagePack, but faster and producing even smaller files. The goal of this project is to be able to use BinaryPack as a drop-in replacement for JSON/XML/MessagePack serialization, when the serialized models don't need to be shared with other applications or with web services. BinaryPack is built to be as fast and memory efficient as possible: it uses virtually no memory allocations, and the serialized data is packed to take up as little space as possible. Whenever you're using either JSON, MessagePack, XML or some other format to cache data for your apps, to send data between clients or to save data that is not critical, you can try using BinaryPack over your previous serialization library - it will provide the same basic functionalities to serialize and deserialize models, but with much higher performance and less memory usage.

Of course you shouldn't take my word for it, so this README includes a number of benchmarks that were performed on a number of different models. The benchmark code and all the models used can be found in this repository. To summarize:

• BinaryPack was consistently the faster library, both during serialization and deserialization. The performance difference ranged from 7.6x faster than Newtonsoft.Json, 7x than Utf8Json and 1.9x than MessagePack when serializing a small JSON response, to 245x faster than Newtonsoft.Json, 129x than Utf8Json and 3.9x than MessagePack when dealing with mostly binary data (eg. a model with a large float[] array, or another unmanaged type).
• The memory usage was on average on par with Utf8Json, except when deserializing mostly binary data, in which case BinaryPack used 1/100 the memory of Utf8Json, and 1/2 that of MessagePack. BinaryPack also almost always resulted in the lowest number of GC collections during serialization and deserialization of models.
• In all cases, the BinaryPack serialization resulted in the smallest file on disk.

• Installing from NuGet
• Quick start
  • Supported properties
  • Attributes
  • FAQ
• Benchmarks
• Requirements
• Special thanks

To install BinaryPack, run the following command in the Package Manager Console

Install-Package BinaryPack

More details available here.

BinaryPack exposes a BinaryConverter class that acts as entry point for all public APIs. Every serialization API is available in an overload that works on a Stream instance, and one that instead uses the new Memory<T> APIs.

The following sample shows how to serialize and deserialize a simple model.

// Assume that this class is a simple model with a few properties
var model = new Model { Text = "Hello world!", Date = DateTime.Now, Values = new[] { 3, 77, 144, 256 } };

// Serialize to a memory buffer
var data = BinaryConverter.Serialize(model);

// Deserialize the model
var loaded = BinaryConverter.Deserialize<Model>(data);

Here is a list of the property types currently supported by the library:

✅ Primitive types (except object): string, bool, int, uint, float, double, etc.

✅ Nullable value types: Nullable<T> or T? for short, where T : struct

✅ Unmanaged types: eg. System.Numerics.Vector2, and all unmanaged value types

✅ .NET collections: List<T>, T[], IList<T>, ICollection<T>, IEnumerable<T>, etc.

✅ .NET dictionaries: Dictionary<TKey, TValue>, IDictionary<TKey, TValue> and IReadOnlyDictionary<TKey, TValue>

BinaryPack has a series of attributes that can be used to customize how the BinaryConverter class handles the serialization of input objects. By default, it will serialize all public properties of a type, but this behavior can be changed by using the BinarySerialization attribute. Here's an example:

[BinarySerialization(SerializationMode.Properties | SerializationMode.NonPublicMembers)]
public class MyModel
{
    internal string Id { get; set; }    
    
    public int Valud { get; set; }    
    
    [IgnoredMember]
    public DateTime Timestamp { get; set; }
}

Similarly, there's also a SerializableMember that can be used when the mode is set to SerializationMode.Explicit.

There are a number of reasons for this. First of all, BinaryPack dynamically generates code to serialize and deserialize every type you need. This means that it doesn't need to inspect types using reflection while serializing/deserializing, eg. to see what fields it needs to read etc. - it just creates the right methods once that work directly on instances of each type, and read/write members one after the other exactly as you would do if you were to write that code manually. This also allows BinaryPack to have some extremely optimized code paths that would otherwise be completely impossible. Then, unlike the JSON/XML/MessagePack formats, BinaryPack doesn't need to include any additional metadata for the serialized items, which saves time. This allows it to use the minimum possible space to serialize every value, which also makes the serialized files as small as possible.

Yes, skipping all the metadata means that the BinaryPack format is not partcularly resilient to changes. This means that if you add or remove one of the serialized members of a type, it will not be possible to read previously serialized instances of that model. Because of this, BinaryPack should not be used with important data and is best suited for caching models or for quick serialization of data being exhanged between different clients.

Unfortunately not at the moment, UWP is still on .NET Standard 2.0 and doesn't support dynamic code generation due to how the .NET Native compiler is implemented. Hopefully it will be possible to use BinaryPack on UWP when it moves to .NET 5 and the new MonoAOT compiler in the second half of 2020.

Here are three full benchmarks executed with the benchmark sample included in this repository. The error and standard deviation columns have been removed to fit each table in the horizontal space available for the README file reader on GitHub. The JSON response model used in the first two benchmarks is the JsonResponseModel class, using 240 child items in the first case, and 2000 in the second. The class used in the last benchmark is instead NeuralNetworkLayerModel.

The BinaryPack library requires .NET Standard 2.1 support and it has no external dependencies.

Additionally, you need an IDE with .NET Core 3.0 and C# 8.0 support to compile the library and samples on your PC.

Icon made by freepik from www.flaticon.com.