C# AutoMapper对象映射详解

引言

在现代软件开发中，特别是采用分层架构的应用程序，我们经常需要在不同的对象类型之间进行转换。例如，从数据库实体（Entity）转换为数据传输对象（DTO），或者从视图模型（ViewModel）转换为领域模型（Domain Model）。手动编写这些转换代码不仅繁琐，还容易出错。这就是 AutoMapper 这类对象映射工具的价值所在。

本文将详细介绍 C# 中 AutoMapper 的使用方法、最佳实践以及一些高级特性，帮助你在项目中高效地实现对象映射。

什么是 AutoMapper？

AutoMapper 是一个简单、实用的 .NET 对象映射工具，它可以自动将一个对象的属性值复制到另一个对象中，从而消除了手动编写重复的对象转换代码的需要。

AutoMapper 的核心理念是约定大于配置，它会根据属性名称的匹配自动创建映射关系，同时也提供了丰富的配置选项来处理复杂的映射场景。

安装 AutoMapper

在开始使用 AutoMapper 之前，我们需要先安装它。使用 NuGet 包管理器可以轻松完成这一步：

# 使用 NuGet Package Manager Console
Install-Package AutoMapper

# 或者使用 .NET CLI
dotnet add package AutoMapper

对于 ASP.NET Core 应用程序，你可能还想安装 AutoMapper 的依赖注入扩展：

# 使用 NuGet Package Manager Console
Install-Package AutoMapper.Extensions.Microsoft.DependencyInjection

# 或者使用 .NET CLI
dotnet add package AutoMapper.Extensions.Microsoft.DependencyInjection

基本使用

创建映射配置

使用 AutoMapper 的第一步是创建映射配置。以下是一个简单的例子：

using AutoMapper;

// 源类和目标类
public class Customer
{
    public int Id { get; set; }
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public string Email { get; set; }
}

public class CustomerDto
{
    public int Id { get; set; }
    public string FullName { get; set; }
    public string Email { get; set; }
}

// 创建映射配置
var config = new MapperConfiguration(cfg => 
{
    cfg.CreateMap<Customer, CustomerDto>()
       .ForMember(dest => dest.FullName, 
                  opt => opt.MapFrom(src => $"{src.FirstName} {src.LastName}"));
});

// 创建映射器实例
var mapper = config.CreateMapper();

执行映射

一旦配置好映射关系，就可以使用 mapper.Map<TDestination>(source) 方法执行映射：

// 创建源对象
var customer = new Customer
{
    Id = 1,
    FirstName = "John",
    LastName = "Doe",
    Email = "john.doe@example.com"
};

// 执行映射
var customerDto = mapper.Map<CustomerDto>(customer);

// 输出结果
Console.WriteLine($"Id: {customerDto.Id}");
Console.WriteLine($"FullName: {customerDto.FullName}");
Console.WriteLine($"Email: {customerDto.Email}");

输出结果：

Id: 1
FullName: John Doe
Email: john.doe@example.com

在 ASP.NET Core 中使用 AutoMapper

在 ASP.NET Core 应用程序中，我们可以利用依赖注入来简化 AutoMapper 的使用。

注册 AutoMapper 服务

在 Program.cs 或 Startup.cs 中注册 AutoMapper 服务：

// Program.cs in .NET 6+
var builder = WebApplication.CreateBuilder(args);

// 添加 AutoMapper 服务
builder.Services.AddAutoMapper(typeof(Program).Assembly);

// 或者指定包含配置文件的程序集
// builder.Services.AddAutoMapper(typeof(MappingProfile).Assembly);

var app = builder.Build();
// ...

创建映射配置文件

为了保持代码的整洁，我们通常会创建单独的映射配置文件：

using AutoMapper;

public class MappingProfile : Profile
{
    public MappingProfile()
    {
        // 配置 Customer 到 CustomerDto 的映射
        CreateMap<Customer, CustomerDto>()
            .ForMember(dest => dest.FullName, 
                      opt => opt.MapFrom(src => $"{src.FirstName} {src.LastName}"));
        
        // 可以在这里添加更多映射配置
    }
}

在控制器中使用 AutoMapper

通过依赖注入在控制器中使用 AutoMapper：

[ApiController]
[Route("api/[controller]")]
public class CustomersController : ControllerBase
{
    private readonly IMapper _mapper;
    private readonly ICustomerRepository _repository;

    public CustomersController(IMapper mapper, ICustomerRepository repository)
    {
        _mapper = mapper;
        _repository = repository;
    }

    [HttpGet("{id}")]
    public ActionResult<CustomerDto> GetCustomer(int id)
    {
        var customer = _repository.GetById(id);
        
        if (customer == null)
            return NotFound();
            
        return _mapper.Map<CustomerDto>(customer);
    }
    
