AutoMapper → Mapperly trong ASP.NET MVC

AutoMapper → Mapperly trong ASP.NET MVC - Part 1

Đây là phần 1 trong series modernize ASP.NET MVC 5 trên .NET Framework 4.8.

Series này gồm 2 phần:

Part 1: migrate sang SDK-style .csproj
Part 2: tích hợp compile-time mapping (Mapperly)

Nếu nền móng project chưa ổn, việc tối ưu phía trên (mapping, performance, architecture) sẽ rất khó maintain về lâu dài.

Vì vậy, bài này chỉ tập trung vào một việc duy nhất: chuyển project MVC 5 sang SDK-style và chạy ổn định với IIS Express.

1. Vấn đề của project legacy

Hầu hết project ASP.NET MVC 5 lâu năm đều có đặc điểm chung:

.csproj dạng cũ (old-style)
Khai báo file thủ công
Sử dụng packages.config

Những vấn đề thường gặp:

File .csproj dài hàng trăm dòng, khó đọc
Thêm/xóa file → phải sửa project file
Merge conflict xảy ra thường xuyên

Project vẫn chạy — nhưng càng ngày càng khó maintain.

2. SDK-style giải quyết điều gì?

SDK-style .csproj mang lại cách tiếp cận đơn giản hơn:

Tự động include toàn bộ *.cs
Không cần khai báo từng file
Hỗ trợ PackageReference hiện đại
File .csproj gọn hơn rất nhiều

Hiểu đơn giản: từ config thủ công → config theo convention.

3. Điểm quan trọng nhất: chọn đúng SDK

SDK	Kết quả
`Microsoft.NET.Sdk`	❌ IIS Express không chạy
`Microsoft.NET.Sdk.Web`	✅ Hoạt động bình thường

Dù tên là Web, SDK này không chỉ dành cho ASP.NET Core. Nó hoạt động tốt với ASP.NET MVC 5 trên .NET Framework 4.8.

4. Cấu hình .csproj chuẩn cho MVC 5

Đây là cấu hình tối thiểu để project chạy đúng với IIS Express:

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net48</TargetFramework>

    <!-- Bắt buộc cho MVC 5 -->
    <OutputType>Library</OutputType>
    <IsAspNetCoreProject>false</IsAspNetCoreProject>

    <!-- IIS Express yêu cầu output tại bin\ -->
    <AppendTargetFrameworkToOutputPath>false</AppendTargetFrameworkToOutputPath>
    <OutputPath>bin\</OutputPath>

    <UseIISExpress>true</UseIISExpress>
  </PropertyGroup>

</Project>

Những dòng này nhìn đơn giản, nhưng thiếu một dòng là có thể lỗi runtime.

5. Diff: old-style vs SDK-style

Old-style (rút gọn):

<Project>

  <ItemGroup>
    <Compile Include="Controllers\HomeController.cs" />
    <Compile Include="Models\Product.cs" />
    ...
  </ItemGroup>

</Project>

SDK-style:

<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>net48</TargetFramework>
  </PropertyGroup>
</Project>

SDK-style tự động include file → không cần khai báo thủ công nữa.

6. Những lỗi thường gặp

Lỗi 1: IIS Express không chạy

Nguyên nhân: dùng Microsoft.NET.Sdk

Fix:

<Project Sdk="Microsoft.NET.Sdk.Web">

Lỗi 2: Missing Main()

Nguyên nhân: project bị build như executable

Fix:

<OutputType>Library</OutputType>

Lỗi 3: Không load được assembly

Nguyên nhân: output sai thư mục

Fix:

<AppendTargetFrameworkToOutputPath>false</AppendTargetFrameworkToOutputPath>
<OutputPath>bin\</OutputPath>

Lỗi 4: 404 toàn bộ Views

Nguyên nhân: conflict Content items

Fix: kiểm soát lại include hoặc tắt default items nếu cần

7. Kết quả sau khi migrate

.csproj từ vài trăm dòng → còn vài chục dòng
Giảm đáng kể merge conflict
Thêm/xóa file không cần sửa project file

Quan trọng hơn: project trở nên “dễ thở” hơn rất nhiều.

8. Bước tiếp theo

Sau khi đã migrate sang SDK-style, bạn đã có nền tảng tốt để:

Refactor architecture
Thêm Dependency Injection
Chuyển sang compile-time mapping (Mapperly)

Phần tiếp theo mình sẽ tập trung vào: thay AutoMapper bằng Mapperly và so sánh chi tiết.

Kết luận

SDK-style không phải là thay đổi “hào nhoáng”, nhưng lại là một trong những nâng cấp đáng giá nhất cho project legacy.

Nó giúp:

Giảm độ phức tạp
Tăng khả năng maintain
Mở đường cho các nâng cấp tiếp theo

Nói ngắn gọn: dọn nền móng trước, rồi hãy xây tầng trên.

Nhật ký học tập

Tìm kiếm Blog này