当前位置：首页 > article >正文

C# AutoMapper对象映射详解

article 2025/9/4 17:45:28

引言

在现代软件开发中，特别是采用分层架构的应用程序，我们经常需要在不同的对象类型之间进行转换。例如，从数据库实体（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());

问题三：性能问题

对于大量对象的映射，性能可能成为问题。解决方案：

使用 ProjectTo<T>() 在数据库查询级别执行映射
编译映射配置
考虑使用对象池来重用 Mapper 实例

最佳实践

组织映射配置：将映射配置组织到单独的 Profile 类中，按领域或功能分组
验证映射配置：使用 AssertConfigurationIsValid() 方法验证映射配置
使用依赖注入：在 ASP.NET Core 应用中使用依赖注入来管理 AutoMapper
避免深层嵌套映射：对于复杂对象图，考虑分解为多个映射步骤
编写单元测试：为映射配置编写单元测试，确保映射行为符合预期
使用 ProjectTo：在 LINQ 查询中使用 ProjectTo<T>() 方法提高性能

结论

AutoMapper 是一个强大的对象映射工具，可以显著减少样板代码，提高开发效率。通过本文介绍的基本用法、高级特性和最佳实践，你应该能够在自己的 C# 项目中有效地使用 AutoMapper 进行对象映射。

记住，虽然 AutoMapper 可以自动处理大多数映射场景，但对于复杂的业务逻辑，有时手动映射或自定义解析器可能是更好的选择。选择合适的工具和方法，取决于你的具体需求和场景。

参考资源

AutoMapper 官方文档
AutoMapper GitHub 仓库
AutoMapper 在 ASP.NET Core 中的使用

引言