Skip to content

Common serialization abstraction with multiple implementations

Notifications You must be signed in to change notification settings

Greentube/serialization

Repository files navigation

Greentube.Serialization Build Status Build status codecov

A set of libraries for serialization which work as a common interface for serialization. It includes multiple implementations available for use.

Each project under src contains its own documentation and a link to its NuGet package. One of such packages is the convenience package Greentube.Serialization.All which is a metapackage that allows bringing all dependencies with one reference: NuGet

dotnet add package Greentube.Serialization.All

Although optional, it provides one-line configuration for applications using Microsoft.Extensions.DependencyInjection.

Implementations

The supported serialization formats are:

Adding to your project

With Microsoft.Extensions.DependencyInjection

All of the above can be 'plugged-in' with a single line when using the Serialization.DependencyInjection.* packages. Example serialization setup:

dotnet add package Greentube.Serialization.DependencyInjection.Json

Then JSON can be added with:

services.AddJsonSerializer();

Other packages:

dotnet add package Greentube.Serialization.DependencyInjection.Xml
dotnet add package Greentube.Serialization.DependencyInjection.ProtoBuf
dotnet add package Greentube.Serialization.DependencyInjection.MessagePack
services.AddXmlSerializer();
// or
services.AddProtoBufSerializer();
// or
services.AddMessagePackSerializer();

Or with the builder:

services.AddSerialization(builder =>
    {
        builder.AddMessagePack();
        // or
        builder.AddProtoBuf();
        // or
        builder.AddJson();
        // or
        builder.AddXml();
    });

Without dependency injection or using other containers

If you are using another container like Autofac, Castle Windsor or not using any container at all, you can avoid bringing the Microsoft.Extensions.DependencyInjection dependencies. Just reference the implementation you want to use directly:

dotnet add package Greentube.Serialization.MessagePack

Then MessagePack can be used:

var messagePack = new MessagePackSerializer();

Likewise with the other implementations:

dotnet add package Greentube.Serialization.Json
dotnet add package Greentube.Serialization.Xml
dotnet add package Greentube.Serialization.ProtoBuf
new JsonSerializer();
new XmlSerializer();
new ProtoBufSerializer();

Configuration

Each implementation has some additional settings

MessagePack

Define a custom IFormatterResolver and compressiong LZ4:

builder.AddMessagePack(o => {
    // Don't require attributes on model
    o.FormatterResolver = global::MessagePack.Resolvers.ContractlessStandardResolver.Instance;
    // Use LZ4 compression
    o.UseLz4Compression = true;
});

ProtoBuf

Custom RuntimeTypeModel

var model = RuntimeTypeModel.Create();
model.Add(typeof(SomeMessage), false).Add(1, nameof(SomeMessage.Body));
builder.AddProtoBuf(o => o.RuntimeTypeModel = model);

JSON

Define the encoding.

// Use UTF-16 instead of the default UTF-8
builder.AddJson(o => o.Encoding = Encoding.Unicode);

XML

Xml with user-defined default namespace

builder.AddXml(p => p.DefaultNamespace = "some-namespace");

Xml with user-defined factory delegate

// Root attribute will be named: 'messaging'
builder.AddXml(p => p.Factory = type => new XmlSerializer(type, new XmlRootAttribute("messaging")));

Highlights

  • Simple abstraction
  • Multiple serialization formats supported
  • Pay for play: no unwanted dependencies
  • DI packages to consume with single line of code

This library was created mainly to support Greentube.Messaging.