Mapster — Fast Object Mapping for .NET

Introduction

Mapster eliminates repetitive property-by-property mapping code between domain entities and DTOs. It auto-maps properties by name and type convention, supports deep cloning, flattening, and unflattening, and achieves this with benchmark-proven performance that outpaces alternatives by significant margins.

What Mapster Does

• Auto-maps objects by matching property names and types with zero configuration
• Supports deep object cloning, flattening, and unflattening of nested hierarchies
• Generates mapping code at compile time via Mapster.Tool for AOT and performance
• Handles collections, dictionaries, records, and custom constructors
• Provides queryable extensions for projecting EF Core queries directly to DTOs

Architecture Overview

Mapster uses a two-phase approach. At runtime, it reflects on source and target types to build an expression tree, then compiles it into a delegate cached for reuse. This means the first mapping incurs a small JIT cost, but subsequent calls run at compiled-code speed. The optional Mapster.Tool generates static mapping methods at build time, eliminating all runtime reflection for Native AOT compatibility.

Self-Hosting & Configuration

• Install via NuGet: dotnet add package Mapster
• Optionally add Mapster.DependencyInjection for ASP.NET Core DI integration
• Configure mappings globally with TypeAdapterConfig.GlobalSettings or per-type with NewConfig()
• Use Mapster.Tool CLI to generate mapping code: dotnet mapster model -a MyAssembly.dll
• Validate all mappings at startup with TypeAdapterConfig.GlobalSettings.Compile()

Key Features

• Up to 4x faster than AutoMapper in benchmark comparisons
• Zero-config convention-based mapping with optional explicit overrides
• Compile-time code generation for Native AOT and minimal reflection
• IQueryable projection for efficient database queries via ProjectToType<T>()
• Two-way mapping, conditional mapping, and before/after map hooks

Comparison with Similar Tools

• AutoMapper — profile-based configuration; Mapster is faster and requires less setup
• Manual mapping — full control but verbose; Mapster auto-generates equivalent code
• Mapperly — source-generator-only mapper; Mapster offers both runtime and compile-time modes
• ExpressMapper — convention-based like Mapster but less actively maintained
• TinyMapper — lightweight but lacks queryable projection and code generation

FAQ

Q: How does Mapster compare to AutoMapper in performance? A: Benchmarks show Mapster is 2-4x faster than AutoMapper for most mapping scenarios, thanks to its compiled expression tree approach.

Q: Can Mapster map to existing objects? A: Yes. Use source.Adapt(destination) to map onto an existing instance without creating a new one.

Q: Does Mapster support .NET Native AOT? A: Yes. Use Mapster.Tool to generate mapping code at build time, which eliminates runtime reflection and is fully AOT-compatible.

Q: How do I map collections? A: Mapster handles List<T>, arrays, and IEnumerable<T> automatically. Just call sourceList.Adapt<List<TargetDto>>().

Sources

• https://github.com/MapsterMapper/Mapster
• https://github.com/MapsterMapper/Mapster/wiki