نحوه کار با Trace listener در ASP.NET Core 6

از ردیابی شنوندگان در ASP.NET Core 6 استفاده کنید تا به راحتی عملکرد و ابزارهای اشکال زدایی را به برنامه های خود اضافه کنید.

هنگام کار بر روی برنامه‌هایی که با استفاده از ASP.NET Core 6 ساخته شده‌اند، اغلب بخواهید از ردیابی و گزارش‌گیری برای نظارت بر عملکرد برنامه خود و تشخیص خطاها استفاده کنید. همچنین می‌توانید از ردیابی در محیط تولید برای اندازه‌گیری عملکرد برنامه‌تان در زمان اجرا استفاده کنید.

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

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

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

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

1. Visual Studio 2022 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 6 Web API برای کار با شنوندگان ردیابی در بخش‌های بعدی این مقاله استفاده خواهیم کرد.

ردیابی چیست؟

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

فضای نام System.Diagnostics شامل کلاس‌های Trace و Debug است. در حالی که کلاس Trace در محیط های تولید استفاده می شود، کلاس Debug در زمان توسعه استفاده می شود.

ردیابی معمولاً شامل سه مرحله زیر است:

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

شنوندگان ردیابی چیست؟ چرا آنها مورد نیاز هستند؟

شنوندگان ردیابی پیام‌های ردیابی را جمع‌آوری می‌کنند، آنها را ذخیره می‌کنند و آنها را به یک هدف مناسب مانند یک فایل متنی هدایت می‌کنند. دات نت چندین شنونده ردیابی از جمله موارد زیر را ارائه می دهد:

• ConsoleTraceListener – پیام های ردیابی را به پنجره کنسول ارسال می کند.
• DefaultTraceListener – پیام های ردیابی را به خروجی اشکال زدایی استاندارد می فرستد.
• DelimitedListTraceListener – خروجی ردیابی را در قالبی محدود به یک جریان، یک نویسنده جریان، یا یک نویسنده متن ارسال می کند.
• EventLogTraceListener – پیام‌های ردیابی را به گزارش‌های رویداد ارسال می‌کند.
• TextWriterTraceListener – پیام های ردیابی را به یک فایل متنی ارسال می کند.
• XmlWriterTraceListener – پیام های ردیابی را به XML تبدیل می کند.

کلاس‌های System.Diagnostics.Debug و System.Diagnostics.Trace می‌توانند پیام‌هایی را برای ردیابی شنوندگان ارسال کنند که به نوبه خود پیام‌ها را به یک هدف مناسب هدایت می‌کنند.

یک شنونده ردیابی با استفاده از یک فایل پیکربندی در ASP.NET Core 6 ایجاد کنید

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

<configuration>
  <system.diagnostics>
    <trace autoflush="false" indentsize="4">
      <listeners>
        <add name="MyFirstListener"
        type="System.Diagnostics.TextWriterTraceListener"
        initializeData="TraceOutput.txt" />
        <remove name="Default" />
      </listeners>
    </trace>
  </system.diagnostics>
</configuration>

همه شنوندگان اضافه شده به مجموعه Listeners خروجی ردیابی دریافت خواهند کرد. با این حال، می‌توانید از شنونده بدون اضافه کردن آن به مجموعه Listeners استفاده کنید. در این مورد، خروجی را با استفاده از روش Write یا WriteLine در شنونده ارسال می‌کنید.

کد زیر شنونده‌ای را نشان می‌دهد که به مجموعه Listeners اضافه نشده است اما همچنان می‌تواند پیام‌های ردیابی را به یک پنجره خروجی، یک فایل یا هر خروجی از پیش پیکربندی شده ارسال کند.

TextWriterTraceListener myFirstListener = new
TextWriterTraceListener("Output.txt", "myFirstListener");
myFirstListener.WriteLine("This is a test message.");
myFirstListener.Flush();

یک شنونده ردیابی سفارشی در ASP.NET Core 6 ایجاد کنید

شنوندگان ردیابی که به طور پیش‌فرض با .NET 6 ارائه می‌شوند در اکثر موارد نیازهای شما را برآورده می‌کنند. با این حال، اگر می‌خواهید پیام‌های ردیابی خود را به مقصد دیگری ارسال کنید، می‌توانید شنونده ردیابی خود را پیاده‌سازی کنید.

