ktsu.UniversalSerializer

A unified serialization library for .NET that provides a consistent API for various serialization formats including JSON, XML, YAML, TOML, and MessagePack.

Features

• Unified API: Serialize and deserialize objects with a consistent interface regardless of the format
• Multiple Formats: Support for common text formats (JSON, XML, YAML, TOML) and binary formats (MessagePack)
• Type Conversion: Built-in type conversion for non-natively supported types
• Polymorphic Serialization: Support for inheritance and polymorphic types
• Dependency Injection: First-class support for Microsoft DI with fluent configuration
• SerializationProvider Integration: Compatible with the ISerializationProvider interface for standardized DI scenarios
• Extensible: Easy to extend with custom serializers or type converters

Installation

dotnet add package ktsu.UniversalSerializer

Quick Start

Minimal DI (SerializationProvider):

usingktsu.SerializationProvider;usingktsu.UniversalSerializer;usingMicrosoft.Extensions.DependencyInjection;varservices=newServiceCollection();// Registers a default JSON-based provider and all required core services automaticallyservices.AddUniversalSerializationProvider();usingvarprovider=services.BuildServiceProvider();varsp=provider.GetRequiredService<ISerializationProvider>();vardata=newMyData{Id=1,Name="Example"};stringjson=sp.Serialize(data);varroundTrip=sp.Deserialize<MyData>(json);publicclassMyData{publicintId{get;set;}publicstringName{get;set;}=string.Empty;}

Format-specific providers:

services.AddJsonSerializationProvider();services.AddYamlSerializationProvider();services.AddTomlSerializationProvider();services.AddXmlSerializationProvider();services.AddMessagePackSerializationProvider();// Or choose by format/extension/content-type at registration timeservices.AddUniversalSerializationProviderForFormat("yaml");services.AddUniversalSerializationProviderForExtension(".toml");services.AddUniversalSerializationProviderForContentType("application/xml");

Advanced Configuration

Configuring Serializer Options (DI)

usingktsu.UniversalSerializer;// Registers core services and applies optionsservices.AddUniversalSerializer(options =>{// Built-in simple propertiesoptions.UseStringConversionForUnsupportedTypes=true;options.EnableCompression=true;options.CompressionLevel=9;// Format-specific options via keysoptions.SetOption(SerializerOptionKeys.Json.AllowComments,true);options.SetOption(SerializerOptionKeys.Json.CaseInsensitive,true);options.SetOption(SerializerOptionKeys.Xml.Indent,true);});// Optional: register serializer types for DI construction (e.g., to inject registries)services.AddJsonSerializer();services.AddXmlSerializer();services.AddYamlSerializer();services.AddMessagePackSerializer();

Type Conversion

The library supports custom type conversion for types that aren't natively handled by serializers:

usingktsu.UniversalSerializer;// Define a custom type with string conversionpublicclassCustomId{publicGuidValue{get;}publicCustomId(Guidvalue){Value=value;}// ToString for serializationpublicoverridestringToString(){returnValue.ToString("D");}// Parse method for deserializationpublicstaticCustomIdParse(stringvalue){returnnewCustomId(Guid.Parse(value));}}// Enable string conversion in optionsservices.AddUniversalSerializer(options =>{options.UseStringConversionForUnsupportedTypes=true;});

Polymorphic Serialization

usingktsu.UniversalSerializer;// Register core and enable discriminators (Json/Yaml/Toml read option via key)services.AddUniversalSerializer(options =>{options.SetOption(SerializerOptionKeys.TypeRegistry.EnableTypeDiscriminator,true);});// Ensure JSON serializer is constructed with registries when used via DIservices.AddJsonSerializationProvider();// Define typespublicabstractclassAnimal{publicstringName{get;set;}=string.Empty;}publicclassDog:Animal{publicstringBreed{get;set;}=string.Empty;}publicclassCat:Animal{publicintLives{get;set;}}// Use polymorphic serializationvaranimals=newList<Animal>{newDog{Name="Rex",Breed="German Shepherd"},newCat{Name="Whiskers",Lives=9}};// Resolve and configure the type registryusingvarprovider=services.BuildServiceProvider();varregistry=provider.GetRequiredService<TypeRegistry>();registry.RegisterType<Dog>("dog");registry.RegisterType<Cat>("cat");// Use provider (JSON)varsp=provider.GetRequiredService<ktsu.SerializationProvider.ISerializationProvider>();stringjson=sp.Serialize(animals);vardeserializedAnimals=sp.Deserialize<List<Animal>>(json);

Binary Serialization

usingktsu.UniversalSerializer;// Option 1: Use providerservices.AddUniversalSerializationProviderForFormat("messagepack");usingvarprovider=services.BuildServiceProvider();varsp=provider.GetRequiredService<ktsu.SerializationProvider.ISerializationProvider>();byte[]bytes=sp.SerializeToBytes(data);// if you need bytes, use serializer directly instead// Option 2: Use factory directlyvarfactory=newSerializerFactory();factory.RegisterSerializer(o =>newktsu.UniversalSerializer.MessagePack.MessagePackSerializer(o));varmp=factory.Create<ktsu.UniversalSerializer.MessagePack.MessagePackSerializer>();byte[]binary=mp.SerializeToBytes(data);varresult=mp.DeserializeFromBytes<MyData>(binary);

SerializationProvider Integration

UniversalSerializer implements the ISerializationProvider interface for standardized dependency injection scenarios:

usingktsu.SerializationProvider;// Add a default JSON provider (auto-bootstraps core)services.AddUniversalSerializationProvider();// Or add specific providersservices.AddJsonSerializationProvider();services.AddYamlSerializationProvider();services.AddMessagePackSerializationProvider();// Use the providerpublicclassMyService{privatereadonlyISerializationProvider_provider;publicMyService(ISerializationProviderprovider){_provider=provider;}publicasyncTaskProcessAsync(){vardata=newMyData{Id=1,Name="Example"};// Serialize and deserializestringserialized=await_provider.SerializeAsync(data);vardeserialized=await_provider.DeserializeAsync<MyData>(serialized);}}

For more details, see the SerializationProvider Integration Documentation.

Supported Formats

Format	Content Type	File Extension	Package Dependency
JSON	application/json	.json	System.Text.Json (built-in)
XML	application/xml	.xml	System.Xml.Serialization (built-in)
YAML	text/yaml (also registers application/x-yaml)	.yaml	YamlDotNet
TOML	application/toml	.toml	Tomlyn
MessagePack	application/x-msgpack	.msgpack	MessagePack

License

This project is licensed under the MIT License - see the LICENSE file for details.