نحوه استفاده از فیلترهای مدیریت مسیر در حداقل APIها در ASP.NET Core 7

از حداقل فیلترهای API در ASP.NET Core 7 برای تغییر اشیاء درخواست و پاسخ یا اتصال کوتاه خط لوله پردازش درخواست استفاده کنید.

ASP.NET Core 6 یک مدل میزبانی ساده را معرفی کرد که به ما اجازه می دهد API های سبک وزن با حداقل وابستگی بسازیم. حداقل APIها در ASP.NET Core 6 از کنترلرها استفاده نمی کنند و آنها عدم پشتیبانی از تعدادی از ویژگی های مفید ASP.NET. یکی از این ویژگی‌های گمشده فیلترها هستند.

اما، با ASP.NET Core 7 (اکنون در کاندیدا انتشار)، می‌توانیم از رابط جدید معرفی‌شده IRouteHandlerFilter برای ترکیب فیلترها در حداقل API‌هایمان استفاده کنیم. از این فیلترها می توان برای اصلاح درخواست یا اشیاء پاسخ به دلخواه یا برای اتصال کوتاه خط لوله پردازش درخواست استفاده کرد.

این مقاله نحوه کار با فیلترهای کنترل کننده مسیر را در هنگام ساخت حداقل برنامه های API در ASP.NET Core 7 مورد بحث قرار می دهد. برای استفاده از نمونه کد ارائه شده در این مقاله، باید Visual Studio 2022 Preview را در سیستم خود نصب کنید. اگر قبلاً نسخه‌ای ندارید، می‌توانید Visual Studio 2022 را از اینجا بارگیری کنید.

یک پروژه ASP.NET Core 7 مینیمال Web API در Visual Studio 2022 ایجاد کنید

ابتدا، اجازه دهید یک پروژه ASP.NET Core 7 در Visual Studio 2022 Preview ایجاد کنیم. این مراحل را دنبال کنید:

1. Visual Studio 2022 Preview IDE را راه اندازی کنید.
2. روی “ایجاد پروژه جدید” کلیک کنید.
3. در پنجره “ایجاد پروژه جدید”، “ASP.NET Core Web API” را از لیست الگوهای نمایش داده شده انتخاب کنید.
4. بعدی را کلیک کنید.
5. در پنجره “پیکربندی پروژه جدید خود”، نام و مکان پروژه جدید را مشخص کنید.
6. به صورت اختیاری، بسته به تنظیمات برگزیده خود، کادر انتخاب «قرار دادن راه حل و پروژه در یک فهرست راهنمای» را علامت بزنید.
7. بعدی را کلیک کنید.
8. در پنجره «اطلاعات اضافی» که در ادامه نشان داده شده است، علامت کادری را که می‌گوید «استفاده از کنترل‌کننده‌ها…» را بردارید، زیرا در این مثال از حداقل API استفاده خواهیم کرد. “نوع احراز هویت” را به عنوان “هیچ” (پیش‌فرض) بگذارید.
9. مطمئن شوید که چک باکس‌های «Enable Docker»، «Configure for HTTPS» و «Enable Open API Support» علامت نخورده باشند زیرا ما در اینجا از هیچ یک از این ویژگی‌ها استفاده نخواهیم کرد.
10. روی ایجاد کلیک کنید.

ما از این پروژه ASP.NET Core 7 Web API برای ایجاد یک API حداقل و پیاده‌سازی فیلترهای مدیریت مسیر در بخش‌های زیر استفاده خواهیم کرد.

فیلترها چیست؟ چرا باید از آنها استفاده کنیم؟

فیلترها به شما امکان می دهند کد را در مراحل خاصی از خط لوله پردازش درخواست اجرا کنید. به عبارت دیگر فیلتر قطعه کدی است که قبل یا بعد از اجرای یک متد اکشن اجرا می شود. به عنوان مثال، می‌توانید از یک فیلتر برای ورود به سیستم هر بار که شخصی به یک صفحه وب دسترسی پیدا می‌کند یا برای تأیید اعتبار پارامترهای درخواست ارسال شده به نقطه پایانی استفاده کنید.

فیلترها چندین مزیت را ارائه می دهند:

• فیلترها با اجازه دادن به شما برای رد درخواست هایی که معیارهای خاصی (از جمله مجوز) را ندارند، برنامه شما را ایمن تر می کنند.
• فیلترها می‌توانند با ایجاد توابع و کلاس‌های قابل استفاده مجدد، به شما در پاکسازی کد کمک کنند.
• فیلترها به شما این امکان را می‌دهند که به جای صرف زمان برای نوشتن کد برای نگرانی‌های بین‌بخشی مانند گزارش‌گیری، رسیدگی به استثناها و امنیت، بر منطق تجاری برنامه خود تمرکز کنید.

چرا باید از فیلترها در حداقل APIها استفاده کنیم؟

می‌توانید از فیلترها در حداقل APIها برای نوشتن کدی استفاده کنید که می‌تواند کارهای زیر را انجام دهد:

• کد را قبل و بعد از کنترل کننده نقطه پایانی اجرا کنید.
• وقتی یک کنترل کننده نقطه پایانی اجرا می شود، پارامترها را بررسی و ویرایش کنید.
• رفتار پاسخ یک کنترل کننده نقطه پایانی را بررسی کنید.
• گزارش فراداده درخواست و پاسخ.
• مطمئن شوید که درخواست یک نسخه API پشتیبانی شده را هدف قرار می دهد.
• یک درخواست و پارامترهای درخواست را تأیید کنید.

