Replacing AutoMapper, at compile time

The starting point

The subject of this case study is a production REST API that manages a scientific reference-code catalog: code tables, code types, cross-table relations, synonyms. Names below are neutralized, but the shapes, the AutoMapper usage, and every migration decision are real.

The API kept two parallel models, as most layered .NET systems do:

• an immutable domain record — IDs suffixed ID, non-nullable booleans, audit timestamps inherited from a base record;
• a mutable EF Core entity — IDs suffixed Id, nullable database columns (bool?, DateTime?), an audit User column, navigation collections, and a few [NotMapped] relationship helpers.

One static MapperFactory owned every CreateMap. Three maps per entity, eight entities — and the two failure modes every AutoMapper codebase knows:

// The old world: runtime configuration, checked (maybe) by a test.
var config = new MapperConfiguration(cfg =>
{
    cfg.CreateMap<Domain.Code, Entities.CodeEntity>()
       .ForMember(d => d.User,        o => o.Ignore())
       .ForMember(d => d.Created,     o => o.Ignore())
       .ForMember(d => d.Modified,    o => o.Ignore())
       .ForMember(d => d.ParentCodes, o => o.Ignore());

    cfg.CreateMap<Entities.CodeEntity, Domain.Code>();

    // Self-map: scalar copy onto the EF-tracked instance during updates.
    cfg.CreateMap<Entities.CodeEntity, Entities.CodeEntity>()
       .ForMember(d => d.User,    o => o.Ignore())
       .ForMember(d => d.Created, o => o.Ignore());
    // ... five more entities of the same ...
});

The Mapwright shape

Mapwright replaces the configuration object with declarations. Each mapping is a static partial method on a [Mapper] class; a Roslyn incremental source generator writes the body while the compiler runs:

[Mapper]
public static partial class CatalogMapper
{
    // Domain -> entity. The same four ignores the old profile declared —
    // now verified against the entity type on every build.
    [MapIgnore(nameof(CodeEntity.User), nameof(CodeEntity.Created),
               nameof(CodeEntity.Modified), nameof(CodeEntity.ParentCodes))]
    public static partial CodeEntity ToEntity(Code source);

    // Entity -> domain. bool? columns collapse to the domain's non-nullable bools.
    [MapIgnoreSource(nameof(CodeEntity.User), nameof(CodeEntity.ParentCodes))]
    public static partial Code ToDomain(CodeEntity source);

    // The self-map, as an in-place copy for the Repository.Update pattern.
    [MapIgnore(nameof(CodeEntity.User), nameof(CodeEntity.Created), nameof(CodeEntity.Modified))]
    public static partial void CopyScalars(CodeEntity source, CodeEntity target);

    // The ProjectTo replacement — EF Core translates this to SQL.
    public static partial Expression<Func<CodeEntity, CodeSummary>> SummaryProjection();

    public static partial List<CodeEntity> ToEntities(IEnumerable<Code> source);
}

And this is what the generator emits — not IL, not a runtime plan, but a .g.cs file that reads exactly like the code a careful engineer writes by hand (because that is the standard it was built against):

// <auto-generated by Mapwright — the mapping code below is yours to read, debug, and step through />
public static partial Code ToDomain(CodeEntity source)
{
    ArgumentNullException.ThrowIfNull(source);
    var result = new Code
    {
        CodeID      = source.CodeId,              // ID ↔ Id casing: matched automatically
        CodeTypeID  = source.CodeTypeId,
        Value       = source.Value,
        Description = source.Description,
        Visibility  = source.Visibility.GetValueOrDefault(),  // bool? → bool, visibly
        Deprecated  = source.Deprecated.GetValueOrDefault(),
        LongDescription = source.LongDescription,
        Created     = source.Created,             // inherited record members included
        Modified    = source.Modified,
    };
    return result;
}

Feature-by-feature: where each AutoMapper behavior went

The verification story, before and after

What the numbers looked like

The migration, step by step

1. Install. Add the Mapwright attributes package and the Mapwright.Generator analyzer package to the project that owns the mappings.
2. Inventory the profiles. Each CreateMap<S,D> becomes one static partial declaration; each ForMember(...Ignore()) list becomes a [MapIgnore(...)] with nameof. Direction matters: the case study's domain→entity and entity→domain maps carried different ignore lists, and kept them.
3. Let MW0001 drive. Build. Every warning is a decision the old profile made implicitly — map it, ignore it, or hand it to an [AfterMap]. When the build is clean, the mapping layer is provably total.
4. Rewrite call sites mechanically. _mapper.Map<CodeEntity>(code) → CatalogMapper.ToEntity(code); _mapper.Map(incoming, tracked) → CatalogMapper.CopyScalars(incoming, tracked); ProjectTo<CodeSummary>() → .Select(CatalogMapper.SummaryProjection()). Then delete the IMapper constructor parameters and DI registrations.
5. Delete. The MapperFactory, the AutoMapper package references, and the configuration-validity test. The compiler owns that job now.
6. Tighten. dotnet_diagnostic.MW0001.severity = error in .editorconfig once the team trusts the workflow — full AutoMapper-strictness with zero runtime cost.

Where the boundaries are

Since this case study was written, Mapwright has reached full Mapperly parity: constructor and positional-record mapping, enums by name, dictionaries and sets, flattening and unflattening, derived types, deep cloning, hand-written converters — including instance methods on instance mappers, so constructor-injected services convert values — and generic Map<TSource, TTarget> dispatch. The boundaries that remain are deliberate: projections never contain hooks or service calls (so EF can always translate them), and the mapper class itself stays non-generic — generic methods dispatch across its declared maps. For anything the generator shouldn't guess, [BeforeMap]/[AfterMap] and hand-written methods are first-class escape hatches.

Getting started

git clone https://github.com/lodestar-labs/Mapwright.git
cd Mapwright
dotnet test          # 86 tests — behavior over real generated mappers + diagnostics

Then read the generated mappers for the case-study shapes under tests/Mapwright.Tests/obj/generated/ after a build — the fastest way to convince yourself there is no magic left.