از فیلترهای نقطه پایانی در ASP.NET Core 7 برای تغییر اشیاء درخواست و پاسخ، اتصال کوتاه به خط لوله پردازش درخواست، یا رسیدگی به نگرانی های مقطعی برای هر درخواست استفاده کنید.
با ASP.NET Core 7، می‌توانیم از رابط جدید معرفی‌شده IEndpointFilter برای ایجاد فیلترها و وصل کردن آنها به نقاط پایانی در حداقل APIهایمان استفاده کنیم. از این فیلترها می توان برای تغییر اشیاء درخواست یا پاسخ یا برای اتصال کوتاه خط لوله پردازش درخواست استفاده کرد.
این مقاله نحوه کار با فیلترهای نقطه پایانی را در هنگام ساخت حداقل برنامه های API در ASP.NET Core 7 مورد بحث قرار می دهد. برای استفاده از نمونه کد ارائه شده در این مقاله، باید Visual Studio 2022 را در سیستم خود نصب کنید. اگر قبلاً نسخه‌ای ندارید، می‌توانید Visual Studio 2022 را از اینجا بارگیری کنید.
یک پروژه ASP.NET Core 7 مینیمال Web API در Visual Studio 2022 ایجاد کنید
ابتدا، اجازه دهید یک پروژه ASP.NET Core 7 در Visual Studio 2022 Preview ایجاد کنیم. این مراحل را دنبال کنید:
- Visual Studio 2022 IDE را راه اندازی کنید.
- روی “ایجاد پروژه جدید” کلیک کنید.
- در پنجره “ایجاد پروژه جدید”، “ASP.NET Core Web API” را از لیست الگوهای نمایش داده شده انتخاب کنید.
- بعدی را کلیک کنید.
- در پنجره “پیکربندی پروژه جدید خود”، نام و مکان پروژه جدید را مشخص کنید.
- به صورت اختیاری، بسته به تنظیمات برگزیده خود، کادر انتخاب «قرار دادن راه حل و پروژه در یک فهرست راهنمای» را علامت بزنید.
- بعدی را کلیک کنید.
- در پنجره «اطلاعات اضافی» که در ادامه نشان داده شده است، «NET 7.0 (Current)» را به عنوان چارچوب انتخاب کنید و تیک کادری که می گوید «استفاده از کنترلرها…» را بردارید زیرا در این مثال از حداقل API استفاده خواهیم کرد. «نوع احراز هویت» را روی «هیچ‌کدام» (پیش‌فرض) بگذارید.
- مطمئن شوید که چک باکس‌های “فعال کردن پشتیبانی OpenAPI”، “Enable Docker”، “Configure for HTTPS” و “Enable Open API Support” علامت نخورده باشند زیرا ما در اینجا از هیچ یک از این ویژگی‌ها استفاده نخواهیم کرد.
- روی ایجاد کلیک کنید.
ما از این پروژه ASP.NET Core 7 Web API برای ایجاد یک API حداقل و پیاده‌سازی فیلترهای نقطه پایانی در بخش‌های زیر استفاده خواهیم کرد.
فیلتر نقطه پایانی چیست؟
فیلتر کدی است که می تواند در نقاط مختلف در طول خط لوله پردازش درخواست، قبل یا بعد از یک اقدام اجرا شود. می‌توانید از یک فیلتر برای بررسی مجوز، یا بررسی پارامترهای درخواست، یا برای ضبط هر بار دسترسی به یک صفحه وب استفاده کنید.
یک فیلتر نقطه پایانی را می توان در اقدامات و در نقاط پایانی مسیر فراخوانی کرد. نقطه پایانی آدرس اینترنتی است که نقطه ورودی یک برنامه کاربردی است، مانند http://example.com/.
مزایای کلیدی فیلترها شامل امنیت بیشتر و ساده کردن پایه کد شما از طریق استفاده مجدد از کد است. به عنوان مثال، می توانید از فیلترها برای:
استفاده کنید
- درخواست‌هایی را رد کنید که معیارهای خاصی را ندارند.
- توابع و کلاس های قابل استفاده مجدد ایجاد کنید.
- به جای صرف زمان برای نوشتن کد برای نگرانی های بین بخشی، روی منطق تجاری برنامه خود تمرکز کنید.
- کد را قبل و بعد از کنترل کننده نقطه پایانی اجرا کنید.
- گزارش فراداده درخواست و پاسخ.
- یک درخواست و پارامترهای درخواست را تأیید کنید.
یک فیلتر نقطه پایانی به شما امکان می‌دهد درخواست ورودی را رهگیری کنید، آن را تغییر دهید، آن را اتصال کوتاه کنید، و حتی نگرانی‌های متقابل خود را در یک مکان واحد تجمیع کنید. نمونه‌های معمولی از نگرانی‌های مقطعی که می‌توان در یک کلاس واحد رسیدگی کرد عبارتند از: مجوز، اعتبارسنجی، و رسیدگی به استثنا.
رابط فیلتر نقطه پایانی در ASP.NET Core i7
ASP.NET Core 7 یک رابط جدید به نام IEndpointFilter معرفی می کند که می تواند برای تغییر درخواست، تغییر پاسخ یا اتصال کوتاه خط لوله درخواست استفاده شود. رابط IEndpointFilter می تواند برای افزودن اطلاعات به درخواست های دریافتی قبل از پردازش آنها توسط نقطه پایانی استفاده شود.
واسط IEndpointFilter در فضای نام Microsoft.AspNetCore.Http مطابق شکل زیر تعریف شده است.
public interface IEndpointFilter
{
ValueTask<object?> InvokeAsync(
EndpointFilterInvocationContext context,
EndpointFilterDelegate next);
}
چرا باید از رابط IEndpointFilter استفاده کنم؟
واسط IEndpointFilter برای افزودن قابلیت به نقطه پایانی HTTP استفاده می شود. این یک رابط ساده با تنها یک روش به نام InvokeAsync است که می تواند منطق سفارشی را به خط لوله درخواست/پاسخ اضافه کند.
وقتی می‌خواهید درخواست یا پاسخ را در نقطه خاصی از خط لوله تغییر دهید، می‌توانید از رابط IEndpointFilter استفاده کنید. می‌توانید از آن برای قرار دادن تمام اجزای متقاطع خود، مانند ورود به سیستم، احراز هویت، مجوز، و رمزگذاری، در یک مکان استفاده کنید، جایی که می‌توانید بدون تغییر هیچ بخش دیگری از کد برنامه‌تان که از این مؤلفه‌ها استفاده می‌کند، آنها را نگهداری کنید.
یک فیلتر نقطه پایانی در ASP.NET Core 7 ایجاد کنید
می توانید با استفاده از نماینده ای که EndPointFilterInvocationContext را به عنوان پارامتر می پذیرد و یک EndpointFilterDelegate را برمی گرداند، یک فیلتر را ثبت کنید. نمونه EndPointFilterInvocationContext دسترسی به HttpContext درخواست فعلی را فراهم می کند.
قطعه کد زیر نشان می دهد که چگونه می توانید یک فیلتر نقطه پایانی ساده ایجاد کنید که مقداری متن را برمی گرداند. توجه داشته باشید که چگونه از HttpContext برای بازیابی هدرهای درخواست استفاده شده است.
string AuthorName(string author) => $"Name of author: {author}";
app.MapGet("/endpointfilterexample/{author}", AuthorName)
.AddEndpointFilter(async (invocationContext, next) =>
{
var httpContext = invocationContext.HttpContext;
var requestHeaders = httpContext.Request.Headers;
var author = invocationContext.GetArgument<string>(0);
return await next(invocationContext);
});
هنگامی که قطعه کد قبلی را اجرا می کنید، سرصفحه های درخواست همانطور که در شکل ۱ در زیر نشان داده شده است نمایش داده می شود.
شکل ۱. فیلترهای نقطه پایانی ASP.NET Core 7 در حال عمل هستند.
چند فیلتر نقطه پایانی را در ASP.NET Core 7 با هم زنجیره بزنید
کد زیر نشان می‌دهد که چگونه چندین فیلتر نقطه پایانی می‌توانند در نقطه پایانی پیش‌فرض به هم متصل شوند.
app.MapGet("/", () =>
{
return "Demonstrating multiple filters chained together.";
})
.AddEndpointFilter(async (endpointFilterInvocationContext, next) =>
{
app.Logger.LogInformation("This is the first filter.");
var result = await next(endpointFilterInvocationContext);
return result;
})
.AddEndpointFilter(async (endpointFilterInvocationContext, next) =>
{
app.Logger.LogInformation("This is the second filter.");
var result = await next(endpointFilterInvocationContext);
return result;
})
.AddEndpointFilter(async (endpointFilterInvocationContext, next) =>
{
app.Logger.LogInformation("This is the third context.");
var result = await next(endpointFilterInvocationContext);
return result;
});
هنگامی که نقطه پایانی را اجرا می کنید، سه فیلتر نقطه پایانی یکی پس از دیگری اجرا می شوند.
ایجاد یک فیلتر سفارشی در یک API حداقل در ASP.NET Core 7
همچنین می‌توانید فیلترهای سفارشی را با پیاده‌سازی رابط IEndpointFilter همانطور که در قطعه کد زیر نشان داده شده است ایجاد کنید.
public class MyCustomFilter : IEndpointFilter
{
public async ValueTask<object?> InvokeAsync(
EndpointFilterInvocationContext context,
EndpointFilterDelegate next
)
{
if (context.HttpContext.GetRouteValue("city") is string city)
{
return Results.Ok($"The name of the city is: {city}");
}
return await next(context);
}
}
app.MapGet("/demo/{city}", () =>
{
return "Execute filters in a chain.";
})
.AddEndpointFilter<MyCustomFilter>();
برای دسترسی به پارامترهای مرتبط با یک درخواست HTTP خاص، می‌توانید از روش GetArguments شی EndpointFilterInvocationContext استفاده کنید. اگر چندین فیلتر دارید، می توانید آنها را با استفاده از کد زیر در فایل Program.cs خود ثبت کنید.
app.MapGet("/", () =>
{
return "This is a sample text.";
})
.AddEndpointFilter<MyCustomFilterA>()
.AddEndpointFilter<MyCustomFilterB>()
.AddEndpointFilter<MyCustomFilterC>();
فیلترها در ASP.NET Core به شما این امکان را می دهند که کدهای سفارشی را قبل یا بعد از نقطه خاصی در خط لوله پردازش درخواست اجرا کنید. شما می توانید از فیلترهای نقطه پایانی برای اتصال کوتاه اجراهای نقطه پایانی استفاده کنید یا منطق اعتبارسنجی را در حداقل API خود پیاده سازی کنید. در پست آینده در اینجا درباره فیلترهای نقطه پایانی با جزئیات بیشتری صحبت خواهم کرد.
پست های مرتبط
نحوه کار با فیلترهای نقطه پایانی در ASP.NET Core 7
نحوه کار با فیلترهای نقطه پایانی در ASP.NET Core 7
نحوه کار با فیلترهای نقطه پایانی در ASP.NET Core 7