Mapwright 0.5.0

Mapwright

The compile-time object mapper. Declare the mapping; the compiler writes it, checks it, and shows you the code.

AutoMapper resolves mappings at runtime, by reflection and convention: a renamed property maps to nothing, silently, until AssertConfigurationIsValid() fails in a test — or nobody notices at all. Mapwright inverts the model. You declare each mapping as a static partial method; a Roslyn incremental source generator writes the implementation as plain C# you can read, diff, and step through; and every destination property that nothing maps is a compiler diagnostic, not a runtime surprise.

[Mapper]
public static partial class CatalogMapper
{
    // Domain record -> EF entity. Audit fields are the database's business.
    [MapIgnore(nameof(CodeEntity.User), nameof(CodeEntity.Created), nameof(CodeEntity.Modified))]
    public static partial CodeEntity ToEntity(Code source);

    // EF entity -> domain record. bool? columns collapse to non-nullable domain booleans.
    public static partial Code ToDomain(CodeEntity source);

    // In-place scalar copy onto the EF-tracked instance — 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: an expression EF Core translates to SQL.
    public static partial Expression<Func<CodeEntity, CodeSummary>> SummaryProjection();

    // Collection overload, wired to the ToEntity map above.
    public static partial List<CodeEntity> ToEntities(IEnumerable<Code> source);
}

That is the entire mapping layer. No profiles, no MapperConfiguration, no IMapper to inject, nothing to register in DI. Call CatalogMapper.ToEntity(code) like the ordinary method it is.

Why compile-time

• Verification is the build. AutoMapper's AssertConfigurationIsValid() runs when a test remembers to call it. Mapwright's equivalent (MW0001) runs on every keystroke, in the IDE, before the code ever executes — and stale configuration is an error: [MapIgnore("RemovedLastSprint")] referring to a property that no longer exists fails the build (MW0003), so ignore lists cannot rot.
• The mapping is code you own. Generated implementations land in ordinary .g.cs files: object initializers, GetValueOrDefault() where a nullable column collapses, a null-guard before a nested map. Breakpoints work. git diff of behavior is possible. There is no runtime black box to reverse-engineer at 2 a.m.
• Nothing happens at runtime. The Mapwright package is attributes only. No reflection, no expression compilation, no cache warm-up — which also means Native AOT and trimming just work, and the only allocation is the destination object itself.
• EF Core projections without the magic. A Expression<Func<TSource, TDest>> partial method generates the whole projection shape — nested maps inlined as initializers — so queryable.Select(CatalogMapper.SummaryProjection()) translates to SQL exactly like a hand-written projection, because it is one.

Install

Two packages: the attributes, and the generator that does the work.

<ItemGroup>
  <PackageReference Include="Mapwright" Version="0.5.0" />
  <PackageReference Include="Mapwright.Generator" Version="0.5.0" PrivateAssets="all" />
</ItemGroup>

Building from source instead: reference src/Mapwright/Mapwright.csproj normally and src/Mapwright.Generator/Mapwright.Generator.csproj with OutputItemType="Analyzer" ReferenceOutputAssembly="false".

The mapping shapes

Matching: case-insensitive by name (CodeID → CodeId needs nothing), [MapProperty] for real renames, inherited members included, T? → T collapses via visible GetValueOrDefault(), nested objects and collections route through sibling maps.

Construction (0.2): the generator picks the public constructor with the most parameters whose every parameter matches a source member — so positional records map through their primary constructor, remaining members flow through the object initializer, and classes keep their parameterless behavior. required members must be mapped or the build fails (MW0012); a destination nothing can construct is MW0010.

Enums (0.2): enum-to-enum members map by numeric cast by default, or by name with [Mapper(EnumMappingStrategy = EnumMappingStrategy.ByName)] — a generated, readable switch; source members with no same-named destination member are flagged (MW0011). Projections always cast (expression trees cannot contain switches).

Dictionaries & sets (0.2): Dictionary<K,V>/IDictionary/IReadOnlyDictionary members map when keys agree and values are identical or element-mappable; HashSet<T>/ISet<T>/IReadOnlySet<T> join the supported collection shapes.

Auto-synthesized nested maps (0.3): a nested object or element pair with no declared sibling map gets a private helper map synthesized in the generated file — readable, steppable, and reported on (MW0001 still fires inside it). Declared maps always win; cyclic object graphs resolve to recursive calls. Opt out per mapper with [Mapper(AutoNestedMaps = false)] to restore the strict declare-every-pair contract.

Instance & interface mappers (0.3): [Mapper] public partial class M : IM with instance partial methods works — register the class in DI and inject the interface.

Flattening (0.4): CustomerName resolves to Customer.Name by convention when no direct member matches (up to three hops, null-guarded), and [MapProperty] accepts dotted source paths ([MapProperty("Customer.Id", "Buyer")]).