    [HttpGet]
    public ActionResult<IEnumerable<CustomerDto>> GetAllCustomers()
    {
        var customers = _repository.GetAll();
        return Ok(_mapper.Map<IEnumerable<CustomerDto>>(customers));
    }
}

高级映射技巧

处理不同名称的属性

当源对象和目标对象的属性名称不同时，可以使用 ForMember 方法来指定映射关系：

CreateMap<Source, Destination>()
    .ForMember(dest => dest.DestinationProperty, 
               opt => opt.MapFrom(src => src.SourceProperty));

条件映射

有时我们只想在特定条件下执行映射：

CreateMap<Source, Destination>()
    .ForMember(dest => dest.Property, 
               opt => opt.Condition(src => src.SomeValue != null));

值转换器

对于需要进行复杂转换的情况，可以使用值转换器：

CreateMap<Source, Destination>()
    .ForMember(dest => dest.FormattedDate, 
               opt => opt.MapFrom(src => src.Date.ToString("yyyy-MM-dd")));

集合映射

AutoMapper 可以自动处理集合之间的映射：

// 源类和目标类
public class Order
{
    public int Id { get; set; }
    public List<OrderItem> Items { get; set; }
}

public class OrderDto
{
    public int Id { get; set; }
    public List<OrderItemDto> Items { get; set; }
}

// 映射配置
CreateMap<Order, OrderDto>();
CreateMap<OrderItem, OrderItemDto>();

// 使用
var orderDto = _mapper.Map<OrderDto>(order);

扁平化映射

当目标对象的属性需要从源对象的嵌套属性中获取值时，可以使用扁平化映射：

// 源类和目标类
public class Customer
{
    public int Id { get; set; }
    public string Name { get; set; }
    public Address Address { get; set; }
}

public class Address
{
    public string Street { get; set; }
    public string City { get; set; }
    public string ZipCode { get; set; }
}

public class CustomerViewModel
{
    public int Id { get; set; }
    public string Name { get; set; }
    public string Street { get; set; }
    public string City { get; set; }
    public string ZipCode { get; set; }
}

// 映射配置
CreateMap<Customer, CustomerViewModel>()
    .ForMember(dest => dest.Street, opt => opt.MapFrom(src => src.Address.Street))
    .ForMember(dest => dest.City, opt => opt.MapFrom(src => src.Address.City))
    .ForMember(dest => dest.ZipCode, opt => opt.MapFrom(src => src.Address.ZipCode));

或者使用更简洁的方式：

CreateMap<Customer, CustomerViewModel>()
    .ForMember(dest => dest.Street, opt => opt.MapFrom(src => src.Address.Street))
    .ForMember(dest => dest.City, opt => opt.MapFrom(src => src.Address.City))
    .ForMember(dest => dest.ZipCode, opt => opt.MapFrom(src => src.Address.ZipCode));

自定义值解析器

对于更复杂的映射逻辑，可以创建自定义值解析器：

public class FullNameResolver : IValueResolver<Customer, CustomerDto, string>
{
    public string Resolve(Customer source, CustomerDto destination, string destMember, ResolutionContext context)
    {
        return $"{source.FirstName} {source.LastName}";
    }
}

// 在映射配置中使用
CreateMap<Customer, CustomerDto>()
    .ForMember(dest => dest.FullName, 
               opt => opt.MapFrom<FullNameResolver>());

忽略属性

有时我们不希望映射某些属性：

CreateMap<Source, Destination>()
    .ForMember(dest => dest.PropertyToIgnore, opt => opt.Ignore());

双向映射

如果需要在两个类型之间进行双向映射，可以使用 ReverseMap 方法：

CreateMap<Customer, CustomerDto>()
    .ForMember(dest => dest.FullName, 
               opt => opt.MapFrom(src => $"{src.FirstName} {src.LastName}"))
    .ReverseMap()
    .ForMember(dest => dest.FirstName, 
               opt => opt.MapFrom(src => src.FullName.Split(' ')[0]))
    .ForMember(dest => dest.LastName, 
               opt => opt.MapFrom(src => src.FullName.Split(' ')[1]));

性能优化

编译映射

AutoMapper 提供了编译映射功能，可以显著提高映射性能：

var config = new MapperConfiguration(cfg => 
{
    cfg.CreateMap<Customer, CustomerDto>();
});

// 验证配置
config.AssertConfigurationIsValid();

// 编译映射
config.CompileMapping();

使用映射表达式

对于性能要求极高的场景，可以使用映射表达式：

var config = new MapperConfiguration(cfg => 
{
    cfg.CreateMap<Customer, CustomerDto>();
});

