AutoMapper vs Mapwright, side by side

1. The problem mapping solves

Almost every layered application keeps more than one shape for the "same" data, and has to convert between them constantly.

A typical API has an immutable domain model and a mutable, database-shaped persistence entity (nullable columns, audit fields like Created/User, navigation properties), plus DTOs for what actually crosses the wire. Converting between them — mapping — is trivial once:

var dto = new ProductDto
{
    Id = entity.ProductId,
    Name = entity.Name,
    Price = entity.Price,
    IsActive = entity.IsActive ?? false,
};

The trouble is that a real app has that same block for dozens of types, written by different people over months, and every one rots the same way: someone adds a property and forgets to map it, or renames one and the assignment silently maps nothing. Both AutoMapper and Mapwright exist to take that mechanical code off your hands — but they do it in opposite ways, and that difference is the entire story here.

2. Why AutoMapper exists

AutoMapper is the long-standing, hugely popular convention-based mapper for .NET. Instead of writing the assignment block, you configure a mapping once and call a generic Map everywhere:

// configure once (in a Profile)
CreateMap<ProductEntity, ProductDto>();

// register once
services.AddAutoMapper(typeof(ProductProfile));

// use everywhere (IMapper injected)
ProductDto dto = _mapper.Map<ProductDto>(entity);

Its appeal is real: same-named properties (Id, Name, Price) are copied automatically by convention, so the boring 90% of a mapping writes itself, and one CreateMap serves every call site. That convenience is why it became a default.

Under the hood, at application start AutoMapper inspects your profiles with reflection, compiles an internal execution plan per CreateMap, caches it, and every later Map() runs that cached plan. None of it is visible to the C# compiler — the compiler has no idea what CreateMap<A, B>() will do; it finds out only when the program runs. That single fact is the root of everything in the next section.

3. The issues AutoMapper leaves open

AutoMapper is not "bad" — it has mapped an enormous amount of production .NET successfully. But the runtime, convention-driven model has specific, well-known costs:

Five of these six are consequences of resolving the mapping at runtime. The natural fix is to resolve it while the code compiles — so a bad mapping is a build error instead of a production incident. That is exactly what a source generator makes possible, and it's what Mapwright is.

4. How Mapwright solves each, with modern C#

Mapwright is a compile-time mapper. You still declare what maps to what — you don't hand-write the assignments — but instead of a runtime engine reading that declaration, a Roslyn incremental source generator reads it while your project builds and writes the mapping method for you as ordinary C#, before the program ever runs.

Two more modern-C# details make the ergonomics work: partial methods let half a method live in your file and half in the generated file, stitched into one class by the compiler; and the generator emits EF-translatable Expression trees for projections, so the ProjectTo scenario keeps working without the runtime engine.

5. Side-by-side at a glance

6. Statement-by-statement replacement guide

Every AutoMapper construct has a direct Mapwright equivalent. The table is the cheat sheet; the worked pairs below show each one.

6.1 The basic map + ignore list

public class ProductProfile : Profile
{
    public ProductProfile()
    {
        CreateMap<Product, ProductEntity>()
          .ForMember(d => d.User,     o => o.Ignore())
          .ForMember(d => d.Created,  o => o.Ignore())
          .ForMember(d => d.Modified, o => o.Ignore())
          .ForMember(d => d.Tags,     o => o.Ignore());
    }
}
services.AddAutoMapper(typeof(ProductProfile));

[Mapper]
public static partial class CatalogMapper
{
    [MapIgnore(nameof(ProductEntity.User),
               nameof(ProductEntity.Created),
               nameof(ProductEntity.Modified),
               nameof(ProductEntity.Tags))]
    public static partial ProductEntity ToEntity(Product source);
}
// no DI registration — nothing to add to Program.cs

6.2 The call site

private readonly IMapper _mapper;   // injected

var entity = _mapper.Map<ProductEntity>(product);

// no field, no constructor parameter, no mock in tests

var entity = CatalogMapper.ToEntity(product);

6.3 Rename, computed value, in-place update, collection, projection

6.4 Deleting the old world

Once the declarations compile clean, delete the AutoMapper Profile classes, the services.AddAutoMapper(...) registration, every IMapper constructor parameter, and the AssertConfigurationIsValid() test — the compiler owns that job now. The full production walkthrough of exactly this migration is the Replacing AutoMapper case study.

7. A complete sample app (with real output)

The repository ships a runnable console app at samples/CatalogApi.Sample that exercises every shape above. Everything below is the actual source and the actual program output — nothing is deployed; it runs locally with one command:

git clone https://github.com/lodestar-labs/Mapwright.git
cd Mapwright
dotnet run --project samples/CatalogApi.Sample

7.1 The mapping layer (the whole thing)

[Mapper]
public static partial class CatalogMapper
{
    [MapIgnore(nameof(ProductEntity.User), nameof(ProductEntity.Created),
               nameof(ProductEntity.Modified), nameof(ProductEntity.Tags))]
    public static partial ProductEntity ToEntity(Product source);

