⚠️ DEPRECATED

This project is no longer maintained. Its functionality has been moved to ktsu.Abstractions.

Please migrate to the new library for continued support and updates.

---

ktsu.SerializationProvider

A dependency injection interface for pluggable serialization providers. Define serialization contracts once and swap implementations without changing application code.

Features

• Unified Interface: Single interface for all serialization operations
• Dependency Injection Ready: Easy registration with Microsoft.Extensions.DependencyInjection
• Zero Dependencies: Pure interface library with no specific serialization library dependencies
• Async Support: Full async/await support for all operations
• Type Safety: Generic methods provide compile-time type safety
• Extensible: Easy to create custom serialization providers
• Well Tested: Comprehensive unit test coverage

Installation

dotnet add package SerializationProvider

Quick Start

1. Create a Serialization Provider

First, implement the ISerializationProvider interface:

publicclassJsonSerializationProvider:ISerializationProvider{publicstringProviderName=>"System.Text.Json";publicstringContentType=>"application/json";publicstringSerialize<T>(Tobj){returnSystem.Text.Json.JsonSerializer.Serialize(obj);}publicTDeserialize<T>(stringdata){if(string.IsNullOrWhiteSpace(data))thrownewArgumentException("Data cannot be null or empty",nameof(data));returnSystem.Text.Json.JsonSerializer.Deserialize<T>(data)!;}publicstringSerialize(objectobj,Typetype){returnSystem.Text.Json.JsonSerializer.Serialize(obj,type);}publicobjectDeserialize(stringdata,Typetype){if(string.IsNullOrWhiteSpace(data))thrownewArgumentException("Data cannot be null or empty",nameof(data));returnSystem.Text.Json.JsonSerializer.Deserialize(data,type)!;}publicTask<string>SerializeAsync<T>(Tobj,CancellationTokencancellationToken=default){returnTask.FromResult(Serialize(obj));}publicTask<string>SerializeAsync(objectobj,Typetype,CancellationTokencancellationToken=default){returnTask.FromResult(Serialize(obj,type));}publicTask<T>DeserializeAsync<T>(stringdata,CancellationTokencancellationToken=default){returnTask.FromResult(Deserialize<T>(data));}publicTask<object>DeserializeAsync(stringdata,Typetype,CancellationTokencancellationToken=default){returnTask.FromResult(Deserialize(data,type));}}

2. Register the Serialization Provider

usingktsu.SerializationProvider.Extensions;// In your Startup.cs or Program.csservices.AddSerializationProvider<JsonSerializationProvider>();// Or register by instanceservices.AddSerializationProvider(newJsonSerializationProvider());// Or register by factoryservices.AddSerializationProvider(serviceProvider =>newJsonSerializationProvider());

3. Inject and Use the Serialization Provider

publicclassMyService{privatereadonlyISerializationProvider_serializationProvider;publicMyService(ISerializationProviderserializationProvider){_serializationProvider=serializationProvider;}publicasyncTask<string>SerializeDataAsync<T>(Tdata){returnawait_serializationProvider.SerializeAsync(data);}publicasyncTask<T>DeserializeDataAsync<T>(stringjson){returnawait_serializationProvider.DeserializeAsync<T>(json);}}

API Reference

ISerializationProvider Interface

publicinterfaceISerializationProvider{stringProviderName{get;}stringContentType{get;}// Synchronous methodsstringSerialize<T>(Tobj);stringSerialize(objectobj,Typetype);TDeserialize<T>(stringdata);objectDeserialize(stringdata,Typetype);// Asynchronous methodsTask<string>SerializeAsync<T>(Tobj,CancellationTokencancellationToken=default);Task<string>SerializeAsync(objectobj,Typetype,CancellationTokencancellationToken=default);Task<T>DeserializeAsync<T>(stringdata,CancellationTokencancellationToken=default);Task<object>DeserializeAsync(stringdata,Typetype,CancellationTokencancellationToken=default);}

Usage Examples

Basic Serialization

publicclassPerson{publicstringName{get;set;}publicintAge{get;set;}publicDateTimeBirthDate{get;set;}}// Serializevarperson=newPerson{Name="John Doe",Age=30,BirthDate=DateTime.Now};stringjson=serializationProvider.Serialize(person);// DeserializevardeserializedPerson=serializationProvider.Deserialize<Person>(json);

Async Operations

// Async serializestringjson=awaitserializationProvider.SerializeAsync(person);// Async deserializevarperson=awaitserializationProvider.DeserializeAsync<Person>(json);

Type-based Operations

// When you need to work with Type objectsTypepersonType=typeof(Person);stringjson=serializationProvider.Serialize(person,personType);objectdeserializedObject=serializationProvider.Deserialize(json,personType);

Dependency Injection Registration Options

Register by Type

services.AddSerializationProvider<MyCustomSerializationProvider>();

Register by Instance

services.AddSerializationProvider(newMyCustomSerializationProvider());

Register by Factory

services.AddSerializationProvider(serviceProvider =>newMyCustomSerializationProvider(serviceProvider.GetRequiredService<ILogger<MyCustomSerializationProvider>>()));

Creating Custom Serialization Providers

JSON Provider with Newtonsoft.Json

publicclassNewtonsoftJsonSerializationProvider:ISerializationProvider{privatereadonlyJsonSerializerSettings_settings;publicNewtonsoftJsonSerializationProvider(JsonSerializerSettings?settings=null){_settings=settings??newJsonSerializerSettings();}publicstringProviderName=>"Newtonsoft.Json";publicstringContentType=>"application/json";publicstringSerialize<T>(Tobj){returnJsonConvert.SerializeObject(obj,_settings);}publicTDeserialize<T>(stringdata){if(string.IsNullOrWhiteSpace(data))thrownewArgumentException("Data cannot be null or empty",nameof(data));returnJsonConvert.DeserializeObject<T>(data,_settings)!;}// Implement other interface methods...}

XML Provider

publicclassXmlSerializationProvider:ISerializationProvider{publicstringProviderName=>"System.Xml";publicstringContentType=>"application/xml";publicstringSerialize<T>(Tobj){varserializer=newXmlSerializer(typeof(T));usingvarstringWriter=newStringWriter();serializer.Serialize(stringWriter,obj);returnstringWriter.ToString();}publicTDeserialize<T>(stringdata){if(string.IsNullOrWhiteSpace(data))thrownewArgumentException("Data cannot be null or empty",nameof(data));varserializer=newXmlSerializer(typeof(T));usingvarstringReader=newStringReader(data);return(T)serializer.Deserialize(stringReader)!;}// Implement other interface methods...}

Best Practices

1. Use Async Methods: For I/O operations, prefer async methods to avoid blocking threads
2. Handle Exceptions: Wrap serialization operations in try-catch blocks for production code
3. Validate Input: Always validate input data in your serialization provider implementations
4. Single Provider per Application: Register only one serialization provider per application to avoid confusion
5. Provider Naming: Use descriptive provider names to help with debugging and logging

Testing

The library includes comprehensive unit tests. Run them using:

dotnet test

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

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

Changelog

See CHANGELOG.md for a list of changes and version history.