Bộ lọc Filters trong ASP.NET Core Minimal API

Bộ lọc (Filters) trong ASP.NET Core Minimal API là các thành phần thực thi trước và/hoặc sau một route handler. Chúng cho phép bạn bổ sung các chức năng chung như kiểm tra hợp lệ (validation), ghi log, kiểm tra xác thực, hoặc sửa đổi request và response mà không phải lặp lại mã ở mọi endpoint.

Các công dụng của Filters:

Kiểm tra dữ liệu đầu vào
Ghi log request và response
Kiểm tra xác thực (authentication) hoặc phân quyền (authorization)
Sửa đổi dữ liệu request hoặc response
Xử lý ngoại lệ
Thực thi logic chung cho nhiều endpoint

Luồng thực thi:

Client Request │ ▼ Endpoint Filter (Before) │ ▼ Route Handler │ ▼ Endpoint Filter (After) │ ▼ Client Response

Nội dung trang:

Mục lục

Cách sử dụng filters trong Minimal API

Chúng ta sử dụng phương thức mở rộng AddEndpointFilter. Phương thức này nhận một Delegate đảm nhận hai vai trò cốt lõi:

Nó nhận bối cảnh thực thi: EndpointFilterInvocationContext
Nó trả về bước tiếp theo trong pipeline: EndpointFilterDelegate

EndpointFilterInvocationContext: cung cấp quyền truy cập trực tiếp vào HttpContext của request hiện tại và hé lộ một danh sách Arguments.

Arguments List: chứa các đối số được truyền vào route handler. Các đối số này được sắp xếp theo đúng thứ tự xuất hiện trong khai báo của handler. Một ví dụ điển hình được nêu trên tài liệu chính thức của Microsoft, xem bên dưới:

Giải thích:

Ở đây chúng ta đã định nghĩa endpoint handler:

string ColorName(string color) => $"Color specified: {color}!";

Đây là một phương thức đơn giản nhận một tham số string. Nếu endpoint thực thi thành công, nó trả về:

Color specified: Blue! hoặc Color specified: Green!

tùy thuộc vào URL.

Ánh xạ endpoint:

app.MapGet("/colorSelector/{color}", ColorName)

Đoạn này tạo ra một endpoint GET.

Các URL ví dụ:

GET /colorSelector/Blue GET /colorSelector/Green GET /colorSelector/Red

Phần {color} là một route parameter. Ví dụ:

/colorSelector/Blue

sẽ liên kết:

color = "Blue"

và truyền nó vào:

ColorName(color)

Thêm một Endpoint Filter:

