آموزش کار با Logging در ASP.NET Core

Logging آموزشی که در ادامه بیشتر در مورد آن بحث میکنیم.فریمورک ASP.NET Core برای ثبت رویداد یا همان logging پشتیبانی هایی را ارائه داده است. با این وجود، ما باز هم می توانیم به راحتی از کتابخانه های ارائه دهنده ثبت Logging در اپلیکیشن ASP.NET Core استفاده کنیم.

قبل از اینکه به سراغ پیاده سازی ثبت Logging در برنامه ASP.NET Core برویم، ابتدای کار با اینترفیس ها و کلاس های مهم ثبت Logging موجود در فریمورک ASP.NET Core آشنا می شویم. موارد زیر اینترفیس ها و کلاس های تعبیه شده موجود برای ثبت Logging در فضای نام Microsoft.Extensions.Logging است.

بررسی Logging

• ILoggingFactory
• ILoggingProvider
• ILogger
• LoggingFactory

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

در ادامه هر یک از این کلاس ها را باهم مرور می کنیم.

ILoggerFactory:

ILoggerFactory اینترفیس فکتوری برای ایجاد یک شی مناسب از نوع ILogger و همچنین برای اضافه کردن شی ILoggerProvider است.

public interface ILoggerFactory : IDisposable
{
    ILogger CreateLogger(string categoryName);
    void AddProvider(ILoggerProvider provider);
}

فریمورک ASP.NET Core شامل کلاس تعبیه شده LoggerFactory است که اینترفیس ILoggerFactory را پیاده سازی می کند. می توانیم از آن برای اضافه کردن شیی از نوع ILoggerProvider و بازیابی شی ILogger برای طبقه بندی خاصی استفاده کنیم.

ASP.NET Core زمان اجرا یک شی از کلاس LoggerFactory می سازد و زمانی که اپلیکیشن استارت می شود، با IoC container تعبیه شده آن را برای ILoggerFactory رجیستر می کند. بنابراین، می توانیم اینترفیس ILoggerFactory را هرجایی در برنامه استفاده کنیم. IoC container هرجایی از اپلیکیشن که با نوع ILoggerFactory مواجه شود، یک شی از LoggerFactory ارسال می کند.

ILoggerProvider:

ILoggerProvider ثبت کننده رویدادی (logger) مناسب مشخص شده با طبقه بندی ثبت رویداد را ایجاد و مدیریت می کند.

ILoggerProvider

public interface ILoggerProvider : IDisposable
{
   ILogger CreateLogger(string categoryName);
}

علاوه براین ما با پیاده سازی اینترفیس ILoggerProvider می توانیم ارائه دهنده ثبت رویداد دلخواه خود را ایجاد کنیم.

ILogger:

اینترفیس ILogger شامل متدهایی برای ثبت رویداد در محل ذخیره سازی اصلی است.

ILogger

public interface ILogger
{
    void Log<TState>(LogLevel logLevel, EventId eventId, TState state, Exception exception, Func<TState, Exception, string> formatter);
    bool IsEnabled(LogLevel logLevel);
    IDisposable BeginScope<TState>(TState state);
} 

ارائه دهندگان ثبت رویداد (Logging Providers) تعبیه شده:

ارائه دهندگان ثبت رویداد متفاوتی مانند NuGet packages وجود دارند که می توانیم برای ارسال خروجی رویداد به رسانه های مختلفی مانند console، پنجره debug، EventSource وغیره استفاده کنیم. ASP.NET Core از ارائه دهندگان زیر برای ارسال رویداد استفاده می کند:

1. console
2. Debug
3. EventSource
4. EventLog
5. TraceSource
6. Azure App Service

در ادامه ثبت کننده رویداد Console را مرور خواهیم کرد.

Console Logger:

پکیج Microsoft.Extensions.Logging.Console شامل کلاس های ثبت رویداد است که خروجی رویداد را به console ارسال می کند. موارد زیر کلاس های مهم برای ثبت رویداد console است.

