# Mapster — Fast Object Mapping for .NET

> Mapster is a high-performance object-to-object mapper for .NET that is up to 4x faster than AutoMapper, with a simple API for mapping DTOs, view models, and entities without manual property assignment.

## Install

Save in your project root:

# Mapster — Fast Object Mapping for .NET

## Quick Use
```bash
dotnet add package Mapster
```
```csharp
using Mapster;
var userDto = user.Adapt<UserDto>();
var users = dbUsers.Select(u => u.Adapt<UserDto>()).ToList();
// Or configure globally:
TypeAdapterConfig<User, UserDto>.NewConfig()
    .Map(dest => dest.FullName, src => $"{src.First} {src.Last}");
```

## 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

---
Source: https://tokrepo.com/en/workflows/asset-a74cd451
Author: AI Open Source