نحوه رسیدگی به خطاها در حداقل APIها در ASP.NET Core

چگونه از میان‌افزار مدیریت استثنا در ASP.NET Core برای رسیدگی به خطاها در حداقل برنامه‌های API خود استفاده کنید.

در ASP.NET Core 7، حداقل APIها روشی سبک برای ایجاد 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 ایجاد کنیم. این مراحل را دنبال کنید:

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

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

رسیدگی به خطاها در حداقل برنامه های API

کد منبع تولید شده پیش فرض فایل Program.cs را در پروژه ای که ایجاد کردیم با قطعه کد زیر جایگزین کنید.

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
app.MapGet("/", () => "Hello World!");
app.Map("/error", ()
    => {
            throw new InvalidOperationException("An Error Occurred...");
        });
app.Run();

هنگامی که برنامه را اجرا می کنید، پیام متنی “Hello World” در مرورگر وب شما نمایش داده می شود. اگر به نقطه پایانی /error مراجعه کنید، یک خطای زمان اجرا رخ می دهد و اجرای برنامه متوقف می شود، همانطور که در شکل ۱ نشان داده شده است.

شکل ۱. یک استثناء مرگبار در حداقل برنامه API ما.

دو مکانیسم داخلی برای رسیدگی به خطاها در حداقل برنامه های API وجود دارد، میان افزار Developer Exception Page و Exception Handler میان افزار. بیایید هر کدام را به ترتیب بررسی کنیم.

استفاده از میان افزار Developer Exception Page

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

در اینجا نمونه‌ای از نحوه استفاده از میان‌افزار صفحه استثنای توسعه‌دهنده در یک API حداقل آورده شده است.

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddEndpointsApiExplorer();
//builder.Services.AddSwaggerGen();
var app = builder.Build();
if (app.Environment.IsDevelopment())
{
   app.UseDeveloperExceptionPage();
}
app.MapGet("/", () => "Hello, world!");
app.Run();

در این مثال، از روش UseDeveloperExceptionPage برای افزودن میان افزار به خط لوله استفاده می شود. میان‌افزار تنها زمانی فعال می‌شود که برنامه در محیط توسعه اجرا می‌شود، که توسط متد ()app.Environment.IsDevelopment تعیین می‌شود.

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

شکل ۲. میان افزار صفحه استثنای توسعه دهنده در حال عمل است.

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

استفاده از میان افزار Exception Handler

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

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
app.UseExceptionHandler(exceptionHandlerApp
    => exceptionHandlerApp.Run(async context => await Results.Problem().ExecuteAsync(context)));
app.Map("/error", ()
    => { throw new InvalidOperationException("An Error Occurred..."); });
app.MapGet("/", () => "Hello, world!");
app.Run();

در این مثال، از روش UseExceptionHandler برای پیکربندی این میان افزار استفاده شده است. پارامتر “/error” نقطه پایانی را مشخص می کند که میان افزار در صورت استثنا به آن هدایت می شود.

اگر یک استثنا کنترل نشده در خط لوله رخ دهد، میان افزار Exception Handling آن را می گیرد و درخواست را به نقطه پایانی مشخص شده هدایت می کند. متعاقباً خطا بررسی می شود و یک پیام خطای مناسب برگردانده می شود.

با استفاده از میان‌افزار Exception Handling، می‌توانید به راحتی استثناهایی را که در حداقل APIها در ASP.NET Core 7 رخ می‌دهند، مدیریت کنید. این می‌تواند به بهبود قابلیت اطمینان و قابلیت استفاده API شما کمک کند.

استفاده از ProblemDetails برای قالب بندی پاسخ

کلاس ProblemDetails راهی برای گنجاندن جزئیات اطلاعات خطا برای جلوگیری از ایجاد فرمت‌های سفارشی پاسخ به خطا در ASP.NET Core است. روش افزودنی AddProblemDetails مربوط به رابط IServiceCollection می تواند برای ثبت اجرای پیش فرض IProblemDetailsService استفاده شود.

هنگامی که با متد AddProblemDetailsMiddleware در برنامه خود تماس می گیرید، میان افزار زیر در ASP.NET Core پاسخ های ProblemDetails HTTP ایجاد می کند.

• ExceptionHandlerMiddleware: این میان افزار برای ایجاد پاسخ ProblemDetails در صورتی که کنترل کننده سفارشی در دسترس نباشد استفاده می شود.
• DeveloperExceptionPageMiddleware: اگر هدر Accept HTTP حاوی متن/html نباشد، DeveloperExceptionPageMiddleware یک پاسخ ProblemDetails ایجاد می کند.
• StatusCodePagesMiddleware: به طور پیش فرض، StatusCodePagesMiddleware پاسخ های ProblemDetails را ایجاد می کند.

لیست کد زیر نشان می دهد که چگونه می توانید از ProblemDetails در حداقل API های خود استفاده کنید.

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddProblemDetails();
var app = builder.Build();
app.UseExceptionHandler();
app.UseStatusCodePages();
app.Map("/authors/{id:int}", (int id)
=> id <= 0 ? Results.BadRequest() : Results.Ok(new Author(id)));
app.Map("/error", ()
=> {
       throw new InvalidOperationException("An Error Occurred...");
   });
app.Run();
public record Author(int Id);

در این مثال، نقطه پایانی /error اطلاعات استثنا را از HttpContext استخراج می کند و یک شی ProblemDetails با جزئیات خطا ایجاد می کند. سپس کد وضعیت پاسخ و نوع محتوا را تنظیم می کند و شی ProblemDetails را به عنوان پاسخ JSON برمی گرداند.

استفاده از میان افزار Status Code Pages برای تولید بدنه پاسخ

وقتی یک برنامه ASP.NET Core با کدهای خطای HTTP مانند “۴۰۴ – یافت نشد” مواجه می شود، به طور پیش فرض صفحه کد وضعیت را ارائه نمی دهد. هر زمان که بدنه پاسخی برای کد وضعیت خطای HTTP 400-599 ارائه نشود، برنامه کد وضعیت و بدنه پاسخ خالی را برمی‌گرداند.

می توانید روش UseStatusCodePages را در فایل Program.cs برنامه خود فراخوانی کنید تا کنترل کننده های متنی را برای کدهای وضعیت خطای رایج فعال کنید. می توانید از کلاس StatusCodePagesMiddleware در ASP.NET Core برای ایجاد پاسخ همانطور که در قطعه کد زیر نشان داده شده است استفاده کنید.

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
app.UseStatusCodePages(async statusCodeContext
    => await Results.Problem(statusCode: statusCodeContext.HttpContext.Response.StatusCode)
                 .ExecuteAsync(statusCodeContext.HttpContext));
app.Map("/authors/{id:int}", (int id)
    => id <= 0 ? Results.BadRequest() : Results.Ok(new Author(id)));
app.Run();
public record Author(int Id);

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