.NET幫助

Automapper C#（開發者的工作原理）

Q: 在 C# 项目中如何开始使用 Automapper？

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

更新日期:7月 28, 2025

Automapper 是一個多功能且強大的 C# 庫，旨在促進對象到對象的映射，使在複雜對象模型之間轉移數據更輕鬆且更易於維護。在本文中，我們將探討 Automapper 如何有效地映射屬性，扁平化複雜對象模型，以及與各種對象類型配合使用，例如用戶域對象和數據傳輸對象。

Automapper 簡介

C# 中的 Automapper 是一種對象對象映射器，一種簡化在不同對象類型之間轉換和傳輸數據的工具。這在涉及數據實體及其向數據傳輸對象（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 用於 PDF 管理：此組件允許開發人員創建、閱讀、編輯和簽署 PDF。它還提供將 HTML 轉換為 PDF 的功能，這在從基於 Web 的數據生成報告或文檔時特別有用。

Automapper C# (How it Works For Developers): 圖 1 - IronPDF for .NET: The C# PDF Library

IronXL Excel 文件處理：IronXL 便於處理 Excel 文件，無需 Office Interop，簡化數據操作和分析任務。

Automapper C# (How it Works For Developers): 圖 2 - IronXL for .NET: The C# Excel Library

IronOCR 用於文字提取：它支持從圖像中提取文本，支持多達 125 種語言，使其對於國際項目而言高度多樣化。

Automapper C# (How it Works For Developers): 圖 3 - IronOCR for .NET: The C# OCR Library

IronBarcode 用於 QR 和條形碼支持：一個允許讀取和寫入 QR 碼和條形碼的庫，增強了庫存管理、跟蹤和其他相關任務的能力。

Automapper C# (How it Works For Developers): 圖 4 - IronBarcode for .NET: The C# Barcode Library

與 Automapper 的互補性

雖然 Automapper 在 C# 中在不同對象模型之間映射屬性方面表現出色，但 Iron Software 的庫通過提供處理各種數據格式和類型的工具來擴展功能。例如，在使用 Automapper 將用戶域對象轉換為 DTO 之後，可以使用 IronPDF 生成 PDF 格式的綜合報告。同樣，使用 Automapper 提取或轉換的數據可以進一步使用 IronXL 進行操作或分析。

結論

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# 項目，增加數據處理和文檔操作能力。