.NET 帮助

Automapper C#（开发者如何使用）

Q: 在 C# 项目中开始使用 Automapper 的步骤是什么？

要在 C# 项目中开始使用 Automapper，通过包管理器控制台使用命令： Install-Package AutoMapper 安装。然后，定义映射配置以自动化您的对象模型之间的映射过程。

已更新:七月 28, 2025

Automapper 是一个在 C# 中设计用于促进对象到对象映射的多功能和强大的库，使在复杂对象模型之间转移数据变得更容易且更可维护。在本文中，我们将探讨 Automapper 如何有效地映射属性，展平复杂的对象模型，并与诸如用户域对象和数据传输对象等各种类型的对象一起工作。

Automapper 简介

Automapper 在 C# 中是一个对象到对象的映射器，能够简化不同对象类型之间的数据转换和传输。这在涉及数据实体及其转化为数据传输对象 (DTO) 的场景中特别有用。

Automapper 的关键特性

代码简化：Automapper 通过自动映射属性，大幅减少了手动编写代码的需求，从而防止错误并节省时间。
映射配置的灵活性：Automapper 允许详细自定义映射配置，适用于广泛的映射场景。
性能效率：该库旨在处理大型和复杂的对象模型，而不会出现显著的性能开销。

开始使用 Automapper

要使用 Automapper，必须先通过包管理器控制台安装它，包管理器控制台是开发环境的组成部分，便于管理软件包。

通过包管理器控制台进行安装

您可以通过在包管理器控制台中执行一个简单的命令轻松在项目中安装 Automapper：

Install-Package AutoMapper

设置基本映射配置

使用 Automapper 的基础步骤是定义映射配置。这涉及指定输入对象（源）属性应如何传输到输出对象（目标）。

var config = new MapperConfiguration(cfg => 
{
    cfg.CreateMap<SourceClass, DestinationClass>();
});
IMapper mapper = config.CreateMapper();

var config = new MapperConfiguration(cfg => 
{
    cfg.CreateMap<SourceClass, DestinationClass>();
});
IMapper mapper = config.CreateMapper();

Dim config = New MapperConfiguration(Sub(cfg)
	cfg.CreateMap(Of SourceClass, DestinationClass)()
End Sub)
Dim mapper As IMapper = config.CreateMapper()

$vbLabelText $csharpLabel

在上面的例子中，创建了一个映射配置，将 SourceClass 的属性映射到 DestinationClass。
然后使用该配置创建一个 IMapper 实例。

使用 Automapper 进行高级映射技术

Automapper 的功能远不止简单的属性对属性映射。它能够巧妙地处理更复杂的场景。

展平复杂的对象模型

Automapper 的一个优势是能够展平复杂的对象模型。该功能在处理嵌套对象时特别有用，可将这些嵌套属性映射到平面目标类结构。

多样的对象类型处理

Automapper 可以熟练地在各种对象类型之间映射，包括用户域对象、DTO 甚至视图模型，为不同数据传输需求提供多样化的解决方案。

实用使用示例

为了更好地理解 Automapper 的实用性，让我们探索一些实用示例。

示例 1：简单映射

考虑一个需要将用户实体的属性映射到用户 DTO 的场景：

public class User
{
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public string Address { get; set; }
    public string City { get; set; }
}

public class UserDTO
{
    public string FullName { get; set; }
    public string Address { get; set; }
    public string City { get; set; }
}

// Mapping Configuration
var config = new MapperConfiguration(cfg =>
{
    cfg.CreateMap<User, UserDTO>()
       .ForMember(dest => dest.FullName, opt => opt.MapFrom(src => src.FirstName + " " + src.LastName));
});
IMapper mapper = config.CreateMapper();
User user = new User { FirstName = "John", LastName = "Doe", Address = "123 Street", City = "CityName" };
UserDTO userDto = mapper.Map<UserDTO>(user);

public class User
{
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public string Address { get; set; }
    public string City { get; set; }
}

public class UserDTO
{
    public string FullName { get; set; }
    public string Address { get; set; }
    public string City { get; set; }
}

// Mapping Configuration
var config = new MapperConfiguration(cfg =>
{
    cfg.CreateMap<User, UserDTO>()
       .ForMember(dest => dest.FullName, opt => opt.MapFrom(src => src.FirstName + " " + src.LastName));
});
IMapper mapper = config.CreateMapper();
User user = new User { FirstName = "John", LastName = "Doe", Address = "123 Street", City = "CityName" };
UserDTO userDto = mapper.Map<UserDTO>(user);

Public Class User
	Public Property FirstName() As String
	Public Property LastName() As String
	Public Property Address() As String
	Public Property City() As String
End Class

Public Class UserDTO
	Public Property FullName() As String
	Public Property Address() As String
	Public Property City() As String
End Class

' Mapping Configuration
Private config = New MapperConfiguration(Sub(cfg)
	cfg.CreateMap(Of User, UserDTO)().ForMember(Function(dest) dest.FullName, Function(opt) opt.MapFrom(Function(src) src.FirstName & " " & src.LastName))
End Sub)
Private mapper As IMapper = config.CreateMapper()
Private user As New User With {
	.FirstName = "John",
	.LastName = "Doe",
	.Address = "123 Street",
	.City = "CityName"
}
Private userDto As UserDTO = mapper.Map(Of UserDTO)(user)