.AddEndpointFilter(async (invocationContext, next) => {

Lệnh này gắn một filter chỉ cho endpoint này. Hãy hình dung thứ tự thực thi như sau:

Request ↓ Endpoint Filter ↓ Endpoint Handler (ColorName) ↓ Response

Bạn cũng có thể muốn tìm hiểu thêm – ASP.NET Core Minimal API Parameter Binding – hướng dẫn đầy đủ kèm mã.

Filter có thể:

kiểm tra các đối số
sửa đổi các đối số
dừng việc thực thi
sửa đổi response

Đọc đối số của endpoint:

var color = invocationContext.GetArgument<string>(0);

invocationContext chứa tất cả đối số được truyền vào endpoint. Endpoint là:

string ColorName(string color)

Các tham số của nó là:

Index 0 → color

Vì vậy:

GetArgument<string>(0)

sẽ trả về giá trị route. Nếu URL là:

/colorSelector/Blue

thì:

color == "Blue"

Kiểm tra giá trị:

if (color == "Red") { return Results.Problem("Red not allowed!"); }

Nếu client gửi request:

GET /colorSelector/Red

filter sẽ ngay lập tức trả về:

Results.Problem(...)

mà không gọi endpoint. Endpoint handler không bao giờ được thực thi. Client nhận được một response tương tự:

{ "title": "An error occurred.", "detail": "Red not allowed!" }

Tiếp tục tới endpoint:

return await next(invocationContext);

next() gọi thành phần tiếp theo trong endpoint pipeline. Nếu không còn filter nào, nó sẽ gọi:

ColorName(color)

Vậy nên:

GET /colorSelector/Blue

sẽ thực thi:

ColorName("Blue")

và trả về:

Color specified: Blue!

Nhiều Endpoint Filters trong Minimal API

Chúng ta cũng có thể thêm nhiều Endpoint Filter cho Minimal API. Hãy hình dung chúng như những lớp bao quanh endpoint, giống như các hộp xếp chồng nhau. Xem đoạn mã bên dưới – bạn sẽ nhận thấy endpoint hầu như không làm gì cả. Phần thú vị chính là các filter được gắn vào nó.

Giải thích:

Ánh xạ endpoint:

app.MapGet("/", () => { app.Logger.LogInformation(" Endpoint"); return "Test of multiple filters"; })

Đoạn này tạo một endpoint GET cho URL gốc (/).

Khi endpoint cuối cùng được thực thi, nó:

Ghi chữ “Endpoint” vào log.
Trả về chuỗi:

Test of multiple filters

Endpoint Filter thứ nhất:

.AddEndpointFilter(async (efiContext, next) => { app.Logger.LogInformation("Before 1st filter"); var result = await next(efiContext); app.Logger.LogInformation("After 1st filter"); return result; })

Filter này chạy trước endpoint. Trước khi gọi next():

app.Logger.LogInformation("Before 1st filter");

sẽ in ra:

Before first filter

Gọi next:

await next(efiContext);

Hướng dẫn đầy đủ về Minimal API Response trình bày các cách mà một endpoint Minimal API có thể trả dữ liệu cho client. Một handler có thể trả về một chuỗi đơn giản (được gửi dưới dạng plain text) hoặc một đối tượng (tự động được serialize sang JSON). Khi bạn cần kiểm soát mã trạng thái và thân response, bạn có thể trả về một IResult được dựng bằng các helper Results hoặc TypedResults, chẳng hạn như Ok, Created, NoContent, NotFound và BadRequest. Hướng dẫn này cũng đề cập tới file, stream và redirect, đồng thời giải thích cách khai báo các response có thể có của endpoint để các công cụ như Swagger có thể ghi chú chúng. Mỗi cách đều kèm ví dụ mã.

Lệnh này truyền việc thực thi cho filter tiếp theo. Sau khi filter đó (và cuối cùng là endpoint) hoàn tất, việc thực thi quay lại đây. Sau đó:

app.Logger.LogInformation("After 1st filter");

sẽ chạy.

Endpoint Filter thứ hai:

.AddEndpointFilter(async (efiContext, next) => { app.Logger.LogInformation(" Before 2nd filter"); var result = await next(efiContext); app.Logger.LogInformation(" After 2nd filter"); return result; })

Filter này hoạt động hoàn toàn giống filter thứ nhất. Nó bao quanh mọi thứ đứng sau nó.

Endpoint Filter thứ ba:

.AddEndpointFilter(async (efiContext, next) => { app.Logger.LogInformation(" Before 3rd filter"); var result = await next(efiContext); app.Logger.LogInformation(" After 3rd filter"); return result; });

Đây là filter cuối cùng.

Khi gọi:

await next(efiContext);

không gọi thêm filter nào nữa vì không còn filter nào. Thay vào đó, nó gọi endpoint.

Thứ tự thực thi:

Giả sử bạn request:

GET /

Bước 1: Filter đầu tiên bắt đầu.

Before first filter

Nó gọi:

await next()

Bước 2: Filter thứ hai bắt đầu.

Before 2nd filter

Nó gọi:

await next()

Bước 3: Filter thứ ba bắt đầu.

Before 3rd filter

Nó gọi:

await next()

Bước 4: Không còn filter nào, nên endpoint được thực thi.

Endpoint

Endpoint trả về:

Test of multiple filters

Bước 5: Việc thực thi quay lại filter thứ ba.

After 3rd filter

Bước 6: Việc thực thi quay lại filter thứ hai.

After 2nd filter

Bước 7: Việc thực thi quay lại filter đầu tiên.

After first filter

Log đầu ra cuối cùng: Các log xuất hiện theo thứ tự sau:

Before first filter Before 2nd filter Before 3rd filter Endpoint After 3rd filter After 2nd filter After first filter

Kiểm tra dữ liệu trong Minimal API với Filters

Khi ứng dụng phát triển, việc kiểm tra các request đầu vào trở nên cần thiết để đảm bảo tính toàn vẹn của dữ liệu, độ tin cậy của ứng dụng và bảo mật. Một cách hiệu quả để triển khai validation trong Minimal API là sử dụng endpoint filter – cho phép nhà phát triển chặn các request trước khi chúng tới endpoint handler. Endpoint filter giúp logic kiểm tra dữ liệu được tập trung và tái sử dụng trên nhiều endpoint, giảm thiểu việc trùng lặp mã và cải thiện khả năng bảo trì.

Ví dụ dưới đây thực hiện kiểm tra dữ liệu với sự trợ giúp của filter:

app.MapPut("/works/{id}", async (int id, Work work, WorkDb db) => { var todo = await db.Works.FindAsync(id); if (todo is null) return Results.NotFound(); todo.Name = work.Name; todo.TimeStart = work.TimeStart; todo.TimeEnd = work.TimeEnd; todo.IsComplete = work.IsComplete; await db.SaveChangesAsync(); return Results.NoContent(); }).AddEndpointFilter(async (efiContext, next) => { var w = efiContext.GetArgument<Work>(1); var validationError = Utilities.IsValid(w); if (!string.IsNullOrEmpty(validationError)) { return Results.Problem(validationError); } return await next(efiContext); });

Mã của lớp Work:

public class Work { public int Id { get; set; } public string Name { get; set; } public string TimeStart { get; set; } public string TimeEnd { get; set; } public bool IsComplete { get; set; } }

Giải thích:

Sau khi định nghĩa endpoint, đoạn mã dưới đây gắn một endpoint filter:

.AddEndpointFilter(async (efiContext, next) =>

Endpoint filter thực thi trước và/hoặc sau endpoint handler. Nó có thể:

kiểm tra dữ liệu đầu vào
ghi log request
phân quyền người dùng
đo thời gian thực thi
sửa đổi response

Trong ví dụ này, nó thực hiện việc kiểm tra dữ liệu.

Truy cập đối tượng Request:

var w = efiContext.GetArgument<Work>(1);

GetArgument() lấy một trong các đối số của endpoint handler. Ở đây nó lấy đối tượng Work, vì Work là tham số thứ hai.

Kiểm tra đối tượng:

var validationError = Utilities.IsValid(w);

Phương thức Utilities.IsValid() thực hiện kiểm tra tùy chỉnh trên đối tượng Work.

Ví dụ, nó có thể kiểm tra rằng:

Name không được rỗng.
TimeStart phải sớm hơn TimeEnd.
Các trường bắt buộc phải có giá trị.

Nó trả về:

một thông báo lỗi nếu validation thất bại.
null hoặc chuỗi rỗng nếu validation thành công.

Trả về lỗi validation:

if (!string.IsNullOrEmpty(validationError)) { return Results.Problem(validationError); }

Nếu validation thất bại, filter dừng request và trả về một HTTP error response chứa thông báo kiểm tra.

Ví dụ:

{ "title": "An error occurred.", "detail": "TimeStart must be earlier than TimeEnd." }

Endpoint handler không được thực thi khi validation thất bại.

Unit và Integration Testing trong Minimal APIs hướng dẫn cách kiểm thử các endpoint Minimal API ở hai cấp độ. Unit test kiểm tra logic của handler một cách độc lập, thường dùng framework như xUnit với các dependency được mock. Integration test chạy toàn bộ ứng dụng trong bộ nhớ bằng WebApplicationFactory và gửi các HTTP request thật để xác nhận routing, binding và response hoạt động cùng nhau. Các ví dụ mã cho thấy cách thiết lập và viết cả hai loại test.

Gọi endpoint:

return await next(efiContext);

Nếu validation thành công, filter gọi giai đoạn tiếp theo trong pipeline, vốn thực thi endpoint handler.

Luồng thực thi:

HTTP Request │ ▼ Endpoint Filter │ ├── Validation fails │ │ │ ▼ │ Return Problem() │ └── Validation succeeds │ ▼ Endpoint Handler │ ▼ Update Database │ ▼ Return 204 No Content

Lợi ích của việc dùng Endpoint Filter để validation:

Tách biệt trách nhiệm: Logic validation được giữ tách biệt với logic nghiệp vụ của endpoint.
Tái sử dụng mã: Cùng một filter validation có thể áp dụng cho nhiều endpoint.
Handler gọn gàng hơn: Các phương thức endpoint tập trung vào việc xử lý request hợp lệ.
Xử lý lỗi nhất quán: Mọi lỗi validation đều có thể trả về định dạng response tiêu chuẩn hóa.
Cải thiện khả năng bảo trì: Quy tắc validation có thể cập nhật ở một nơi mà không phải sửa từng endpoint.

Triển khai giao diện IEndpointFilter

Ngoài việc được định nghĩa dưới dạng delegate, endpoint filter còn có thể được triển khai bằng cách tạo một lớp implements giao diện IEndpointFilter. Cách tiếp cận này gói logic filter vào một lớp có thể tái sử dụng, giúp dễ bảo trì và áp dụng trên nhiều endpoint hơn. Đoạn mã dưới đây minh họa filter validation ở trên được viết thành một lớp implements giao diện IEndpointFilter:

public class WorkIsValidFilter : IEndpointFilter { private ILogger _logger; public WorkIsValidFilter(ILoggerFactory loggerFactory) { _logger = loggerFactory.CreateLogger<WorkIsValidFilter>(); } public async ValueTask<object?> InvokeAsync(EndpointFilterInvocationContext efiContext, EndpointFilterDelegate next) { var work = efiContext.GetArgument<Work>(1); var validationError = Utilities.IsValid(work!); if (!string.IsNullOrEmpty(validationError)) { _logger.LogWarning(validationError); return Results.Problem(validationError); } return await next(efiContext); } }

Các filter implements giao diện IEndpointFilter có thể truy cập các service được đăng ký trong Dependency Injection (DI) container thông qua constructor injection hoặc service resolution, như đã minh họa ở ví dụ trên. Tuy nhiên, trong khi endpoint filter có thể dùng các dependency do DI cung cấp, chính các instance của filter lại không được resolve trực tiếp từ DI container.

Lớp “WorkIsValidFilter” được áp dụng cho các endpoint dưới đây:

app.MapPut("/works/{id}", async (int id, Work work, WorkDb db) => { var todo = await db.Works.FindAsync(id); if (todo is null) return Results.NotFound(); todo.Name = work.Name; todo.TimeStart = work.TimeStart; todo.TimeEnd = work.TimeEnd; todo.IsComplete = work.IsComplete; await db.SaveChangesAsync(); return Results.NoContent(); }).AddEndpointFilter<WorkIsValidFilter>();

Authentication & Authorization trong Minimal API

Authentication (Xác thực) xác minh danh tính của người dùng trước khi cho phép truy cập API. Sau khi danh tính người dùng được thiết lập, Authorization (Phân quyền) xác định xem người dùng đã được xác thực có quyền truy cập các tài nguyên API cụ thể hay không.

Trong ASP.NET Core, việc phân quyền được xử lý bởi IAuthorizationService, được đăng ký khi bạn gọi phương thức mở rộng AddAuthorization.

Trong ví dụ sau, endpoint /hello được bảo vệ bởi một authorization policy. Để truy cập endpoint này, người dùng đã được xác thực phải đáp ứng hai yêu cầu:

Thuộc vai trò “admin”.
Có một claim scope với giá trị “head”.

Chỉ những người dùng đáp ứng cả hai điều kiện mới được phép truy cập tài nguyên /hello.

Đoạn mã dưới đây tạo một authorization policy mới tên LevelOne, bao hàm hai yêu cầu phân quyền:

Một yêu cầu dựa trên vai trò thông qua RequireRole cho người dùng có vai trò admin.
Một yêu cầu dựa trên claim thông qua RequireClaim, theo đó người dùng phải cung cấp một claim scope head.

Policy LevelOne được cung cấp như policy bắt buộc cho endpoint /hello:

using Microsoft.Identity.Web; var builder = WebApplication.CreateBuilder(args); builder.Services.AddAuthorizationBuilder() .AddPolicy("LevelOne", policy => policy .RequireRole("admin") .RequireClaim("scope", "head")); var app = builder.Build(); app.MapGet("/hello", () => "Hello world!") .RequireAuthorization("LevelOne"); app.Run();

Dùng Endpoint Filter cho phân quyền tùy chỉnh

Filter rất hữu ích khi bạn cần các quy tắc phân quyền vượt ra ngoài hệ thống policy tích hợp sẵn. Ví dụ, giả sử chỉ chủ sở hữu của một work item mới được phép chỉnh sửa nó.

public class OwnerFilter : IEndpointFilter { public async ValueTask<object?> InvokeAsync( EndpointFilterInvocationContext context, EndpointFilterDelegate next) { var httpContext = context.HttpContext; if (!httpContext.User.Identity!.IsAuthenticated) { return Results.Unauthorized(); } var userId = httpContext.User.FindFirst("sub")?.Value; var work = context.GetArgument<Work>(1); if (work.OwnerId != userId) { return Results.Forbid(); } return await next(context); } }

Áp dụng filter:

app.MapPut("/works/{id}", UpdateWork) .AddEndpointFilter<OwnerFilter>() .RequireAuthorization();

Luồng thực thi:

Client Request │ ▼ Authentication Middleware │ ▼ Authorization Middleware │ ▼ Endpoint Filter (Custom Rule) │ ▼ Endpoint Handler │ ▼ Database

Best Practice

Hãy sử dụng hệ thống authentication và authorization tích hợp sẵn để bảo vệ các Minimal API của bạn. Endpoint filter nên bổ sung cho hệ thống này bằng cách triển khai các quy tắc riêng của ứng dụng, chẳng hạn như xác minh quyền sở hữu tài nguyên, kiểm tra các ràng buộc nghiệp vụ, hoặc áp dụng các yêu cầu truy cập tùy chỉnh. Sự tách biệt này giúp ứng dụng của bạn an toàn, dễ bảo trì và phù hợp với các best practice của ASP.NET Core.

Kết luận

Endpoint filter là một tính năng mạnh mẽ của ASP.NET Core Minimal API, cung cấp một cách gọn gàng và có thể tái sử dụng để thực thi logic trước và sau endpoint handler. Chúng giúp tách các mối quan tâm cắt ngang – như validation, logging, authentication, authorization và xử lý ngoại lệ – khỏi logic nghiệp vụ cốt lõi, dẫn đến các triển khai endpoint sạch sẽ và dễ bảo trì hơn.

Bằng cách gói các chức năng chung vào filter, nhà phát triển có thể giảm thiểu trùng lặp mã, cải thiện tính nhất quán giữa các endpoint và đơn giản hóa việc bảo trì ứng dụng. Dù được triển khai dưới dạng delegate cho các tình huống đơn giản, hay dưới dạng lớp implements giao diện IEndpointFilter cho chức năng phức tạp và tái sử dụng hơn, endpoint filter nâng cao tính linh hoạt, khả năng đọc và khả năng mở rộng của các ứng dụng Minimal API – khiến chúng trở thành công cụ thiết yếu để xây dựng các web API vững chắc và dễ bảo trì.

Bài tutorial tiếp theo – Cách thực hiện Unit và Integration Testing trong Minimal APIs

Bộ lọc Filters trong ASP.NET Core Minimal API