نحوه استفاده از نشانه های لغو در ASP.NET Core 7

از توکن های لغو در ASP.NET Core استفاده کنید تا عملیات طولانی مدت را به خوبی لغو کنید و برنامه ها را پاسخگو نگه دارید.

اگرچه ASP.NET Core 7 آخرین نسخه چارچوب توسعه برنامه وب منبع باز مایکروسافت است، اما از ویژگی های بی شماری قابل توجه نسخه های قبلی دات نت بهره می برد. یکی از این ویژگی‌های مهم، توکن‌های لغو است که راهی برای رسیدگی به برنامه‌های چند رشته‌ای ارائه می‌دهد.

هنگام کار با برنامه‌های ASP.NET Core، تمرین خوبی است که عملیات طولانی‌مدت (مانند پرس و جو پایگاه داده یا فرآیند پس‌زمینه) را پس از مدت زمان معینی یا در صورت درخواست کاربر لغو کنید تا برنامه بتواند منابع را آزاد کنید و پاسخگو باشید. در اینجا نشانه‌های لغو وارد عمل می‌شوند.

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

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

ابتدا، اجازه دهید یک پروژه ASP.NET Core minimal API در ویژوال استودیو ایجاد کنیم. با دنبال کردن این مراحل، یک پروژه ASP.NET Core 7 Web API جدید در 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 و کار با نشانه‌های لغو استفاده خواهیم کرد.

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

یک CancellationToken یک شی سبک وزن است که توسط یک نمونه CancellationTokenSource ایجاد شده است. هنگامی که CancellationTokenSource لغو می شود، به همه مصرف کنندگان CancellationTokens اطلاع داده می شود. علاوه بر این، ویژگی IsCancellationRequested نمونه نشانه لغو روی true تنظیم شده است، که نشان می دهد CancellationTokenSource لغو شده است و لغو کار درخواست شده است.

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

می‌توانید از CancellationTokens برای متوقف کردن کارهای ناهمگام‌سازی نیز استفاده کنید. در یک کار ناهمگام، لغو نشان می دهد که کار باید فعالیت فعلی خود را متوقف کند. یک کار ناهمگام یک نشانه لغو را دریافت می کند و آن را بررسی می کند تا ببیند آیا لغو درخواست شده است یا خیر. در این صورت، عملیات فعلی باید فوراً متوقف شود.

درخواست های طولانی در ASP.NET Core

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

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

گوش دادن به درخواست های لغو در ASP.NET Core

شما می‌توانید با نظرسنجی ارزش ویژگی CancellationToken.IsCancellationRequested همانطور که در قطعه کد زیر نشان داده شده است، به درخواست‌های لغو گوش دهید.

while(!cancellationToken.IsCancellationRequested)
{
     //Write your code here to perform some operation
}

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

while(true)
{
     //Write your code here to perform some operation
     cancellationToken.ThrowIfCancellationRequested();
}

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

WebClient webClient = new WebClient();   
cancellationToken.Register(() =>
{
    webClient.CancelAsync();
});

یک کنترلر API حداقل در ASP.NET Core ایجاد کنید

بیایید اکنون یک درخواست طولانی را شبیه سازی کنیم و ببینیم لغو چگونه کار می کند. ابتدا یک درخواست طولانی مدت را بدون لغو امتحان می کنیم. کد زیر را در فایل Program.cs بنویسید.

app.MapGet("/hello", async () =>
{
    app.Logger.LogInformation("Request started at: "+DateTime.Now.ToLongTimeString());
    await Task.Delay(TimeSpan.FromSeconds(5));
    app.Logger.LogInformation("Request completed at: " + DateTime.Now.ToLongTimeString());
    return "Success";
});

وقتی این برنامه را اجرا می‌کنید و نقطه پایانی /hello را می‌زنید، می‌بینید که کنترل‌کننده به طور کامل اجرا می‌شود، حتی اگر بخواهید با تازه کردن مرورگر وب همانطور که در شکل ۱ نشان داده شده است، درخواست را متوقف کنید.

شکل ۱: بدون لغو، کنترل کننده به طور کامل اجرا می شود حتی اگر درخواست توسط کاربر لغو شود.

از CancellationToken در حداقل API handler

استفاده کنید

لیست کد زیر نشان می‌دهد که چگونه می‌توانید CancellationToken را به کنترل‌کننده نقطه پایانی ما تزریق کنید و این نشانه را به روش Task.Delay ارسال کنید.

app.MapGet("/hello", async (CancellationToken token) =>
{
    app.Logger.LogInformation("Request started at: " + DateTime.Now.ToLongTimeString());
    await Task.Delay(TimeSpan.FromSeconds(5), token);
    app.Logger.LogInformation("Request completed at: " + DateTime.Now.ToLongTimeString());
    return "Success";
});

اکنون وقتی برنامه را اجرا می‌کنید و نقطه پایانی /hello را می‌زنید، بازخوانی مرورگر وب قبل از تکمیل درخواست، درخواست را متوقف می‌کند. از گزارش‌ها خواهید دید که درخواست هرگز تکمیل نمی‌شود. در عوض، یک TaskCancelledException پرتاب می شود زیرا ویژگی CancellationToken.IsCancellationRequested روی true تنظیم می شود.

پیام های استثنا شامل اطلاعات ردیابی درخواست لغو شده همانطور که در شکل ۲ نشان داده شده است.

شکل ۲: هنگامی که لغو در کد کنترل کننده استفاده شده است، درخواستی که در میانه راه لغو می شود تکمیل نمی شود.

بررسی وضعیت لغو در ASP.NET Core

شاید اغلب بخواهید بدانید که آیا لغو در یک نشانه لغو درخواست شده است یا خیر. با بررسی ویژگی IsCancellationRequested می توانید وضعیت لغو را بررسی کنید. اگر لغو روی توکن درخواست شده باشد، ویژگی IsCancellationRequested درست خواهد بود (یعنی مقدار بولی درست خواهد داشت) در غیر این صورت نادرست است.

همانطور که در بالا ذکر شد، اگر نمونه نشانه لغو درخواست لغو کرده باشد، روش CancellationToken.ThrowIfCancellationRequested یک OperationCanceledException ایجاد می کند.

قطعه کد زیر نشان می‌دهد که چگونه می‌توان از ویژگی IsCancellationRequested برای بررسی اینکه آیا توکن درخواست لغو کرده است استفاده کرد. اگر درخواست لغو شده باشد، یک نمونه از OperationCanceledException پرتاب می شود.

if (token.IsCancellationRequested)
{
    app.Logger.LogInformation("Request has been cancelled..");
    throw new OperationCanceledException();
}

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

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