یک کنترل کننده استثنا در ASP.NET Core 8 ایجاد کنید

از رابط جدید IExceptionHandler برای رسیدگی به استثناها در برنامه های ASP.NET Core خود بهره ببرید.

نسخه ماه نوامبر .NET 8 مایکروسافت انواع ویژگی های جدید و عالی را به ارمغان آورد. یکی از پیشرفت‌های خوب معرفی‌شده در ASP.NET Core 8، IExceptionHandler است، رابطی که مدیریت استثنائات را در برنامه‌های وب ASP.NET Core آسان‌تر می‌کند.

رسیدگی به خطاها سابقه طولانی در زبان‌ها و چارچوب‌های برنامه‌نویسی دارد. IExceptionHandler خطا را ساده می کند مدیریت با ارائه یک پاسخ تماس و یک مکان مرکزی برای رسیدگی به استثناهای شناخته شده. در این مقاله به نحوه استفاده از IExceptionHandler در برنامه‌های ASP.NET Core 8 و ارائه پاسخ‌های خطای معنادار به کاربر می‌پردازیم.

برای استفاده از نمونه کدهای ارائه شده در این مقاله، باید Visual Studio 2022 را در سیستم خود نصب کنید. اگر قبلاً نسخه‌ای ندارید، می‌توانید Visual Studio 2022 را از اینجا بارگیری کنید.

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

برای ایجاد یک پروژه ASP.NET Core 8 Web API در Visual Studio 2022، مراحل ذکر شده در زیر را دنبال کنید.

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

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

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

در ASP.NET Core، یک کنترل کننده استثناء مؤلفه ای است که می تواند استثناها را به صورت سراسری در یک برنامه مدیریت کند. می‌تواند همه استثناهای کنترل نشده را بگیرد و سپس پاسخ‌های خطای مناسب را ایجاد کند.

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

اجازه دهید این را با یک مثال درک کنیم. کد زیر را در نظر بگیرید.

using Microsoft.AspNetCore.Diagnostics;
using Microsoft.AspNetCore.Mvc;
using System.ComponentModel.DataAnnotations;
using System.Net;
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
app.UseExceptionHandler(opt => { });
app.MapGet("/GenerateError", () =>
{
    throw new NotImplementedException();
});
app.Run();

هنگامی که برنامه را اجرا می‌کنید و نقطه پایانی /GenerateError را می‌زنید، پاسخی که در مرورگر وب شما نمایش داده می‌شود مطابق شکل زیر ظاهر می‌شود.

شکل ۱: پاسخ بدون استفاده از کنترل‌کننده‌های استثنا ایجاد می‌شود.

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

معرفی رابط IExceptionHandler

مدیریت استثناها برای چندین دهه در زبان های برنامه نویسی برای رسیدگی به خطاهای زمان اجرا در برنامه ها استفاده شده است. ASP.NET Core 8 مدیریت استثنا را به طور قابل توجهی با معرفی رابط IExceptionHandler بهبود می بخشد. می توانید با پیاده سازی رابط IExceptionHandler یک کلاس مرکزی برای مدیریت استثنا در ASP.NET Core 8 ایجاد کنید.

رابط IExceptionHandler به شکل زیر است:

public interface IExceptionHandler
{
    ValueTask<bool> TryHandleAsync(HttpContext httpContext, Exception exception, CancellationToken cancellationToken);
}

اینترفیس IExceptionHandler حاوی اعلان متد TryHandleAsync است. این روش سه پارامتر را می پذیرد: یک نمونه از نوع HttpContext، یک Exception و یک CancellationToken. ValueTask را برمی گرداند تا نشان دهد که آیا استثنا با موفقیت انجام شده است یا خیر.

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

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

برای پیاده سازی رابط IExceptionHandler، یک کلاس جدید به نام GlobalExceptionHandler در فایلی به همین نام با پسوند cs ایجاد کنید. و کد زیر را در آنجا وارد کنید.

public class GlobalExceptionHandler(IHostEnvironment hostEnvironment, ILogger<GlobalExceptionHandler> logger)
    : IExceptionHandler
{
    public async ValueTask<bool> TryHandleAsync(HttpContext httpContext, Exception exception, CancellationToken cancellationToken)
    {
        return true;
    }
}

