Bắt Đầu Với Mapperly Trong Dự Án ASP.NET Core: Ánh Xạ Đối Tượng Hiệu Quả Với Source Generator (Lộ Trình .NET)

Mapperly không phải “AutoMapper nhưng nhanh hơn”. Nó là một source generator: bạn khai báo chữ ký hàm ánh xạ, trình biên dịch sinh ra thân hàm bằng C# thường, và mọi sai lệch giữa entity với DTO trở thành lỗi build thay vì lỗi runtime trên production. Bài này đi từ cài đặt, các attribute cần biết, projection cho EF Core, đến việc chuyển từ AutoMapper và những lúc ánh xạ thủ công vẫn là lựa chọn đúng.

Cập nhật 2026: ba thay đổi làm Mapperly thành lựa chọn mặc định

  • Mapperly 4.3.1 (Apache-2.0) là bản ổn định hiện tại. Thư viện chỉ gồm generator và một assembly attribute nhỏ, không có reflection lúc chạy.
  • AutoMapper 16.3.0 đã chuyển sang giấy phép RPL-1.5 hoặc giấy phép thương mại từ v15. Với phần mềm đóng mã nguồn, chi phí giấy phép là một biến số thật trong quyết định kỹ thuật, không còn là chi tiết pháp lý.
  • .NET 10 LTS và C# 14 hỗ trợ partial method có accessibility và kiểu trả về non-void từ C# 9, nên mapper dạng partial class là kiểu khai báo chuẩn; không cần interface để “dễ mock”.
  • Native AOT và trimming là yêu cầu thường gặp ở API .NET 10, và code sinh lúc build tương thích với cả hai — điều AutoMapper phải xử lý bằng cấu hình reflection.

Mapperly hoạt động như thế nào

Luồng chạy gồm bốn bước, tất cả diễn ra trong lúc build:

  1. Bạn thêm package Riok.Mapperly vào project. Package đóng vai trò analyzer/source generator.
  2. Bạn khai báo một partial class gắn [Mapper] và các partial method chỉ có chữ ký, không có thân hàm.
  3. Generator phân tích kiểu nguồn và kiểu đích, đối chiếu tên và kiểu của từng member, rồi sinh phần thân còn thiếu vào một file .g.cs.
  4. Nếu không ánh xạ được một member bắt buộc, compiler phát diagnostic (RMG012, RMG020, …) và build fail hoặc cảnh báo tùy mức độ.

Hệ quả thực tế: chi phí khởi tạo bằng 0, không có MapperConfiguration để validate lúc startup, không có ProjectTo dựa trên biểu thức reflection, và stack trace khi lỗi trỏ đúng vào dòng gán property trong file sinh ra. Bạn có thể đọc code sinh ra — nên đọc, ít nhất một lần.

Cài đặt và mapper đầu tiên

dotnet add package Riok.Mapperly --version 4.3.1
// File: Features/Users/UserEntity.cs
public sealed class UserEntity
{
    public Guid Id { get; set; }
    public string FirstName { get; set; } = "";
    public string LastName { get; set; } = "";
    public string Email { get; set; } = "";
    public DateTime DateOfBirth { get; set; }
    public bool IsActive { get; set; }
    public string? InternalNotes { get; set; }
}

// File: Features/Users/UserDto.cs
public sealed record UserDto(
    Guid Id,
    string GivenName,
    string FamilyName,
    string EmailAddress,
    int Age,
    bool IsActive);

Mapper cho hai kiểu trên. Chú ý: class là partial, method cũng là partial và không có thân hàm.

// File: Features/Users/UserMapper.cs
using Riok.Mapperly.Abstractions;

[Mapper(RequiredMappingStrategy = RequiredMappingStrategy.Target)]
public partial class UserMapper
{
    [MapProperty(nameof(UserEntity.FirstName), nameof(UserDto.GivenName))]
    [MapProperty(nameof(UserEntity.LastName), nameof(UserDto.FamilyName))]
    [MapProperty(nameof(UserEntity.Email), nameof(UserDto.EmailAddress))]
    [MapProperty(nameof(UserEntity.DateOfBirth), nameof(UserDto.Age), Use = nameof(ToAge))]
    [MapperIgnoreSource(nameof(UserEntity.InternalNotes))]
    public partial UserDto ToDto(UserEntity entity);

