ktsu.UniversalSerializer 1.0.9
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
ISerializationProviderinterface 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):
using ktsu.SerializationProvider;
using ktsu.UniversalSerializer;
using Microsoft.Extensions.DependencyInjection;
var services = new ServiceCollection();
// Registers a default JSON-based provider and all required core services automatically
services.AddUniversalSerializationProvider();
using var provider = services.BuildServiceProvider();
var sp = provider.GetRequiredService<ISerializationProvider>();
var data = new MyData { Id = 1, Name = "Example" };
string json = sp.Serialize(data);
var roundTrip = sp.Deserialize<MyData>(json);
public class MyData
{
public int Id { get; set; }
public string Name { 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 time
services.AddUniversalSerializationProviderForFormat("yaml");
services.AddUniversalSerializationProviderForExtension(".toml");
services.AddUniversalSerializationProviderForContentType("application/xml");
Advanced Configuration
Configuring Serializer Options (DI)
using ktsu.UniversalSerializer;
// Registers core services and applies options
services.AddUniversalSerializer(options =>
{
// Built-in simple properties
options.UseStringConversionForUnsupportedTypes = true;
options.EnableCompression = true;
options.CompressionLevel = 9;
// Format-specific options via keys
options.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:
using ktsu.UniversalSerializer;
// Define a custom type with string conversion
public class CustomId
{
public Guid Value { get; }
public CustomId(Guid value)
{
Value = value;
}
// ToString for serialization
public override string ToString()
{
return Value.ToString("D");
}
// Parse method for deserialization
public static CustomId Parse(string value)
{
return new CustomId(Guid.Parse(value));
}
}
// Enable string conversion in options
services.AddUniversalSerializer(options =>
{
options.UseStringConversionForUnsupportedTypes = true;
});
Polymorphic Serialization
using ktsu.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 DI
services.AddJsonSerializationProvider();
// Define types
public abstract class Animal
{
public string Name { get; set; } = string.Empty;
}
public class Dog : Animal
{
public string Breed { get; set; } = string.Empty;
}
public class Cat : Animal
{
public int Lives { get; set; }
}
// Use polymorphic serialization
var animals = new List<Animal>
{
new Dog { Name = "Rex", Breed = "German Shepherd" },
new Cat { Name = "Whiskers", Lives = 9 }
};
// Resolve and configure the type registry
using var provider = services.BuildServiceProvider();
var registry = provider.GetRequiredService<TypeRegistry>();
registry.RegisterType<Dog>("dog");
registry.RegisterType<Cat>("cat");
// Use provider (JSON)
var sp = provider.GetRequiredService<ktsu.SerializationProvider.ISerializationProvider>();
string json = sp.Serialize(animals);
var deserializedAnimals = sp.Deserialize<List<Animal>>(json);
Binary Serialization
using ktsu.UniversalSerializer;
// Option 1: Use provider
services.AddUniversalSerializationProviderForFormat("messagepack");
using var provider = services.BuildServiceProvider();
var sp = provider.GetRequiredService<ktsu.SerializationProvider.ISerializationProvider>();
byte[] bytes = sp.SerializeToBytes(data); // if you need bytes, use serializer directly instead
// Option 2: Use factory directly
var factory = new SerializerFactory();
factory.RegisterSerializer(o => new ktsu.UniversalSerializer.MessagePack.MessagePackSerializer(o));
var mp = factory.Create<ktsu.UniversalSerializer.MessagePack.MessagePackSerializer>();
byte[] binary = mp.SerializeToBytes(data);
var result = mp.DeserializeFromBytes<MyData>(binary);
SerializationProvider Integration
UniversalSerializer implements the ISerializationProvider interface for standardized dependency injection scenarios:
using ktsu.SerializationProvider;
// Add a default JSON provider (auto-bootstraps core)
services.AddUniversalSerializationProvider();
// Or add specific providers
services.AddJsonSerializationProvider();
services.AddYamlSerializationProvider();
services.AddMessagePackSerializationProvider();
// Use the provider
public class MyService
{
private readonly ISerializationProvider _provider;
public MyService(ISerializationProvider provider)
{
_provider = provider;
}
public async Task ProcessAsync()
{
var data = new MyData { Id = 1, Name = "Example" };
// Serialize and deserialize
string serialized = await _provider.SerializeAsync(data);
var deserialized = 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.
No packages depend on ktsu.UniversalSerializer.
## v1.0.9 (patch)
Changes since v1.0.8:
- Merge remote-tracking branch 'refs/remotes/origin/main' ([@ktsu[bot]](https://github.com/ktsu[bot]))
- Sync .github\workflows\dotnet.yml ([@ktsu[bot]](https://github.com/ktsu[bot]))
- Sync .github\workflows\dotnet.yml ([@ktsu[bot]](https://github.com/ktsu[bot]))
- Sync .github\workflows\dotnet.yml ([@ktsu[bot]](https://github.com/ktsu[bot]))
- Sync .github\workflows\dotnet.yml ([@ktsu[bot]](https://github.com/ktsu[bot]))
## v1.0.9-pre.1 (prerelease)
Changes since v1.0.8:
- Sync .github\workflows\dotnet.yml ([@ktsu[bot]](https://github.com/ktsu[bot]))
- Sync .github\workflows\dotnet.yml ([@ktsu[bot]](https://github.com/ktsu[bot]))
- Sync .github\workflows\dotnet.yml ([@ktsu[bot]](https://github.com/ktsu[bot]))
## v1.0.8 (patch)
Changes since v1.0.7:
- Remove legacy build scripts ([@matt-edmondson](https://github.com/matt-edmondson))
## v1.0.7 (patch)
Changes since v1.0.6:
- Sync .github\workflows\dotnet.yml ([@ktsu[bot]](https://github.com/ktsu[bot]))
- Sync global.json ([@ktsu[bot]](https://github.com/ktsu[bot]))
- Merge remote-tracking branch 'refs/remotes/origin/main' ([@ktsu[bot]](https://github.com/ktsu[bot]))
- Sync scripts\update-winget-manifests.ps1 ([@ktsu[bot]](https://github.com/ktsu[bot]))
## v1.0.7-pre.1 (prerelease)
No significant changes detected since v1.0.7.
## v1.0.6 (patch)
Changes since v1.0.5:
- Add target frameworks to UniversalSerializer project file ([@matt-edmondson](https://github.com/matt-edmondson))
## v1.0.5 (patch)
Changes since v1.0.4:
- refactor ([@matt-edmondson](https://github.com/matt-edmondson))
## v1.0.5-pre.4 (prerelease)
Changes since v1.0.5-pre.3:
- Sync scripts\update-winget-manifests.ps1 ([@ktsu[bot]](https://github.com/ktsu[bot]))
## v1.0.5-pre.3 (prerelease)
Changes since v1.0.5-pre.2:
- Sync .github\workflows\dotnet.yml ([@ktsu[bot]](https://github.com/ktsu[bot]))
## v1.0.5-pre.2 (prerelease)
Changes since v1.0.5-pre.1:
- Sync scripts\PSBuild.psm1 ([@ktsu[bot]](https://github.com/ktsu[bot]))
- Sync .github\workflows\dotnet.yml ([@ktsu[bot]](https://github.com/ktsu[bot]))
## v1.0.5-pre.1 (prerelease)
No significant changes detected since v1.0.5.
## v1.0.4 (patch)
Changes since v1.0.3:
- Simplify dependency injection ([@matt-edmondson](https://github.com/matt-edmondson))
- Update package versions in Directory.Packages.props ([@matt-edmondson](https://github.com/matt-edmondson))
- Add comprehensive unit tests to improve test coverage ([@matt-edmondson](https://github.com/matt-edmondson))
- Update project files and configurations ([@matt-edmondson](https://github.com/matt-edmondson))
## v1.0.4-pre.2 (prerelease)
Changes since v1.0.4-pre.1:
- Update package versions in Directory.Packages.props ([@matt-edmondson](https://github.com/matt-edmondson))
## v1.0.4-pre.1 (prerelease)
No significant changes detected since v1.0.4.
## v1.0.3 (patch)
Changes since v1.0.2:
- Enhance winget manifest update script with improved configuration and error handling ([@matt-edmondson](https://github.com/matt-edmondson))
## v1.0.2 (patch)
Changes since v1.0.1:
- Refactor Invoke-DotNetPack to use PackageReleaseNotesFile for changelog reference ([@matt-edmondson](https://github.com/matt-edmondson))
## v1.0.1 (patch)
Changes since v1.0.0:
- Enhance UniversalSerializer with SerializationProvider integration and new features ([@matt-edmondson](https://github.com/matt-edmondson))
- Refactor PSBuild script for improved functionality and clarity ([@matt-edmondson](https://github.com/matt-edmondson))
- Update project configuration and dependencies ([@matt-edmondson](https://github.com/matt-edmondson))
## v1.0.0 (major)
- Remove PowerShell script for adding missing using statements and update README to reflect package name change to ktsu.UniversalSerializer. Add a new rule for ensuring unit and integration tests with > 80% code coverage. ([@matt-edmondson](https://github.com/matt-edmondson))
- Enhance serializer functionality and update project files ([@matt-edmondson](https://github.com/matt-edmondson))
- Add LZ4 compression support and enhance serializer error handling ([@matt-edmondson](https://github.com/matt-edmondson))
- Refactor serializer interfaces and implementations to improve code clarity and consistency. Removed unnecessary using directives, added access modifiers to interface members, and standardized variable declarations. Enhanced type handling in various serializers and converters, ensuring better adherence to coding standards and practices. ([@matt-edmondson](https://github.com/matt-edmondson))
- Refactor project files to use custom SDKs for improved build management. Updated UniversalSerializer, UniversalSerializer.Benchmarks, and UniversalSerializer.Test projects to utilize ktsu.Sdk.Lib, ktsu.Sdk.ConsoleApp, and ktsu.Sdk.Test respectively. This change enhances compatibility and streamlines the build process across different project types. ([@matt-edmondson](https://github.com/matt-edmondson))
- Add compression and encryption support to serializers, including the implementation of ICompressionProvider and associated compression algorithms (GZip, Deflate). Integrated compression functionality into SerializerBase for byte serialization. Established security infrastructure with IEncryptionProvider and EncryptionType enum. Enhanced YAML polymorphic type converter and improved overall build stability by addressing compilation errors and validation issues. ([@matt-edmondson](https://github.com/matt-edmondson))
- Add streaming and compression support to serializers, including new methods in ISerializer for stream handling. Introduced CompressionType enum and updated SerializerOptions for compression settings. Enhanced TOML serializer with complete object conversion and added parameter validation for compliance. Fixed various compilation errors and improved YAML polymorphic type converter implementation. ([@matt-edmondson](https://github.com/matt-edmondson))
- Add XML serializer options, enhance JsonPolymorphicConverter for better type handling, and fix missing using statements across various serializers. Implemented HasPolymorphicTypes method in TypeRegistry and updated SerializerOptionKeys for XML settings. Addressed pattern matching issues in TOML and YAML serializers. ([@matt-edmondson](https://github.com/matt-edmondson))
- Update .editorconfig to disable var usage for built-in types, modify .runsettings for parallel test execution, enhance .gitignore for SpecStory files, and update Directory.Packages.props with new dependencies and versioning. Introduce global.json for SDK management and refine PSBuild.psm1 for improved package publishing and version handling. ([@matt-edmondson](https://github.com/matt-edmondson))
- Add .cursorignore for SpecStory backup files, update Directory.Packages.props with main and test dependencies, and refactor project files to use Microsoft.NET.Sdk. Added new history file for library development progress and updated .gitignore to include backup files. ([@matt-edmondson](https://github.com/matt-edmondson))
- Add initial project files for UniversalSerializer, including configuration for package management and serialization rules. Implemented core serializer interfaces and added YAML, JSON, and XML serializers with dependency injection support. Updated README for documentation and added initial tests for serializer functionality. ([@matt-edmondson](https://github.com/matt-edmondson))
- Add community and core plugins configuration; update project dependencies ([@matt-edmondson](https://github.com/matt-edmondson))
- Enhance serializer functionality and update dependencies ([@matt-edmondson](https://github.com/matt-edmondson))
- Refactor SerializerRegistry and TomlSerializer for improved clarity and performance ([@matt-edmondson](https://github.com/matt-edmondson))
- Refactor SerializerRegistry and update serializer methods ([@matt-edmondson](https://github.com/matt-edmondson))
- Refactor SerializerServiceCollectionExtensions and update serializer registrations ([@matt-edmondson](https://github.com/matt-edmondson))
- Refactor SerializerRegistry and update serialization methods ([@matt-edmondson](https://github.com/matt-edmondson))
- Remove Protobuf and FlatBuffers support from UniversalSerializer ([@matt-edmondson](https://github.com/matt-edmondson))
- Update dependencies and enhance serialization options ([@matt-edmondson](https://github.com/matt-edmondson))
- Update README.md with comprehensive documentation for UniversalSerializer ([@matt-edmondson](https://github.com/matt-edmondson))
- Update task list to mark build pipeline configuration as complete ([@matt-edmondson](https://github.com/matt-edmondson))
- Add support for MessagePack, Protobuf, and FlatBuffers serialization ([@matt-edmondson](https://github.com/matt-edmondson))
- Remove INI serialization support ([@matt-edmondson](https://github.com/matt-edmondson))
- Add INI serialization support ([@matt-edmondson](https://github.com/matt-edmondson))
- Add TOML serialization support ([@matt-edmondson](https://github.com/matt-edmondson))
- Add polymorphic serialization support for JSON, XML, and YAML ([@matt-edmondson](https://github.com/matt-edmondson))
- Add common and type registry option keys for serialization ([@matt-edmondson](https://github.com/matt-edmondson))
- Complete implementation tasks for UniversalSerializer project ([@matt-edmondson](https://github.com/matt-edmondson))
- Add YAML serialization support ([@matt-edmondson](https://github.com/matt-edmondson))
- Add core serialization framework with JSON and XML support ([@matt-edmondson](https://github.com/matt-edmondson))
- Add implementation tasks for UniversalSerializer ([@matt-edmondson](https://github.com/matt-edmondson))
- Remove unnescessary file ([@matt-edmondson](https://github.com/matt-edmondson))
- Add support for MessagePack, Protobuf, and FlatBuffers serializers ([@matt-edmondson](https://github.com/matt-edmondson))
- Enhance serializer options with format-specific keys and advanced customization ([@matt-edmondson](https://github.com/matt-edmondson))
- Add polymorphic serialization support with type discriminator options ([@matt-edmondson](https://github.com/matt-edmondson))
- Refine StringConvertibleTypeConverter and enhance documentation ([@matt-edmondson](https://github.com/matt-edmondson))
- Add support for custom type conversion in serializers ([@matt-edmondson](https://github.com/matt-edmondson))
- Add enum serialization format options to serializer settings ([@matt-edmondson](https://github.com/matt-edmondson))
- initial commit ([@matt-edmondson](https://github.com/matt-edmondson))
.NET 8.0
- K4os.Compression.LZ4 (>= 1.3.8)
- MessagePack (>= 3.1.4)
- Microsoft.Extensions.DependencyInjection (>= 10.0.2)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 10.0.2)
- Polyfill (>= 9.8.1)
- System.Text.Json (>= 10.0.2)
- Tomlyn (>= 0.19.0)
- YamlDotNet (>= 16.3.0)
- ktsu.SerializationProvider (>= 1.0.5)
.NET 10.0
- ktsu.SerializationProvider (>= 1.0.5)
- Tomlyn (>= 0.19.0)
- Polyfill (>= 9.8.1)
- YamlDotNet (>= 16.3.0)
- Microsoft.Extensions.DependencyInjection (>= 10.0.2)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 10.0.2)
- K4os.Compression.LZ4 (>= 1.3.8)
- MessagePack (>= 3.1.4)
.NET Standard 2.0
- K4os.Compression.LZ4 (>= 1.3.8)
- MessagePack (>= 3.1.4)
- Microsoft.Extensions.DependencyInjection (>= 10.0.2)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 10.0.2)
- Polyfill (>= 9.8.1)
- System.Text.Json (>= 10.0.2)
- Tomlyn (>= 0.19.0)
- YamlDotNet (>= 16.3.0)
- ktsu.SerializationProvider (>= 1.0.5)
.NET Standard 2.1
- K4os.Compression.LZ4 (>= 1.3.8)
- MessagePack (>= 3.1.4)
- Microsoft.Extensions.DependencyInjection (>= 10.0.2)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 10.0.2)
- Polyfill (>= 9.8.1)
- System.Text.Json (>= 10.0.2)
- Tomlyn (>= 0.19.0)
- YamlDotNet (>= 16.3.0)
- ktsu.SerializationProvider (>= 1.0.5)
.NET 9.0
- K4os.Compression.LZ4 (>= 1.3.8)
- MessagePack (>= 3.1.4)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 10.0.2)
- Polyfill (>= 9.8.1)
- System.Text.Json (>= 10.0.2)
- Tomlyn (>= 0.19.0)
- YamlDotNet (>= 16.3.0)
- ktsu.SerializationProvider (>= 1.0.5)
- Microsoft.Extensions.DependencyInjection (>= 10.0.2)
| Version | Downloads | Last updated |
|---|---|---|
| 1.0.9 | 1 | 02/16/2026 |
| 1.0.9-pre.1 | 2 | 02/16/2026 |
| 1.0.8 | 15 | 02/14/2026 |
| 1.0.7 | 15 | 02/14/2026 |
| 1.0.7-pre.1 | 52 | 02/06/2026 |
| 1.0.6 | 53 | 02/05/2026 |
| 1.0.5 | 52 | 02/05/2026 |
| 1.0.5-pre.4 | 122 | 11/24/2025 |
| 1.0.5-pre.3 | 124 | 11/23/2025 |
| 1.0.5-pre.2 | 126 | 11/23/2025 |
| 1.0.5-pre.1 | 124 | 11/23/2025 |