NLog لـ C# (.NET): دليل شامل مع أمثلة عملية

مرحبًا بك في الدليل التفصيلي لمكتبة NLog الخاصة بمنصة .NET. NLog هي نظام تسجيل أخطاء (Logging) قوي ومرن وعالي الأداء، وأصبحت المعيار الفعلي للعديد من مشاريع .NET. في هذا المقال، سنغطي كل شيء بدءًا من التثبيت وصولاً إلى التقنيات المتقدمة، مع أمثلة كود حقيقية ونصائح لتحسين الأداء.

1. ما هي NLog ولماذا تحتاجها؟

NLog (اختصار لـ ".NET Logging") هي مكتبة مجانية مفتوحة المصدر لمنصة .NET، مصممة لتوفير تسجيل أخطاء مرن وفعال. تتيح للمطورين كتابة معلومات تشخيصية (سجلات) إلى وجهات متعددة: ملفات، وحدة التحكم، قواعد البيانات، مآخذ الشبكة، أنظمة المراقبة (مثل Seq, Elasticsearch, Sentry) وغيرها الكثير.

لماذا تحتاج إلى تسجيل الأخطاء؟ في تطوير البرمجيات الحديثة، تعتبر السجلات بمثابة "الصندوق الأسود" للتطبيق. بدونها، يستحيل معرفة سبب تعطل الخادم، أو مكان حدوث الخطأ، أو البيانات التي كانت قيد المعالجة وقت العطل. تحل NLog هذه المشكلة من خلال توفير:

• مرونة التوجيه: يمكنك ضبط مستويات مختلفة لتسجيل الأخطاء (Trace, Debug, Info, Warn, Error, Fatal) لأجزاء مختلفة من التطبيق.
• الأداء العالي: كتابة غير متزامنة، تهيئة بطيئة (Lazy Initialization)، وتأثير ضئيل على سرعة التشغيل.
• قابلية التوسع: مئات الأهداف (Targets) الجاهزة وإمكانية كتابة أهداف مخصصة.
• إعدادات بدون إعادة ترجمة: يمكن تغيير الإعدادات أثناء التشغيل عبر XML أو JSON أو الكود.

NLog مثالية لـ: تطبيقات الويب (ASP.NET Core)، الأدوات الطرفية (Console Apps)، الخدمات المصغرة (Microservices)، تطبيقات سطح المكتب (WPF/WinForms)، والخدمات الخلفية (Windows Services, Worker Services).

2. التثبيت

يتم تثبيت NLog عبر مدير الحزم NuGet. قم بتنفيذ أحد الأوامر التالية في وحدة تحكم مدير الحزم في Visual Studio أو في terminal .NET CLI:

// عبر .NET CLI (موصى به)
dotnet add package NLog

// عبر Package Manager Console
Install-Package NLog

// لتطبيقات ASP.NET Core، يُوصى أيضًا بتثبيت حزمة التكامل:
dotnet add package NLog.Web.AspNetCore

بعد التثبيت، ستحتاج إلى إنشاء ملف إعدادات nlog.config في جذر المشروع (أو إعداد NLog برمجيًا).

3. بداية سريعة — مثال عملي بسيط

أنشئ تطبيقًا طرفيًا (Console App) وأضف ملف nlog.config (اضغط بزر الفأرة الأيمن على المشروع → Add → New Item → XML File → سمّه nlog.config). الصق فيه المحتوى التالي:

<?xml version="1.0" encoding="utf-8" ?>
<nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    <!-- الهدف: أين نكتب السجلات -->
    <targets>
        <target name="console" xsi:type="Console" layout="${longdate} | ${level:uppercase=true} | ${message} ${exception:format=ToString}" />
        <target name="file" xsi:type="File" fileName="${basedir}/logs/app-${shortdate}.log"
                layout="${longdate} | ${level:uppercase=true} | ${logger} | ${message} ${exception:format=ToString}" />
    </targets>

    <!-- قواعد التوجيه -->
    <rules>
        <logger name="*" minlevel="Debug" writeTo="console,file" />
    </rules>
