One e-commerce order aggregate, mapped by Mapsicle, AutoMapper, Mapperly and Mapster, in a working CRUD API over SQLite.
The point is not that one wins. It is that the same graph goes through all four in the same process, so the differences are visible without a debugger and without taking anyone's word for it.
dotnet run --project src/Shop.Api # http://localhost:5199/swagger
curl "http://localhost:5199/compare/1" # all three, member by memberOrder into OrderDto. Nine types, and every shape that makes mapping hard:
| Shape | Where |
|---|---|
| Three levels of nesting | Order.Customer.Address.Country |
| A collection inside a collection | Order.Lines[].Discounts[] |
| Widening | int Id into long Id |
| Enum into a string | OrderState.Shipped into "Shipped" |
| Enum into a different enum type | Domain.Channel into Contracts.Channel |
DateTime into DateTimeOffset |
PlacedOn |
| Nullable | DateTime? ShippedOn |
| Flattening, two levels | CustomerFullName from Customer.FullName |
| Flattening, three levels | CustomerAddressCity from Customer.Address.City |
| A self referencing type | Category.Parent is a Category |
| A cycle | Order.Customer.Orders[0] is the order |
Counted from src/Shop.Api/Mapping/Mappers.cs, which holds all
three side by side.
| Setup code | Build warnings | Runtime cost of a missed member | |
|---|---|---|---|
| Mapsicle | none, or one line per pair to bind it at compile time, or one line for the whole assembly | none | there is nothing to miss |
| Mapster | none | none | there is nothing to miss |
| Mapperly | 1 partial method | 12 RMG020 |
a build warning, before you ship |
| AutoMapper | 9 CreateMap calls |
none | the member comes back empty |
Mapster is the closest neighbour here and the most interesting comparison: it also maps by
convention with no setup at all, it is also MIT, and its configuration API is deliberately shaped
like AutoMapper's to make a port mechanical. The differences show up on shapes rather than on
ceremony, which is what /compare and the cycle probe are for.
Mapsicle needs no configuration at all: order.MapTo<OrderDto>() and nothing else. Mapperly needs
one declared method, and for this graph it derives the enum conversion, the widening, the
DateTimeOffset and both flattened members on its own, with no hand written rules. AutoMapper needs
a CreateMap for every pair in the graph, and if you forget one the member is silently empty at
runtime.
The 12 Mapperly warnings are its design, not a misconfiguration: it reports every source member no destination member claims, on the theory that you should say so out loud. That is a real safety net and a real amount of noise, and which of those it is depends on the codebase.
Run /compare/1 and the current answer is: nowhere.
disagreements: 0
OK Channel | Mobile Mobile Mobile
OK Customer.Address.Country.Iso | PH PH PH
OK CustomerAddressCity (flattened) | Cebu Cebu Cebu
...
That took two fixes to Mapsicle, both found by this repository:
- Three level flattening (Mapsicle #56).
CustomerAddressCitycame back empty because the flattening search descended one level. - Enum into a different enum type.
Channelcame back asWeb, the zero member, because the conversion cascade had no rule for it and the member fell out entirely.
Both returned a wrong value rather than throwing, which is the shape that reaches production.
Mapping SrcColour.Amber = 7 into a destination enum whose Amber = 2:
| Result | |
|---|---|
| AutoMapper 15.1.3 | Amber (2), matched by name |
| Mapperly 4.1.1 | 7, matched by value, naming no member of the destination |
| Mapsicle 2.5.0 | Amber (2), matched by name |
Mapsicle matches by name because the rest of its cascade already does: an enum into a string is
ToString, and a string into an enum is a case insensitive Enum.TryParse. Matching by value would
mean the same source arrives as Amber when it goes through a string and as 7 when it does not.
Pinned in Mapsicle by ConversionGapTests.AnEnumIsMatchedByNameNotByValue, which fails if the rule
ever changes to by value.
Order.Customer.Orders[0] is the order. Point a mapper at a destination that exposes the back
reference and the three do three different things. Run it yourself, one at a time, because one of
them ends the process:
dotnet run --project probes/CycleProbe -- mapsicle # cycle expanded to 15 levels, then stopped
dotnet run --project probes/CycleProbe -- automapper # reference preserved
dotnet run --project probes/CycleProbe -- mapperly # Stack overflow. exit 134
dotnet run --project probes/CycleProbe -- mapster # Stack overflow. exit 134
dotnet run --project probes/CycleProbe -- mapster-safe # PreserveReference on: reference preserved| On a cycle, default settings | With cycle handling on | |
|---|---|---|
| AutoMapper 15.1.3 | Preserves the reference. The cycle survives the mapping intact. | same |
| Mapsicle 2.5.0 | Stops on a repeated instance and returns a usable object. | same |
| Mapperly 4.1.1 | Stack overflow. The process aborts, exit 134. | preserves the reference |
| Mapster 7.4.0 | Stack overflow. The process aborts, exit 134. | preserves the reference |
Both source generators handle every cycle shape correctly with one line, UseReferenceHandling on
Mapperly and PreserveReference on Mapster, so this is a story about a default rather than about
two broken libraries. It is worth knowing which default you have, because an Entity Framework entity
with a navigation back to its parent is the most ordinary graph in .NET and it is the shape that
does it.
AutoMapper has the best answer here and it is worth saying so plainly: its output has the same shape as its input. Mapsicle's is safe but lossy. Mapperly's takes the process with it.
That is why CustomerDto in this repository has no Orders member. It is not an oversight, it is
the only shape all three survive.
Mapsicle maps anything with no setup, by compiling an expression tree the first time it sees a pair. Declaring a pair moves it to generated code instead:
[assembly: MapsicleGenerate(typeof(Order), typeof(OrderSummaryDto))]The call site does not change. order.MapTo<OrderSummaryDto>() still compiles, and now binds to an
emitted method rather than to the engine. See
src/Shop.Api/generated/ after a build.
Order into OrderDto is declared too, and the whole nine type graph generates: the nesting, both
collections, the widening, the enum into a string, the enum into a different enum, and both
flattened paths. Read src/Shop.Api/generated/ after a build to see exactly what came out.
It did not always. Until the generator was widened it refused that pair on Id, which widens int
to long, and OrderSummaryDto exists because something had to be left to demonstrate. That is
worth keeping in view when reading any generator's marketing: the shapes it handles and the shapes
your DTOs actually have are different questions.
Three things are still refused on purpose, and each is a refusal rather than a gap:
- A cyclic graph. Generated code has no depth ceiling and the engine has one, so emitting a mapper that follows a cycle would produce a lane that aborts the process where the other returns.
- A destination member with a non-public setter. Reflection writes one and generated code cannot.
- Anything into a string that is not an enum. The engine formats through
CultureInfo.InvariantCulture, and re-deriving that in the emitter is how two implementations of one rule start disagreeing.
A refused pair keeps mapping through the engine, the build carries on, and the call site does not change.
Two things worth knowing before you try this on your own code:
- The generated extension is internal to the assembly that declares the pair. Declaring it in one
project does nothing for another;
bench/Shop.Benchmarksdeclares it again for exactly that reason. - If you turn on
EmitCompilerGeneratedFiles, exclude the output folder from compilation. It lands inside the project directory, the SDK globs it back in, and every generated type is defined twice.
Apple M1, .NET 8.0.24, Release, BenchmarkDotNet 0.13.12 default job. dotnet run -c Release --project bench/Shop.Benchmarks -- --filter '*'.
All numbers below were measured on Mapsicle 2.2.0 and have not been re-run on 2.5.0.
Five members, no nesting. Every entry maps the same source into the same destination, including the baseline.
| Mean | Ratio | Allocated | |
|---|---|---|---|
| hand written | 12.91 ns | 1.00 | 64 B |
| Mapsicle, compile-time bound | 12.74 ns | 1.00 | 64 B |
| Mapperly | 13.18 ns | 1.03 | 64 B |
| Mapsicle, registry lookup | 43.60 ns | 3.41 | 64 B |
| AutoMapper | 59.97 ns | 4.69 | 64 B |
The first three are the same number. Mapsicle bound at compile time, Mapperly and code a person would write are indistinguishable at this scale, and reading anything into the ordering between them would be reading noise: the standard deviations are around 1 ns on a 13 ns mean, and a second full run put Mapsicle at 11.81 ns and hand written at 13.57 ns, swapping them. The claim this table supports is "the same", not "faster".
The gap that is real is the one below them. A declared pair reached through an untyped call site,
((object)order).MapTo<OrderSummaryDto>(), runs the identical generated delegate and costs 3.4x,
because the source's runtime type has to be looked up first. Same code, different way in.
All five allocate exactly the destination object and nothing else.
Nine types, three levels deep, two collections, a widening, an enum into a string, an enum into a different enum and two flattened paths. Every lane maps the same object and is checked against the hand written baseline member by member before a single timing is taken.
| Mean | vs hand written | Allocated | |
|---|---|---|---|
| hand written | 288.5 ns | 1.00 | 1.41 KB |
| Mapsicle, pair declared | 287.7 ns | 1.00 | 1.41 KB |
| Mapperly 4.1.1 | 312.8 ns | 1.08 | 1.50 KB |
| Mapster 7.4.0 | 313.7 ns | 1.09 | 1.38 KB |
| Mapsicle, declared, untyped call | 316.1 ns | 1.10 | 1.41 KB |
| Mapsicle, nothing declared | 519.5 ns | 1.80 | 1.41 KB |
| AutoMapper 15.1.3 | 715.8 ns | 2.48 | 1.48 KB |
The baseline is hand written code, not one of the mappers. Using a mapper as the baseline tells you which mapper is faster and never tells you how far any of them is from the ceiling.
Read the middle of that table as a range, not as a ranking. Mapperly and Mapster are 1.08 and 1.09 here and have swapped places between runs. The three modern mappers sit inside ten percent of each other and of hand written code, and nobody migrates a codebase for ten percent.
What holds across every run is the two ends. A declared pair is level with hand written code and allocates the same. An undeclared one is 1.80, which is still 1.4x faster than AutoMapper and is what you get with no setup at all.
The third Mapsicle row is the same generated code reached a different way.
((object)order).MapTo<OrderDto>() runs the identical emitted method; it just pays a lookup to find
it, because the receiver's type is not known until it runs. That 28 ns is what declaring the pair
buys.
Mapster allocates the least of anyone, including hand written code, at 1.38 KB.
Cold start is the larger and less obvious difference:
| first map of a pair | |
|---|---|
| declared | 2,480 ns |
| undeclared | 367,138 ns |
That 148x is the Expression.Compile a declared pair never pays.
The API has no authentication, no authorization and no rate limiting, and it logs SQL to the
console. It exists to show three mappers producing the same object. Do not lift Program.cs into
anything that faces a network.
src/Shop.Api/
Domain/Aggregate.cs the entities
Contracts/Dtos.cs the read model
Mapping/Mappers.cs all three mappers, side by side
Data/ShopContext.cs EF Core, SQLite, seeded on first run
Program.cs minimal API: CRUD plus /compare
bench/Shop.Benchmarks/ BenchmarkDotNet
probes/CycleProbe/ the cycle table above, runnable
samples/GenerateAll/ one attribute instead of one declaration per pair
GET /orders?mapper= |
all orders, through mapsicle, mapperly, mapster or automapper |
GET /orders/{id}?mapper= |
one order |
GET /orders/{id}/summary |
the flat projection, through generated code |
POST /orders |
create, from a request DTO holding only what a caller may set |
DELETE /orders/{id} |
delete |
GET /compare/{id} |
all three, member by member, with disagreements counted |
POST takes a CreateOrderRequest rather than an Order on purpose. A convention mapper pointed at
a request body will set anything whose name lines up, Total and State included. That is true of
all three of these, and the DTO is the control.
If a Mapsicle checkout sits beside this one at ../Mapsicle, the build uses it instead of the
published package. Use that to try unreleased changes. Force the package with
-p:UseLocalMapsicle=false.
Mapsicle and Mapsicle.SourceGen 2.5.0, AutoMapper 15.1.3, Riok.Mapperly 4.1.1, Mapster 7.4.0, EF Core 8.0.30, .NET 8.
The enum and cycle results above were re-checked on 2.5.0. The benchmark numbers were measured on 2.2.0.