EonaCat.Mapper 2.0.1

EonaCat.Mapper

A high-performance, flexible object mapping library for .NET with support for:

• Fast object-to-object mapping
• DTO ↔ Domain model transformations
• Async mapping
• Mapping profiles
• Middleware pipeline
• Dependency Injection integration
• Collection and dictionary mapping
• Runtime and strongly typed mapping
• Validation and diagnostics
• Expression generation
• Configuration-based mapping
• Named mapper instances via MapperFactory

Features

Core Mapping

• Strongly typed mapping (Map<TSource, TDestination>)
• Runtime mapping using Type
• Map into existing destination instances
• Automatic property matching
• Expression-based mapping generation

Async Support

• Async mapping operations
• Async collection mapping
• After-map async hooks

Profiles

• Group mappings into reusable profile classes
• Register profiles manually or scan assemblies

Pipeline Middleware

• Intercept mapping requests
• Add logging, validation, metrics, caching, auditing, and more

Diagnostics

• Validate mapping configurations
• Detect mapping issues early

Dependency Injection

• Easy integration with DI containers
• Automatic profile registration

Factory Support

• Default mapper instance
• Named mapper instances
• Centralized mapper management

Installation

dotnet add package EonaCat.Mapper

Supported Frameworks

• .NET Standard 2.0
• .NET Standard 2.1
• .NET 6
• .NET 7
• .NET 8

Quick Start

Source Model

public class User
{
    public int Id { get; set; }
    public string Name { get; set; }
}

public class UserDto
{
    public int Id { get; set; }
    public string Name { get; set; }
}

Simple Mapping

var mapper = new Mapper();

var dto = mapper.Map<User, UserDto>(user);

Dynamic Mapping

object dto = mapper.Map(
    user,
    typeof(User),
    typeof(UserDto));

Mapping Into Existing Objects

var dto = new UserDto();

mapper.Map(user, dto);

Useful when updating existing entities.

Fluent Builder API

var dto = mapper
    .From(user)
    .MapToType<UserDto>();

Map into an existing object:

mapper
    .From(user)
    .MapTo(existingDto);

Configuration

Create a Mapping Configuration

var config = new TypeMapConfig();

config.NewConfig<User, UserDto>();

var mapper = new Mapper(config);

Profiles

Profiles help organize mappings.

public class UserProfile : MappingProfile
{
    public UserProfile()
    {
        CreateMap<User, UserDto>();
    }
}

Register:

var mapper = new AdvancedMapper()
    .AddProfile<UserProfile>();

Or:

var config = new TypeMapConfig();

config.AddProfile<UserProfile>();

Assembly Scanning

config.AddProfilesFromAssemblies(
    typeof(Program).Assembly);

Automatically discovers all MappingProfile classes.

AdvancedMapper

AdvancedMapper provides the complete feature set.

var mapper = new AdvancedMapper();

Includes:

• Sync mapping
• Async mapping
• Profiles
• Validation
• Middleware pipeline

Async Mapping

var dto = await mapper
    .MapAsync<User, UserDto>(user);

Map collections:

var users = await mapper
    .MapCollectionAsync<User, UserDto>(userList);

After-map hook:

mapper.AfterMapAsync<User, UserDto>(
    async (source, destination, ct) =>
    {
        await auditService.LogAsync(destination);
    });

Collections

List<UserDto> result =
    mapper.Map<List<User>, List<UserDto>>(users);

Arrays:

UserDto[] result =
    mapper.Map<User[], UserDto[]>(users);

Dictionaries

var destination =
    mapper.Map<Dictionary<string, object>,
               Dictionary<string, object>>(source);

Middleware Pipeline

The mapping pipeline allows custom behavior before and after mappings.

var mapper = new AdvancedMapper();

mapper.Pipeline.Use(async (context, next) =>
{
    Console.WriteLine("Before");

    await next();

    Console.WriteLine("After");
});

Common uses:

• Logging
• Auditing
• Metrics
• Validation
• Performance tracking
• Caching

MapperFactory

Default mapper:

var dto =
    MapperFactory.Default.Map<User, UserDto>(user);

Named mapper:

MapperFactory.Create(
    "api",
    builder =>
    {
        builder.AddProfile<UserProfile>();
    });

var mapper = MapperFactory.Get("api");

Fallback:

var mapper =
    MapperFactory.GetOrDefault("api");

Validation

var result =
    MapperFactory.ValidateAll();

if (!result.IsValid)
{
    foreach (var issue in result.Issues)
    {
        Console.WriteLine(issue.Message);
    }
}

Dependency Injection

services.AddEonaCatMapper(options =>
{
    options.ProfileAssemblies =
    [
        typeof(Program).Assembly
    ];

    options.RegisterAsyncMapper = true;
});

Inject:

public class UserService
{
    private readonly IMapper _mapper;

    public UserService(IMapper mapper)
    {
        _mapper = mapper;
    }
}

Expression Generation

Create reusable expressions.

Expression<Func<User, UserDto>> expr =
    mapper
        .From(new User())
        .CreateMapExpression<UserDto>();

Useful for:

• LINQ
• Entity Framework
• Query projections

Runtime Mapping

Type sourceType = typeof(User);
Type destinationType = typeof(UserDto);

var dto = mapper.Map(
    user,
    sourceType,
    destinationType);

Real World Example

public class UserProfile : MappingProfile
{
    public UserProfile()
    {
        CreateMap<User, UserDto>();
        CreateMap<Address, AddressDto>();
    }
}

var mapper =
    new AdvancedMapper()
        .AddProfile<UserProfile>();

var dto =
    await mapper.MapAsync<User, UserDto>(user);

Architecture

Application
    |
AdvancedMapper
    |
+------------------+
| Profiles         |
| Pipeline         |
| Validation       |
| Async Mapper     |
+------------------+
    |
Core Mapper
    |
TypeMapConfig

Performance Notes

• Mapping delegates are compiled and cached.
• Designed for high-throughput applications.
• Supports reusable configuration instances.
• Minimal reflection after initial setup.

Best Practices

• Use profiles for large applications.
• Register mappings during startup.
• Reuse TypeMapConfig instances.
• Use AdvancedMapper when async or middleware is required.
• Validate mappings during application startup.

License

Apache License 2.0

Copyright © EonaCat (Jeroen Saey)