nlog輕量級日志元件

一.NLog簡要介紹:                                    

1.NLog是一個簡單靈活的.NET日志記錄類庫。通過使用NLog，我們可以在任何一種.NET語言中輸出帶有上下文的（contextual information）調試診斷資訊，根據喜好配置其表現樣式之後發送到一個或多個輸出目标（target）中。

2.NLog的API非常類似于log4net，且配置方式非常簡單。NLog使用路由表（routing table）進行配置，但log4net卻使用層次性的appender配置，這樣就讓NLog的配置檔案非常容易閱讀，并便于今後維護。

3.NLog遵從BSD license，即允許商業應用且完全開放源代碼。任何人都可以免費使用并對其進行測試，然後通過郵件清單回報問題以及建議。

4.NLog支援.NET、C/C++以及COM interop API，是以我們的程式、元件、包括用C++/COM 編寫的遺留子產品都可以通過同一個路由引擎将資訊發送至NLog中。

5.NLog的.NET API的過濾資訊功能執行效率很高，這樣我們就可以一直保留程式中的日志寫入代碼，然後由NLog在運作時将其根據需要過濾掉。在一個1.6G單CPU筆記本電腦上，NLog每秒鐘可以過濾掉1.5億條日志寫入語句！加上異步處理（asynchronous processing）以及其他包裝程式（wrappers）的支援，NLog将成為一個極為強大的、且極具伸縮性的日志記錄工具.

二.NLog中Logger類的方法解釋:

1.   Trace - 最常見的記錄資訊，一般用于普通輸出

2.   Debug - 同樣是記錄資訊，不過出現的頻率要比Trace少一些，一般用來調試程式

3.   Info - 資訊類型的消息

4.   Warn - 警告資訊，一般用于比較重要的場合

5.   Error - 錯誤資訊

6.   Fatal - 緻命異常資訊。一般來講，發生緻命異常之後程式将無法繼續執行。

以下的方法讓你決定是否将日志用于特定的等級:

1.IsEnabled() –決定日志是否能用于特定的等級.

2.IsTraceEnabled –決定日志是否能用于Trace這個等級

3.IsDebugEnabled – 決定日志是否能用于Debug這個等級

4.IsInfoEnabled –決定日志是否能用于Info這個等級

5.IsWarnEnabled – 決定日志是否能用于Warn這個等級

6.IsErrorEnabled – 決定日志是否能用于Error這個等級

7.IsFatalEnabled – 決定日志是否能用于Fatal這個等級

三. 配置檔案詳細配置過程

通過在啟動的時候對一些常用目錄的掃描，NLog會嘗試使用找到的配置資訊進行自動的自我配置。當你運作一個獨立的*.exe用戶端可執行程式時，NLog将在以下目錄搜尋配置資訊：

1. 标準的程式配置檔案（通常為 程式名.exe.config）
2. 程式目錄下的程式名.exe.nlog檔案
3. 程式目錄下的NLog.config檔案
4. NLog.dll所在目錄下的NLog.dll.nlog檔案
5. 如果定義了NLOG_GLOBAL_CONFIG_FILE環境變量，則該變量所指向的檔案

如果是一個ASP.NET程式，被搜尋的目錄包括：

1. 标準的web程式配置檔案web.config
2. 和web.config在同一目錄下的web.nlog檔案
3. 程式目錄下的NLog.config檔案
4. NLog.dll所在目錄下的NLog.dll.nlog檔案
5. 如果定義了NLOG_GLOBAL_CONFIG_FILE環境變量，則該變量所指向的檔案

由于.NET Compact Framework不支援程式配置檔案（*.exe.config）和環境變量，是以NLog将隻會掃描這些地方：

1. 程式目錄下的NLog.config檔案
2. NLog.dll所在目錄下的NLog.dll.nlog檔案
3. 如果定義了NLOG_GLOBAL_CONFIG_FILE環境變量，則該變量所指向的檔案

配置檔案格式

 NLog支援兩種配置檔案格式

1. 配置資訊嵌入在.NET應用程式标準的*.exe.config或者web.config檔案裡
2. 儲存在獨立檔案裡，也叫單一格式

如果你選擇了第一種方式，使用的是标準的configSections這種機制，那麼你的配置檔案看起來差不多是這個樣子：

<configuration>

  <configSections>

    <section name="nlog" type="NLog.Config.ConfigSectionHandler, NLog"/>

  </configSections>

  <nlog>

  </nlog>

</configuration>

單一格式的配置檔案就是一個以<nlog />為根節點的純XMl檔案。命名空間并不強制使用，如果使用的話我們就可以利用Visual Studio的智能感應。

<nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd"

      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

</nlog>

需要注意的是NLog的配置檔案總是大小寫敏感的，不管是在使用的時候，或者即使你沒有使用名字空間。當然隻有你的大小寫符合要求，智能感應才能正常工作。

配置元素

下面這些元素可以作為<nlog />的位元組點。清單中的前兩個元素在所有的NLog配置檔案中都必須提供，其餘的則可以選擇使用，通常用于一些複雜場景。

1. <targets /> - 定義日志的目标/輸出
2. <rules /> - 定義日志的路由規則
3. <extensions /> - 從*.dll加載NLog擴充
4. <include /> - 導入外部配置檔案
5. <variable /> - 為配置變量指派

輸出目标

<target />區域定義了日志的目标或者說輸出。每一個<target />元素代表一個目标。我們需要為每一個目标設定兩個屬性：

1. name - 目标的名稱
2. type - 目标的類型 - 比如“File”，“Database”，“Mail”。如果你使用了名字空間，這個屬性會被命名為 xsi:type.

