Marvin-Brouwer/FluentSerializer

[![XML][package-shield-i-xml]][package-url-xml] [![XML Nuget][package-shield-v-xml]![XML Downloads][package-shield-d-xml]][package-url-xml] [![JSON][package-shield-i-json]![JSON Nuget][package-shield-v-json]![JSON Downloads][package-shield-d-Json]][package-url-json] [![Stars][repo-stars-shield]][repo-stars-url] [![License][license-shield]][license-url] [![Discord][discord-shield]][discord-url]

[Getting started](#getting-started) - [Basic usage](#basic-usage) - [Use-case examples](#use-case-examples) - [Basic concepts](#basic-concepts) - [Advanced concepts](#advanced-concepts)

FluentSerializer is a library to help you with serializing to-and-from C# POCOs using profiles. The use of profiles helps making it easier to understand how the data vs the code looks in a single glance. So instead of needing a library like Mappster or AutoMapper to mold data into your code structure, you can now map that same data into a clean data representation and use the mapping frameworks for what their intended, to translate data.

Next to a clear overview of how the data looks, this library provides you with serializing methods for multiple data formats with a similar api. So when you're required to tie XML and JSON together at least the code for serializing looks similar across your solution.

If you're just looking for a simple JSON or XML serializer checkout these options:

Newtonsoft.Json The most commonly used dotnet JSON serializer
JaxLib An awesome XML serializer that's miles ahead of the DotNet default one.

Getting started

Install a FluentSerializer for the serial format you need.

Json: FluentSerializer.Json

dotnet add package FluentSerializer.Json

Xml: FluentSerializer.Xml
```
dotnet add package FluentSerializer.Xml
```

Basic usage

For the serializer to work you need to create a profile and call the serializer.

Creating profiles

You create a profile by creating a class that inherits from the serializer's profile class. FluentSerializer.Json.JsonSerializerProfile, FluentSerializer.Xml.JsonSerializerProfile, and maybe others.

When these profiles are created in an assembly that has been registered in the DI startup the startup will find the correct profiles for the correct serializer. Each profile has it's own builder methods but follow a similar style.

For illustration's sake, here's a basic example of a profile:

JSON structure & supporting classes

```jsonc { "data": [{ "identifier": 1, "name": "someName", // Some other properties we don't map }] } ``` ```csharp public sealed class Request where TDataEntity: IDataEntity { public List Data { get; set; } } ``` ```csharp public sealed class SomeDataEntity: IDataEntity { public string Id { get; set; } public string Name { get; set; } } ```

public sealed class RequestProfile : JsonSerializerProfile
{
    protected override void Configure()
    {
        For<Request<IDataEntity>>()
            .Property(request => request.Data);

        For<SomeDataEntity>()
            .Property(entity => entity.Id,
                namingStrategy: Names.Equal("identifier"))
            .Property(entity => entity.Name);
    }
}

Calling the serializer

Once the profiles are registered all you have to do is inject the serializer into the service responsible for handling serialized application dependencies and call the serializer or deserialize method.

public sealed class WeirdExample : IWeirdExample {

    private readonly IWebClient _webClient;
    private readonly IJsonSerializer _jsonSerializer;
    private readonly IXmlSerializer _xmlSerializer;

    public WeirdExample(IWebClient webClient) {

        _webClient = webClient;

        _jsonSerializer = SerializerFactory.For
            .Json()
            .UseProfilesFromAssembly<IAssemblyMarker>();
        _xmlSerializer =  SerializerFactory.For
            .Xml()
            .UseProfilesFromAssembly<IAssemblyMarker>();
    }

    public TReceive DoApiCall<TSend, TReceive>(TSend sendModel) {

        var sendXML = _xmlSerializer.Serialize(sendModel);
        var idResponse = _webClient.Post(sendXML);

        var otherApiJsonResponse = _webClient.Get(idResponse);
        return _jsonSerializer.Deserialize<TReceive>(otherApiJsonResponse);
    }
}

The serialize will automatically find the correct profile for the types that are passed or requested and (de)serialize as expected.

Configuration

Every serializer has overloads for the factory that will allow you to configure the serialier to fit your application.
To read more about that you can either visit the specific serializer's readme, check out the Basic concepts or the Advanced concepts section of this guide.

Dependency injection

Alternatively, if you prefer dependency injection;
Each serializer has an adjacent NuGet package that makes registering the serializer to the default DotNet dependency injection library easier.

Install a corresponding NuGet package for the serial format you need.

Json: FluentSerializer.Json.DependencyInjection.NetCoreDefault

dotnet add package FluentSerializer.Json.DependencyInjection.NetCoreDefault

Xml: FluentSerializer.Xml.DependencyInjection.NetCoreDefault

dotnet add package FluentSerializer.Xml.DependencyInjection.NetCoreDefault

And then add the serializer to the DI registration, pointing to the a type in the assembly where your profiles live.

serviceCollection
    .AddFluentJsonSerializer<TAssemblyMarker>()
    .AddFluentXmlSerializer<TAssemblyMarker>();

Like for the factory approach, there are multiple overloads for overriding configurations and passing assemblies.
Please read the respective readme's for the DependencyInjection libraries to read more.

Use-case Examples

To get a quick view of how this library may benefit you, check out these use-cases:

Mavenlink (JSON)
OpenAir (XML)

Basic concepts

Here are some links to some basic concepts:

Advanced concepts

Here are some links to some more advanced topics:

General

JSON

Using raw JSON

XML

Using raw XML

Contributing

We are currently figuring out what the best branching model is, and we're still fleshing out release, contribution and development guidelines.
Suggestions on how to do this are very welcome.

If you want to help out the project, you are very welcome to.
Please read our Contribution guidelines and contributor covenant's code of conduct before starting. For maintainers we have an additional Maintenance guide.

Note Because of backwards compatibility, you will need to install additional runtimes if you want to debug the solution locally.
See Contribution guidelines - Technical prerequisites for more detail.

Release management

Maintainers are responsible for the release cycles. However, if you register a bug blocking your development you can request an alpha package version for your branch to be deployed while the code is in review.

For more information, review the Maintenance guides Release management chapter.

Contributors

Made with contrib.rocks.