Unflattening (0.5): [MapProperty] also accepts dotted target paths — [MapProperty("CustomerName", "Customer.Name")] builds the nested destination object, grouping every rename that shares a head and recursing for deeper paths. Works in projections. And rename targets are now rot-checked like everything else: a [MapProperty] pointing at a member that no longer exists fails the build (MW0003).

Scalar conversions (0.4): numbers, dates, Guid, bool and enums convert to string; string parses to all of them; DateTime ↔ DateOnly/TimeOnly bridge — all culture-invariant, dates via round-trip "o". A hand-written method for the pair always wins; projections stay conversion-free so the tree remains translatable.

Derived types (0.4): [MapDerivedType(typeof(CarEntity), typeof(CarDto))] turns an object map into a runtime-type switch; unmatched types map as the base pair when constructible and throw otherwise (invalid pairs are MW0013 build errors).

Custom methods (0.4): any hand-written static method on the mapper with shape TDest Name(TSource) is picked up as the map for that pair — nested resolution and scalar overrides use it automatically.

Deep cloning (0.4): [Mapper(DeepClone = true)] makes same-type reference members (and their collections/dictionary values) clone through synthesized maps instead of copying references — T Clone(T source) duplicates the whole graph.

Escape hatches: [BeforeMap] runs before, [AfterMap] after the generated assignments — for computed values and everything a generator shouldn't guess.

The diagnostics

Promote MW0001 to an error in .editorconfig when you want AutoMapper-strictness:

dotnet_diagnostic.MW0001.severity = error

Performance

Generated code runs at hand-written speed, because it is hand-written-style code. benchmarks/Mapwright.Benchmarks maps an order with a nested customer and ten lines, four ways (BenchmarkDotNet, .NET 10, Intel i5-1035G1; read the ratios and allocations — absolute nanoseconds are machine-specific):

Reading it honestly: on a collection — the case that dominates real workloads — Mapwright is the fastest of all four, ~10% ahead of Mapperly and faster than hand-written LINQ itself, because its element loop writes straight into a pre-sized List backing span (CollectionsMarshal.SetCount + AsSpan): no enumerator, no per-element delegate, no Add capacity checks. Allocations tie Mapperly exactly. On a single object Mapperly stays ~8% ahead (less method-call indirection in the tiny-domain case), and AutoMapper's runtime resolution costs 1.75–2.07× throughout. Run dotnet run -c Release in the benchmarks folder to reproduce.

Replacing AutoMapper

docs/automapper-vs-mapwright.html — the side-by-side migration reference: why AutoMapper exists, the issues it leaves open, how Mapwright closes each with modern C#, a statement-by-statement replacement guide, and a runnable sample app whose real output is printed in the doc (samples/CatalogApi.Sample — dotnet run --project samples/CatalogApi.Sample).

docs/replacing-automapper.html is the full walkthrough, built on a real production case study: a catalog API whose AutoMapper MapperFactory (entity↔domain maps, self-maps for tracked updates, ForMember(...Ignore()) lists) became three Mapwright declarations per entity — with the runtime AssertConfigurationIsValid() test replaced by the compiler.

docs/automapper-and-mapwright-explained.html — a from-zero explanation of what AutoMapper is and how source-generated mapping replaces it.

Honest limitations (v0.4)

• Mapper classes must be non-generic and mapping methods non-generic (instance methods are fine as of 0.3; hook targets stay static).
• No DI-resolved value converters inside maps — that's what hooks and hand-written methods are for.
• Dictionary members, scalar conversions, by-name enum maps and hooks are unavailable inside projections/queryables (expression trees must stay translatable).
• Synthesized maps use default configuration; a pair that needs [MapIgnore]/renames still wants an explicit declared map (which always takes precedence).
• Flattening reads paths; reverse unflattening (writing ChildName back into Child.Name) is not implemented.

Road to Mapperly parity

• Constructor & positional-record mapping; required-member enforcement (0.2)
• Enum maps, by value and by name (0.2)
• Dictionaries and sets (0.2)
• Auto-synthesized nested maps — undeclared pairs get private helper maps (0.3)
• Instance & interface mappers for DI (0.3)
• IQueryable<TDest> Name(IQueryable<TSource>) — the ProjectTo shape (0.3)
• Flattening + dotted [MapProperty] paths (0.4)
• Derived-type / polymorphic mapping (0.4)
• Built-in scalar conversions, culture-invariant (0.4)
• Hand-written method resolution (0.4)
• Deep cloning (DeepClone = true) and [BeforeMap] (0.4)
• Unflattening — dotted [MapProperty] target paths; rename-target rot detection (0.5)
• Benchmarks vs AutoMapper and Mapperly; incremental-caching regression test (0.5)
• NuGet packaging & release automation (awaiting the first v* tag)
• Generic mappers.

Project layout

License

MIT — see LICENSE.