介紹好用函式庫：NLog - Advanced .NET Logging

最近這陣子已經都改用 NLog 當作 .NET 應用程式的追蹤記錄工具，使用方式跟 log4net 非常像，不過設定檔簡單多了，非常容易上手，而且 NLog 支援非常多種儲存記錄的形式(Target)，例如儲存至檔案、資料庫、Console、Event Log 或透過 Email、TCP 或 UDP、SOAP (Web Service)、MSMQ 傳送出去等等非常多種形式，除此之外，在 Visual Studio 中還支援設定檔的 Intellisense 支援。

※ 下載 NLog

下載網址：http://nlog.codeplex.com/Release/ProjectReleases.aspx

建議可下載含有自動安裝的封裝檔 NLog-1.0-Refresh-setup.exe

下載安裝完成後的路徑預設會在 C:\Program Files (x86)\NLog 或 C:\Program Files\NLog

安裝號之後的檔案可謂是一應俱全，完整的 API 文件＋非常詳盡的範例＋可直接加入專案參考的組件

※ 如何將 NLog 加入現有專案

1. 先將 NLog 組件加入參考

瀏覽至 C:\Program Files (x86)\NLog\bin\net-2.0 目錄，並選取 NLog.dll 即可

※ 如何新增 NLog 設定檔

在 Visual Studio 2008 需選取如下圖左側 Visual C# Items，然後再右側視窗拉到最下面才看的到 My Templates 的自訂範本，如果是 Visual Studio 2010 的話用搜尋的方式找比較快 ( 快速鍵 Ctrl + E )。

預設的內容如下：

<?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="file" xsi:type="File" fileName="${basedir}/log.txt" />
    </targets>

    <rules>
        <logger name="*" minlevel="Debug" writeTo="file" />
    </rules>
</nlog>

注意：如果你的專案 "不是 Web 應用程式專案" ( 例如: 主控台應用程式、Windows 服務應用程式)，那麼你要將新增的 NLog.config 修改項目屬性，讓 NLog.config 設定檔可以在建置時一併複製到輸出目錄！

如果是 Web 應用程式專案的話，就要新增 NLog.config 或 Web.nlog 檔案到網站根目錄即可。(兩種檔名都可以，二選一即可)

如果是類別庫(Class Library)專案，則新增 NLog.config 似乎沒什麼意義，若新增也只能僅供參考。

※ 如何修改 NLog 設定檔

基本上 NLog 的設定檔可以分成幾個部分，最重要也最常用的就是 <targets> 與 <rules> 設定，釐清其用途就很好設定了。

<targets> 用來定義你要怎麼處理應用程式收到的紀錄，例如儲存的方式、內容的格式、儲存的檔名為何、…等等，但 <targets> 僅僅定義這些而已，他不會真的讓你的紀錄被寫入。

<rules> 用來定義你的記錄器(Logger)要記錄多仔細的內容(minlevel)，以及要利用哪一個 target 來記錄這些內容 (writeTo)。

在撰寫的過程中都會有 Intellsense 可用，這部分幫助很大，不過前提是要看的懂才行：

如下是一個在 ASP.NET 網站設定的範例，其中有幾個地方值得注意：

<?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" autoReload="true">

    <targets>
      <target name="file" xsi:type="File" 
              fileName="${basedir}/App_Data/Logs/${shortdate}/${logger}.txt" />
    </targets>

    <rules>
        <logger name="*" minlevel="Debug" writeTo="file" />
    </rules>
  
</nlog>

1. autoReload="true" 代表該設定檔更新的時候會自動刷新，並自動反應至整個站台的記錄器。

2. fileName="${basedir}/App_Data/Logs/${shortdate}/${logger}.txt" 用來定義儲存的檔名與路徑，如果目錄不存在的話會自動被建立，如上範例就是將 Log 儲存到 App_Data 的子目錄下，有個需注意的地方是，你必須先確保檔案有權限可寫入 App_Data 的資料夾，如果 NLog 發生任何錯誤是不會引發任何例外事件的。

3. 在 fileName 的內容會看到許多變數，要注意變數的格式是先有一個錢字號($)在加上大刮號({…})裡面放變數名稱，例如 ${basedir} 代表網站根目錄 (或應用程式所在目錄)、${shortdate} 代表短日期格式(yyyy-MM-dd)、${logger} 代表記錄器名稱（何謂記錄器(Logger)後續會說明），關於這些變數的說明可以參考 Layout Renderers 頁面的說明。

※ 如何在程式中使用 NLog 記錄器

常見的用法是在類別層級定義一個 Logger 型別的物件，並透過 LogManager.GetCurrentClassLogger() 靜態方法取得 Logger 物件實體(instance)，透過這種方式取得的 Logger 預設的「記錄器名稱」類別的完整名稱 (含命名空間與類別名稱)。

在方法中要調用 logger 物件可以參考以下範例，使用上非常直覺：

輸出的結果範例如下，預設的格式為 日期時間｜記錄等級｜記錄器名稱｜記錄內容：

2010-07-07 01:33:53.3939|DEBUG|MyProject.Services.EssbaseService|TEST_LOG_MESSAGE
2010-07-07 01:33:53.3939|INFO|MyProject.Services.EssbaseService|TEST_LOG_MESSAGE
2010-07-07 01:33:53.3939|FATAL|MyProject.Services.EssbaseService|TEST_LOG_MESSAGE

另一種取得記錄器的方式是自訂記錄器名稱，如下圖的 MySomethingService 會反應到紀錄檔裡。