$vbLabelText $csharpLabel

这个示例展示了在 User 和 UserDTO 之间进行映射的过程，其中 UserDTO 的 FullName 是通过 User 的 FirstName 和 LastName 连接而成的。

示例 2：具有复杂对象的高级映射

在一个更复杂的场景中，让我们将具有嵌套用户详细信息的订单对象映射到简化的订单 DTO：

public class Order
{
    public User OrderedBy { get; set; }
    // Other properties...
}

public class OrderDTO
{
    public string FullName { get; set; }
    // Other properties...
}

// Mapping Configuration
var config = new MapperConfiguration(cfg =>
{
    cfg.CreateMap<Order, OrderDTO>()
       .ForMember(dest => dest.FullName, opt => opt.MapFrom(src => src.OrderedBy.FirstName + " " + src.OrderedBy.LastName));
});
IMapper mapper = config.CreateMapper();
Order order = new Order { OrderedBy = new User { FirstName = "Jane", LastName = "Doe" } };
OrderDTO orderDto = mapper.Map<OrderDTO>(order);

public class Order
{
    public User OrderedBy { get; set; }
    // Other properties...
}

public class OrderDTO
{
    public string FullName { get; set; }
    // Other properties...
}

// Mapping Configuration
var config = new MapperConfiguration(cfg =>
{
    cfg.CreateMap<Order, OrderDTO>()
       .ForMember(dest => dest.FullName, opt => opt.MapFrom(src => src.OrderedBy.FirstName + " " + src.OrderedBy.LastName));
});
IMapper mapper = config.CreateMapper();
Order order = new Order { OrderedBy = new User { FirstName = "Jane", LastName = "Doe" } };
OrderDTO orderDto = mapper.Map<OrderDTO>(order);

Public Class Order
	Public Property OrderedBy() As User
	' Other properties...
End Class

Public Class OrderDTO
	Public Property FullName() As String
	' Other properties...
End Class

' Mapping Configuration
Private config = New MapperConfiguration(Sub(cfg)
	cfg.CreateMap(Of Order, OrderDTO)().ForMember(Function(dest) dest.FullName, Function(opt) opt.MapFrom(Function(src) src.OrderedBy.FirstName & " " & src.OrderedBy.LastName))
End Sub)
Private mapper As IMapper = config.CreateMapper()
Private order As New Order With {
	.OrderedBy = New User With {
		.FirstName = "Jane",
		.LastName = "Doe"
	}
}
Private orderDto As OrderDTO = mapper.Map(Of OrderDTO)(order)

$vbLabelText $csharpLabel

这个示例展示了将包含嵌套 OrderedBy 详细信息的 Order 对象映射到平面 OrderDTO，并提取和组合用户名到一个单一 FullName 属性中。

在 9.0 版本中，Automapper 已从静态 API (Mapper.Initialize) 过渡到基于实例的 API。这一变化增强了灵活性，更适合现代应用程序，尤其是那些使用依赖注入的应用程序。如果您使用的版本早于 9.0，可继续使用静态 API 方式。然而，对于较新的版本，建议如上面的例子中采用基于实例的 API。

Iron Software 套件概览

这款 Iron Software Suite for .NET 是一个强大的包，内含一系列各具特定用途的库。它涵盖了创建、读取和编辑 PDF、将 HTML 转换为 PDF 以及图像转文本等多种功能，支持多国语言。这一套件适用于各种开发需求，成为任何 C# 项目中的多功能补充。

Iron Software 套件的关键组件

IronPDF for PDF Management：该组件允许开发者创建、读取、编辑和签署 PDF。它也提供将 HTML 转换为 PDF 的能力，这在从基于网页的数据生成报告或文档时尤为有用。
IronXL Excel File Handling：IronXL 使处理 Excel 文件无需依赖 Office Interop，简化了数据处理和分析任务。
IronOCR for Text Extraction：它支持从图像中提取文本，支持多达 125 种语言，是国际项目的高性价比选择。
IronBarcode for QR and Barcode Support：一个允许读取和编写 QR 码和条形码的库，提高了库存管理、跟踪以及其他相关任务的能力。

Automapper C# (开发人员如何使用)：图 4 - IronBarcode for .NET: The C# Barcode Library

与 Automapper 的互补性

虽然 Automapper 在 C# 中在不同对象模型之间进行映射时表现出色，Iron Software 的库通过提供处理各种数据格式和类型的工具扩展了其功能。例如，在使用 Automapper 将用户域对象转换为 DTO 后，IronPDF 可以用于生成 PDF 格式的详细报告。同样，通过 Automapper 提取或转换的数据可以使用 IronXL 进行进一步的操作或分析以处理 Excel 文件。

结论

Automapper 是 C# 开发人员不可或缺的工具，它简化了对象之间的映射任务。其强大的属性映射能力、处理复杂对象模型的能力以及可配置的映射配置使其成为高效软件开发的必备工具。理解对象模型的复杂性，以及如何根据特定需求配置 Automapper，对于在任何项目中最大化其潜力至关重要。

The Iron Software's Iron Suite offers various licensing options, including a free trial of Iron Software, to suit different project needs. 其许可证分为 Lite、Plus 和 Professional 等级，适用于不同团队规模，并提供全面的支持特征。将此套件与 Automapper 集成可以极大地增强 C# 项目，增加数据处理和文档操作功能。