    private static int ToAge(DateTime dateOfBirth)
    {
        var today = DateOnly.FromDateTime(DateTime.UtcNow);
        var birth = DateOnly.FromDateTime(dateOfBirth);
        var age = today.Year - birth.Year;
        return birth.AddYears(age) > today ? age - 1 : age;
    }
}

Sau khi build, generator sinh ra phần thân tương đương đoạn dưới (đã rút gọn phần kiểm tra null và comment của generator):

// obj/Debug/net10.0/generated/Riok.Mapperly/.../UserMapper.g.cs (rút gọn)
public partial class UserMapper
{
    public partial UserDto ToDto(UserEntity entity)
    {
        return new UserDto(
            entity.Id,
            entity.FirstName,
            entity.LastName,
            entity.Email,
            ToAge(entity.DateOfBirth),
            entity.IsActive);
    }
}

Không có gì huyền bí: đó là code bạn sẽ viết tay, chỉ là viết một lần và luôn đồng bộ với kiểu dữ liệu. Để xem file sinh ra trong solution, thêm hai property vào .csproj:

<PropertyGroup>
  <EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles>
  <CompilerGeneratedFilesOutputPath>$(BaseIntermediateOutputPath)Generated</CompilerGeneratedFilesOutputPath>
</PropertyGroup>

Thư mục obj/Generated sau đó chứa toàn bộ mã Mapperly sinh cho project — hữu ích khi bạn nghi ngờ một property bị bỏ qua.

Tùy chỉnh: đổi tên, bỏ qua, và logic riêng

Ba attribute làm được 90% công việc thực tế:

  • [MapProperty(source, target)] — nối hai member khác tên hoặc khác đường dẫn. Tham số Use chỉ định một method chuyển đổi cho riêng member đó.
  • [MapPropertyFromSource(target, Use = ...)] — target được tính từ cả object nguồn, không phải từ một property. Dùng cho FullName, URL tuyệt đối, hoặc cờ tổng hợp.
  • [MapperIgnoreSource] / [MapperIgnoreTarget] — loại member khỏi hợp đồng ánh xạ. Đây là cách duy nhất để “im lặng” một cảnh báo một cách có chủ ý.
// File: Features/Users/UserSummaryMapper.cs
using Riok.Mapperly.Abstractions;

[Mapper]
public partial class UserSummaryMapper
{
    [MapPropertyFromSource(nameof(UserSummary.FullName), Use = nameof(BuildFullName))]
    [MapPropertyFromSource(nameof(UserSummary.Initials), Use = nameof(BuildInitials))]
    public partial UserSummary ToSummary(UserEntity entity);

    private static string BuildFullName(UserEntity e) => $"{e.FirstName} {e.LastName}".Trim();

    private static string BuildInitials(UserEntity e) =>
        string.Concat(e.FirstName.AsSpan(0, 1), e.LastName.AsSpan(0, 1)).ToUpperInvariant();
}

Đừng dùng custom method để “vá” dữ liệu. Nếu ToAge phụ thuộc DateTime.UtcNow, kết quả test sẽ phụ thuộc thời điểm chạy và projection EF Core sẽ không dịch được. Logic phụ thuộc thời gian hoặc dữ liệu ngoài nên nằm ở tầng service, còn mapper chỉ nên là hàm thuần của input.

Object lồng nhau, collection, enum, null