    [MapIgnoreSource(nameof(ProductEntity.User), nameof(ProductEntity.Tags))]
    public static partial Product ToDomain(ProductEntity source);

    [MapIgnore(nameof(ProductEntity.User), nameof(ProductEntity.Created), nameof(ProductEntity.Modified))]
    public static partial void CopyScalars(ProductEntity source, ProductEntity target);

    public static partial Expression<Func<ProductEntity, ProductSummary>> SummaryProjection();

    public static partial List<ProductEntity> ToEntities(IEnumerable<Product> source);
}

[Mapper]
public static partial class OrderMapper
{
    public static partial CustomerDto ToDto(CustomerEntity source);

    [MapProperty(nameof(LineEntity.Sku), nameof(LineDto.ProductCode))]
    public static partial LineDto ToDto(LineEntity source);

    public static partial OrderDto ToDto(OrderEntity source);   // nested Customer + Lines auto-routed
}

7.2 What the generator writes (excerpt)

These land in obj/.../generated/ at build time — ordinary C# you can read and breakpoint. The only edit below is readability: the generator emits fully qualified names (global::System.Linq.Enumerable, global::CatalogApi.Sample.OrderDto), shortened here to Enumerable / OrderDto. Note the bool? → bool collapse and the nested/collection routing are written out plainly:

// <auto-generated by Mapwright — the mapping code below is yours to read, debug, and step through />
public static partial Product ToDomain(ProductEntity source)
{
    ArgumentNullException.ThrowIfNull(source);
    var result = new Product
    {
        ProductID = source.ProductId,
        CategoryID = source.CategoryId,
        Name = source.Name,
        Price = source.Price,
        IsActive = source.IsActive.GetValueOrDefault(),   // bool? → bool, visibly
        Created = source.Created,
        Modified = source.Modified,
    };
    return result;
}

public static partial OrderDto ToDto(OrderEntity source)
{
    ArgumentNullException.ThrowIfNull(source);
    var result = new OrderDto
    {
        OrderId = source.OrderId,
        Number = source.Number,
        Customer = source.Customer is null ? null! : ToDto(source.Customer),
        Lines = source.Lines is null ? null! : Enumerable.ToList(Enumerable.Select(source.Lines, ToDto)),
    };
    return result;
}

7.3 The program output (actual run)

Mapwright sample — every mapping below is generated C#, verified by the compiler.

=== 1. Entity -> domain (ToDomain) ===
  ProductID=42  Name=Widget  Price=$19.95  IsActive=True  Created=2025-06-01

=== 2. Domain -> entity (ToEntity) ===
  ProductId=100  Name=Gadget  IsActive=True  User=<null>  Created=<null>

=== 3. In-place update (CopyScalars) — audit fields preserved ===
  Name=New name  Price=$12.49  (User still 'auditor', Created still 2024-01-01 — untouched)

=== 4. Collection map (ToEntities) ===
  mapped 2 entities: 1:A, 2:B

=== 5. Projection (SummaryProjection) applied in-memory here, EF-translatable in a query ===
  1 summary: ProductId=42  Name=Widget  Price=$19.95

=== 6. Nested map + collection + rename (Order -> OrderDto) ===
  Order ORD-5001 for Acme Corp
    line 1: ProductCode=SKU-A (from Sku), Qty=3
    line 2: ProductCode=SKU-B (from Sku), Qty=1

=== 7. AfterMap (ToNewEntity stamps audit fields) ===
  Name=Gadget  User=provisioning  Created=2026-01-01  (stamped by AfterMap)

All mappings ran. Nothing was configured at startup, and no IMapper was injected.

8. The diagnostics that replace runtime checks

These are what turn "silent null in production" into "red squiggle in the IDE." They run on every build; no test calls them.

Promote the main one to a hard error once your team trusts the workflow — strictly stronger than AutoMapper's opt-in test ever was:

# .editorconfig
dotnet_diagnostic.MW0001.severity = error

9. Design boundaries

Mapwright covers the full everyday mapping surface — constructor and positional-record mapping, enums by value or by name, collections, sets and dictionaries, flattening and unflattening, derived types, deep cloning, hand-written and DI-resolved converters, and generic Map<TSource, TTarget> dispatch. The boundaries that remain are deliberate choices, not gaps:

• Projections stay EF-translatable, always: no hooks, no service calls, nothing inside the expression tree that a database provider can't handle. A projection is exactly the query you would have written by hand.
• The mapper class stays non-generic. Generic methods dispatch across the maps declared on the class, and each closed instantiation folds down to a single direct call.
• Declared maps always win: auto-synthesized helpers use default configuration, so a pair that needs renames or ignores gets its own declaration — visible, diffable, compiler-verified.

The trade for those boundaries is the whole point of this document: within its scope, every mapping is plain C# the compiler has already checked, drift is a build error rather than a production bug, and there's no runtime engine, no DI, and no licensing question in the loop.