2012年12月30日 星期日

NLog API

LogManager

LogManager是用來建立日誌和管理設定檔用的類別,有以下幾個Method

  • LogManager.GetLogger - 取得或建立指定的logger
    建議建立Logger的方式,需要手動指定名稱
  • LogManager.GetCurrentClassLogger  - 取得或建立目前類別名稱的logger
    雖然比較方便,但底層是以StackTrace取得名稱,成本高很多
  • LogManager.Configuration - 取得或設定目前日誌的設定資訊
  • LogManaget.GlobalThreshold - 取得或設定全域日誌的threshold


Logger

NLog.Logger類別是用來輸出Log用的,有以下幾個Method用來輸出不同層級的Log
每個Method都有多個overloads用來最小化內存配置以提高日誌速度
  • Log() - 使用指定的格式和參數,將訊息寫入指定的級別
  • Trace() - 使用指定的格式和參數,將訊息寫入Trace級別
  • Debug() - 使用指定的格式和參數,將訊息寫入Debug級別
  • Info() - 使用指定的格式和參數,將訊息寫入Info級別
  • Warn() - 使用指定的格式和參數,將訊息寫入Warn級別
  • Erro() - 使用指定的格式和參數,將訊息寫入Error級別
  • Fatal() - 使用指定的格式和參數,將訊息寫入Fatal級別
以下的方法和屬性用來檢查該層級的日誌是否啟用

  • IsEnabled() - 確定指定的級別日誌是否啟用
  • IsTraceEnabled - 確定Trace級別日誌是否啟用
  • IsDebugEnabled - 確定Debug級別日誌是否啟用
  • IsInfoEnabled - 確定Info級別日誌是否啟用
  • IsWarnEnabled - 確定Warn級別日誌是否啟用
  • IsErrorEnabled - 確定Error級別日誌是否啟用
  • IsFatalEnabled - 確定Fatal級別日誌是否啟用
除此之外,NLog還提供了一組方法來記錄Exception
通過配置Layout Renderer的${exception},可以取得很詳細的訊息
  • LogException() - 使用指定的格式和參數,將訊息和例外寫入指定的級別
  • TraceException() - 使用指定的格式和參數,將訊息和例外寫入Trace級別
  • DebugException() - 使用指定的格式和參數,將訊息和例外寫入Debug級別
  • InfoException() - 使用指定的格式和參數,將訊息和例外寫入Info級別
  • WarnException() - 使用指定的格式和參數,將訊息和例外寫曾Warn級別
  • ErrorException() - 使用指定的格式和參數,將訊息和例外寫曾Error級別
  • FatalException() - 使用指定的格式和參數,將訊息和例外寫曾Fatal級別

${exception}的詳細設定方式,請參考官網文件
  • format - 用逗號分隔的例外屬性例表,不區分大小寫
    Message, Type, ShortType, ToString, Method, StackTrace
  • innerFormat - 用逗號分隔的例外屬性例表,不區分大小寫
    Message, Type, ShortType, ToString, Method, StackTrace
  • maxInnerExceptionLevel - 內部錯誤的最大層數

${onexception} - 用來輸出內部例外

範例
StackTrace:${exception:format=stacktrace}
Exception Type:${exception:format=type}
Exception Message:${exception:format=message}
Inner Exception :${onexception:${exception:format=type,message,method:maxInnerExceptionLevel=5:innerFormat=shortType,message,method}}


Example

最基本的使用範例,取得Logger並輸出了一個字串訊息

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using NLog;

namespace NLogApp
{
    class Program
    {
        static readonly Logger log = LogManager.GetLogger("Program");

        static void Main(string[] args)
        {
            log.Debug("Debug Message...");
        }
    }
}

如果需要更多細部控制,可以實例化一個LogEvent來調整屬性,再傳給logger輸出
using System;
using System.Globalization;
using NLog;

class MyClass
{
    static Logger logger = LogManager.GetLogger("MyClass");

    public void LogSomething()
    {
        LogEventInfo myEvent = new LogEventInfo(LogLevel.Debug, "", "My debug message");
        myEvent.LoggerName = logger.Name;
        myEvent.Properties.Add("MyCustomValue", "This is from MyClass");

        logger.Log(myEvent);
    }
}