# AutoMapper — Convention-Based Object Mapping for .NET

> A .NET library that eliminates boilerplate object-to-object mapping code by using conventions and configuration profiles.

## Install

Save as a script file and run:

# AutoMapper — Convention-Based Object Mapping for .NET

## Quick Use
```bash
dotnet add package AutoMapper
```
```csharp
var config = new MapperConfiguration(cfg =>
    cfg.CreateMap<Order, OrderDto>());
var mapper = config.CreateMapper();
var dto = mapper.Map<OrderDto>(order);
```

## Introduction
AutoMapper is a convention-based object mapper for .NET that eliminates repetitive property-by-property copying code. It maps between objects by matching property names automatically and supports custom projections, flattening, and value transformations through configuration profiles.

## What AutoMapper Does
- Maps properties between source and destination types by name convention
- Flattens nested object hierarchies into flat DTOs
- Supports custom value resolvers and type converters
- Projects mappings into LINQ expressions for efficient database queries
- Validates mapping configurations at startup to catch errors early

## Architecture Overview
AutoMapper builds an execution plan for each source-destination type pair during configuration. It compiles these plans into expression trees for fast execution. Mapping profiles group related configurations, and the MapperConfiguration object is created once at startup. For DI scenarios, IMapper is registered as a singleton that reuses the compiled plans.

## Self-Hosting & Configuration
- Install via NuGet: `dotnet add package AutoMapper`
- For DI: `dotnet add package AutoMapper.Extensions.Microsoft.DependencyInjection`
- Create Profile classes to organize mapping configurations
- Register with `builder.Services.AddAutoMapper(typeof(Program).Assembly)`
- Call `config.AssertConfigurationIsValid()` in tests to verify all mappings

## Key Features
- Convention-based mapping with zero configuration for matching property names
- Projection via `ProjectTo<T>()` that translates to SQL through EF Core
- Before/after map actions for side effects during mapping
- Conditional mapping to skip properties based on runtime logic
- Reverse mapping support with `ReverseMap()`

## Comparison with Similar Tools
- **Mapster** — code-generation-based mapper; faster runtime performance, less mature ecosystem
- **Manual mapping** — explicit property assignment; no dependencies, but verbose and error-prone
- **Mapperly** — source-generator-based mapper; compile-time safety, zero runtime overhead
- **TinyMapper** — lightweight mapper using IL emission; fewer features, smaller footprint
- **ExpressMapper** — convention-based alternative; smaller community and less active development

## FAQ
**Q: Does AutoMapper affect performance?**
A: The initial configuration has a cost, but subsequent mapping operations use compiled expression trees and are fast. For hot paths, consider source-generator alternatives like Mapperly.

**Q: Can I use AutoMapper with Entity Framework Core?**
A: Yes. Use `ProjectTo<TDto>(mapper.ConfigurationProvider)` on IQueryable to generate efficient SQL that only selects mapped columns.

**Q: How do I handle complex nested mappings?**
A: AutoMapper flattens nested properties by convention (e.g., Order.Customer.Name maps to OrderDto.CustomerName). For non-conventional mappings, use ForMember with MapFrom.

**Q: What is the licensing model?**
A: AutoMapper v12 and earlier are MIT-licensed. Version 13+ uses a dual license with a free Community edition for individuals and non-commercial use, and a commercial license for enterprises.

## Sources
- https://github.com/AutoMapper/AutoMapper
- https://docs.automapper.org/

---
Source: https://tokrepo.com/en/workflows/asset-8971216a
Author: Script Depot