The Will Will Web

記載著 Will 在網路世界的學習心得與技術分享

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

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

※ 下載 NLog

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

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

下載安裝完成後的路徑預設會在 C:\Program Files (x86)\NLogC:\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.configWeb.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 會反應到紀錄檔裡。

NLog 最常用的功能大概就這些,剩下一些進階設定可以自行參考官方網站的 Wiki 文件說明

相關連結