【C#】AutoMapper 使用手冊

丹楓無跡發表於2020-06-12

本文基於 AutoMapper 9.0.0

AutoMapper 是一個物件-物件對映器，可以將一個物件對映到另一個物件。

官方文件：https://docs.automapper.org/en/latest/

1 入門例子

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<Foo, FooDto>());

    var mapper = config.CreateMapper();

    Foo foo = new Foo { ID = 1, Name = "Tom" };

    FooDto dto = mapper.Map<FooDto>(foo);
}

2 註冊

在使用 Map 方法之前，首先要告訴 AutoMapper 什麼類可以對映到什麼類。

var config = new MapperConfiguration(cfg => cfg.CreateMap<Foo, FooDto>());

每個 AppDomain 只能進行一次配置。這意味著放置配置程式碼的最佳位置是在應用程式啟動中，例如 ASP.NET 應用程式的 Global.asax 檔案。

從 9.0 開始 Mapper.Initialize 方法就不可用了。

2.1 Profile

Profile 是組織對映的另一種方式。新建一個類，繼承 Profile，並在建構函式中配置對映。

public class EmployeeProfile : Profile
{
    public EmployeeProfile()
    {
        CreateMap<Employee, EmployeeDto>();
    }
}

var config = new MapperConfiguration(cfg =>
{
    cfg.AddProfile<EmployeeProfile>();
});

Profile 內部的配置僅適用於 Profile 內部的對映。應用於根配置的配置適用於所有建立的對映。

AutoMapper 也可以在指定的程式集中掃描從 Profile 繼承的類，並將其新增到配置中。

var config = new MapperConfiguration(cfg =>
{
    // 掃描當前程式集
    cfg.AddMaps(System.AppDomain.CurrentDomain.GetAssemblies());
    
    // 也可以傳程式集名稱（dll 名稱）
    cfg.AddMaps("LibCoreTest");
});

3 配置

3.1 命名約定

預設情況下，AutoMapper 基於相同的欄位名對映，並且是 不區分大小寫 的。

但有時，我們需要處理一些特殊的情況。

SourceMemberNamingConvention 表示源型別命名規則
DestinationMemberNamingConvention 表示目標型別命名規則

LowerUnderscoreNamingConvention 和 PascalCaseNamingConvention 是 AutoMapper 提供的兩個命名規則。前者命名是小寫幷包含下劃線，後者就是帕斯卡命名規則（每個單詞的首字母大寫）。

我的理解，如果源型別和目標型別分別採用了 蛇形命名法 和 駝峰命名法，那麼就需要指定命名規則，使其能正確對映。

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<Foo, FooDto>();

        cfg.SourceMemberNamingConvention = new PascalCaseNamingConvention();
        cfg.DestinationMemberNamingConvention = new LowerUnderscoreNamingConvention();
    });

    var mapper = config.CreateMapper();

    Foo foo = new Foo { Id = 2, MyName = "Tom" };

    FooDto dto = mapper.Map<FooDto>(foo);
}

3.2 配置可見性

預設情況下，AutoMapper 僅對映 public 成員，但其實它是可以對映到 private 屬性的。

var config = new MapperConfiguration(cfg =>
{
    cfg.ShouldMapProperty = p => p.GetMethod.IsPublic || p.SetMethod.IsPrivate;
    cfg.CreateMap<Source, Destination>();
});

需要注意的是，這裡屬性必須新增 private set，省略 set 是不行的。

3.3 全域性屬性/欄位過濾

預設情況下，AutoMapper 嘗試對映每個公共屬性/欄位。以下配置將忽略欄位對映。

var config = new MapperConfiguration(cfg =>
{
	cfg.ShouldMapField = fi => false;
});

3.4 識別字首和字尾

var config = new MapperConfiguration(cfg =>
{
    cfg.RecognizePrefixes("My");
    cfg.RecognizePostfixes("My");
}

3.5 替換字元

var config = new MapperConfiguration(cfg =>
{
    cfg.ReplaceMemberName("Ä", "A");
});

這功能我們基本上用不上。

4 呼叫建構函式

有些類，屬性的 set 方法是私有的。

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。

禁用建構函式對映：

var config = new MapperConfiguration(cfg => cfg.DisableConstructorMapping());

禁用建構函式對映的話，目標類要有一個無參建構函式。

5 陣列和列表對映

陣列和列表的對映比較簡單，僅需配置元素型別，定義簡單型別如下：

public class Source
{
    public int Value { get; set; }
}

public class Destination
{
    public int Value { get; set; }
}

對映：

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

var sources = new[]
{
    new Source { Value = 5 },
    new Source { Value = 6 },
    new Source { Value = 7 }
};

IEnumerable<Destination> ienumerableDest = mapper.Map<Source[], IEnumerable<Destination>>(sources);
ICollection<Destination> icollectionDest = mapper.Map<Source[], ICollection<Destination>>(sources);
IList<Destination> ilistDest = mapper.Map<Source[], IList<Destination>>(sources);
List<Destination> listDest = mapper.Map<Source[], List<Destination>>(sources);
Destination[] arrayDest = mapper.Map<Source[], Destination[]>(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 集合中的多型

這個官方的文件不是很好理解。我重新舉個例子。實體類如下：

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; }
}

