Mappify.NET 1.0.2

Mappify.NET

A zero-dependency, production-ready object-mapping library for .NET 10 written in C# 14. It replicates the core behaviour of AutoMapper — automatic property mapping, nested-object recursion, collection projection, and a fluent ForMember configuration API — entirely through compiled System.Linq.Expressions delegates that are cached per type-pair for near-zero per-call overhead.

Installation

dotnet add package Mappify.NET

Table of Contents

1. Features
2. Project Structure
3. Architecture & How It Works
4. Getting Started
5. Defining Types
6. Creating a Mapping Profile
7. ForMember – All Four Options
8. Registering Profiles & Building the Mapper
9. Mapping Methods on IMapper
10. Nested Object Mapping
11. Collection Mapping
12. Type Conversion Rules
13. Null Safety
14. Error Handling
15. Performance Notes
16. Complete End-to-End Example
17. API Reference
18. Limitations

Features

Project Structure

AkzoAutoMapper/
│
├── MappingException.cs        # Typed exception with SourceType / DestinationType
├── TypePair.cs                # Internal readonly struct — cache dictionary key
│
├── IMappingExpression.cs      # Public fluent-API interfaces
├── MemberConfig.cs            # Internal resolver storage (abstract base + generic impl)
├── MappingExpression.cs       # Internal fluent-builder; implements IHasMemberConfigs
│
├── MappingProfile.cs          # Abstract base class — users derive from this
├── MapperConfiguration.cs     # MappingRegistry + MapperConfiguration + IMapperConfigurationExpression
├── IMapper.cs                 # Public IMapper contract
├── Mapper.cs                  # Engine: plan builder, collection mapper, compiled accessors
│
└── Examples/
    └── MappingExamples.cs     # Runnable demonstrations (7 scenarios)

Architecture & How It Works

MapperConfiguration.Create(cfg => cfg.AddProfile<MyProfile>())
        │
        ▼
  MappingRegistry                     ← Dictionary<TypePair, MappingExpression<,>>
        │
        ▼
  MapperConfiguration.CreateMapper()
        │
        ▼
  Mapper  ──── _planCache  ───────────  ConcurrentDictionary<TypePair, Func<obj,obj,Mapper,int,obj>>
                                                      │
                             First call for a type-pair
                                                      │
                                              BuildPlan(srcType, dstType)
                                                      │
                          ┌───────────────────────────┤
                          │                           │
                   ForMember configs            Auto-map by name
                   (custom resolvers)           (case-insensitive)
                          │                           │
                          └──── compiled Action<obj,obj,Mapper,int>[] ──── frozen array
                                                      │
                          Subsequent calls execute the frozen array directly

Plan execution routing (per property, per call)

value is null?
  ├─ dest type is reference / Nullable<T>  → setter(null)
  └─ dest type is non-nullable value type  → skip (leave default)

dest.IsAssignableFrom(src)               → direct setter  [fastest path]

both are collections (non-string IEnumerable)
                                         → MapCollection(...)

both are primitive/scalar
  (bool,byte,char,int,long,float,double,decimal,
   string,DateTime,DateTimeOffset,DateOnly,
   TimeOnly,TimeSpan,Guid, + Nullable<T> of each)
                                         → Convert.ChangeType(value, underlyingType)

both are complex objects (neither is primitive)
                                         → MapCore(value, depth + 1)   [recursive]

otherwise                                → throw MappingException

Compiled getter / setter (built once per PropertyInfo)

// Getter
(object owner) => (object)((OwnerType)owner).Property

// Setter — reference type or non-nullable value type
(object owner, object? value) => ((OwnerType)owner).Property = (PropType)value

// Setter — Nullable<T>
(object owner, object? value) =>
    ((OwnerType)owner).Property = (value == null ? default(T?) : (T?)(T)value)

Getting Started

1 — Reference the project

Add a project reference from your application to AkzoAutoMapper.csproj, or package it as a NuGet library and install the package.

2 — Create a singleton mapper

using AkzoAutoMapper;

// Build configuration once at application start-up.
var config = MapperConfiguration.Create(cfg =>
{
    cfg.AddProfile<UserProfile>();
    cfg.AddProfile<OrderProfile>();
});

// IMapper is thread-safe — share it for the application lifetime.
IMapper mapper = config.CreateMapper();

With ASP.NET Core dependency injection:

// Program.cs
builder.Services.AddSingleton(_ =>
{
    var config = MapperConfiguration.Create(cfg =>
    {
        cfg.AddProfile<UserProfile>();
        cfg.AddProfile<OrderProfile>();
    });
    return config.CreateMapper();
});

Defining Types

Destination types must expose a public parameterless constructor. Properties must be public and either readable (source) or writable (destination).

