{"id":28928188,"url":"https://github.com/ktsu-dev/universalserializer","last_synced_at":"2026-02-16T05:04:33.227Z","repository":{"id":298215060,"uuid":"999244230","full_name":"ktsu-dev/UniversalSerializer","owner":"ktsu-dev","description":null,"archived":false,"fork":false,"pushed_at":"2025-06-18T09:06:35.000Z","size":540,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-18T09:29:02.286Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ktsu-dev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS.md","dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-10T00:58:23.000Z","updated_at":"2025-06-18T09:04:56.000Z","dependencies_parsed_at":"2025-06-10T01:47:52.772Z","dependency_job_id":null,"html_url":"https://github.com/ktsu-dev/UniversalSerializer","commit_stats":null,"previous_names":["ktsu-dev/universalserializer"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ktsu-dev/UniversalSerializer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ktsu-dev%2FUniversalSerializer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ktsu-dev%2FUniversalSerializer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ktsu-dev%2FUniversalSerializer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ktsu-dev%2FUniversalSerializer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ktsu-dev","download_url":"https://codeload.github.com/ktsu-dev/UniversalSerializer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ktsu-dev%2FUniversalSerializer/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261304302,"owners_count":23138306,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-22T14:12:25.979Z","updated_at":"2026-01-20T16:34:01.227Z","avatar_url":"https://github.com/ktsu-dev.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ktsu.UniversalSerializer\n\nA unified serialization library for .NET that provides a consistent API for various serialization formats including JSON, XML, YAML, TOML, and MessagePack.\n\n## Features\n\n- **Unified API**: Serialize and deserialize objects with a consistent interface regardless of the format\n- **Multiple Formats**: Support for common text formats (JSON, XML, YAML, TOML) and binary formats (MessagePack)\n- **Type Conversion**: Built-in type conversion for non-natively supported types\n- **Polymorphic Serialization**: Support for inheritance and polymorphic types\n- **Dependency Injection**: First-class support for Microsoft DI with fluent configuration\n- **SerializationProvider Integration**: Compatible with the `ISerializationProvider` interface for standardized DI scenarios\n- **Extensible**: Easy to extend with custom serializers or type converters\n\n## Installation\n\n```shell\ndotnet add package ktsu.UniversalSerializer\n```\n\n## Quick Start\n\nMinimal DI (SerializationProvider):\n\n```csharp\nusing ktsu.SerializationProvider;\nusing ktsu.UniversalSerializer;\nusing Microsoft.Extensions.DependencyInjection;\n\nvar services = new ServiceCollection();\n\n// Registers a default JSON-based provider and all required core services automatically\nservices.AddUniversalSerializationProvider();\n\nusing var provider = services.BuildServiceProvider();\nvar sp = provider.GetRequiredService\u003cISerializationProvider\u003e();\n\nvar data = new MyData { Id = 1, Name = \"Example\" };\nstring json = sp.Serialize(data);\nvar roundTrip = sp.Deserialize\u003cMyData\u003e(json);\n\npublic class MyData\n{\n    public int Id { get; set; }\n    public string Name { get; set; } = string.Empty;\n}\n```\n\nFormat-specific providers:\n\n```csharp\nservices.AddJsonSerializationProvider();\nservices.AddYamlSerializationProvider();\nservices.AddTomlSerializationProvider();\nservices.AddXmlSerializationProvider();\nservices.AddMessagePackSerializationProvider();\n\n// Or choose by format/extension/content-type at registration time\nservices.AddUniversalSerializationProviderForFormat(\"yaml\");\nservices.AddUniversalSerializationProviderForExtension(\".toml\");\nservices.AddUniversalSerializationProviderForContentType(\"application/xml\");\n```\n\n## Advanced Configuration\n\n### Configuring Serializer Options (DI)\n\n```csharp\nusing ktsu.UniversalSerializer;\n\n// Registers core services and applies options\nservices.AddUniversalSerializer(options =\u003e\n{\n    // Built-in simple properties\n    options.UseStringConversionForUnsupportedTypes = true;\n    options.EnableCompression = true;\n    options.CompressionLevel = 9;\n\n    // Format-specific options via keys\n    options.SetOption(SerializerOptionKeys.Json.AllowComments, true);\n    options.SetOption(SerializerOptionKeys.Json.CaseInsensitive, true);\n    options.SetOption(SerializerOptionKeys.Xml.Indent, true);\n});\n\n// Optional: register serializer types for DI construction (e.g., to inject registries)\nservices.AddJsonSerializer();\nservices.AddXmlSerializer();\nservices.AddYamlSerializer();\nservices.AddMessagePackSerializer();\n```\n\n### Type Conversion\n\nThe library supports custom type conversion for types that aren't natively handled by serializers:\n\n```csharp\nusing ktsu.UniversalSerializer;\n\n// Define a custom type with string conversion\npublic class CustomId\n{\n    public Guid Value { get; }\n    \n    public CustomId(Guid value)\n    {\n        Value = value;\n    }\n    \n    // ToString for serialization\n    public override string ToString()\n    {\n        return Value.ToString(\"D\");\n    }\n    \n    // Parse method for deserialization\n    public static CustomId Parse(string value)\n    {\n        return new CustomId(Guid.Parse(value));\n    }\n}\n\n// Enable string conversion in options\nservices.AddUniversalSerializer(options =\u003e\n{\n    options.UseStringConversionForUnsupportedTypes = true;\n});\n```\n\n### Polymorphic Serialization\n\n```csharp\nusing ktsu.UniversalSerializer;\n\n// Register core and enable discriminators (Json/Yaml/Toml read option via key)\nservices.AddUniversalSerializer(options =\u003e\n{\n    options.SetOption(SerializerOptionKeys.TypeRegistry.EnableTypeDiscriminator, true);\n});\n\n// Ensure JSON serializer is constructed with registries when used via DI\nservices.AddJsonSerializationProvider();\n\n// Define types\npublic abstract class Animal\n{\n    public string Name { get; set; } = string.Empty;\n}\n\npublic class Dog : Animal\n{\n    public string Breed { get; set; } = string.Empty;\n}\n\npublic class Cat : Animal\n{\n    public int Lives { get; set; }\n}\n\n// Use polymorphic serialization\nvar animals = new List\u003cAnimal\u003e\n{\n    new Dog { Name = \"Rex\", Breed = \"German Shepherd\" },\n    new Cat { Name = \"Whiskers\", Lives = 9 }\n};\n\n// Resolve and configure the type registry\nusing var provider = services.BuildServiceProvider();\nvar registry = provider.GetRequiredService\u003cTypeRegistry\u003e();\nregistry.RegisterType\u003cDog\u003e(\"dog\");\nregistry.RegisterType\u003cCat\u003e(\"cat\");\n\n// Use provider (JSON)\nvar sp = provider.GetRequiredService\u003cktsu.SerializationProvider.ISerializationProvider\u003e();\nstring json = sp.Serialize(animals);\nvar deserializedAnimals = sp.Deserialize\u003cList\u003cAnimal\u003e\u003e(json);\n```\n\n## Binary Serialization\n\n```csharp\nusing ktsu.UniversalSerializer;\n\n// Option 1: Use provider\nservices.AddUniversalSerializationProviderForFormat(\"messagepack\");\n\nusing var provider = services.BuildServiceProvider();\nvar sp = provider.GetRequiredService\u003cktsu.SerializationProvider.ISerializationProvider\u003e();\nbyte[] bytes = sp.SerializeToBytes(data); // if you need bytes, use serializer directly instead\n\n// Option 2: Use factory directly\nvar factory = new SerializerFactory();\nfactory.RegisterSerializer(o =\u003e new ktsu.UniversalSerializer.MessagePack.MessagePackSerializer(o));\nvar mp = factory.Create\u003cktsu.UniversalSerializer.MessagePack.MessagePackSerializer\u003e();\nbyte[] binary = mp.SerializeToBytes(data);\nvar result = mp.DeserializeFromBytes\u003cMyData\u003e(binary);\n```\n\n## SerializationProvider Integration\n\nUniversalSerializer implements the `ISerializationProvider` interface for standardized dependency injection scenarios:\n\n```csharp\nusing ktsu.SerializationProvider;\n\n// Add a default JSON provider (auto-bootstraps core)\nservices.AddUniversalSerializationProvider();\n\n// Or add specific providers\nservices.AddJsonSerializationProvider();\nservices.AddYamlSerializationProvider();\nservices.AddMessagePackSerializationProvider();\n\n// Use the provider\npublic class MyService\n{\n    private readonly ISerializationProvider _provider;\n    \n    public MyService(ISerializationProvider provider)\n    {\n        _provider = provider;\n    }\n    \n    public async Task ProcessAsync()\n    {\n        var data = new MyData { Id = 1, Name = \"Example\" };\n        \n        // Serialize and deserialize\n        string serialized = await _provider.SerializeAsync(data);\n        var deserialized = await _provider.DeserializeAsync\u003cMyData\u003e(serialized);\n    }\n}\n```\n\nFor more details, see the [SerializationProvider Integration Documentation](docs/serialization-provider-integration.md).\n\n## Supported Formats\n\n| Format | Content Type | File Extension | Package Dependency |\n|--------|-------------|----------------|-------------------|\n| JSON | application/json | .json | System.Text.Json (built-in) |\n| XML | application/xml | .xml | System.Xml.Serialization (built-in) |\n| YAML | text/yaml (also registers application/x-yaml) | .yaml | YamlDotNet |\n| TOML | application/toml | .toml | Tomlyn |\n| MessagePack | application/x-msgpack | .msgpack | MessagePack |\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fktsu-dev%2Funiversalserializer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fktsu-dev%2Funiversalserializer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fktsu-dev%2Funiversalserializer/lists"}