陣列對映程式碼如下：

var config = new MapperConfiguration(cfg =>
{
    cfg.CreateMap<Employee, EmployeeDto>().Include<Employee2, EmployeeDto2>();
    cfg.CreateMap<Employee2, EmployeeDto2>();
});
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<Employee[], EmployeeDto[]>(employees);

可以看到，對映後，dto 中兩個元素的型別，一個是 EmployeeDto，一個是 EmployeeDto2，即實現了父類對映到父類，子類對映到子類。

如果去掉 Include 方法，則對映後 dto 中兩個元素的型別均為 EmployeeDto。

6 方法到屬性對映

AutoMapper 不僅能實現屬性到屬性對映，還可以實現方法到屬性的對映，並且不需要任何配置，方法名可以和屬性名一致，也可以帶有 Get 字首。

例如下例的 Employee.GetFullName() 方法，可以對映到 EmployeeDto.FullName 屬性。

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 自定義對映

當源型別與目標型別名稱不一致時，或者需要對源資料做一些轉換時，可以用自定義對映。

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 不僅屬性名不同，屬性型別也不同。

var config = new MapperConfiguration(cfg =>
{
    cfg.CreateMap<Employee, EmployeeDto>()
        .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 扁平化對映

物件-物件對映的常見用法之一是將複雜的物件模型並將其展平為更簡單的模型。

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

如果屬性命名不符合上述的規則，而是像下面這樣：

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 方法指定。

var config = new MapperConfiguration(cfg =>
{
    cfg.CreateMap<Employee, EmployeeDto>().IncludeMembers(e => e.Department);
    cfg.CreateMap<Department, EmployeeDto>();
});

9 巢狀對映

有時，我們可能不需要展平。看如下例子：

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。

var config = new MapperConfiguration(cfg =>
{
    cfg.CreateMap<Employee, EmployeeDto>();
    cfg.CreateMap<Department, DepartmentDto>();
});

AutoMapper使用手冊(一)
2015-02-14
APP
【C#】CsvHelper 使用手冊
2020-05-20
C#
Linux使用手冊-vi使用手冊
2014-11-27
Linux
TcpDump使用手冊
2020-08-19
TCP
MyBatis 使用手冊
2020-11-21
MyBatis
sqlmap使用手冊
2022-03-04
SQL
Mybatis應用手冊
2023-03-26
MyBatis
Tmux使用手冊
2017-10-10
UX
Docker使用手冊
2017-12-13
Docker
Promise使用手冊
2017-04-19
Promise
Redis使用手冊
2014-08-18
Redis
iptables 使用手冊
2010-12-02
DotProject 使用手冊
2011-11-08
Project
git 基本使用手冊
2020-07-06
Git
Cobra框架使用手冊
2021-07-07
框架
Memcached Client 使用手冊
2013-10-29
client
jQuery使用手冊（收藏）
2007-04-19
jQuery
儀器使用手冊
2024-03-22
PerfDog WEB端使用手冊
2020-08-04
Web
Room Database完全使用手冊
2019-01-18
OOMDatabase
MongoDB和pymongo自用手冊
2018-09-14
MongoDB
Git 快速使用手冊（二）
2020-12-08
Git
less語法實用手冊
2017-11-23
Linux iptables應用手冊
2008-06-23
Linux
gcc使用手冊(2)(轉)
2007-08-11
GC
gcc使用手冊(3)(轉)
2007-08-11
GC
gcc使用手冊(4)(轉)
2007-08-11
GC
《Redis 使用手冊》- 字串（PHP 版本）
2019-12-24
Redis字串PHP
MySQL DBA 常用手冊小結
2021-09-09
MySql
ThreadLocal 使用手冊 | 按需收藏
2023-01-12
thread
Linux parallel 命令使用手冊
2023-04-10
LinuxParallel
BeautifulSoup使用手冊（查詢篇）
2020-10-03
Kotlin 協程使用手冊
2018-02-24
Kotlin
Gerrit和Jenkins使用手冊
2018-04-24
Jenkins
MySQL DBA常用手冊小結
2016-04-18
MySql
WebApiThrottle限流框架使用手冊
2015-07-21
WebAPI框架
Rational ClearQuest 安裝、配置、使用手冊
2020-04-05
mysql常用命令使用手冊
2021-09-09
MySql