برای ساختن یک شنونده ردیابی سفارشی، باید کلاسی ایجاد کنید که کلاس انتزاعی TraceListener را گسترش دهد. چندین روش مجازی و انتزاعی در کلاس TraceListener وجود دارد. حداقل باید متدهای Write و WriteLine را پیاده سازی کنید. حداقل، شنونده ردیابی سفارشی شما باید به این شکل باشد:

public class CustomTraceListener : TraceListener
{
    public CustomTraceListener(ILoggerFactory loggerFactory)
    {
    }
    public override void Write(string? message, string? category)
    {           
    }  
    public override void Write(string? message)
    {           
    }
    public override void WriteLine(string? message)
    {           
    }
}

بنابراین، کلاس شنونده ردیابی سفارشی شما باید یک سازنده آرگومان و متدهای Write و WriteLine داشته باشد.

شما همچنین به یک نمونه ILogger که نمایانگر Logger است، یک کارخانه Logger برای ایجاد Logger و یک StringBuilder برای ذخیره پیام های ردیابی قبل از ارسال به هدف log نیاز دارید.

private readonly ILoggerFactory _loggerFactory;
private readonly ILogger _iLogger;
private readonly StringBuilder _stringBuilder = new();

می‌توانید از تزریق وابستگی برای تزریق نمونه‌ای از ILoggerFactory در سازنده و سپس استفاده از نمونه برای ایجاد نمونه‌ای از ILogger استفاده کنید.

public CustomTraceListener(ILoggerFactory loggerFactory)
{
   _loggerFactory = loggerFactory;
   _iLogger = loggerFactory.CreateLogger(nameof(CustomTraceListener));
}

در اینجا یک پیاده‌سازی حداقلی از روش‌های Write و WriteLine وجود دارد:

public override void Write(string? message, string? category)
{
     _stringBuilder.Append(message + "-" + category);
}
public override void Write(string? message)
{
     _stringBuilder.Append(message);
}
public override void WriteLine(string? message)
{
   _stringBuilder.AppendLine(message);
   _iLogger.LogInformation(_stringBuilder.ToString());
   _stringBuilder.Clear();
}

نمونه شنونده ردیابی سفارشی را در ASP.NET Core 6 کامل کنید

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

using System.Collections.Concurrent;
using System.Diagnostics;
using System.Text;
namespace TraceListenerDemo
{
    public class CustomTraceListener : TraceListener
    {
        private readonly ILoggerFactory _loggerFactory;
        private readonly ILogger _iLogger;
        private readonly StringBuilder _stringBuilder = new();
        public CustomTraceListener(ILoggerFactory loggerFactory)
        {
            _loggerFactory = loggerFactory;
            _iLogger =
             loggerFactory.CreateLogger(nameof(CustomTraceListener));
        }
        public override void Write(string? message, string? category)
        {
            _stringBuilder.Append(message + "-" + category);
        }
        public override void Write(string? message)
        {
            _stringBuilder.Append(message);
        }
        public override void WriteLine(string? message)
        {
            _stringBuilder.AppendLine(message);
            _iLogger.LogInformation(_stringBuilder.ToString());
            _stringBuilder.Clear();
        }
    }
}

شنونده ردیابی سفارشی را در فایل Program.cs ثبت کنید

برای استفاده از شنونده ردیابی سفارشی، باید آن را با استفاده از کد زیر در مجموعه Listeners ثبت کنید.

var loggerFactory = app.Services.GetRequiredService<ILoggerFactory>();
Trace.Listeners.Add(new LoggerTraceListener(loggerFactory));

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

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

هنگام کار با شنوندگان ردیابی سفارشی، باید به خاطر داشته باشید که شنونده ردیابی را ببندید یا آن را شستشو دهید تا مطمئن شوید که بافر خروجی خالی شده است. می توانید از کلاس StringBuilderCache برای بهینه سازی کد خود (در کلاس CustomTraceListener) که از StringBuilder استفاده می کند، استفاده کنید.