منطق مدیریت خطای سفارشی شما باید در روش TryHandleAsync باشد. قطعه کد زیر نشان می دهد که چگونه می توانید استثناهایی را که در برنامه شما به طور ناهمزمان رخ می دهند مدیریت کنید.

private const string ExceptionMessage = "An unhandled exception has occurred while executing the request.";

همگام عمومی ValueTask TryHandleAsync(HttpContext httpContext، استثنا استثنا، CancellationToken cancellationToken)

    logger.LogError(exception, استثناء Exception است؟ استثنا است. Message : ExceptionMessage)؛

    var problemDetails = CreateProblemDetails(httpContext، استثنا)؛

    منتظر httpContext.Response.WriteAsJsonAsync(problemDetails, cancellationToken)؛

    true;

}

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

private ProblemDetails CreateProblemDetails(in HttpContext httpContext, in Exception exception)

    httpContext.Response.ContentType = “application/json”;

    سوئیچ (استثنا)

    {

        مورد NotImplementedException notImplementedException:

            httpContext.Response.StatusCode = (int)HttpStatusCode.BadRequest;

            شکست؛

        پیش‌فرض:

            httpContext.Response.StatusCode = (int)HttpStatusCode.InternalServerError;

            شکست؛

    }

    جزئیات مشکل جدید را برگردانید

    {

        وضعیت = (int)httpContext.Response.StatusCode،

        Type = استثنا.GetType().Name,

        عنوان = “یک خطای غیرمنتظره روی داد”،

        جزئیات = استثنا. پیام،

        نمونه = $”{httpContext.Request.Method} {httpContext.Request.Path}”

    };

}

کد منبع کامل کنترل کننده استثنای سفارشی ما

فهرست کد زیر شامل کد منبع کامل کلاس GlobalExceptionHandler است.

public class GlobalExceptionHandler(IHostEnvironment hostEnvironment, ILogger<GlobalExceptionHandler> logger)

    : IExceptionHandler

    const private string ExceptionMessage = “یک استثناء کنترل نشده در حین اجرای درخواست رخ داده است.”;

    همگام‌سازی عمومی ValueTask TryHandleAsync(HttpContext httpContext، استثنا استثنا، CancellationToken cancellationToken)

    {

        logger.LogError(exception, استثناء Exception است؟ استثنا است. Message : ExceptionMessage)؛

        var problemDetails = CreateProblemDetails(httpContext، استثنا)؛

        در انتظار httpContext.Response.WriteAsJsonAsync(problemDetails, cancellationToken)؛

        true;

    }

    ProblemDetails خصوصی CreateProblemDetails (در HttpContext httpContext، در استثناء استثناء)

    {

        httpContext.Response.ContentType = “application/json”;

        سوئیچ (استثنا)

        {

            مورد NotImplementedException notImplementedException:

                httpContext.Response.StatusCode = (int)HttpStatusCode.BadRequest;

                شکست؛

            پیش‌فرض:

                httpContext.Response.StatusCode = (int)HttpStatusCode.InternalServerError;

                شکست؛

        }

        جزئیات مشکل جدید را برگردانید

        {

            وضعیت = (int)httpContext.Response.StatusCode،

            Type = استثنا.GetType().Name,

            عنوان = “یک خطای غیرمنتظره رخ داد”،

            جزئیات = استثنا. پیام،

            Instance = $”{httpContext.Request.Method} {httpContext.Request.Path}”

        }؛

    }

}

کنترل کننده استثنا را با خط لوله پردازش درخواست ثبت کنید

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

builder.Services.AddExceptionHandler<GlobalExceptionHandler>();

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

app.MapGet("/GenerateError", () =>

    ValidationException();

جدید را پرتاب کنید

})؛

فراخوانی به روش UseExceptionHandler() خط لوله پردازش درخواست را در ASP.NET Core پیکربندی می‌کند تا استثنائات را با استفاده از میان‌افزار ما مدیریت کند.

app.UseExceptionHandler(opt => { });

اکنون وقتی برنامه را اجرا می کنید و نقطه پایانی /GenerateError را می زنید، پاسخ نمایش داده شده در مرورگر وب به صورت زیر ظاهر می شود. خیلی بهتر است!

شکل ۲: پاسخ خطا با استفاده از کنترل کننده خطا ایجاد شده است.

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