Mapperly xử lý các trường hợp này theo cùng một nguyên tắc: nếu tồn tại một ánh xạ hợp lệ giữa hai kiểu, nó sinh lời gọi tới ánh xạ đó; nếu không, nó báo lỗi thay vì đoán.

  • Lồng nhau: Order.Customer kiểu CustomerEntity sang CustomerDto sẽ dùng một partial method ToDto(CustomerEntity) trong cùng mapper, hoặc sinh ánh xạ inline nếu bạn không khai báo. Khai báo tường minh giúp tái sử dụng và dễ debug hơn.
  • Collection: List<OrderLine> sang IReadOnlyList<OrderLineDto> được sinh thành vòng lặp hoặc Select; kiểu đích phổ biến (T[], List<T>, IEnumerable<T>, IReadOnlyList<T>) đều được hỗ trợ. Với Dictionary<TKey, TValue>, bạn nên khai báo rõ ràng vì khoá và giá trị đều cần ánh xạ.
  • Enum: mặc định theo giá trị số, có thể đổi sang theo tên bằng [MapEnum(EnumMappingStrategy.ByName)]. Theo tên an toàn hơn khi hai phía không kiểm soát thứ tự giá trị; theo giá trị nhanh hơn nhưng vỡ ngay khi ai đó chèn một thành viên vào giữa.
  • Null: nullable annotation là hợp đồng. Nếu nguồn là string? và đích là string, đừng để generator tự quyết: viết một method string? -> string rõ ràng (trả chuỗi rỗng hay ném lỗi là quyết định nghiệp vụ), rồi dùng Use để gắn vào member đó.

ProjectToDto: ánh xạ xuống SQL với EF Core

Đây là phần quan trọng nhất với API đọc nhiều. Mapperly sinh biểu thức LINQ Select thay vì gọi hàm sau khi đã tải dữ liệu, nên EF Core 10 dịch được xuống SQL và chỉ trả về các cột cần thiết.

// File: Features/Cars/CarMapper.cs
using Riok.Mapperly.Abstractions;

[Mapper]
public static partial class CarMapper
{
    public static partial IQueryable<CarDto> ProjectToDto(this IQueryable<Car> q);

    public static partial CarDto ToDto(this Car car);
}

Chữ ký trên là hợp đồng với generator: tham số là IQueryable<Car>, kiểu trả về là IQueryable<CarDto>. Dùng trong service:

// File: Features/Cars/CarService.cs
public sealed class CarService(AppDbContext db)
{
    public Task<List<CarDto>> ListAsync(CancellationToken ct) =>
        db.Cars
          .AsNoTracking()
          .Where(c => c.IsActive)
          .OrderBy(c => c.Model)
          .ProjectToDto()
          .ToListAsync(ct);
}

Code sinh ra có dạng .Select(c => new CarDto { ... }) với các member được gán trực tiếp. Ba giới hạn bạn phải biết trước khi thiết kế DTO:

  • Chỉ áp dụng cho IQueryable. Trên IEnumerable đã tải vào bộ nhớ, dùng ToDto thường; nếu gọi projection sau ToListAsync thì bạn đã mất lợi ích và có thể nhận lỗi build.
  • Không phải mọi tính năng mapper đều dịch được. Các hook sau khi map, custom method có thân hàm, và logic phụ thuộc thời gian không thể biểu diễn trong expression tree. Mapperly báo diagnostic lúc build thay vì để EF Core ném lỗi lúc chạy — đó là điểm cộng, nhưng bạn phải thiết kế DTO theo hướng “tính được bằng cột trong bảng”.
  • Không có include ngầm. Navigation property vẫn cần Include hoặc Select tường minh ở tầng truy vấn; projection không tự thêm Include và cũng không nên.

Lỗi biên dịch: đọc diagnostic thay vì đoán

Hai diagnostic gặp nhiều nhất:

Mã Ý nghĩa Cách xử lý
RMG012 Member của target không có nguồn tương ứng Thêm nguồn (đổi tên, MapPropertyFromSource), hoặc MapperIgnoreTarget nếu target cố ý để trống
RMG020 Member của source không được map đi đâu MapperIgnoreSource, hoặc nới RequiredMappingStrategy xuống Target

RequiredMappingStrategy là công tắc chính sách: Source bắt mọi member nguồn phải có đích, Target bắt mọi member đích phải có nguồn, Both bắt cả hai. Với DTO chỉ lấy một phần entity, Target là mức hợp lý — bạn vẫn được bảo vệ khỏi DTO thiếu field, nhưng không phải liệt kê từng cột nội bộ của bảng. Với DTO dùng để ghi dữ liệu, hãy dùng Both.

