Aoxe.Tomlyn 2024.3.0

Aoxe.Serialization

Provide an easy way to use serializations. It is also the serializer provider for all Aoxe technology stacks like configuration, cache, queue, rpc, etc.

• 1. Why use Aoxe.Serialization?
• 2. Functions
• 3. Getting Started
• 4. Packages introductions
  • 4.1. Aoxe.DataContractSerializer
  • 4.2. Aoxe.Jil
  • 4.3. Aoxe.MemoryPack
  • 4.4. Aoxe.MessagePack
  • 4.5. Aoxe.MsgPack
  • 4.6. Aoxe.NetJson
  • 4.7. Aoxe.NewtonsoftJson
  • 4.8. Aoxe.Utf8Json
  • 4.9. Aoxe.Protobuf
  • 4.10. Aoxe.SharpYaml
  • 4.11. Aoxe.SpanJson
  • 4.12. Aoxe.SystemTextJson
  • 4.13. Aoxe.Xml
  • 4.14. Aoxe.YamlDotNet
  • 4.15. Aoxe.ZeroFormatter
• 5. Benchmark
  • 5.1. Stream
    • 5.1.1. To Stream
    • 5.1.2. From Stream
  • 5.2. Bytes
    • 5.2.1. To Bytes
    • 5.2.2. From Bytes
  • 5.3. Text
    • 5.3.1. Json
      • 5.3.1.1. To Json
      • 5.3.1.2. From Json
    • 5.3.2. Xml
      • 5.3.2.1. To Xml
      • 5.3.2.2. From Xml
    • 5.3.3. Yaml
      • 5.3.3.1. To Yaml
      • 5.3.3.2. From Yaml
    • 5.3.4. Ini
      • 5.3.4.1. To Ini
      • 5.3.4.2. From Ini
    • 5.3.5. Toml
      • 5.3.5.1. To Toml
      • 5.3.5.2. From Toml

1. Why use Aoxe.Serialization?

There are many different serializers in the world, they have different features and limitations. This project allows you to use difference serializers in the same way. Also it set nullable and default value for all serializers.

Serializers can be divided into two categories (binary and text):

• Binary serializers
  • MemoryPack
  • MessagePack
  • MsgPack.Cli
  • protobuf-net
  • ZeroFormatter
• Text serializers
  • Json
    • Jil
    • NetJson
    • Newtonsoft.Json
    • SpanJson
    • System.Text.Json
    • Utf8Json
  • Xml
    • XmlSerializer
    • DataContractSerializer
  • Yaml
    • SharpYaml
    • YamlDotNet
  • Ini
    • ini-parser-netstandard
  • Toml
    • Tomlet
    • Tomlyn

Though some serializers does not support stream or bytes, the Aoxe serializers will supply the lack. And the text serializers will support text on this base.

2. Functions

• Helper: Unified code style and provide lack of features. The default enconding is UTF-8.
  • stream
    • sync
      • MemoryStream ToStream<TValue>(TValue? value)
      • MemoryStream ToStream(Type type, object? value)
      • void Pack<TValue>(TValue? value, Stream? stream)
      • void Pack(Type type, object? value, Stream? stream)
      • TValue? FromStream<TValue>(Stream? stream)
      • object? FromStream(Type type, Stream? stream)
    • async
      • Task PackAsync<TValue>(TValue? value, Stream? stream)
      • Task PackAsync(Type type, object? value, Stream? stream)
      • Task<TValue?> FromStreamAsync<TValue>(Stream? stream)
      • Task<object?> FromStreamAsync(Type type, Stream? stream)
  • bytes
    • byte[] ToBytes<TValue>(TValue? value)
    • byte[] ToBytes(Type type, object? value)
    • TValue? FromBytes<TValue>(byte[]? bytes)
    • object? FromBytes(Type type, byte[]? bytes)
  • text
    • json
      • string ToJson<TValue>(TValue? value)
      • string ToJson(Type type, object? value)
      • TValue? FromJson<TValue>(string? json)
      • object? FromJson(Type type, string? json)
    • xml
      • string ToXml<TValue>(TValue? value)
      • string ToXml(Type type, object? value)
      • TValue? FromXml<TValue>(string? xml)
      • object? FromXml(Type type, string? xml)
    • yaml
      • string ToYaml<TValue>(TValue? value)
      • string ToYaml(Type type, object? value)
      • TValue? FromYaml<TValue>(string? xml)
      • object? FromYaml(Type type, string? xml)
    • Ini
      • string ToIni<TValue>(TValue? value)
      • string ToIni(Type type, object? value)
      • TValue? FromIni<TValue>(string? xml)
      • object? FromIni(Type type, string? xml)
    • Toml
      • string ToToml<TValue>(TValue? value)
      • string ToToml(Type type, object? value)
      • TValue? FromToml<TValue>(string? xml)
      • object? FromToml(Type type, string? xml)