// Source (domain model)
public class User
{
    public int      Id          { get; set; }
    public string   FirstName   { get; set; } = "";
    public string   LastName    { get; set; } = "";
    public string   Email       { get; set; } = "";
    public DateTime DateOfBirth { get; set; }
}

// Destination (DTO)
public class UserDto
{
    public int      Id          { get; set; }
    public string   FirstName   { get; set; } = "";
    public string   LastName    { get; set; } = "";
    public string   Email       { get; set; } = "";
    public DateTime DateOfBirth { get; set; }
}

Creating a Mapping Profile

Derive from MappingProfile and call CreateMap<TSource, TDestination>() inside the constructor. Every call returns IMappingExpression<TSource, TDestination> for optional ForMember chaining.

public class UserProfile : MappingProfile
{
    public UserProfile()
    {
        // Pure auto-mapping — all property names and types match exactly.
        CreateMap<User, UserDto>();
    }
}

ForMember – All Four Options

ForMember selects a destination property and then routes to one of four behaviours:

Option 1 — MapFrom with a source expression

Best for simple, direct property access. The lambda is compiled once; type conversion between compatible primitives is automatic.

CreateMap<Order, OrderDto>()
    .ForMember(
        d => d.CustomerName,
        o => o.MapFrom(src => src.Customer.FullName));   // expression tree, compiled once

Option 2 — MapFrom with a two-argument resolver (src, dst) => ...

Use for transformations, calculations, string formatting, or when the result depends on the partially-mapped destination object.

CreateMap<Employee, EmployeeDto>()
    // Combine two source fields
    .ForMember(
        d => d.FullName,
        o => o.MapFrom((src, _) => $"{src.FirstName} {src.LastName}".Trim()))

    // Calculation
    .ForMember(
        d => d.MonthlySalary,
        o => o.MapFrom((src, _) => Math.Round(src.AnnualSalary / 12m, 2)))

    // Derived / computed value
    .ForMember(
        d => d.YearsEmployed,
        o => o.MapFrom((src, _) => (int)((DateTime.Today - src.HireDate).TotalDays / 365.25)))

    // Null-coalescing
    .ForMember(
        d => d.Department,
        o => o.MapFrom((src, _) => src.Department ?? "Unassigned"))

    // Using a partially-mapped destination value
    .ForMember(
        d => d.Label,
        o => o.MapFrom((src, dst) => $"{dst.FullName} — {src.Department}"));

Option 3 — Ignore

The destination property is skipped entirely and retains its default value.

CreateMap<User, UserDto>()
    .ForMember(d => d.PasswordHash, o => o.Ignore())
    .ForMember(d => d.InternalNotes, o => o.Ignore());

Option 4 — UseValue

Always assigns a compile-time constant to the destination property.

CreateMap<CsvRow, ProductDto>()
    .ForMember(d => d.Source,    o => o.UseValue("CSV-Import"))
    .ForMember(d => d.IsDeleted, o => o.UseValue(false));

Registering Profiles & Building the Mapper

AddProfile<TProfile>()

Instantiates the profile internally — the simplest option.

var config = MapperConfiguration.Create(cfg =>
{
    cfg.AddProfile<UserProfile>();
    cfg.AddProfile<OrderProfile>();
    cfg.AddProfile<ProductProfile>();
    cfg.AddProfile<EmployeeProfile>();
});

AddProfile(instance)

Use when your profile needs constructor arguments (e.g., injected services).

var config = MapperConfiguration.Create(cfg =>
{
    cfg.AddProfile(new OrderProfile(currencyService));
});

Mapping Methods on IMapper

// New destination instance (compile-time types)
UserDto dto = mapper.Map<User, UserDto>(user);

// New destination instance (runtime source type)
UserDto dto = mapper.Map<UserDto>(user);

// Populate existing instance
mapper.Map<User, UserDto>(updatedUser, existingDto);

// Collection
List<UserDto> dtos = mapper.MapList<User, UserDto>(users);

Nested Object Mapping

Register a CreateMap for each type-pair that appears anywhere in the object graph. The mapper resolves nested properties recursively with an incremented depth counter.

public class OrderProfile : MappingProfile
{
    public OrderProfile()
    {
        // Must register the nested type-pair separately.
        CreateMap<Address, AddressDto>();

        // Order.ShippingAddress (Address) is mapped to OrderDto.ShippingAddress (AddressDto)
        // automatically, because the Address→AddressDto mapping is registered above.
        CreateMap<Order, OrderDto>()
            .ForMember(
                d => d.PlacedAt,
                o => o.MapFrom((s, _) => s.PlacedAt.ToString("yyyy-MM-dd HH:mm")));
    }
}

Depth limit — the mapper allows up to 32 levels of nesting before throwing MappingException. This prevents runaway recursion on circular object graphs.

