Cách để route của Controller kế thừa hoạt động trong ASP.NET Core

Ngày 30 tháng 6 năm 2026

Theo mặc định, ASP.NET áp dụng các route bằng attribute của Controller trên những kiểu cụ thể. Khi tạo một lớp Controller, ASP.NET sẽ tự động nhận diện lớp đó cùng các route của nó trong quá trình khởi động.

ASP.NET quét assembly khởi động để tìm các Controller dạng instance, sau đó thêm những route tìm được vào bảng route. Nếu Controller nằm trong một assembly khác, bạn vẫn có thể đăng ký chúng, nhưng phải chỉ rõ assembly cần quét trong cấu hình MVC:

var mvcBuilder = services.AddControllersWithViews()
    // Cho MVC biết rằng có Controller được nạp từ bên ngoài
    .AddApplicationPart(typeof(QmmApiController).Assembly);

Mọi việc trở nên phức tạp hơn khi muốn kế thừa Controller, bởi không phải lúc nào cũng rõ các endpoint đã định tuyến cung cấp route như thế nào cho lớp kế thừa.

Bài viết này trình bày những vấn đề cần lưu ý khi kế thừa Controller có route từ lớp cơ sở, dù lớp đó nằm trong cùng dự án hay trong một thư viện bên ngoài.

Kế thừa Controller?

Kế thừa Controller không phải trường hợp sử dụng phổ biến, nhưng tôi thường dùng cách này để cung cấp API quản trị mặc định hoặc hành vi giao diện mặc định cho việc tạo template và xử lý lỗi trong các thành phần dùng chung và template ứng dụng.

Ví dụ, trong thư viện Westwind.AspNetCore.Markdown, một lớp Controller cơ sở cung cấp khả năng xử lý template và kiểu hiển thị mặc định cho việc kết xuất tệp Markdown. Trong một dự án khác là giải pháp nhắn tin, Controller cơ sở cung cấp một giao diện REST tùy chọn cho các API nhắn tin vốn sử dụng SignalR. Trong cả hai trường hợp, Controller được đóng gói trong một dự án thư viện riêng và được tham chiếu vào dự án cấp cao nhất thông qua NuGet.

Người dùng có thể ghi đè chức năng. Với thư viện template Markdown, họ còn có thể cung cấp View tùy chỉnh để thay đổi hành vi hoặc giao diện.

Controller và Minimal API

Tôi biết nhiều người cho rằng dùng Controller là cách làm lỗi thời. Tuy nhiên, với các chức năng được đóng gói như trên, Controller dễ quản lý và mở rộng hơn nhiều so với việc tạo hàng loạt thành phần middleware cùng một cấu hình phức tạp để hỗ trợ khả năng mở rộng.

Controller cung cấp một giao diện gốc phong phú, và bạn có thể dễ dàng tạo lớp con để mở rộng chức năng. Tất cả đều có sẵn, vì vậy với những thành phần cần cung cấp hành vi HTTP một cách tổng quát, Controller vẫn là lựa chọn ưu tiên của tôi.

Một lý do khác, rất liên quan đến bài viết này, là Controller cho phép ghi đè route. ASP.NET không cho phép định nghĩa route trùng lặp và sẽ phát sinh lỗi theo cách này hay cách khác nếu chúng xuất hiện. Tuy nhiên, với Controller, có những cách để thay đổi hành vi đó, cho phép kế thừa hoặc ghi đè route.

Theo hiểu biết của tôi, điều này gần như không thể thực hiện với app.Map() nếu không can thiệp trực tiếp vào các định nghĩa route.

Trường hợp sử dụng và cách tôi gặp vấn đề này

Tôi sử dụng Controller cho chức năng API tổng quát trong một giải pháp nhắn tin. Đây là REST API được định nghĩa trong một thư viện và được nạp bằng:

var mvcBuilder = services.AddControllersWithViews()
    // Cho MVC biết rằng có Controller được nạp từ bên ngoài
    .AddApplicationPart(typeof(QmmApiController).Assembly);

