【C#】AutoMapper 使用手冊
阿新 • • 發佈：2020-06-12
[TOC]
> 本文基於 AutoMapper 9.0.0
AutoMapper 是一個物件-物件對映器，可以將一個物件對映到另一個物件。
官網地址：http://automapper.org/
官方文件：https://docs.automapper.org/en/latest/
### 1 入門例子
```csharp
public class Foo
{
public int ID { get; set; }
public string Name { get; set; }
}
public class FooDto
{
public int ID { get; set; }
public string Name { get; set; }
}
public void Map()
{
var config = new MapperConfiguration(cfg => cfg.CreateMap());
var mapper = config.CreateMapper();
Foo foo = new Foo { ID = 1, Name = "Tom" };
FooDto dto = mapper.Map(foo);
}
```
### 2 註冊
在使用 `Map` 方法之前，首先要告訴 AutoMapper 什麼類可以對映到什麼類。
```csharp
var config = new MapperConfiguration(cfg => cfg.CreateMap());
```
每個 AppDomain 只能進行一次配置。這意味著放置配置程式碼的最佳位置是在應用程式啟動中，例如 ASP.NET 應用程式的 Global.asax 檔案。
從 9.0 開始 `Mapper.Initialize` 方法就不可用了。
#### 2.1 Profile
`Profile` 是組織對映的另一種方式。新建一個類，繼承 `Profile`，並在建構函式中配置對映。
```csharp
public class EmployeeProfile : Profile
{
public EmployeeProfile()
{
CreateMap();
}
}
var config = new MapperConfiguration(cfg =>
{
cfg.AddProfile();
});
```
`Profile` 內部的配置僅適用於 `Profile` 內部的對映。應用於根配置的配置適用於所有建立的對映。
AutoMapper 也可以在指定的程式集中掃描從 `Profile` 繼承的類，並將其新增到配置中。
```csharp
var config = new MapperConfiguration(cfg =>
{
// 掃描當前程式集
cfg.AddMaps(System.AppDomain.CurrentDomain.GetAssemblies());
// 也可以傳程式集名稱（dll 名稱）
cfg.AddMaps("LibCoreTest");
});
```
### 3 配置
#### 3.1 命名約定
預設情況下，AutoMapper 基於相同的欄位名對映，並且是 **不區分大小寫** 的。
但有時，我們需要處理一些特殊的情況。
- `SourceMemberNamingConvention` 表示源型別命名規則
- `DestinationMemberNamingConvention` 表示目標型別命名規則
`LowerUnderscoreNamingConvention` 和 `PascalCaseNamingConvention` 是 AutoMapper 提供的兩個命名規則。前者命名是小寫幷包含下劃線，後者就是帕斯卡命名規則（每個單詞的首字母大寫）。
我的理解，如果源型別和目標型別分別採用了 **蛇形命名法** 和 **駝峰命名法**，那麼就需要指定命名規則，使其能正確對映。
```csharp
public class Foo
{
public int Id { get; set; }
public string MyName { get; set; }
}
public class FooDto
{
public int ID { get; set; }
public string My_Name { get; set; }
}
public void Map()
{
var config = new MapperConfiguration(cfg =>
{
cfg.CreateMap();
cfg.SourceMemberNamingConvention = new PascalCaseNamingConvention();
cfg.DestinationMemberNamingConvention = new LowerUnderscoreNamingConvention();
});
var mapper = config.CreateMapper();
Foo foo = new Foo { Id = 2, MyName = "Tom" };
FooDto dto = mapper.Map(foo);
}
```
#### 3.2 配置可見性
預設情況下，AutoMapper 僅對映 `public` 成員，但其實它是可以對映到 `private` 屬性的。
```csharp
var config = new MapperConfiguration(cfg =>
{
cfg.ShouldMapProperty = p => p.GetMethod.IsPublic || p.SetMethod.IsPrivate;
cfg.CreateMap();
});
```
需要注意的是，這裡屬性必須新增 `private set`，省略 `set` 是不行的。
#### 3.3 全域性屬性/欄位過濾
預設情況下，AutoMapper 嘗試對映每個公共屬性/欄位。以下配置將忽略欄位對映。
```csharp
var config = new MapperConfiguration(cfg =>
{
cfg.ShouldMapField = fi => false;
});
```
#### 3.4 識別字首和字尾
```csharp
var config = new MapperConfiguration(cfg =>
{
cfg.RecognizePrefixes("My");
cfg.RecognizePostfixes("My");
}
```
#### 3.5 替換字元
```csharp
var config = new MapperConfiguration(cfg =>
{
cfg.ReplaceMemberName("Ä", "A");
});
```
這功能我們基本上用不上。
### 4 呼叫建構函式
有些類，屬性的 `set` 方法是私有的。
```csharp
public class Commodity
{
public string Name { get; set; }
public int Price { get; set; }
}
public class CommodityDto
{
public string Name { get; }
public int Price { get; }
public CommodityDto(string name, int price)
{
Name = name;
Price = price * 2;
}
}
```
AutoMapper 會自動找到相應的建構函式呼叫。如果在建構函式中對引數做一些改變的話，其改變會反應在對映結果中。如上例，對映後 `Price` 會乘 2。
禁用建構函式對映：
```csharp
var config = new MapperConfiguration(cfg => cfg.DisableConstructorMapping());
```
禁用建構函式對映的話，目標類要有一個無參建構函式。
### 5 陣列和列表對映
陣列和列表的對映比較簡單，僅需配置元素型別，定義簡單型別如下：
```csharp
public class Source
{
public int Value { get; set; }
}
public class Destination
{
public int Value { get; set; }
}
```
對映：
```csharp
var config = new MapperConfiguration(cfg =>
{
cfg.CreateMap();
});
IMapper mapper = config.CreateMapper();
var sources = new[]
{
new Source { Value = 5 },
new Source { Value = 6 },
new Source { Value = 7 }
};
IEnumerable ienumerableDest = mapper.Map>(sources);
ICollection icollectionDest = mapper.Map>(sources);
IList ilistDest = mapper.Map>(sources);
List listDest = mapper.Map>(sources);
Destination[] arrayDest = mapper.Map(sources);
```
具體來說，支援的源集合型別包括：
- IEnumerable
- IEnumerable
- ICollection
- ICollection
- IList
- IList
- List
- Arrays
> 對映到現有集合時，將首先清除目標集合。如果這不是你想要的，請檢視AutoMapper.Collection。
#### 5.1 處理空集合
對映集合屬性時，如果源值為 `null`，則 AutoMapper 會將目標欄位對映為空集合，而不是 `null`。這與 Entity Framework 和 Framework Design Guidelines 的行為一致，認為 C＃ 引用，陣列，List，Collection，Dictionary 和 IEnumerables 永遠不應該為 `null`。
#### 5.2 集合中的多型
這個官方的文件不是很好理解。我重新舉個例子。實體類如下：
```csharp
public class Employee
{
public int ID { get; set; }
public string Name { get; set; }
}
public class Employee2 : Employee
{
public string DeptName { get; set; }
}
public class EmployeeDto
{
public int ID { get; set; }
public string Name { get; set; }
}
public class EmployeeDto2 : EmployeeDto
{
public string DeptName { get; set; }
}
```
陣列對映程式碼如下：
```csharp
var config = new MapperConfiguration(cfg =>
{
cfg.CreateMap().Include();
cfg.CreateMap();
});
IMapper mapper = config.CreateMapper();
var employees = new[]
{
new Employee { ID = 1, Name = "Tom" },
new Employee2 { ID = 2, Name = "Jerry", DeptName = "R & D" }
};
var dto = mapper.Map(employees);
```
可以看到，對映後，`dto` 中兩個元素的型別，一個是 `EmployeeDto`，一個是 `EmployeeDto2`，即實現了父類對映到父類，子類對映到子類。
如果去掉 `Include` 方法，則對映後 `dto` 中兩個元素的型別均為 `EmployeeDto`。
### 6 方法到屬性對映
AutoMapper 不僅能實現屬性到屬性對映，還可以實現方法到屬性的對映，並且不需要任何配置，方法名可以和屬性名一致，也可以帶有 `Get` 字首。
例如下例的 `Employee.GetFullName()` 方法，可以對映到 `EmployeeDto.FullName` 屬性。
```csharp
public class Employee
{
public int ID { get; set; }
public string FirstName { get; set; }
public string LastName { get; set; }
public string GetFullName()
{
return $"{FirstName} {LastName}";
}
}
public class EmployeeDto
{
public int ID { get; set; }
public string FirstName { get; set; }
public string LastName { get; set; }
public string FullName { get; set; }
}
```
### 7 自定義對映
當源型別與目標型別名稱不一致時，或者需要對源資料做一些轉換時，可以用自定義對映。
```csharp
public class Employee
{
public int ID { get; set; }
public string Name { get; set; }
public DateTime JoinTime { get; set; }
}
public class EmployeeDto
{
public int EmployeeID { get; set; }
public string EmployeeName { get; set; }
public int JoinYear { get; set; }
}
```
如上例，`ID` 和 `EmployeeID` 屬性名不同，`JoinTime` 和 `JoinYear` 不僅屬性名不同，屬性型別也不同。
```csharp
var config = new MapperConfiguration(cfg =>
{
cfg.CreateMap()
.ForMember("EmployeeID", opt => opt.MapFrom(src => src.ID))
.ForMember(dest => dest.EmployeeName, opt => opt.MapFrom(src => src.Name))
.ForMember(dest => dest.JoinYear, opt => opt.MapFrom(src => src.JoinTime.Year));
});
```
### 8 扁平化對映
物件-物件對映的常見用法之一是將複雜的物件模型並將其展平為更簡單的模型。
```csharp
public class Employee
{
public int ID { get; set; }
public string Name { get; set; }
public Department Department { get; set; }
}
public class Department
{
public int ID { get; set; }
public string Name { get; set; }
}
public class EmployeeDto
{
public int ID { get; set; }
public string Name { get; set; }
public int DepartmentID { get; set; }
public string DepartmentName { get; set; }
}
```
如果目標型別上的屬性，與源型別的屬性、方法都對應不上，則 AutoMapper 會將目標成員名按駝峰法拆解成單個單詞，再進行匹配。例如上例中，`EmployeeDto.DepartmentID` 就對應到了 `Employee.Department.ID`。
#### 8.1 IncludeMembers
如果屬性命名不符合上述的規則，而是像下面這樣：
```csharp
public class Employee
{
public int ID { get; set; }
public string Name { get; set; }
public Department Department { get; set; }
}
public class Department
{
public int DepartmentID { get; set; }
public string DepartmentName { get; set; }
}
public class EmployeeDto
{
public int ID { get; set; }
public string Name { get; set; }
public int DepartmentID { get; set; }
public string DepartmentName { get; set; }
}
```
`Department` 類中的屬性名，直接跟 `EmployeeDto` 類中的屬性名一致，則可以使用 `IncludeMembers` 方法指定。
```csharp
var config = new MapperConfiguration(cfg =>
{
cfg.CreateMap().IncludeMembers(e => e.Department);
cfg.CreateMap();
});
```
### 9 巢狀對映
有時，我們可能不需要展平。看如下例子：
```csharp
public class Employee
{
public int ID { get; set; }
public string Name { get; set; }
public int Age { get; set; }
public Department Department { get; set; }
}
public class Department
{
public int ID { get; set; }
public string Name { get; set; }
public string Heads { get; set; }
}
public class EmployeeDto
{
public int ID { get; set; }
public string Name { get; set; }
public DepartmentDto Department { get; set; }
}
public class DepartmentDto
{
public int ID { get; set; }
public string Name { get; set; }
}
```
我們要將 `Employee` 對映到 `EmployeeDto`，並且將 `Department` 對映到 `DepartmentDto`。
```csharp
var config = new MapperConfiguration(cfg =>
{
cfg.CreateMap();
cfg.CreateMap();