laget.Mapper 1.3.27

laget.Mapper

An extremely simple object-object mapper.

Configuration

This example is shown using Autofac since this is the go-to IoC for us.

await Host.CreateDefaultBuilder()
    .ConfigureContainer<ContainerBuilder>((context, builder) =>
    {
        builder.RegisterMappers();
    })
    .UseServiceProviderFactory(new AutofacServiceProviderFactory())
    .Build()
    .RunAsync();

This is the simplest way to register your mappers but also has some constraints:

• The mapper implementations must exist in the program that calls RegisterMappers.
• The mapper implementations must implement the interface IMapper.

await Host.CreateDefaultBuilder()
    .ConfigureContainer<ContainerBuilder>((context, builder) =>
    {
        builder.RegisterMappers(_ =>
        {
            _.TheCallingAssembly();
            _.TheCallingAssembly<T>();
            _.AssemblyContainingType<T>();
            _.Assembly("Mappers");
        });
    })
    .UseServiceProviderFactory(new AutofacServiceProviderFactory())
    .Build()
    .RunAsync();

This is the advanced and more customizable way to register your mappers

• TheCallingAssembly(); will register mapper implementations from the calling assembly that implements the interface IMapper.
• TheCallingAssembly<T>(); will register mapper implementations from the calling assembly that implements the interface T.
• AssemblyContainingType<T>(); will register mapper implementations from the assembly of the provided type, this is useful if you e.g. have class libraries with Mappers and/or custom implementations of IMapper.
• Assembly("name"); will register mapper implementations in the assembly, will load assembly via the name provided using System.Reflection, that implements the interface IMapper.

Usage

Creating a mapper class

To create a mapper class use the marker interface IMapper to mark the class and the MapperMethod attribute to mark all methods in the class that are mapping methods.

The global mapper will pick up all classes tagged with the IMapper marker interface and register all methods tagged with the MapperMethod that match the following critera

• The method is not private
• The method has a non void return value
• The method has only one parameter

public class ModelMapper : IMapper 
{
    [MapperMethod] // Will be registered as the mapping method for converting Model -> Entity
    public Entity ModelToEntity(Model model) => 
        new Entity 
        {
            // ...
        };
        
    [MapperMethod] // Will be registered as the mapping method for converting Dto -> Model
    public Model ModelFromDto(Dto dto) => 
        new Model 
        {
            // ...
        };
        
    [MapperMethod] // Will not be registered as the mapping method for converting Dto -> Model is already defined above
    public Model ModelFromDto2(Dto dto) => 
        new Model 
        {
            // ...
        };
        
    // Will not be registered as it lacks the MapperMethod attribute
    public Dto DtoFromModel(Model model) =>
        new Dto 
        {
            // ...
        };
    
    [MapperMethod] // Will not be registered as it is a private method
    private Model ModelFromEntity(Entity entity) =>
        new Model 
        {
            // ...
        };
        
    [MapperMethod] // Will not be registered as it returns void
    public void UpdateModelState(Model model) { /* ... */ }
     
    [MapperMethod] // Will not be registered as it doesn't take a parameter
    public int GetConstantInt() => 42;
        
    [MapperMethod] // Will not be registered as it takes multiple arguments
    public Model ModelFromEntityAndDto(Entity entity, Dto dto) =>
        new Model 
        {
            // ...
        };
}

Using the mapper

The mapper can be used in different ways, either through direct access to the static method

var model = new Model();
var dto = Mapper.Mapper.Map<Dto>(model);
var baseClassDto = Mapper.Mapper.Map<ModelBase, DtoBase>(model);

Or using one of the built in extensions on object or IEnumerable<TSource>

var model = new Model();
var dto = model.Map<Dto>();

var dtos = new [] { new Dto() /*, ... */ };
var models = dtos.Map<Model>();

Using the extensions is the recommended way as it provides a clean way of writing Linq chains, however it can be useful to access the mapper directly if you need to map based on an inherited class.

Benchmarks

BenchmarkDotNet v0.13.12, Windows 10 (10.0.19045.4123/22H2/2022Update) (VMware)
AMD Ryzen Threadripper 3960X, 1 CPU, 12 logical and 12 physical cores
.NET SDK 8.0.200
  [Host]     : .NET 6.0.27 (6.0.2724.6912), X64 RyuJIT AVX2
  Job-BJZLVN : .NET 6.0.27 (6.0.2724.6912), X64 RyuJIT AVX2
  Job-OQIHXW : .NET 8.0.2 (8.0.224.6711), X64 RyuJIT AVX2

IterationCount=10  LaunchCount=1  RunStrategy=Throughput  WarmupCount=5

Mappings

Registration