Kịch bản cụ thể là:

  • Tôi có lớp Controller cơ sở public class QmmApiController : BaseApiController trong một assembly riêng. Lớp này cung cấp giao diện quản trị cơ sở và có nhiều attribute [Route()] để định nghĩa chức năng API.
  • Sau đó, trong ứng dụng ASP.NET cấp cao nhất, tôi kế thừa Controller này bằng public class SampleAppQmmApiController : QmmApiController.

Khi truy cập các route được định nghĩa ở lớp cơ sở, ứng dụng trả về 500 Internal Server Error, chứ không phải 404. Đây là kết quả khá nghiêm trọng.

Trong log Console phía máy chủ, lỗi cho thấy nguyên nhân là ngoại lệ route không rõ ràng, tức AmbiguousRouteException. Đây là dấu hiệu quan trọng mà ban đầu cả tôi lẫn nhiều LLM đều bỏ qua. Đáng tiếc là thông báo lỗi không cho biết chính xác route nào bị lỗi.

Attribute route của Controller và tính kế thừa

Việc dùng Controller với các định nghĩa Route kế thừa khá khó xử lý. Các route được định nghĩa trực tiếp trên Controller cụ thể ở cấp cao nhất vẫn hoạt động. Ngược lại, các route được định nghĩa trên lớp cơ sở cụ thể lại thất bại.

Ban đầu tôi nghĩ ASP.NET không nhận diện route của lớp cơ sở. Tôi và nhiều LLM đã chẩn đoán sai hoàn toàn, cho rằng route bị thiếu rồi cố gắng thêm chúng thủ công vào bảng route. Cách đó không giải quyết được vấn đề.

Sau nhiều lần thử nghiệm, cùng rất nhiều lệnh Console.WriteLine() để theo dõi route và endpoint, nguyên nhân thực sự đã rõ: đây không phải là route bị thiếu mà là route bị trùng lặp.

Vấn đề: route bị trùng lặp

Khi tạo lớp con của một Controller, các attribute route trên Controller đó được kế thừa bởi lớp con. Vì vậy, về thực tế sẽ có hai tập attribute route: một trên lớp cơ sở và một trên lớp con.

ASP.NET phát hiện route trên toàn bộ cấu trúc kế thừa. Với lớp cụ thể, nó nhận cả route được định nghĩa trực tiếp trên lớp đó lẫn route từ lớp kế thừa. Sau đó, ASP.NET lại nhận diện lớp cơ sở như một lớp cụ thể riêng và ánh xạ các route được định nghĩa trên lớp này.

Kết quả là route bị đăng ký hai lần. Đây chính là nguyên nhân của lỗi Ambiguous Route.

Kế thừa Controller khá phức tạp

Vấn đề nằm ở tính kế thừa, nhưng không đơn giản chỉ như vậy. Kiểu của lớp cơ sở cũng rất quan trọng.

Ví dụ ban đầu của tôi dùng lớp cơ sở cụ thể:

public class SampleQmmApiController : QmmApiController {}

Và lớp cơ sở là:

public class QmmApiController : BaseApiController {}

Cách này không hoạt động và gây ra lỗi Ambiguous Route.

Nhưng nếu dùng một lớp cơ sở abstract thì các attribute route không bị nhân đôi. Controller kế thừa có thể nhận đúng một tập route:

public abstract class QmmApiController : BaseApiController {}

Khi kế thừa lớp abstract này, route sẽ hoạt động.

Các trường hợp chính:

  • Không kế thừa, lớp cơ sở là concrete: hoạt động; route được nhận diện trên lớp thư viện.
  • Không kế thừa, lớp là abstract: ASP.NET không tự nhận diện.
  • Kế thừa lớp concrete: không hoạt động; route trên lớp cơ sở gây xung đột.
  • Kế thừa lớp abstract: hoạt động; route được nhận diện trên lớp con.

Trường hợp không kế thừa hoạt động với cả Controller trong dự án hiện tại lẫn Controller từ thư viện bên ngoài, miễn là assembly đã được nạp bằng AddApplicationPart(). Với lớp instance, route luôn được công khai. Đây là hành vi phù hợp với cơ chế phát hiện Controller mặc định, nhưng có thể gây bất ngờ khi một thư viện bên ngoài tự động cung cấp mọi Controller public dạng instance cho ứng dụng.