Collection Mapping

No extra configuration is required. Property-level collection mapping is automatic when the element types have a compatible mapping registered.

Supported destination collection shapes

// Using MapList (explicit)
List<ProductDto> dtos = mapper.MapList<Product, ProductDto>(products);

// Via auto-mapped property
public class Catalogue     { public List<Product>    Items { get; set; } = []; }
public class CatalogueDto  { public List<ProductDto> Items { get; set; } = []; }

// No ForMember needed — mapper recurses into Items automatically.
CreateMap<Catalogue, CatalogueDto>();
CreateMap<Product,   ProductDto>();

Type Conversion Rules

When source and destination property types do not match, the mapper applies the following rules in priority order:

Primitive / scalar types recognised:

bool, byte, sbyte, char, short, ushort, int, uint, long, ulong, float, double, decimal, string, DateTime, DateTimeOffset, DateOnly, TimeOnly, TimeSpan, Guid, and Nullable<T> wrappers of any of the above.

// int → long  works automatically (Convert.ChangeType)
// int → int?  works automatically (Nullable<T> setter unwraps the type)
// string → Guid  works if the string is a valid GUID

Null Safety

// Safe — returns null, not an exception
UserDto? dto = mapper.Map<User, UserDto>(null!);   // dto == null

// Null nested object
var order = new Order { ShippingAddress = null! };
OrderDto orderDto = mapper.Map<Order, OrderDto>(order);
// orderDto.ShippingAddress == null

Error Handling

All mapping failures throw MappingException — never a raw InvalidCastException, NullReferenceException, or TargetInvocationException.

public sealed class MappingException : Exception
{
    public Type SourceType      { get; }   // the source type at the point of failure
    public Type DestinationType { get; }   // the destination type at the point of failure
    // Message: "Mapping 'FullTypeName' → 'FullTypeName': <reason>"
}

Common causes and fixes

try
{
    OrderDto dto = mapper.Map<Order, OrderDto>(order);
}
catch (MappingException ex)
{
    Console.WriteLine(ex.SourceType.Name);       // e.g. "Order"
    Console.WriteLine(ex.DestinationType.Name);  // e.g. "OrderDto"
    Console.WriteLine(ex.Message);               // full explanation
    Console.WriteLine(ex.InnerException);        // original BCL exception, if any
}

Performance Notes

Complete End-to-End Example

using AkzoAutoMapper;

// ── Models ────────────────────────────────────────────────────────────────────

public class Product
{
    public int     Id         { get; set; }
    public string  Name       { get; set; } = "";
    public decimal Price      { get; set; }
    public int     StockCount { get; set; }
}

public class ProductDto
{
    public int    Id             { get; set; }
    public string Name           { get; set; } = "";
    public string FormattedPrice { get; set; } = "";
    public bool   InStock        { get; set; }
}

// ── Profile ───────────────────────────────────────────────────────────────────

public class ProductProfile : MappingProfile
{
    public ProductProfile()
    {
        CreateMap<Product, ProductDto>()
            .ForMember(d => d.FormattedPrice,
                       o => o.MapFrom((s, _) => $"$ {s.Price:F2}"))
            .ForMember(d => d.InStock,
                       o => o.MapFrom((s, _) => s.StockCount > 0));
    }
}

// ── Application entry point ───────────────────────────────────────────────────

var config = MapperConfiguration.Create(cfg => cfg.AddProfile<ProductProfile>());
IMapper mapper = config.CreateMapper();

// Single object
var product = new Product { Id = 1, Name = "Primer", Price = 24.99m, StockCount = 50 };
ProductDto dto = mapper.Map<Product, ProductDto>(product);
Console.WriteLine($"{dto.Name}  {dto.FormattedPrice}  InStock:{dto.InStock}");
// Primer  $ 24.99  InStock:True

// Collection
var products = new List<Product>
{
    new() { Id = 2, Name = "Topcoat", Price = 89.50m, StockCount = 0 },
    new() { Id = 3, Name = "Varnish", Price = 49.00m, StockCount = 12 }
};
List<ProductDto> dtos = mapper.MapList<Product, ProductDto>(products);
dtos.ForEach(d => Console.WriteLine($"{d.Name}  {d.FormattedPrice}  InStock:{d.InStock}"));
// Topcoat  $ 89.50  InStock:False
// Varnish  $ 49.00  InStock:True

For seven fully worked examples (simple, nested, collection, custom, existing-instance, null-safety, error-handling), run:

AkzoAutoMapper.Examples.MappingExamples.Run();

API Reference

MapperConfiguration

IMapperConfigurationExpression

MappingProfile

IMappingExpression<TSource, TDestination>

IMemberConfigurationExpression<TSource, TDestination, TMember>

IMapper

MappingException

Limitations