• Extensions: Supply Extension methods base by Helper. Also it supports generic type and non-generic type.
  • Bytes
    • FromBytes
  • Object
    • PackTo
    • ToBytes
    • ToJson/ToXml/ToYaml
    • ToStream
  • Stream
    • FromStream
    • PackBy
  • String
    • FromJson/FromXml/FromYaml
• Serializer: Implement Aoxe.Serialization.Abstractions, The Aoxe technology stacks use this library to serialize and deserialize.
  • Stream
    • stream ToStream<TValue>(TValue? value)
    • TValue? FromStream<TValue>(Stream? stream)
    • stream ToStream(Type type, object? value)
    • object? FromStream(Type type, Stream? stream)
  • Bytes
    • byte[] ToBytes<TValue>(TValue? value)
    • TValue? FromBytes<TValue>(byte[]? bytes)
    • byte[] ToBytes(Type type, object? value)
    • object? FromBytes(Type type, byte[]? bytes)
  • Text
    • string ToText<TValue>(TValue? value)
    • TValue? FromText<TValue>(string? text)
    • string ToText(Type type, object? value)
    • object? FromText(Type type, string? text)

3. Getting Started

Use nuget to install the package which you want.

PM> Install-Package Aoxe.DataContractSerializer
PM> Install-Package Aoxe.Jil
PM> Install-Package Aoxe.MemoryPack
PM> Install-Package Aoxe.MessagePack
PM> Install-Package Aoxe.MsgPack
PM> Install-Package Aoxe.NewtonsoftJson
PM> Install-Package Aoxe.NetJson
PM> Install-Package Aoxe.Utf8Json
PM> Install-Package Aoxe.Protobuf
PM> Install-Package Aoxe.SharpYaml
PM> Install-Package Aoxe.SpanJson
PM> Install-Package Aoxe.SystemTextJson
PM> Install-Package Aoxe.Xml
PM> Install-Package Aoxe.YamlDotNet
PM> Install-Package Aoxe.ZeroFormatter

You can then use the serializer in extension method way

var testModel = new TestModel();

// bytes
var bytes = testModel.ToBytes();
var deserializedModelFromBytes = bytes.FromBytes<TestModel>();

// stream
var stream = testModel.ToStream();
var deserializedModelFromStream = stream.FromStream<TestModel>();

// you can pack to a stream
var stream1 = new MemoryStream();
testModel.PackTo(stream1);
var result1 = stream1.FromStream<TestModel>();

// or use a stream pack by
var stream2 = new MemoryStream();
stream2.PackBy(testModel);
var result2 = stream2.FromStream<TestModel>();

// also the stream functions have async version
var stream = testModel.ToStream();
var deserializedModelFromStream = await stream.FromStreamAsync<TestModel>();

var stream1 = new MemoryStream();
await testModel.PackToAsync(stream1);
var result1 = await stream1.FromStreamAsync<TestModel>();

var stream2 = new MemoryStream();
await stream2.PackByAsync(testModel);
var result2 = await stream2.FromStreamAsync<TestModel>();