</nlog>

الآن لنكتب الكود في ملف Program.cs:

using NLog;

public class Program
{
    // إنشاء مسجل للكلاس الحالي
    private static readonly Logger Logger = LogManager.GetCurrentClassLogger();

    public static void Main(string[] args)
    {
        Logger.Info("تم تشغيل التطبيق");
        
        try
        {
            var result = Divide(10, 0);
            Logger.Debug($"النتيجة: {result}");
        }
        catch (Exception ex)
        {
            Logger.Error(ex, "حدث خطأ أثناء عملية القسمة");
        }
        
        Logger.Warn("التطبيق على وشك الإنهاء");
        Logger.Fatal("تم إنهاء التطبيق بشكل غير متوقع");
    }

    static int Divide(int a, int b)
    {
        return a / b;
    }
}

عند تشغيل التطبيق، ستظهر السجلات في وحدة التحكم وفي ملف السجل (في مجلد logs). لاحظ كيف تم تسجيل الخطأ تلقائيًا عند محاولة القسمة على صفر.

4. أهم طرق NLog مع الشرح والأمثلة

توفر NLog مجموعة غنية من الطرق لتسجيل الأخطاء بمستويات مختلفة. إليك أهمها:

4.1. Logger.Trace() — أدق مستوى للتتبع

يُستخدم لتسجيل معلومات تتبع مفصلة جدًا، عادةً لأغراض التطوير والتصحيح المتقدم. لا يُفعل عادةً في بيئة الإنتاج.

Logger.Trace("دخول إلى الدالة ProcessData مع المعامل: {0}", userId);

4.2. Logger.Debug() — معلومات التصحيح

مفيد أثناء التطوير لتتبع تدفق التنفيذ وقيم المتغيرات.

Logger.Debug("تم تحميل {0} سجل من قاعدة البيانات", recordsCount);

4.3. Logger.Info() — معلومات عامة

لتسجيل الأحداث الهامة مثل بدء التطبيق، إتمام عملية، أو تغيير حالة.

Logger.Info("تم بدء تشغيل الخدمة بنجاح على المنفذ {0}", port);

4.4. Logger.Warn() — تحذيرات

للمواقف غير المتوقعة ولكنها غير حرجة، مثل انخفاض المساحة التخزينية أو استخدام API قديم.

Logger.Warn("انتهاء صلاحية شهادة SSL خلال {0} يومًا", daysLeft);

4.5. Logger.Error() — أخطاء

لتسجيل الاستثناءات والأخطاء التي تؤثر على وظيفة معينة ولكنها لا توقف التطبيق بالكامل.

try {
    // كود قد يسبب خطأ
} catch (Exception ex) {
    Logger.Error(ex, "فشل في معالجة الطلب رقم {0}", requestId);
}

4.6. Logger.Fatal() — أخطاء قاتلة

للأخطاء الحرجة التي تؤدي إلى إنهاء التطبيق أو فقدان بيانات مهمة.

Logger.Fatal("تعذر الاتصال بقاعدة البيانات الأساسية، سيتم إيقاف التطبيق");

5. نصائح لتحسين الأداء

• استخدم التسجيل غير المتزامن: أضف async="true" في تعريف الهدف لتجنب إبطاء التطبيق.
• تجنب تسجيل المعلومات الحساسة: مثل كلمات المرور أو أرقام البطاقات الائتمانية.
• استخدم مستويات التسجيل بحكمة: فعّل المستويات العالية (Trace, Debug) فقط في بيئة التطوير.
• قم بتدوير ملفات السجل: استخدم خاصية archiveAboveSize لمنع تضخم الملفات.

بهذا نكون قد غطينا الأساسيات. NLog مكتبة غنية جدًا وتدعم العديد من السيناريوهات المتقدمة مثل التصفية الشرطية والتنسيق المخصص. ننصحك بزيارة الموقع الرسمي للاطلاع على الوثائق الكاملة.