// 获取映射表达式
var customerDtoExpression = config.CreateMapper()
    .ConfigurationProvider
    .BuildExecutionPlan(typeof(Customer), typeof(CustomerDto));

// 在 LINQ 查询中使用
var customerDtos = dbContext.Customers
    .AsNoTracking()
    .ProjectTo<CustomerDto>(config)
    .ToList();

测试映射配置

确保映射配置正确是很重要的，AutoMapper 提供了验证配置的方法：

var config = new MapperConfiguration(cfg => 
{
    cfg.CreateMap<Customer, CustomerDto>();
});

// 验证所有映射配置
config.AssertConfigurationIsValid();

也可以编写单元测试来验证映射配置：

[Fact]
public void AutoMapper_Configuration_IsValid()
{
    var config = new MapperConfiguration(cfg => 
    {
        cfg.AddProfile<MappingProfile>();
    });
    
    config.AssertConfigurationIsValid();
}

实际应用案例

案例一：Web API 中的实体到 DTO 映射

在 Web API 中，我们通常需要将数据库实体转换为 DTO 以返回给客户端：

// 实体类
public class Product
{
    public int Id { get; set; }
    public string Name { get; set; }
    public string Description { get; set; }
    public decimal Price { get; set; }
    public int CategoryId { get; set; }
    public Category Category { get; set; }
    public DateTime CreatedAt { get; set; }
    public DateTime? UpdatedAt { get; set; }
    public bool IsDeleted { get; set; }
}

// DTO 类
public class ProductDto
{
    public int Id { get; set; }
    public string Name { get; set; }
    public string Description { get; set; }
    public decimal Price { get; set; }
    public string CategoryName { get; set; }
}

// 映射配置
public class ProductMappingProfile : Profile
{
    public ProductMappingProfile()
    {
        CreateMap<Product, ProductDto>()
            .ForMember(dest => dest.CategoryName, 
                      opt => opt.MapFrom(src => src.Category.Name));
    }
}

// 在控制器中使用
[HttpGet]
public ActionResult<IEnumerable<ProductDto>> GetProducts()
{
    var products = _repository.GetActiveProducts();
    return Ok(_mapper.Map<IEnumerable<ProductDto>>(products));
}

案例二：表单提交到领域模型的映射

当处理用户提交的表单数据时，我们需要将视图模型映射到领域模型：

// 视图模型
public class UserRegistrationViewModel
{
    public string Username { get; set; }
    public string Email { get; set; }
    public string Password { get; set; }
    public string ConfirmPassword { get; set; }
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public DateTime BirthDate { get; set; }
}

// 领域模型
public class User
{
    public int Id { get; set; }
    public string Username { get; set; }
    public string Email { get; set; }
    public string PasswordHash { get; set; }
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public DateTime BirthDate { get; set; }
    public DateTime CreatedAt { get; set; }
}

// 映射配置
public class UserMappingProfile : Profile
{
    public UserMappingProfile()
    {
        CreateMap<UserRegistrationViewModel, User>()
            .ForMember(dest => dest.PasswordHash, 
                      opt => opt.MapFrom(src => HashPassword(src.Password)))
            .ForMember(dest => dest.CreatedAt, 
                      opt => opt.MapFrom(src => DateTime.UtcNow))
            .ForMember(dest => dest.Id, opt => opt.Ignore());
    }
    
    private string HashPassword(string password)
    {
        // 实际应用中应使用安全的密码哈希算法
        return BCrypt.Net.BCrypt.HashPassword(password);
    }
}

// 在控制器中使用
[HttpPost]
public ActionResult Register(UserRegistrationViewModel model)
{
    if (!ModelState.IsValid)
        return BadRequest(ModelState);
        
    var user = _mapper.Map<User>(model);
    _userService.Create(user);
    
    return CreatedAtAction(nameof(GetUser), new { id = user.Id }, null);
}

常见问题与解决方案

问题一：映射配置无效

当 AssertConfigurationIsValid() 方法抛出异常时，通常是因为存在未配置的属性映射。解决方案：

确保所有需要映射的属性都已配置
对于不需要映射的属性，使用 Ignore() 方法明确忽略
使用 CreateMap<Source, Destination>().ForAllMembers(opt => opt.Condition((src, dest, srcMember) => srcMember != null)); 忽略所有空值

问题二：循环引用

当对象之间存在循环引用时，AutoMapper 可能会陷入无限循环。解决方案：

在映射配置中使用 MaxDepth(n) 限制递归深度
在循环引用的一端使用 Ignore() 方法

CreateMap<Parent, ParentDto>()
    .ForMember(dest => dest.Children, opt => opt.MapFrom(src => src.Children))
    .MaxDepth(2);

CreateMap<Child, ChildDto>()
    .ForMember(dest => dest.Parent, opt => opt.Ignore());