Với thư viện bên ngoài, lựa chọn tốt hơn thường là dùng abstract class. Bộ phân tích của ASP.NET sẽ không tự động thêm lớp này vào bảng route. Nhờ đó, giao diện định tuyến được ẩn đi và chỉ được bật rõ ràng khi ứng dụng cấp cao nhất tạo lớp con.

Lựa chọn nào phù hợp phụ thuộc vào yêu cầu. Với Controller template Markdown, tôi muốn route luôn hoạt động để quá trình xử lý Markdown có thể diễn ra, nên dùng Controller dạng instance. Với Controller hàng đợi, tôi muốn ứng dụng chủ quản quyết định REST API có được mở hay không, nên dùng Controller abstract.

Bảo toàn route của lớp cơ sở

Có hai cách để kế thừa Controller mà vẫn giữ route của lớp cơ sở:

  • Khai báo lớp cơ sở là abstract: lớp abstract không được ASP.NET tự động chọn khi liệt kê route. Khi được kế thừa, nó có thể mang route của lớp cơ sở xuống lớp con một cách an toàn. Cách này thường hoạt động ngay.
  • Kế thừa Controller không abstract bằng cách tùy chỉnh route: nếu cần route luôn hoạt động mặc định nhưng vẫn muốn hỗ trợ kế thừa, bạn có thể chặn và chỉnh sửa các route mà ASP.NET đã tự động phát hiện.

Lớp abstract là cách đơn giản nhất

Nếu xây dựng thành phần thư viện và muốn công khai route có điều kiện, dùng lớp cơ sở abstract là cách dễ nhất. Bằng cách đánh dấu Controller là abstract rồi tạo một lớp triển khai cụ thể, bạn chuyển quyền kích hoạt route về đúng nơi cần dùng và tránh các xung đột ngoài ý muốn.

Nhược điểm là phải tạo lớp con một cách rõ ràng. Vì vậy, cần có tài liệu để người dùng biết bước này là bắt buộc nhằm kích hoạt hành vi của lớp cơ sở.

Tạo bộ chặn route bằng IActionDescriptorProvider

Nếu cần dùng lớp Controller cơ sở dạng instance không abstract, ta phải thao tác với bảng route sau khi ASP.NET đã phát hiện toàn bộ route.

Nguyên nhân là route bị nhân đôi khi kế thừa một lớp instance có chứa route: route của lớp cơ sở được thêm vào bảng route, rồi lại được thêm lần nữa khi ASP.NET quét lớp kế thừa.

Để phát hiện và loại bỏ route trùng, ta có thể:

  • Triển khai IActionDescriptorProvider để chặn danh sách route sau khi tự động phát hiện.
  • Loại bỏ route của lớp cơ sở đối với tất cả lớp con hoặc chỉ những lớp được chỉ định.

IActionDescriptorProvider cho phép chặn vòng đời xử lý route của Controller. Phương thức OnProvidersExecuted() được gọi sau khi route đã được tự động phát hiện.

namespace Westwind.AspNetCore;

public class InheritedControllerRouteConvention : IActionDescriptorProvider
{
    public List<Type> ChildControllerTypes { get; set; } = [];

    public int Order => 0;
    public void OnProvidersExecuting(ActionDescriptorProviderContext context) { }

    public void OnProvidersExecuted(ActionDescriptorProviderContext context)
    {
        var descriptors = context.Results
            .OfType<ControllerActionDescriptor>()
            .ToList();

        var controllerTypes = descriptors
            .Select(d => d.ControllerTypeInfo.AsType())
            .Distinct()
            .ToList();

        var childTypes = ChildControllerTypes.Count > 0
            ? controllerTypes.Where(t => ChildControllerTypes.Contains(t)).ToList()
            : controllerTypes;

        var baseTypesToSuppress = controllerTypes
            .Where(t => childTypes.Any(child => IsSubclassOf(child, t)))
            .ToList();

        var toRemove = descriptors
            .Where(d => baseTypesToSuppress.Any(bt =>
                d.ControllerTypeInfo.AsType() == bt))
            .ToList();

        foreach (var d in toRemove)
            context.Results.Remove(d);
    }

    private static bool IsSubclassOf(Type child, Type parent) =>
        child != parent && parent.IsAssignableFrom(child);
}

