drocdotcode / ceras

Universal binary serializer for a wide variety of scenarios https://discord.gg/FGaCX4c

Ceras

Universal binary serializer for a wide variety of scenarios, lots of features, and tuned for performance

Ceras is a binary serializer. It converts whatever object you give it into a byte[] and back. It's not just a replacement for BinaryFormatter or MessagePack, it also adds tons of features on top.

Supports reference loops, large/complicated inheritance chains, splitting objects into parts, ...

Quick start

using Ceras;

class ExamplePerson { public string Name; public int Number; }
var p = new ExamplePerson { Name = "test", Number = 5 };

var s = new CerasSerializer();

var bytes = s.Serialize(p);

>> 1. Many more examples in the code tutorial

>> 2. Detailed guides for specific scenarios on my blog

>> 3. Read 'Optimization & Usage Pitfalls'

Features

Major Features

• Very fast, very small binary output
• Supports pretty much any type:
  • Hand-written formatters for all common .NET types
  • Generates new formatters at runtime for any new/user type
  • Very easy to extend and customize
• Full support for circular references (including object caching)
• Full support for polymorphism / inheritance / interfaces
• Can serialize objects into parts as "ExtenalObjects" (useful in many many scenarios)
• Automatic version-tolerance, no need to assign any attributes to your classes!

>> Full feature list (and planned features)

>> FAQ

>> Using Ceras to easily send C# objects over TCP/UDP

What can this be used for?

Example usages

The primary goal is to make an universal serializer that can be used in every situation. Personally my primary intentions were easy object persistance and network communication. I've added many features over time and whenever someone can think of a good scenario that should be supported as well I'll make it happen.

Examples:

• Settings: Saving objects to disk quickly without much trouble: settings, savegames, whatever it is. With pretty much zero config. See steps 1 and 2 in the Usage Guide

• Splitting: So your Person has reference to other Person objects, but each one should be serialized individually? No problem, use IExternalRootObject. It's super easy. (see External Objects Guide (Game DB example))).

• Network: In the past people used to manually write network messages into a network stream or packet because serialization was either too slow or couldn't handle complicated object-graphs. Receiving objects from the network also allocated a lot of 'garbage objects' because there was no easy way to recycle packets. Other serializers always write long type names... Ceras fixes all of this, with some simple setup you can implement a very efficient protocol (see Network Example Guide). If you want to, you can even let Ceras 'learn' types that get sent so types will be automatically encoded to short IDs (or use config.KnownTypes to register network types for maximum efficiency).

• More: The above are just examples, Ceras is made so it can be used in pretty much every situation...

When should I not use this?

• If you need human readable output for some reason. For example some file that you want to be able to edit in a text-editor. For those usages JSON or XML are likely better suited.

• You plan to use this on a platform that does not support code generation. Serializers for user-types are created at runtime through code-generation. And if that isn't allowed (for example on iOS) Ceras won't be able to generate arbitrary object-formatters. Built-in types will still work though. There are ways to fix this though... (pre-generating the formatters)

Support

Want me to help you? These are your options:

• Open an issue
• Join my Discord (probably the best for direct one-on-one help)
• Make sure you've read FAQ and Optimization & Pitfalls