Lycoris.AutoMapper.Extensions 8.2.1

Lycoris.AutoMapper.Extensions

AutoMapper 的便捷扩展库，提供 Fluent API 注册、全局扩展方法和实用映射工具

.NET 8  |  NuGet v8.2.1  |  MIT License

目录

• 快速开始
• 注册映射
• API 参考
  • 单一映射 ToMap
  • 集合映射 ToMapList
  • 分页映射 ToMapPageList
  • 合并映射 ToMerge / UpdateFrom
  • EF Core 投影映射 ProjectTo
  • 配置验证
• AutoMapperProfile 实用方法
• PageList<T> 类型
• 最佳实践
• 版本历史
• 开源协议

快速开始

安装

dotnet add package Lycoris.AutoMapper.Extensions

最小配置

using Lycoris.AutoMapper.Extensions;

var builder = WebApplication.CreateBuilder(args);

// 注册 AutoMapper
builder.Services.AddAutoMapperService();

var app = builder.Build();

// 启用全局扩展（必须在 app.Run() 之前调用）
app.UseAutoMapperExtensions();

app.Run();

配置映射关系

builder.Services.AddAutoMapperService(mapper =>
{
    // 单向映射
    mapper.AddMapper<SourceA, DestA>(single: true);

    // 双向映射（默认）
    mapper.AddMapper<SourceB, DestB>();

    // 带 ForMember 自定义映射
    mapper.AddMapper<UserEntity, UserDto>(single: true, configure: opt =>
    {
        opt.ForMember(d => d.FullName, o => o.MapFrom(s => $"{s.FirstName} {s.LastName}"));
        opt.ForMember(d => d.Password, o => o.Ignore());
    });

    // 注册自定义 Profile
    mapper.AddMapperProfile<CustomProfile>();
});

注册映射

方式一：Builder API（推荐）

builder.Services.AddAutoMapperService(mapper =>
{
    // 单向映射：SourceA → DestA
    mapper.AddMapper<SourceA, DestA>(single: true);

    // 双向映射：SourceB ⇄ DestB
    mapper.AddMapper<SourceB, DestB>(single: false);

    // 带 ForMember 配置
    mapper.AddMapper<UserEntity, UserDto>(single: true, configure: opt =>
    {
        opt.ForMember(d => d.FullName, o => o.MapFrom(s => $"{s.FirstName} {s.LastName}"));
    });

    // 添加自定义 Profile
    mapper.AddMapperProfile<CustomProfile>();
});

方式二：IServiceCollection 扩展

// 单向映射
builder.Services.AddMapper<SourceA, DestA>(single: true);

// 双向映射（默认）
builder.Services.AddMapper<SourceB, DestB>();

// 带 ForMember 配置
builder.Services.AddMapper<UserEntity, UserDto>(single: true, configure: opt =>
{
    opt.ForMember(d => d.FullName, o => o.MapFrom(s => $"{s.FirstName} {s.LastName}"));
});

// 添加自定义 Profile
builder.Services.AddMapperProfile<CustomProfile>();

API 参考

单一映射 ToMap

将单个对象映射为目标类型。

var dto = entity.ToMap<UserDto>();
var dto2 = entity.ToMap<UserDto>(d => d.Name = $"[VIP] {d.Name}");
var dto3 = entity.ToMap<UserEntity, UserDto>();

集合映射 ToMapList

将集合映射为目标类型列表。

var dtos = entities.ToMapList<UserDto>();
var dtos2 = entities.ToMapList<UserDto>((d, i) => d.Rank = i + 1);

分页映射 ToMapPageList

映射集合并返回分页结果 PageList<T>。

var result = entities.ToMapPageList<UserDto>(pageIndex: 1, pageSize: 10);

// 返回 PageList<UserDto>
Console.WriteLine($"第 {result.PageIndex} 页 / 共 {result.TotalPages} 页");
Console.WriteLine($"总记录: {result.TotalCount}，当前页: {result.Items.Count} 条");
Console.WriteLine($"上一页: {result.HasPrevious}，下一页: {result.HasNext}");

// 异步回调版本
var result2 = await entities.ToMapPageListAsync<UserDto>(1, 10, async d => await DoSomething(d));

合并映射 ToMerge / UpdateFrom

将源对象属性覆盖到已存在的目标对象，适用于部分更新场景。

var user = db.Users.Find(id);
var request = new UserUpdateRequest { Name = "新名字" };

// 方式一：ToMerge — 源视角
var merged = request.ToMerge(user);

// 方式二：UpdateFrom — 目标视角（更符合直觉）
var updated = user.UpdateFrom(request);

// 带回调
var result = user.UpdateFrom(request, u => u.UpdatedAt = DateTime.Now);

注意： 两个方法底层逻辑相同，均调用 IMapper.Map(source, destination)。仅 this 扩展对象不同，按代码可读性选择。

EF Core 投影映射 ProjectTo

将映射表达式翻译为 SQL，在数据库端执行，避免全表数据加载到内存。是 EF Core 场景下 ToMapList() 的最佳替代。

// 翻译为 SQL SELECT，只查询需要的列
var dtos = await dbContext.Users
    .Where(u => u.IsActive)
    .ProjectTo<UserDto>()
    .ToListAsync();

// 带运行时参数
var dtos2 = await dbContext.Users
    .ProjectTo<UserDto>(new { CurrentTime = DateTime.Now })
    .ToListAsync();

配置验证

在应用启动时验证所有映射配置是否正确。

var app = builder.Build();
app.UseAutoMapperExtensions();

// 开发环境验证，配错会抛出异常
#if DEBUG
app.Services.AssertAutoMapperConfigurationIsValid();
#endif

app.Run();

AutoMapperProfile 实用方法

继承 AutoMapperProfile（而非原生的 Profile）即可在映射配置中直接使用以下内置方法：

数据脱敏

格式转换

字符串处理

使用示例

public class UserProfile : AutoMapperProfile
{
    public UserProfile()
    {
        CreateMap<UserEntity, UserDto>()
            .ForMember(d => d.Phone,    o => o.MapFrom(s => HidePhoneNumber(s.Phone)))
            .ForMember(d => d.Email,    o => o.MapFrom(s => HideEmailDetails(s.Email, 2)))
            .ForMember(d => d.FileSize, o => o.MapFrom(s => ConvertBytesToReadableSize(s.FileSize)))
            .ForMember(d => d.CreatedAt, o => o.MapFrom(s => DateTimeToUnixTimestamp(s.CreatedAt)));
    }
}

PageList<T> 分页结果类型

ToMapPageList() 返回的标准化分页模型：

最佳实践

版本历史

开源协议

MIT License · Copyright © 2026 Lycoris