4. Packages introductions

4.1. Aoxe.DataContractSerializer

Base by System.Runtime.Serialization.DataContractSerializer, serializes and deserializes an instance of a type into an XML stream or document using a supplied data contract.

4.2. Aoxe.Jil

A fast JSON (de)serializer, built on Sigil with a number of somewhat crazy optimization tricks.

4.3. Aoxe.MemoryPack

Zero encoding extreme performance binary serializer for C# and Unity.

4.4. Aoxe.MessagePack

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.

4.5. Aoxe.MsgPack

MessagePack implementation for Common Language Infrastructure / msgpack.org[C#]

4.6. Aoxe.NetJson

Faster than Any Binary?

4.7. Aoxe.NewtonsoftJson

Json.NET is a popular high-performance JSON framework for .NET https://www.newtonsoft.com/json

4.8. Aoxe.Utf8Json

Definitely Fastest and Zero Allocation JSON Serializer for C#(NET, .NET Core, Unity, Xamarin).

4.9. Aoxe.Protobuf

protobuf-net is a contract based serializer for .NET code, that happens to write data in the "protocol buffers" serialization format engineered by Google. The API, however, is very different to Google's, and follows typical .NET patterns (it is broadly comparable, in usage, to XmlSerializer, DataContractSerializer, etc). It should work for most .NET languages that write standard types and can use attributes.

4.10. Aoxe.SharpYaml

SharpYaml is a .NET library that provides a YAML parser and serialization engine for .NET objects, compatible with CoreCLR.

4.11. Aoxe.SpanJson

SpanJson is a JSON serializer for .NET Core 6.0+.

4.12. Aoxe.SystemTextJson

The System.Text.Json namespace provides high-performance, low-allocating, and standards-compliant capabilities to process JavaScript Object Notation (JSON), which includes serializing objects to JSON text and deserializing JSON text to objects, with UTF-8 support built-in. It also provides types to read and write JSON text encoded as UTF-8, and to create an in-memory document object model (DOM) for random access of the JSON elements within a structured view of the data.

4.13. Aoxe.Xml

Serializes and deserializes objects into and from XML documents. The XmlSerializer enables you to control how objects are encoded into XML.

4.14. Aoxe.YamlDotNet

YamlDotNet is a YAML library for netstandard and other .NET runtimes.

YamlDotNet provides low level parsing and emitting of YAML as well as a high level object model similar to XmlDocument. A serialization library is also included that allows to read and write objects from and to YAML streams.

4.15. Aoxe.ZeroFormatter

Fastest C# Serializer and Infinitely Fast Deserializer for .NET, .NET Core and Unity.

5. Benchmark

BenchmarkDotNet v0.13.9+228a464e8be6c580ad9408e98f18813f6407fb5a, Windows 11 (10.0.22621.1105/22H2/2022Update/SunValley2)
AMD Ryzen 7 6800H with Radeon Graphics, 1 CPU, 16 logical and 8 physical cores
.NET SDK 8.0.100-rc.2.23502.2
[Host]     : .NET 8.0.0 (8.0.23.47906), X64 RyuJIT AVX2
DefaultJob : .NET 8.0.0 (8.0.23.47906), X64 RyuJIT AVX2

IterationCount=1000 RunStrategy=Monitoring

5.1. Stream

5.1.1. To Stream

5.1.2. From Stream

5.2. Bytes

5.2.1. To Bytes

5.2.2. From Bytes

5.3. Text

5.3.1. Json

5.3.1.1. To Json

5.3.1.2. From Json

5.3.2. Xml

5.3.2.1. To Xml

5.3.2.2. From Xml

5.3.3. Yaml

5.3.3.1. To Yaml

5.3.3.2. From Yaml

5.3.4. Ini

5.3.4.1. To Ini

5.3.4.2. From Ini

5.3.5. Toml

5.3.5.1. To Toml

5.3.5.2. From Toml

Thank`s for JetBrains for the great support in providing assistance and user-friendly environment for my open source projects.