1. ConsoleLoggingProvider
2. ConsoleLogger
3. ConsoleLoggerExtension
4. ConsoleLoggerSettings
5. ConsoleLoggerScope

شکل زیر کلاس های ثبت کننده رویداد را نشان می دهد.

همانطور که در شکل بالا می بینید، کلاس ConsoleLogger اینترفیس ILogger، کلاس ConsoleLoggingProvider اینترفیس ILoggingProvider را پیاده سازی می کند. کلاس ConsoleLoggerExtensions شامل متد افزونه ()AddConsole است که console logger را به LoggerFactory اضافه می کند.

حالا، در این مرحله از console logger استفاده می کنیم تا خروجی ثبت رویداد به console را در هر دو اپلیکیشن ASP.NET Core 1.x, 2.x نمایش دهیم.

مرحله ۱ – نصب NuGet Package

ASP.NET Core 1.x:

وابستگی Microsoft.Extensions.Logging.Console را اگر در حال حاضر در فایل project.json وجود ندارد، اضافه می کنیم.

"dependencies": {
        "Microsoft.NETCore.App": {
            "version": "1.0.1",
            "type": "platform"
        },
        "Microsoft.AspNetCore.Diagnostics": "1.0.0",
        "Microsoft.AspNetCore.Server.IISIntegration": "1.0.0",
        "Microsoft.AspNetCore.Server.Kestrel": "1.0.1",
        "Microsoft.Extensions.Logging.Console": "1.0.0"
    } 

به محض اینکه project.json ذخیره شود، ویژوال استودیو این پکیج را به صورت خودکار بازیابی می کند.

ASP.NET Core 2.x:

به طور پیش فرض، Microsoft.Extensions.Logging.Console در متا پکیج Microsoft.AspNetCore.All وارد شده است، به همین دلیل نیازی به نصب جداگانه آن در اپلیکیشن ASP.NET Core 2.x نیست.

مرحله ۲ – استفاده از Provider

ASP.NET Core 1.x:

حالا، برای استفاده از console logger ابتدا باید آن را پیکربندی کنیم. ابتدا باید با استفاده از LoggerFactory، ConsoleLoggerProvider را به لیست ارائه دهنده ها اضافه کنیم. همانطور که در کلاس LoggerFactory بالا می بینید، این کلاس متد ()AddProvider را ارائه می دهد که شی نوع سفارشی ILoggerProvider را به لیست اضافه می کند. پکیج Microsoft.Extensions.Logging.Console شامل همه کلاس های ضروری است. به این ترتیب، می توانیم شی ConsoleLoggerProvider را به شکل زیر اضافه کنیم.

مثال: اضافه کردن ConsoleLoggerProvider

public class Startup
{
    public Startup()
    {
    } 
 
    public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
    {
        loggerFactory.AddProvider(new ConsoleLoggerProvider((category, logLevel) => logLevel >= LogLevel.Information, false));
        
        //code removed for clarity 
    }
}

همانطور که می بینید، ما یک شی ConsoleLoggerProvider به فکتوری اضافه می کنیم. حالا، می توانیم ثبت رویداد را شروع کنیم. کنسول تمامی رویدادهایی که LogLevel آن Information یا بالاتر است نمایش خواهد داد.

علاوه براین به جای پیکربندی دستی console logger می توانیم از متد افزونه AddConsole() به شکل زیر استفاده کنیم.

مثال: اضافه کردن Console Logger

public class Startup
{
    public Startup()
    {
    } 
 
    public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
    {
        loggerFactory.AddConsole();

        //code removed for clarity 
    }
}

ASP.NET Core 2.x:

در حال حاضر ()CreateDefaultBuilder ارائه دهندگان ثبت رویداد console و debug را شامل می شود. به همین دلیل در اپلیکیشن ASP.NET Core 2.x نیازی نیست که دوباره آن را در متد Configure() اضافه کنیم.

مرحله ۳ – ایجاد رویدادها

