ktsu.UniversalSerializer 1.0.12

Prefix Reserved
.NET 8.0 This package targets .NET 8.0. The package is compatible with this framework or higher. .NET Standard 2.0 This package targets .NET Standard 2.0. The package is compatible with this framework or higher. 
dotnet add package ktsu.UniversalSerializer --version 1.0.12
                    


                    

                
NuGet\Install-Package ktsu.UniversalSerializer -Version 1.0.12
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package. 
<PackageReference Include="ktsu.UniversalSerializer" Version="1.0.12" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
<PackageVersion Include="ktsu.UniversalSerializer" Version="1.0.12" />
                    


                            Directory.Packages.props
                        

                    

                
<PackageReference Include="ktsu.UniversalSerializer" />
                    


                            Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package. 
paket add ktsu.UniversalSerializer --version 1.0.12
                    


                    

                
#r "nuget: ktsu.UniversalSerializer, 1.0.12"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package. 
#:package ktsu.UniversalSerializer@1.0.12
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package. 
#addin nuget:?package=ktsu.UniversalSerializer&version=1.0.12
                    


                            Install as a Cake Addin
                        

                    

                
#tool nuget:?package=ktsu.UniversalSerializer&version=1.0.12
                    


                            Install as a Cake Tool

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):

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.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 is compatible.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 is compatible. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
1.0.12 143 2026/6/30
1.0.11 141 2026/6/29
1.0.10 120 2026/6/28
1.0.10-pre.1 88 2026/2/17
1.0.9 172 2026/2/16
1.0.9-pre.1 88 2026/2/16
1.0.8 136 2026/2/14
1.0.7 144 2026/2/14
1.0.7-pre.1 90 2026/2/6
1.0.6 152 2026/2/5
1.0.5 142 2026/2/5
1.0.5-pre.4 191 2025/11/24
1.0.5-pre.3 160 2025/11/23
1.0.5-pre.2 143 2025/11/23
1.0.5-pre.1 151 2025/11/23
1.0.4 455 2025/8/10
1.0.4-pre.2 573 2025/7/22
1.0.4-pre.1 191 2025/7/9
1.0.3 275 2025/6/18
1.0.2 279 2025/6/18
Loading failed

## v1.0.12 (patch)

Changes since v1.0.11:

- Bump Polyfill from 10.11.0 to 10.11.1 ([@dependabot[bot]](https://github.com/dependabot[bot]))
- Bump the ktsu group with 8 updates ([@dependabot[bot]](https://github.com/dependabot[bot]))

## v1.0.11 (patch)

Changes since v1.0.10:

- Bump YamlDotNet from 18.0.0 to 18.1.0 ([@dependabot[bot]](https://github.com/dependabot[bot]))
- Bump the ktsu group with 1 update ([@dependabot[bot]](https://github.com/dependabot[bot]))

## v1.0.10 (patch)

Changes since v1.0.9:

- fix: update benchmark package references ([@matt-edmondson](https://github.com/matt-edmondson))
- chore: remove unused SourceLink package versions ([@matt-edmondson](https://github.com/matt-edmondson))
- chore: trim unused package references ([@matt-edmondson](https://github.com/matt-edmondson))
- Remove stale files ([@matt-edmondson](https://github.com/matt-edmondson))

## v1.0.10-pre.1 (prerelease)

No significant changes detected since v1.0.10.

## 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)

No significant changes detected since v1.0.9.

## 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)