رابط IRouteHandlerFilter در ASP.NET Core 7

می‌توانید از رابط IRouteHandlerFilter برای اصلاح درخواست یا پاسخ یا اتصال کوتاه خط لوله پردازش درخواست استفاده کنید. همچنین می‌توانید نگرانی‌های متقابلی مانند احراز هویت، مجوز، و ورود به سیستم را اضافه کنید. در یک نگاه سریع، آنچه می توانید با استفاده از این رابط به دست آورید:

• منطق سفارشی برای رسیدگی به درخواست های دریافتی بنویسید.
• یک درخواست را قطع کنید و شی درخواست را در صورت لزوم تغییر دهید.
• قبل از ارسال پاسخ، تغییراتی در آن ایجاد کنید.
• یک درخواست را اتصال کوتاه کنید، به این معنی که فیلترهای عملیاتی باقی مانده اجرا نمی شوند.

قطعه کد زیر رابط IRoutehandler را نشان می دهد:

namespace Microsoft.AspNetCore.Http;
public interface IRouteHandlerFilter
{
    ValueTask<object?> InvokeAsync(
        RouteHandlerInvocationContext context,
        RouteHandlerFilterDelegate next);
}

یک فیلتر کنترل کننده مسیر سفارشی در ASP.NET Core 7 ایجاد کنید

شما می توانید یک کلاس فیلتر سفارشی از طریق رابط IRouteHandlerFilter همانطور که در لیست کد زیر نشان داده شده است ایجاد کنید.

public class DemoFilter : IRouteHandlerFilter
{
    private ILogger _logger;
    public DemoFilter(ILoggerFactory loggerFactory)
    {
       _logger = logger;
    }
    public async ValueTask<object?> InvokeAsync(RouteHandlerInvocationContext context, RouteHandlerFilterDelegate next)
   {
        var text = context.GetParameters[0];
       if (text.Equals("Error"))
       {
          _logger.LogInformation(“Error.”);
          return Results.Problem("This is a minimal example of an error.");
       }
       _logger.LogInformation(“Success.”);
       return await next(context);
   }
}

در مرحله بعد، باید فیلتر را به عنوان یک سرویس در فایل Program.cs با استفاده از قطعه کد زیر ثبت کنید.

builder.Services.AddSingleton<DemoFilter>();

ثبت فیلتر با استفاده از روش RouteHandlerFilterDelegate یا افزونه AddFilter امکان پذیر است. در این مثال از متد افزونه AddFilter استفاده می کنیم. قطعه کد زیر را در فایل Program.cs بنویسید.

app.MapGet("/v1/MyDemoEndpoint{text}", “Hello”)
   .AddFilter<DemoFilter>();

یک فیلتر اتصال کوتاه در ASP.NET Core 7 ایجاد کنید

ممکن است اغلب لازم باشد خط لوله پردازش درخواست را اتصال کوتاه کنید. برای مثال، فرض کنید یک اپلیکیشن مبتنی بر میکروسرویس ساخته‌اید و یکی از سرویس‌ها پاسخ نمی‌دهد. در این صورت، تمام درخواست‌های این سرویس با شکست مواجه می‌شوند. درعوض، می‌توانید خط لوله پردازش درخواست را اتصال کوتاه کنید و از سرویس دیگری که سالم است استفاده کنید.

اتصال کوتاه اغلب اقدام مطلوب برای جلوگیری از پردازش غیر ضروری است. به عنوان مثال، اگر درخواستی برای فایل‌های ثابت مانند HTML، CSS، و جاوا اسکریپت ایجاد شود، می‌توانید فیلتری بنویسید که آن درخواست را رهگیری، رسیدگی، و در حالی که بقیه موارد را اتصال کوتاه می‌کند، بنویسید. خط لوله اتصال کوتاه خط لوله پردازش درخواست را متوقف می کند و درخواست را به یک روش یا سرویس بازگشتی هدایت می کند.

یک مثال دیگر از اتصال کوتاه، الگوی قطع کننده مدار در برنامه های کاربردی مبتنی بر میکروسرویس است. این الگو مانع از انجام عملیاتی می شود که ممکن است با شکست مواجه شود. به طور معمول، قطع کننده های مدار در صورت مواجهه با مشکل در یک سرویس یا یک روش سرویس، درخواست ها را به یک روش بازگشتی هدایت می کنند. بنابراین، هنگامی که به دلیل یک سرویس ناموفق قطع می‌شود، می‌توانید از قطع کننده‌های مدار برای هدایت درخواست به سرویس‌ها یا روش‌های بازگشتی استفاده کنید.

در اینجا چگونه می توانید یک فیلتر اتصال کوتاه سفارشی برای حداقل API خود پیاده سازی کنید:

public class MyShortCircuitFilter: IRouteHandlerFilter
{
    public ValueTask<object?> InvokeAsync(
        RouteHandlerInvocationContext context,
        RouteHandlerFilterDelegate next)
    {
        return new ValueTask<object?>(Results.Json
        (new { Message = "Terminated" }));
    }
}

فیلترها به شما امکان می دهند کدهای سفارشی را قبل یا بعد از یک نقطه خاص در خط لوله پردازش درخواست اجرا کنید. آنها همچنین به شما کمک می کنند تا از تکرار کد در بین اقدامات جلوگیری کنید. رابط IRouteHandlerFilter یک فیلتر ویژه است که می تواند روی کل یک مسیر یا یک هندلر اعمال شود. این به شما امکان می دهد به شی درخواست دسترسی داشته باشید و سپس درخواست یا پاسخ را در صورت لزوم تغییر دهید.