اتصال برنامه‌های ⁦.NET Framework 4.x⁩

بسیاری از سامانه‌های در حال کار هنوز روی ⁦ASP.NET⁩ MVC 5، Web API 2، WebForms یا سرویس‌های ویندوزی با ⁦.NET Framework⁩ اجرا می‌شوند. برای فرستادن لاگ این برنامه‌ها به LogMug لازم نیست به ⁦.NET⁩ جدید مهاجرت کنید. ساده‌ترین راه، Serilog با sink استاندارد Seq است که روی ⁦.NET Framework 4.6.2⁩ به بعد کار می‌کند.

گام ۱: نصب پکیج‌ها

در Visual Studio، از Package Manager Console:

Install-Package Serilog
Install-Package Serilog.Sinks.Seq
Install-Package Serilog.Enrichers.Environment
Install-Package Serilog.Settings.AppSettings

هر چهار پکیج netstandard2.0 را هدف گرفته‌اند و در پروژه‌های قدیمی با packages.config هم نصب می‌شوند. اگر Visual Studio پیام نسخهٔ نامناسب داد، هدف پروژه را دست‌کم 4.6.2 کنید؛ 4.7.2 یا 4.8 بی‌دردسرتر است.

گام ۲: کلید و نشانی در web.config

به‌جای نوشتن کلید در کد، آن را در appSettings بگذارید. پکیج Serilog.Settings.AppSettings این کلیدها را می‌خواند:

<appSettings>
  <add key="serilog:minimum-level" value="Information" />
  <add key="serilog:using:Seq" value="Serilog.Sinks.Seq" />
  <add key="serilog:write-to:Seq.serverUrl" value="https://ingest.logmug.ir" />
  <add key="serilog:write-to:Seq.apiKey" value="lm_ingest_..." />
  <add key="serilog:enrich:with-property:Application" value="legacy-portal" />
  <add key="serilog:enrich:with-property:Environment" value="production" />
</appSettings>

با تبدیل‌های پیکربندی (Web.Release.config) یا جایگزینی در فرایند استقرار، برای هر محیط کلید جدا بگذارید.

گام ۳: راه‌اندازی در Global.asax

در برنامه‌های وب، logger را در Application_Start بسازید، خطاهای مدیریت‌نشده را در Application_Error ثبت کنید و در Application_End صف را خالی کنید:

using System;
using System.Net;
using System.Web;
using Serilog;

public class MvcApplication : HttpApplication
{
    protected void Application_Start()
    {
        // Needed on 4.6.x; 4.7+ already uses the OS defaults.
        ServicePointManager.SecurityProtocol |= SecurityProtocolType.Tls12;

        Log.Logger = new LoggerConfiguration()
            .ReadFrom.AppSettings()
            .Enrich.WithMachineName()
            .CreateLogger();

        Log.Information("Application started");
        // AreaRegistration, RouteConfig, ...
    }

    protected void Application_Error()
    {
        var ex = Server.GetLastError();
        if (ex != null)
            Log.Error(ex, "Unhandled exception on {Url}", Request.RawUrl);
    }

    protected void Application_End()
    {
        Log.CloseAndFlush();
    }
}

در جاهای دیگر کد، به‌جای ساختن logger جدید از Log.ForContext<OrderService>() یا مستقیم از Log استفاده کنید:

Log.ForContext<OrderService>()
   .Warning("Inventory low for {Sku}: {Count} left", sku, count);

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

در این برنامه‌ها پیکربندی را ابتدای Main بگذارید و Log.CloseAndFlush() را در finally صدا بزنید. در سرویس ویندوزی، همین فراخوانی را در OnStop هم انجام دهید؛ وگرنه لاگ‌های لحظهٔ توقف، که معمولاً علت توقف را نشان می‌دهند، فرستاده نمی‌شوند.

اگر برنامه log4net یا NLog دارد

لازم نیست همهٔ فراخوانی‌های قبلی را یک‌جا عوض کنید. دو راه عملی:

1. Serilog را کنار کتابخانهٔ فعلی اضافه کنید و اول جاهای حساس، مثل Application_Error، پرداخت و فراخوانی سرویس‌های بیرونی، را با آن بنویسید. بقیه را به‌تدریج منتقل کنید.
2. اگر نمی‌خواهید وابستگی جدید اضافه کنید، رویدادها را خودتان به شکل JSON بسازید و به endpoint سادهٔ JSON بفرستید.

دربارهٔ استراتژی کلی این کار، مقالهٔ لاگ متمرکز برای برنامه‌های ⁦.NET Framework⁩ قدیمی را ببینید. OpenTelemetry هم روی ⁦.NET Framework 4.6.2⁩ به بعد کار می‌کند، ولی به Microsoft.Extensions.Logging نیاز دارد که در این برنامه‌ها کمتر رایج است؛ برای اغلب آن‌ها Serilog کوتاه‌ترین مسیر است.

عیب‌یابی

برای دیدن خطاهای sink، موقتاً Serilog.Debugging.SelfLog.Enable(msg => System.Diagnostics.Trace.WriteLine(msg)); را پیش از ساخت logger بگذارید و خروجی را در DebugView یا پنجرهٔ Output ببینید.

• هیچ درخواستی نمی‌رسد و SelfLog خطای SSL/TLS نشان می‌دهد: روی 4.6.x خط SecurityProtocolType.Tls12 را اضافه کنید، یا هدف را به 4.7.2 به بالا ببرید.
• 401: مقدار serilog:write-to:Seq.apiKey نادرست، ناقص یا باطل‌شده است.
• 400: بدنه خوانده نشد؛ serverUrl باید فقط https://ingest.logmug.ir باشد، بدون مسیر.
• 403: سهمیهٔ ماهانهٔ پلن رایگان تمام شده است.
• 429 و 503: عبور از نرخ مجاز یا شلوغی موقت؛ sink دوباره تلاش می‌کند.
• کلیدهای appSettings خوانده نمی‌شوند: ReadFrom.AppSettings() را فراموش کرده‌اید یا پکیج Serilog.Settings.AppSettings نصب نیست.
• IIS برنامه را بی‌خبر recycle می‌کند و لاگ‌های آخر گم می‌شوند: Application_End را بررسی کنید و برای اطمینان بیشتر حالت بافر روی دیسک sink (bufferBaseFilename) را فعال کنید.