除了這兩個屬性，通常來說給目标添加一些其它參數，這些屬性将會影響你在程式中如何使用診斷跟蹤語句（diagnostic traces）。每一個目标都可以有一組不同的參數集合，并且參數都是上下文相關的，你可以在本項目的首頁上找到更多關于參數的詳細說明。Visual Studio的智能感應對這些參數同樣有用。

舉個例子 - “File”目标可以使用“fileName”作為參數來定義輸出檔案名，而“Console”目标可以借助“error”參數的值來判斷是否應該把目前程序的diagnostic traces結果輸出到标準錯誤（stderr）還是标準輸出（stdout）控制台。

下面這個例子示範了在<targets />區域同時定義多個目标：兩個files目标，一個network目标和一個OutputDebugString目标：

<targets>

  <target name="f1" xsi:type="File" fileName="file1.txt"/>

  <target name="f2" xsi:type="File" fileName="file2.txt"/>

  <target name="n1" xsi:type="Network" address="tcp://localhost:4001"/>

  <target name="ds" xsi:type="OutputDebugString"/>

</targets>

注意:target節點的archiveAboveSize屬性,這個屬性比較有用，很多人不知道這個屬性。

archiveAboveSize="50000"  表示日志檔案的最大50KB,超過就建立檔案，并重命名舊的檔案名,舊檔案名類似 xxx.0.txt, xxx.1.txt.

NLog提供了許多已經預先定義好的目标。關于這些目标的詳細說明請參考本項目的首頁。實際上，你也可以很容易的為自己建立目标 - 全部隻需大約15-20行代碼即可，更多資訊請參考項目文檔。

路由規則

<rules />區域定義了日志的路由規則。實際上它是一個簡單的路由表，對每一個日志源/記錄者的名稱和記錄等級的組合，定義了一個日志寫入目标清單。 表中的規則是被順序處理的。每當遇到比對的規則時，日志資訊就會被送到規則中定義的一個或多個目标去。如果一個規則被辨別為最後一個，那麼其後的規則都不會被執行。

每一個路由表項就是一個<logger />元素，它的可以接受的屬性有：

1. name - 日志源/記錄者的名字 (允許使用通配符*)
2. minlevel - 該規則所比對日志範圍的最低級别
3. maxlevel - 該規則所比對日志範圍的最進階别
4. level - 該規則所比對的單一日志級别
5. levels - 該規則所比對的一系列日志級别，由逗号分隔。
6. writeTo - 規則比對時日志應該被寫入的一系列目标，由逗号分隔。
7. final - 标記目前規則為最後一個規則。其後的規則即時比對也不會被運作。

一些例子：

1. <logger name="Name.Space.Class1" minlevel="Debug" writeTo="f1" /> - 名字空間Name.Space下的Class1這個類的所有級别等于或者高于Debug的日志資訊都寫入到“f1”這個目标裡。
2. <logger name="Name.Space.Class1" levels="Debug,Error" writeTo="f1" /> -名字空間Name.Space下的Class1這個類的所有級别等于Debug或Error的日志資訊都寫入到“f1”這個目标裡。
3. <logger name="Name.Space.*" writeTo="f3,f4" /> -名字空間Name.Space下所有類的所有級别的日志資訊都寫入到“f3”和“f4”這兩個目标裡。
4. <logger name="Name.Space.*" minlevel="Debug" maxlevel="Error" final="true" /> - 名字空間Name.Space下所有類的、級别在Debug和Error之間的(包括Debug,Info,Warn,Error) 日志資訊都不會被記錄(因為這條規則沒有定義writeTo)，同時其它後續規則也都會被忽略(因為這裡設定了final="true")。

最簡單的情況下，整個日志的配置資訊可以隻由一個<target />元素和一個<logger />規則構成，就可以吧一定級别的日志資訊路由到期望的目标去。随着程式不斷的變大，增加新的目标和規則也很簡單。

上下文資訊

布局由被一個美元符号$加左大括弧“${”和一個右大括弧“}”為标記所包圍的文本所組成。這個标記也就是所謂的“布局生成器（layout renderers），我們可以用它來把一些上下文相關的資訊插入到日志資訊中。布局可以應用在許多地方，比如可以被用在控制輸出到螢幕或寫入檔案資訊的格式，也可以用在控制檔案名。接下來我們會更多的了解布局的強大。

假設我們希望每個輸出到控制台的資訊都包含一些這些資訊：

• 目前的日期和時間
• 産生日志資訊的類和方法的名字
• 日志等級
• 日志内容

利用Layout來實作很簡單：

<target name="c" xsi:type="Console"

  layout="${longdate} ${callsite} ${level} ${message}"/>

或者我們可以把每一個日志記錄者生成的日志資訊輸出到一個單獨的檔案裡：

<target name="f" xsi:type="File" fileName="${logger}.txt"/>

這裡我們看到fileName屬性的值被設定為布局生成器${logger}，進而使每一條日志資訊被寫到一個以日志生成者名字命名的一個檔案裡。上面這個例子将生成如下一系列檔案：

• Name.Space.Class1.txt
• Name.Space.Class2.txt
• Name.Space.Class3.txt
• Other.Name.Space.Class1.txt
• Other.Name.Space.Class2.txt
• Other.Name.Space.Class3.txt
• ...

有一個常見需求是能夠用日期資訊來區分日志檔案。如果使用${shortdate}布局生成器，這簡直太容易了：

<target name="f" xsi:type="File" fileName="${shortdate}.txt"/>

那麼可以給每一個職員生成一個日志檔案嗎？答案就是${windows-identity}布局生成器：

<target name="f" xsi:type="File" fileName="${windows-identity:domain=false}.txt"/>

這樣我們就能夠給每一個職員生成一個日志檔案了：

1. Administrator.txt
2. MaryManager.txt
3. EdwardEmployee.txt