Awesome
<h1 align="center"> <a href="https://github.com/Marvin-Brouwer/FluentSerializer#readme"> <img alt="Fluent Serializer banner" src="/docs/logo/Banner.optimized.svg" /> </a> </h1> <h3 align="center"> </h3> <h3 align="center">Getting started - Basic usage - Use-case examples - Basic concepts - Advanced concepts
</h3> <hr/>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:
<details> <summary>JSON structure & supporting classes</summary>{
"data": [{
"identifier": 1,
"name": "someName",
// Some other properties we don't map
}]
}
public sealed class Request<TDataEntity> where TDataEntity: IDataEntity {
public List<TDataEntity> Data { get; set; }
}
public sealed class SomeDataEntity: IDataEntity {
public string Id { get; set; }
public string Name { get; set; }
}
</details>
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:
Basic concepts
Here are some links to some basic concepts:
- Naming strategies
- Converters
- Converters, EnumConverter
- Converters, FormattableConverter
- Converters, ParsableConverter
Advanced concepts
Here are some links to some more advanced topics:
General
- Recursive references
- Custom converters and accessing parent nodes
- Custom converters and accessing the root node
- Adding a serializer
- Adding a use-case
JSON
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
<a href="https://github.com/Marvin-Brouwer/FluentSerializer/graphs/contributors"> <img src="https://contrib.rocks/image?repo=Marvin-Brouwer/FluentSerializer" /> </a>Made with contrib.rocks.