Quét assembly không làm DI của bạn tốt hơn; nó làm file đăng ký ngắn hơn. Nếu bạn không giới hạn phạm vi quét, bạn đang đổi một lỗi biên dịch (thiếu đăng ký, phát hiện ngay) lấy một hành vi runtime không xác định (ai đăng ký sau thì thắng). Scrutor hữu ích khi quy ước của bạn rõ — và nguy hiểm khi quy ước chỉ nằm trong đầu một người.
Mục lục
Cập nhật 2026
- Scrutor 7.0.0 là bản stable hiện tại, vẫn là thư viện community của khellang, dùng trực tiếp trên .NET 10 không cần cấu hình thêm.
- Trong .NET 10,
ValidateOnBuildbắt được dependency thiếu, nhưng không bắt được đăng ký trùng hay thứ tự đăng ký sai. Phần đó phải có test riêng. - Scrutor chỉ đăng ký service; nó không tạo scope, không quản lý lifetime hộ bạn. Mọi hiểu biết về scoped/transient/singleton vẫn là điều kiện tiên quyết.
Vấn đề thật của đăng ký thủ công
Với 20 service, đăng ký tường minh là lựa chọn đúng: bạn đọc được toàn bộ graph trong một màn hình, thấy ngay lifetime của từng thứ, và Ctrl+F trả lời được câu “ai đăng ký cái này”. Vấn đề bắt đầu ở khoảng 100 service, khi file đăng ký trở thành danh sách dài, dễ quên, và mỗi lần thêm một lớp theo quy ước lại phải nhớ một dòng.
Hai lỗi thực sự xảy ra: (1) bạn quên đăng ký, và lỗi xuất hiện ở runtime, đúng trên đường dẫn hiếm nhất; (2) bạn đăng ký sai lifetime, và lỗi xuất hiện dưới tải. Scrutor giải quyết (1) tốt hơn (2) — nó không biết service nào cần scoped.
Cài đặt và mô hình quét
dotnet add package Scrutor --version 7.0.0
Một lần Scan gồm ba phần: nguồn (assembly nào), bộ lọc (lớp nào), và ánh xạ + lifetime (đăng ký dưới dạng nào). Thiếu phần thứ ba, Scrutor vẫn đăng ký nhưng bạn phải tự biết lifetime mặc định là gì — đừng dựa vào đó, hãy viết tường minh.
// File: DependencyInjection.cs
public interface IScopedService { } // marker: "tôi là service theo đơn vị công việc"
public interface ISingletonService { } // marker: "tôi dùng chung toàn app"
public static class DependencyInjection
{
public static IServiceCollection AddApplication(this IServiceCollection services)
{
services.Scan(scan => scan
.FromAssemblyOf<IOrderService>()
.AddClasses(classes => classes.AssignableTo<IScopedService>())
.AsImplementedInterfaces()
.AsSelf()
.WithScopedLifetime());
services.Scan(scan => scan
.FromAssemblyOf<IOrderService>()
.AddClasses(classes => classes.AssignableTo<ISingletonService>())
.AsImplementedInterfaces()
.AsSelf()
.WithSingletonLifetime());
return services;
}
}
Ba chi tiết trong đoạn trên đáng để dừng lại. FromAssemblyOf<T>() lấy assembly chứa T, không phải toàn bộ app domain — đây là cách giới hạn phạm vi rẻ nhất. AddClasses(...) với marker interface biến quy ước thành thứ biên dịch được: một lớp không implement marker sẽ không bao giờ bị quét nhầm, và một lớp implement marker mà không đăng ký được là lỗi của người viết code, không phải của container. AsSelf() đăng ký thêm chính lớp đó, cần khi có chỗ inject trực tiếp concrete type thay vì interface.
Với solution nhiều project — kiểu modular monolith với Sales, Billing, Shipping — bạn không cần gom tất cả vào một assembly. FromAssemblies(...) nhận danh sách assembly tường minh:
services.Scan(scan => scan
.FromAssemblies(
typeof(Sales.OrderService).Assembly,
typeof(Billing.InvoiceService).Assembly,
typeof(Shipping.ShipmentService).Assembly)
.AddClasses(classes => classes.AssignableTo<IScopedService>())
.AsImplementedInterfaces()
.WithScopedLifetime());
Cách này khiến mỗi module tự khai báo sự hiện diện của mình trong một dòng, thay vì để bộ quét tự khám phá. Nó cũng là ranh giới kiến trúc: nếu một module mới không được thêm vào danh sách, nó không đăng ký gì cả, và lỗi xuất hiện ngay ở test thay vì âm thầm chạy được.
Chọn lớp và ánh xạ interface
| API | Việc nó làm | Khi dùng |
|---|---|---|
AddClasses(c => c.AssignableTo<T>()) |
Chỉ lớp implement T |
Marker interface — cách an toàn nhất |
AddClasses(c => c.InNamespaces("App.Services")) |
Giới hạn theo namespace | Assembly có nhiều thư mục, chỉ muốn một vùng |
AddClasses(c => c.WithAttribute<T>()) |
Chỉ lớp có attribute | Đánh dấu thủ công một số ít lớp |
AsImplementedInterfaces() |
Đăng ký với mọi interface lớp implement | Quy ước 1 interface / 1 lớp |
AsMatchingInterface() |
Ghép Foo với IFoo |
Quy ước đặt tên cố định |
AsSelf() |
Đăng ký lớp với chính nó | Cần inject concrete type ở vài chỗ |
AsImplementedInterfaces() là API nguy hiểm nhất trong bảng khi lớp của bạn implement nhiều interface. Một lớp OrderService : IOrderService, IOrderValidator sẽ được đăng ký cho cả hai, kể cả khi bạn chỉ muốn interface đầu. Nếu lớp có hai interface với ý nghĩa khác nhau, hãy tách lớp hoặc đăng ký tường minh — đừng để bộ quét quyết định kiến trúc thay bạn.
Quy ước đặt tên thay cho marker
Một số đội thích AsMatchingInterface() với filter theo hậu tố (type.Name.EndsWith("Repository")) vì không phải thêm marker interface vào code nghiệp vụ. Đánh đổi: quy ước nằm trong một chuỗi string, không ai review, và IDE không cảnh báo khi bạn đặt tên sai. Marker interface đánh đổi ngược lại — thêm một interface “không có thành viên” vào domain, nhưng mọi lỗi quy ước trở thành lỗi biên dịch. Với dự án sống nhiều năm, tôi chọn marker.
Đừng lo về chi phí khởi động của reflection trước khi có số đo: quét type là việc một lần lúc startup, và Scrutor chỉ thêm descriptor vào collection — nó không ảnh hưởng đến thời gian resolve service graph sau đó.
Thứ tự và tính xác định
Đây là phần bị bỏ qua nhiều nhất. Thứ tự Assembly.GetTypes() trả về không được hợp đồng API bảo đảm. Nó phụ thuộc thứ tự metadata trong file DLL, và thay đổi khi bạn thêm lớp, đổi tên file, hoặc build bằng toolchain khác. Container DI thì giải quyết theo nguyên tắc “đăng ký sau cùng thắng” khi resolve một service type. Kết hợp hai điều đó: nếu hai lớp cùng implement một interface và cả hai đều bị quét, lớp nào thắng là chuyện không xác định giữa các lần build.
- Một interface, một implementation là điều kiện để quét an toàn. Nếu bạn cần nhiều implementation cho cùng interface, đăng ký tường minh và dùng keyed services (
AddKeyedScoped) thay vì để thứ tự quyết định. - Không trộn đăng ký quét với đăng ký tường minh cho cùng một service type. Nếu phải trộn, đặt phần tường minh sau phần quét và viết test khẳng định điều đó.
- Không quét assembly chứa controller, endpoint, migration, hay test. Một
FromApplicationDependencies()không lọc sẽ kéo cả EF Core migrations vào container.
Decorator: phần đáng dùng nhất của Scrutor
Decorator cho phép thêm logging, caching, retry, metric vào một service mà không sửa lớp gốc và không làm lớp gốc biết về chúng. Với DI thủ công, bạn phải đăng ký lớp gốc dưới một tên khác rồi tự nối factory — dễ sai khi có nhiều decorator. Scrutor làm việc đó bằng một dòng:
services.AddScoped<IOrderService, OrderService>();
services.Decorate<IOrderService, LoggingOrderService>();
// Thêm một decorator nữa: cái gọi sau nằm ngoài cùng
services.Decorate<IOrderService, CachingOrderService>();
Thứ tự lồng nhau là ngược với thứ tự gọi: CachingOrderService bọc LoggingOrderService, bọc OrderService. Request đi vào cache trước, cache miss mới vào log, rồi tới nghiệp vụ. Nếu bạn muốn log cả lần cache hit, đảo thứ tự hai lời gọi Decorate. Đây là lý do thứ tự Decorate phải nằm trong một method duy nhất, có comment nói rõ thứ tự mong muốn.
Decorator cho open generic
Đây là chỗ Scrutor vượt xa đăng ký thủ công. Giả sử bạn có một interface query tổng quát:
public interface IQuery<out TResult> { }
public interface IQueryHandler<in TQuery, TResult> where TQuery : IQuery<TResult>
{
Task<TResult> HandleAsync(TQuery query, CancellationToken ct);
}
public sealed class GetOrderHandler(AppDbContext db) : IQueryHandler<GetOrder, Order?>
{
public Task<Order?> HandleAsync(GetOrder query, CancellationToken ct) =>
db.Orders.AsNoTracking().FirstOrDefaultAsync(o => o.Id == query.Id, ct);
}
Bạn có 40 handler như vậy và muốn log thời gian xử lý cho tất cả. Viết một decorator open generic và đăng ký một lần:
public sealed class LoggingQueryHandler<TQuery, TResult>(
IQueryHandler<TQuery, TResult> inner,
ILogger<LoggingQueryHandler<TQuery, TResult>> logger)
: IQueryHandler<TQuery, TResult> where TQuery : IQuery<TResult>
{
public async Task<TResult> HandleAsync(TQuery query, CancellationToken ct)
{
var sw = Stopwatch.StartNew();
var result = await inner.HandleAsync(query, ct);
logger.LogInformation("{Query} {Elapsed}ms", typeof(TQuery).Name, sw.ElapsedMilliseconds);
return result;
}
}
// Đăng ký: quét các handler closed-generic, rồi decorate bằng open generic
services.Scan(scan => scan
.FromAssemblyOf<GetOrderHandler>()
.AddClasses(c => c.AssignableTo(typeof(IQueryHandler<,>)))
.AsImplementedInterfaces()
.WithScopedLifetime());
services.Decorate(typeof(IQueryHandler<,>), typeof(LoggingQueryHandler<,>));
Hai điều kiện để đoạn trên chạy: decorator phải khai báo cùng ràng buộc generic với interface gốc (where TQuery : IQuery<TResult>), và service gốc phải được đăng ký dưới dạng open generic hoặc closed generic khớp. Nếu thiếu ràng buộc, lỗi xuất hiện lúc resolve với thông báo khó đọc về generic constraint — không phải lúc đăng ký.
Sáu cái bẫy
- Quét quá rộng.
FromApplicationDependencies()không lọc sẽ nuốt mọi assembly phụ thuộc, gồm cả thư viện bên thứ ba có class trùng tên interface của bạn. Luôn bắt đầu bằngFromAssemblyOf<T>(). - Đăng ký trùng. Một lớp vừa implement marker vừa nằm trong namespace bị quét bởi lần
Scanthứ hai sẽ có hai descriptor. Không có cảnh báo; chỉ có hành vi “lần cuối thắng”. - Phụ thuộc ẩn. Sau khi quét, một lớp trở nên resolvable mà không ai thấy nó được đăng ký ở đâu. Người mới vào dự án sẽ mất một buổi để tìm. Marker interface và một method
AddApplication()duy nhất là cách giảm chi phí đó. - Lifetime sai. Đăng ký
DbContexthay repository singleton bằngWithSingletonLifetime()vì “cho nhanh” là captive dependency. Marker phải tách theo lifetime, như ví dụ ở trên. - Decorator che lỗi. Một decorator bắt exception rồi trả default sẽ làm hỏng cả service bên trong. Decorator chỉ nên quan sát, hoặc ném lại sau khi ghi log.
- Quét trong test. Test dùng chính
AddApplication()là đúng; đừng quét thêm assembly test, vì các fake/stub trong test sẽ lọt vào container và che mất đăng ký thật.
Khi nào đăng ký tường minh tốt hơn
| Tình huống | Cách làm | Vì sao |
|---|---|---|
Options, cấu hình, HttpClient, middleware |
Tường minh | Cần tham số, tên client, thứ tự pipeline |
| Nhiều implementation cùng interface | Tường minh hoặc keyed | Thứ tự quét không xác định |
| Vài service hạ tầng dùng chung | Tường minh | Ít dòng, dễ đọc, dễ review |
| Hàng chục handler/repository theo quy ước | Quét | Đây là chỗ Scrutor thắng thật |
| Cross-cutting cho cả một nhóm service | Quét + Decorate |
Một dòng thay cho N lần nối factory |
Kiểm thử cấu hình DI
Đăng ký bằng quy ước chỉ đáng tin khi có test khẳng định quy ước. Hai test dưới đây rẻ và bắt được gần hết lỗi ở trên.
public class DependencyInjectionTests
{
private static IServiceCollection Build() =>
new ServiceCollection().AddLogging().AddApplication();
[Fact]
public void Graph_resolves_without_missing_dependencies()
{
using var provider = Build().BuildServiceProvider(new ServiceProviderOptions
{
ValidateOnBuild = true,
ValidateScopes = true
});
}
[Fact]
public void Order_service_is_scoped_and_single()
{
var services = Build();
var descriptors = services.Where(d => d.ServiceType == typeof(IOrderService)).ToList();
Assert.Single(descriptors);
Assert.Equal(ServiceLifetime.Scoped, descriptors[0].Lifetime);
}
}
Test thứ nhất bắt dependency thiếu và captive dependency. Test thứ hai bắt đăng ký trùng và lifetime sai — đúng hai thứ ValidateOnBuild không thấy. Thêm một test tương tự cho mỗi interface quan trọng, và bạn có hợp đồng DI được kiểm tra tự động thay vì được ghi nhớ.
2027
.NET 11 GA tháng 11/2026 (STS); Scrutor nhiều khả năng vẫn giữ API hiện tại vì nó chỉ là lớp tiện ích trên IServiceCollection. Hướng đi đáng chú ý là keyed services và source generator cho đăng ký — cả hai đều làm bài toán “đăng ký hàng loạt” bớt phụ thuộc vào reflection lúc startup. Trong lúc chờ, quy ước rõ ràng vẫn là thứ đáng đầu tư hơn công cụ.
Checklist
- Mỗi
Scancó đúng một nguồn assembly và một marker interface; không dùngFromApplicationDependencies()không lọc. - Không bao giờ để hai lớp cùng implement một interface trong cùng một lần quét.
- Mọi lifetime viết tường minh; marker tách theo lifetime.
Decoratenằm trong một method, có comment về thứ tự lồng nhau.- Có test
ValidateOnBuild+ test khẳng định lifetime/không trùng cho các interface chính. - Thứ hạ tầng (options,
HttpClient, middleware) vẫn đăng ký tay.
Đọc tiếp: Vòng đời dịch vụ: Scoped, Transient, Singleton, Tiêm phụ thuộc nâng cao khả năng kiểm thử, và MediatR cho CQRS.