این مرحله برای هر دو اپلیکیشن ASP.NET Core 1.x , 2.x یکسان است.

حالا می توانیم رویدادها را ایجاد کرده و با استفاده از LoggerFactory و گرفتن یک شی ILogger آن را در console ببینیم و ثبت رویداد را به شکل زیر شروع کنیم.

مثال: اضافه کردن Console Logger

public class Startup
{
    public Startup()
    {
    } 
 
    public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
    {

        loggerFactory.AddConsole();

        //start logging to the console
        var logger = loggerFactory.CreateLogger<ConsoleLogger>();
        logger.LogInformation("Executing Configure()");

        //code removed for clarity 
    }
}

همچنین می توانیم هرجایی در اپلیکیشن از ILogger استفاده کنیم. IoC container هرجایی که ILogger ببیند، شی ConsoleLogger را تزریق خواهد کرد. به عنوان مثال، می توانیم به شکل زیر از ILogger در MVC-controller استفاده کنیم.

مثال: ثبت رویداد در MVC Controller

public class HomeController : Controller
{
    ILogger _logger;

    public HomeController(ILogger<HomeController> logger)
    {
        _logger = logger;
    }
    public IActionResult Index()
    {
        _logger.LogInformation("Executing Home/Index");

        return View();
    } 
}

زمانی که http://localhost:5000/home/index را در مرورگر باز کنیم، گزارش رویدادها را در کنسول مشاهده خواهیم کرد.

با دنبال کردن همین فرایند می توانیم از هریک از ارائه دهندگان ثبت رویداد تعبیه شده که در بالا اشاره شد استفاده کنیم.

سطوح ثبت رویداد:

سطوح ثبت رویداد به اهمیت و دقت پیام های ثبت رویداد اشاره دارد. ارائه دهندگان ثبت رویداد تعبیه شده شامل متدهای افزونه ای برای اشاره به سطوح ثبت رویداد هستند.

ASP.NET Core سطوح ثبت رویداد زیر را تعریف می کند.

سطح ثبت خطا	دقت	متد افزونه	توضیح
Trace	۰	()LogTrace	پیام های ثبت رویداد فقط برای Trace کردن برنامه نویس نوشته می شوند.
Debug	۱	()LogDebug	پیام های ثبت رویداد برای اهداف اشکال زدایی کوتاه مدت
Information	۲	()LogInformation	پیام های ثبت رویداد برای جریان اپلیکیشن
Warning	۳	()LogWarning	پیام های ثبت رویداد برای رویدادهای غیرنرمال یا غیرمنتظره در جریان اپلیکیشن
Error	۴	()LogError	پیام های رویداد خطا
Critical	۵	()LogCritical	پیام های ثبت رویداد برای خطاهایی که نیاز به توجه فوری دارند.

با استفاده از متد افزونه به شکل زیر می توانیم سطح پیام رویداد را مشخص کنیم.

مثال: سطح رویداد

public class HomeController : Controller
{
    ILogger _logger;

    public HomeController(ILogger<HomeController> logger)
    {
        _logger = logger;
    }

    public IActionResult Index(string id)
    {
        _logger.LogInformation("Home/Index Executing..");

        if (String. IsNullOrEmpty(id))
        {
            _logger.LogWarning(LoggingEvents.GET_ITEM_NOTFOUND, "Index({ID}) NOT FOUND", id);

            return NotFound();
        }

        return View();
    } 
}

کتابخانه های ارائه دهنده ثبت رویداد:

موارد زیر برخی از ارائه دهندگان ثبت رویداد هستند که با ASP.NET Core کار می کنند:

ارائه دهنده ثبت رویداد	توضیح
Elmah.io	ارائه دهنده سرویس Elmah.Io
Lggr	ارائه دهنده کتابخانه سرویس Logger
NLog	ارائه دهنده کتابخانه NLog
Serilog	ارائه دهنده کتابخانه Serilog

در بخش بعدی درباره متغیرهای محلی در ASP.NET Core مطالبی را یاد خواهیم گرفت.

---