Đăng ký DI và vòng đời

Mapper sinh ra là stateless nếu bạn không thêm state vào partial class. Do đó Singleton là lựa chọn đúng và rẻ nhất:

// File: Program.cs
builder.Services.AddSingleton<UserMapper>();
builder.Services.AddSingleton<CarMapper>();

Inject trực tiếp class cụ thể, không cần interface. Nếu bạn thật sự cần mock mapper trong unit test, hãy mock ở tầng service hoặc dùng DTO đầu vào — mock một mapper vô nghĩa vì mapper chỉ là hàm thuần. Đây là chỗ nhiều dự án giữ thói quen từ AutoMapper và tạo ra một interface chỉ để thỏa mãn DI.

Chuyển từ AutoMapper: bảng đối chiếu

AutoMapper Mapperly
CreateMap<A, B>() trong Profile Partial method B ToDto(A) trong [Mapper] class
.ForMember(d => d.X, o => o.MapFrom(s => s.Y)) [MapProperty(nameof(A.Y), nameof(B.X))]
.ForMember(..., o => o.Ignore()) [MapperIgnoreTarget(nameof(B.X))]
AssertConfigurationIsValid() lúc startup Diagnostic lúc build, không cần kiểm tra runtime
ProjectTo<T>() ProjectToDto(this IQueryable<T>)

Chiến lược migration thực dụng: chuyển từng profile một, giữ AutoMapper cho phần chưa chuyển, và xóa dần. Đừng chuyển cơ học — mỗi profile cũ là cơ hội xóa những ánh xạ không ai dùng. Lưu ý AutoMapper 16 đăng ký bằng AddAutoMapper(cfg => ..., assembly), không còn AddAutoMapper(assembly); nếu bạn đang nâng cấp cùng lúc, hãy đọc changelog trước khi sửa.

Khi nào ánh xạ thủ công vẫn thắng

  • DTO 3–5 field, một chiều. Một hàm extension 6 dòng rõ hơn một mapper class, một attribute và một file sinh ra.
  • Ánh xạ là logic nghiệp vụ. Nếu việc tính giá, áp thuế, chuẩn hóa đơn vị nằm trong phép biến đổi, đó là domain logic, không phải mapping — đặt ở service và test trực tiếp.
  • Bạn cần kiểm soát thứ tự và side effect. Generator gán property theo thứ tự sinh; nếu thứ tự quan trọng (hiếm nhưng có, ví dụ khởi tạo phụ thuộc), viết tay.

Ngược lại, dùng Mapperly khi: số DTO nhiều và thay đổi thường xuyên, có object lồng nhau hoặc collection, cần projection EF Core, hoặc dự án publish Native AOT.

2027: generator là hướng đi, không phải mốt

.NET 11 ở giai đoạn RC và vẫn giữ nguyên mô hình source generator; không có thay đổi nào khiến Mapperly phải đổi cách khai báo. Điều đang thay đổi là công cụ: các trình soạn thảo và AI assistant ngày càng đọc được mã sinh ra, nên chi phí bảo trì của generator tiếp tục giảm. Với đội đang trả phí cho AutoMapper, migration sang Mapperly là việc của một sprint, không phải một quý.

Checklist

  • Pin Riok.Mapperly 4.3.1 và bật EmitCompilerGeneratedFiles để đọc code sinh ra khi cần.
  • Khai báo partial class + [Mapper], đặt RequiredMappingStrategy theo hướng: DTO đọc dùng Target, DTO ghi dùng Both.
  • Xử lý null bằng method tường minh, không dựa vào hành vi ngầm của generator.
  • Dùng ProjectToDto cho mọi truy vấn đọc danh sách; giữ logic thời gian ở tầng service.
  • Đăng ký mapper là singleton và inject class cụ thể, bỏ interface chỉ để mock.

Đọc tiếp trong series