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

C# AutoMapper对象映射详解

news 2025/7/13 20:26:57

引言

在现代软件开发中，特别是采用分层架构的应用程序，我们经常需要在不同的对象类型之间进行转换。例如，从数据库实体（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() 方法抛出异常时，通常是因为存在未配置的属性映射。解决方案：

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

问题二：循环引用

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

  1. 在映射配置中使用 MaxDepth(n) 限制递归深度
  2. 在循环引用的一端使用 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());

问题三：性能问题

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

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

最佳实践

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

结论

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

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

参考资源

  • AutoMapper 官方文档
  • AutoMapper GitHub 仓库
  • AutoMapper 在 ASP.NET Core 中的使用
http://www.xdnf.cn/news/605035.html

相关文章：

  • 从细胞工厂到智能制造：Extracellular 用时序数据库 TDengine 打通数据生命线
  • 题目 3330: 蓝桥杯2025年第十六届省赛真题-01 串
  • Spring循环依赖相关问题
  • C++（初阶）（十九）——红黑树
  • LLM多轮对话效果优化之道
  • 每日c/c++题 备战蓝桥杯（修理牛棚 Barn Repair）
  • 【信息系统项目管理师】第19章：配置与变更管理 - 38个经典题目及详解
  • 【Ubuntu】如何在一个脚本文件中跑三个python文件？以及端口被占的解决方法
  • 如何最简单、通俗地理解什么是NLP？
  • el-table控制type=“expand“展开列 根据条件显示或隐藏展开按钮
  • 【萤火工场GD32VW553-IOT开发板】流水灯
  • Git子模块原理与实战详解
  • 【MATLAB代码】扩展卡尔曼滤波估计pmsm的位置误差
  • #6 百日计划第六天 java全栈学习
  • 编译原理 期末速成
  • 从零开始：Python语言进阶之继承
  • window 显示驱动开发-视频内存供应和回收（二）
  • 计算机语言＆计算机安全知识
  • 十、Linux 网络服务基础
  • NLweb本地部署指南
  • EasyRTC音视频实时通话WebP2P技术赋能的全场景实时通信解决方案
  • 数据分析概述and环境配置
  • 照片时光机APP：修复老照片，重现往昔美好
  • Windows逆向工程提升之IMAGE_EXPORT_DIRECTORY
  • Git和Gitcode交互教程
  • 85. Java Record 深入解析：构造函数、访问器、序列化与实际应用
  • 关于千兆网络变压器的详细介绍
  • 【Flutter】多语言适配-波斯语RTL从右到左
  • 基于 Vue3 与 exceljs 实现自定义导出 Excel 模板
  • 如何在Mac 上使用Python Matplotlib