Đoạn mã lấy toàn bộ descriptor route, sau đó tìm các Controller cấp cao nhất cần xử lý, hoặc xử lý tất cả nếu không chỉ định danh sách. Tiếp theo, nó tìm các lớp cơ sở được kế thừa bởi những lớp đã chọn và loại bỏ route của các lớp cơ sở đó.

Trong trường hợp của tôi, có bảy route cần loại bỏ khỏi QmmApiController, là kiểu Controller được chỉ định để xử lý.

Đăng ký convention trong Program.cs như sau:

var inheritedRouteConvention = new InheritedControllerRouteConvention
{
    ChildControllerTypes = [typeof(SampleAppQmmApiController)]
};

services.AddSingleton<IActionDescriptorProvider>(inheritedRouteConvention);

var mvcBuilder = services.AddControllersWithViews()
    .AddApplicationPart(typeof(QmmApiController).Assembly);

Thành phần này đã được xây dựng sẵn trong gói NuGet Westwind.AspNetCore.

LLM: thiên đường hay địa ngục?

Đây là kiểu vấn đề khiến tôi phải nhờ đến LLM, cụ thể là GitHub Copilot và Claude Code với nhiều mô hình khác nhau.

Tôi nhấn mạnh cụm “nhiều mô hình khác nhau” vì trong trường hợp này, các LLM ban đầu đã làm rất tệ ở cả việc xác định đúng vấn đề lẫn đưa ra giải pháp có thể dùng được. Tôi đã nhiều lần chuyển qua lại giữa các công cụ và mô hình, nhưng tất cả đều đi đến cùng một kết luận sai: route bị thiếu.

Phải sau một quá trình xử lý sự cố khá dài, cùng việc in route và endpoint bằng Console.WriteLine(), nguyên nhân mới được xác định là route bị trùng chứ không phải bị thiếu.

Cuối cùng, Claude Code với Sonnet 4.6 đã đưa ra giải pháp hoạt động được, nhưng chỉ sau nhiều vòng xử lý sự cố rất dài. Tôi phải in các ánh xạ route, gửi chúng trở lại cho Claude, rồi từng bước xác định vấn đề trùng lặp. Khi nguyên nhân đã rõ, Claude tạo lớp IActionDescriptorProvider cuối cùng khá tốt.

Nói thẳng ra, có lẽ tôi sẽ không tự mình tìm ra cách này. ASP.NET có khả năng mở rộng rất mạnh, nhưng việc khám phá các điểm mở rộng gần như là bất khả thi. Người ta kỳ vọng LLM sẽ giúp được, nhưng ở những tình huống ít được công bố và nằm ngoài các trường hợp phổ biến, LLM vẫn cần rất nhiều hướng dẫn thực tế.

Hoàn thành việc này thực sự rất vất vả, với rất nhiều giải pháp sai được thử trong quá trình giải quyết nhầm vấn đề.

Tôi vẫn ngạc nhiên khi có người nói rằng họ có thể giải quyết mọi thứ chỉ với một lần hỏi. Điều đó gần như chưa bao giờ xảy ra với tôi. Tôi thường có thể hướng LLM đến một giải pháp, nhưng không bao giờ chỉ cần một hoặc vài prompt. Thông thường phải thử một cách, chờ LLM đưa ra giả định sai, rồi tiếp tục điều chỉnh hướng đi.

Cuối cùng, LLM vẫn cung cấp được một giải pháp hoạt động, mà nhiều khả năng tôi sẽ không tự tìm ra. Dù vậy, tôi đã tốn quá nhiều thời gian cho vấn đề này.

Tóm tắt

Kế thừa route của Controller trong ASP.NET không phải cách làm phổ biến, nhưng nếu có nhu cầu sử dụng, bạn cần ghi nhớ những điểm sau:

  • Không được để route bị trùng lặp.
  • Lớp instance tự động công khai route, kể cả trong thư viện bên ngoài nếu assembly đã được đăng ký.
  • Kế thừa một Controller dạng instance có thể gây lỗi route do route bị nhân đôi trên lớp con.
  • Controller abstract không làm route bị nhân đôi và có thể được kế thừa an toàn.
  • Nếu cần kế thừa Controller dạng instance, có thể dùng IActionDescriptorProvider để loại bỏ route của lớp cơ sở.

Tài nguyên