Ánh xạ đối tượng là công việc ít rủi ro nhất trong một API — cho đến khi nó trở thành nguồn lỗi khó thấy nhất. Một property bị bỏ sót, một `null` bị biến thành chuỗi rỗng, một navigation property bị map vòng: tất cả đều biên dịch được, test đơn giản vẫn xanh, và chỉ lộ ra khi dữ liệu thật chạy qua.
Bài này so sánh ba cách ánh xạ trong .NET 2026: viết tay, AutoMapper 16, và Mapperly 4 (bài riêng). Điểm mới quan trọng nhất không phải kỹ thuật — mà là giấy phép: AutoMapper từ v15 không còn miễn phí cho mọi mục đích thương mại. Điều đó thay đổi bài toán chọn công cụ.
Mục lục
Cập nhật 2026: AutoMapper không còn là lựa chọn “mặc định miễn phí”
- AutoMapper 16.3.0 vẫn là thư viện mạnh nhất về tính năng, nhưng từ v15 chuyển sang giấy phép RPL-1.5 hoặc giấy phép thương mại của Lucky Penny Software. Nếu sản phẩm của bạn là phần mềm đóng mã nguồn, bạn cần mua giấy phép hoặc đổi công cụ.
- Mapperly 4.3.1 là source generator, Apache-2.0, không dùng reflection, sinh code lúc build. Đây là lựa chọn thay thế hợp lý nhất cho AutoMapper trong dự án mới.
- Ánh xạ thủ công không “cũ”. Với DTO nhỏ, một hàm 10 dòng rõ ràng hơn một cấu hình mapping ẩn, và không có chi phí giấy phép.
1. Ánh xạ thủ công: rõ ràng là một tính năng
// File: Orders/OrderDto.cs
public sealed record OrderDto(int Id, string Code, string Status, decimal Total, string CustomerName);
// File: Orders/OrderMapping.cs
public static class OrderMapping
{
public static OrderDto ToDto(this Order order) => new(
order.Id,
order.Code,
order.Status,
order.Total,
order.Customer.Name);
public static Order ToEntity(this CreateOrderRequest request) => new()
{
Code = request.Code.Trim(),
Status = OrderStatus.Pending,
Total = request.Total
};
}
Ba lợi ích thực tế:
- Compiler bắt lỗi ngay. Thêm property vào DTO mà không cập nhật hàm map sẽ fail build, không cần test riêng cho mapping.
- Không có reflection. An toàn với Native AOT/trimming, không có chi phí khởi tạo cấu hình.
- Kiểm soát tuyệt đối. Bạn quyết định field nào được map, field nào bị bỏ, giá trị mặc định là gì.
Nhược điểm: với 40 DTO và quan hệ lồng nhau, viết tay trở nên nhàm chán và dễ sai. Đó là lúc Mapperly hoặc AutoMapper có chỗ đứng.
2. AutoMapper 16: mạnh, nhưng cần kỷ luật
Cài đặt:
dotnet add package AutoMapper --version 16.3.0
Profile cho một DTO:
// File: Mapping/OrderProfile.cs
using AutoMapper;
public sealed class OrderProfile : Profile
{
public OrderProfile()
{
CreateMap<Order, OrderDto>()
.ForMember(d => d.CustomerName, o => o.MapFrom(s => s.Customer.Name));
}
}
// File: Program.cs
builder.Services.AddAutoMapper(
cfg => cfg.AddProfile<OrderProfile>(),
typeof(Program).Assembly);
Với EF Core, dùng ProjectTo thay vì Map để đẩy phép chiếu xuống SQL:
// File: Orders/OrderService.cs
public async Task<List<OrderDto>> ListAsync(CancellationToken ct)
{
return await _db.Orders
.AsNoTracking()
.ProjectTo<OrderDto>(_mapper.ConfigurationProvider)
.ToListAsync(ct);
}
Map load toàn bộ entity rồi mới map trong bộ nhớ; ProjectTo sinh SELECT chỉ các cột cần. Nếu bạn đang map sau khi ToListAsync, bạn đang trả giá cả hai lần.
3. Những cạm bẫy của AutoMapper
- Thuộc tính đích không được map mà không ai biết. AutoMapper không ném lỗi mặc định; property đích chỉ nhận giá trị mặc định. Hãy gọi
AssertConfigurationIsValid()trong test khởi động để biến lỗi cấu hình thành lỗi build/test. ReverseMap()che giấu khác biệt. Nó tạo map ngược với cùng cấu hình, kể cả những field không nên ghi ngược (Id, audit, trạng thái). Với request → entity, hãy viết map riêng và whitelist field.MapFromkhông dịch được sang SQL. Nếu biểu thức gọi hàm C# (ví dụstring.Format),ProjectTosẽ fallback hoặc lỗi. Giữ biểu thức đơn giản, hoặc map sau khi query.AfterMapchạy trong bộ nhớ. Nó không được dịch sang SQL và có thể gây side effect ngoài ý muốn. Dùng cho normalization đơn giản, không dùng để gọi service.- Vòng tham chiếu. Map entity có navigation hai chiều mà không cấu hình
PreserveReferences/MaxDepthcó thể gây đệ quy hoặc payload phình to. - AOT/trimming. AutoMapper dựa trên reflection; không phải lựa chọn an toàn cho Native AOT nếu không cấu hình cẩn thận. Mapperly sinh code nên phù hợp hơn.
- Overposting. Map thẳng request DTO vào entity cho phép client đặt field ngoài ý muốn (Id, OwnerId, Status). Luôn whitelist.
4. Khi nào chọn gì?
| Bối cảnh | Lựa chọn | Lý do |
|---|---|---|
| Ít DTO, domain đơn giản | Ánh xạ thủ công | Rõ ràng, không phụ thuộc, compiler kiểm tra |
| Nhiều DTO, cần compile-time safety | Mapperly | Sinh code, lỗi build, AOT-friendly, Apache-2.0 |
| Đội đã dùng AutoMapper, có giấy phép | AutoMapper | Tính năng phong phú, quen thuộc |
| Sản phẩm thương mại đóng mã nguồn | Mapperly hoặc thủ công | Tránh chi phí giấy phép RPL/commercial |
| Cần projection phức tạp sang EF Core | AutoMapper ProjectTo hoặc Select thủ công |
Kiểm soát SQL, tránh N+1 |
Lời khuyên thẳng: nếu bạn đang bắt đầu dự án mới trong 2026, đừng mặc định chọn AutoMapper chỉ vì “ai cũng dùng”. Hãy bắt đầu bằng ánh xạ thủ công; khi số lượng map vượt ngưỡng chịu đựng, chuyển sang Mapperly. Chỉ chọn AutoMapper khi bạn đã có giấy phép hoặc dự án mã nguồn mở tương thích RPL.
5. Giấy phép: con số cần biết trước khi chọn
Đây là phần dễ bị bỏ qua nhất khi so sánh công cụ. AutoMapper 15+ và MediatR 13+ nằm dưới giấy phép Reciprocal Public License 1.5 (RPL-1.5) hoặc giấy phép thương mại của Lucky Penny Software. RPL là giấy phép “copyleft có điều kiện”: nếu bạn phân phối phần mềm dùng thư viện này, bạn phải cân nhắc nghĩa vụ mở mã nguồn theo RPL — hoặc mua giấy phép thương mại để tránh nghĩa vụ đó.
Hệ quả thực tế:
- Sản phẩm SaaS nội bộ, không phân phối binary: thường dễ thở hơn, nhưng vẫn phải đọc điều khoản; đừng giả định “dùng nội bộ là miễn phí”.
- Sản phẩm bán ra, đóng gói on-premise: gần như chắc chắn cần giấy phép thương mại hoặc thay thế.
- Dự án mã nguồn mở tương thích RPL: có thể dùng miễn phí nếu đáp ứng nghĩa vụ.
- Thư viện nội bộ dùng chung: cần kiểm tra cả trường hợp phân phối nội bộ và phân phối cho khách hàng.
Đừng để việc chọn mapping library trở thành vấn đề pháp lý sau khi sản phẩm đã lên production. Nếu chưa chắc, hãy chọn Mapperly (Apache-2.0) hoặc viết tay — cả hai đều không có ràng buộc này.
6. Mapping trong CQRS và vertical slice
Trong kiến trúc CQRS/vertical slice, mapping thường xuất hiện ở ba chỗ: command → entity, entity → read model, read model → response DTO. Nếu dùng AutoMapper cho cả ba, bạn có nguy cơ một cấu hình mapping phục vụ nhiều mục đích khác nhau và không ai biết field nào thực sự được ghi.
Cách làm sạch hơn:
- Command → entity: viết tay. Đây là nơi bảo mật quan trọng nhất; whitelist field, không dùng
ReverseMap. - Entity → read model: có thể dùng Mapperly hoặc
Selecttrong EF Core. Projection xuống SQL là ưu tiên. - Read model → response: ánh xạ thủ công hoặc Mapperly; thường ít field, không đáng dùng reflection.
Nếu bạn dùng MediatR, đừng để handler vừa map vừa xử lý nghiệp vụ vừa gọi DB. Tách mapper ra khỏi handler giúp test nhanh hơn và tránh cấu hình mapping bị rải rác trong code.
7. Di cư từ AutoMapper sang Mapperly
Không cần chuyển toàn bộ trong một ngày. Một lộ trình thực dụng:
- Đo phạm vi: liệt kê các profile và map đang dùng; xác định map nào chỉ để đọc (projection) và map nào ghi dữ liệu.
- Bắt đầu với read path: thay
ProjectTobằngSelectthủ công hoặc MapperlyProjectToDto. Đây là nơi dễ thấy lợi ích về SQL và hiệu năng. - Chuyển map đơn giản: DTO phẳng, ít field — Mapperly xử lý tốt và compiler bắt lỗi ngay.
- Giữ AutoMapper cho map phức tạp nếu bạn còn giấy phép; đừng cố thay thế mọi thứ cùng lúc.
- Khóa hành vi bằng test: viết test mapping trước khi đổi công cụ, để chắc kết quả không đổi.
Điểm cần kiểm tra khi chuyển: xử lý null, enum, collection, nested object, và các quy tắc đặt tên property. Mapperly báo lỗi compile nếu thiếu map; AutoMapper im lặng — đó là lợi thế lớn nhất khi di cư.
8. Mapping và bảo mật
Mapping là ranh giới giữa dữ liệu không tin cậy (request) và dữ liệu tin cậy (entity). Ba quy tắc:
- Không map request → entity trực tiếp. Client có thể gửi
id,ownerId,status,createdAt. Hãy tạo entity mới với field whitelist. - Không trả entity → response trực tiếp. Navigation property có thể lộ dữ liệu của tenant khác hoặc field nội bộ.
- Kiểm tra quyền trước khi map, không sau. Nếu bạn map xong rồi mới kiểm tra, dữ liệu nhạy cảm đã nằm trong bộ nhớ và có thể bị log.
Với AutoMapper, ForMember và Condition có thể giúp lọc field, nhưng đừng biến cấu hình mapping thành nơi thực thi phân quyền. Phân quyền thuộc về service/handler, không thuộc mapper.
9. Kiểm thử mapping
Mapping là logic, nên cần test — nhưng test đúng cách:
- Test hành vi, không test từng property. Tạo entity mẫu, map, assert các field quan trọng và trường hợp null.
- Với AutoMapper, thêm test
AssertConfigurationIsValid()cho toàn bộ profile. Đây là test rẻ nhất bắt được lỗi cấu hình. - Với EF Core, test
ProjectTotrên SQLite/Testcontainers để chắc biểu thức dịch được; unit test in-memory không phát hiện lỗi translation. - Không snapshot toàn bộ object nếu DTO thay đổi thường xuyên; test sẽ giòn và không chỉ ra lỗi thật.
Checklist
- Đã quyết định công cụ dựa trên giấy phép, không chỉ tính năng.
- Không map entity ↔ DTO hai chiều bằng
ReverseMapcho request ghi. ProjectTo/Selectđược dùng cho read path; không map sauToList.- Có test cấu hình mapping và test translation với database thật.
- Field nhạy cảm (Id, OwnerId, Status, audit) không nằm trong map từ request.
- Nếu dùng AOT/trimming, đã kiểm tra reflection hoặc chọn Mapperly.
Bài tiếp theo trong series: Mapperly — ánh xạ bằng source generator để thấy cách thay thế AutoMapper mà vẫn giữ compile-time safety. Nếu bạn cần hiểu vì sao projection quan trọng, đọc lại bài loading strategies trong EF Core. Và nếu đang cân nhắc MediatR cho CQRS, hãy đọc bài MediatR — nó cũng chịu thay đổi giấy phép tương tự.



