AutoMapper — Convention-Based Object Mapping for .NET

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/