作者：Jaros?aw Kowalski <jaak@jkowalski.net>

翻譯：Dflying Chen：http://dflying.cnblogs.com/

原文：http://www.nlog-project.org/tutorial.html

本文為《NLog文章系列》的第三篇，將繼續(xù)描述演示用NLog書寫日志的方法。本想今天就能搞定整個入門教程，無奈時間實在來不及了……只能再分一篇了……匆忙而為，言語多有不順，還請各位見諒……

日志配置

下面我們來看一下NLog的配置原理。于其他工具不同，NLog將在程序啟動時嘗試進(jìn)行自動配置，換句話說，NLog將自動在某些默認(rèn)位置中搜索其配置文件。當(dāng)NLog和標(biāo)準(zhǔn)的exe文件配合使用時，將自動按照順序搜索下列路徑，以得到配置文件：

1. 應(yīng)用程序的標(biāo)準(zhǔn)配置文件（通常為applicationname.exe.config）
2. 應(yīng)用程序所在目錄中的applicationname.exe.nlog文件
3. 應(yīng)用程序所在目錄中的NLog.config文件
4. NLog.dll所在目錄中的NLog.dll.nlog文件
5. 環(huán)境變量NLOG_GLOBAL_CONFIG_FILE所指向的文件

對于ASP.NET應(yīng)用程序，NLog將自動按照順序搜索下列路徑：

1. Web應(yīng)用程序的標(biāo)準(zhǔn)配置文件——web.config
2. web.config所在目錄中的web.nlog文件
3. 應(yīng)用程序所在目錄中的NLog.config文件
4. NLog.dll所在目錄中的NLog.dll.nlog文件
5. 環(huán)境變量NLOG_GLOBAL_CONFIG_FILE所指向的文件

.NET Compact Framework并不支持應(yīng)用程序配置文件（*.exe.config）以及環(huán)境變量，因此NLog將自動按照順序搜索下列路徑：

1. 應(yīng)用程序所在目錄中的applicationname.exe.nlog文件
2. 應(yīng)用程序所在目錄中的NLog.config文件
3. NLog.dll所在目錄中的NLog.dll.nlog文件

配置文件形式

NLog支持兩種形式的配置文件：

1. 嵌入到*.exe.config或web.config等標(biāo)準(zhǔn)配置文件中
2. 單獨的配置文件

對于第一種形式，我們使用了標(biāo)準(zhǔn)化的configSection機(jī)制。這樣配置文件將類似如下所示：

<configuration> 

  <configSections> 

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

  </configSections> 

  <nlog> 

  </nlog> 

</configuration> 

而對于第二種形式，XML配置文件將以<nlog />作為其根節(jié)點。XML的命名空間是可選的，但如果按照如下所示指定了命名空間，將會得到Visual Studio的智能感知支持。

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

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

</nlog> 

若不指定XML命名空間，則NLog的配置文件對大小寫不敏感。若指定了XML命名空間，則將變?yōu)閷Υ笮懨舾小Ｖ悄芨兄獙⒅荒茉谥付薠ML的命名空間時正常工作。

配置文件元素

在配置文件的<nlog />根元素中，我們可以指定如下的子元素。其中前兩個是必須設(shè)定的，其余三個為可選設(shè)定。

1. <targets /> - 定義日志的輸出目標(biāo)
2. <rules /> - 定義對日志信息進(jìn)行路由的規(guī)則
3. <extensions /> - 定義從其他dll文件中加載的NLog擴(kuò)展模塊
4. <include /> - 引入外部的配置文件
5. <variable /> - 定義配置文件中用到的變量

輸出目標(biāo)（Target）

<targets />配置節(jié)用來定義日志信息的輸出位置。每一個輸出位置都用一個<target />元素表示。<target />元素有兩個必須設(shè)置的屬性：

1. name - 輸出目標(biāo)的名稱
2. type - 輸出目標(biāo)的類型，例如“File”、“DataBase”、“Mail”等。若我們?yōu)榕渲梦募付嗣臻g，則該屬性名為xsi:type。

除了上述兩個必須設(shè)置的屬性之外，<target />元素還支持一些其他的屬性，同樣可以影響記錄診斷信息的方式。我們可以為每一個輸出目標(biāo)設(shè)定不同的屬性參數(shù)，這些屬性均在NLog的主頁上有詳細(xì)描述，且Visual Studio也都為其提供了智能感知功能支持。

例如：“File”輸出目標(biāo)接受一個名為fileName的參數(shù)，用來指定輸出文件的名稱；而“Console”輸出目標(biāo)則接受一個名為error的參數(shù)，表示是否用標(biāo)準(zhǔn)錯誤輸出（stderr）代替標(biāo)準(zhǔn)輸出（stdout）。

NLog提供了很多與定義的輸出目標(biāo)，這些均在NLog的主頁上有詳細(xì)介紹。若你覺得不夠用，并希望能夠編寫自定義的輸出目標(biāo)，那么也同樣非常簡單——15-20行代碼就夠了，請參考Nlog的文檔（documentation）。

路由規(guī)則（Rule）

路由規(guī)則將定義在配置文件的<rules />節(jié)中。這部分內(nèi)容就是一個簡單的路由表，用來定義不同的日志源（Logger的名稱）以及記錄等級的日志信息將被發(fā)送至哪個輸出目標(biāo)中。路由規(guī)則將從列表中的第一項開始執(zhí)行，如果符合當(dāng)前的路由規(guī)則，則該條日志信息將被發(fā)送至指定的輸出目標(biāo)中，若路由表中任意一項都不滿足，則該條日志信息將不會被處理。

路由表中的每一個條目都由一個<logger />元素定義，<logger />元素支持如下幾個屬性：

1. name - 日志源（Logger的名稱），可以使用*通配符
2. minlevel -  匹配該規(guī)則需要的最低記錄等級
3. maxlevel - 匹配該規(guī)則需要的最高記錄等級
4. level - 匹配該規(guī)則需要的單一的記錄等級
5. levels - 匹配該規(guī)則需要的記錄等級列表，記錄等級之間用逗號隔開
6. writeTo - 匹配該規(guī)則的日志信息將被發(fā)送至的輸出目標(biāo)列表，輸出目標(biāo)之間用逗號隔開
7. final - 讓該規(guī)則成為日志信息的最后一個匹配條目。滿足該條規(guī)則的日志信息被處理之后，將不會再繼續(xù)嘗試匹配下面定義的路由規(guī)則。

一些例子：

來自于命名空間Name.Space下Class1的、記錄等級等于或高于Debug的日志信息將被發(fā)送至輸出目標(biāo)f1。

<logger name="Name.Space.Class1" minlevel="Debug" writeTo="f1" />

來自于命名空間Name.Space下Class1的、記錄等級等于為Debug或Error的日志信息將被發(fā)送至輸出目標(biāo)f1。

<logger name="Name.Space.Class1" levels="Debug,Error" writeTo="f1" />

來自于命名空間Name.Space下任意類的任意日志信息將被發(fā)送至輸出目標(biāo)f3和f4。

<logger name="Name.Space.*" writeTo="f3,f4" />

來自于命名空間Name.Space下任意類的、記錄等級在Debug和Error之間（包括Debug、Info、Warn和Error）的日志信息將被忽略（沒有writeTo屬性），且也不會再被下面的路由規(guī)則處理（因為設(shè)置了final="true"）。

<logger name="Name.Space.*" minlevel="Debug" maxlevel="Error" final="true" /> 

在前面的示例程序中，配置文件只包含了一個<target />元素和一個<logger />元素。隨著對程序的需求不斷擴(kuò)充，添加新的輸出目標(biāo)以及路由規(guī)則也將一樣非常簡單。

上下文信息

NLog最具優(yōu)勢的特性之一就是它的布局（layout）概念。“${}”符號用來表示“布局呈現(xiàn)器（layout renderer）”，即隨當(dāng)前日志插入一段上下文信息。我們可以在很多地方使用布局，例如控制日志信息寫入到屏幕以及文件中的格式，甚至還可以控制日志輸出文件的名稱。這個特性功能非常強(qiáng)大，接下來我們就來看看：

假設(shè)我們需要為輸出到控制臺的每一條信息添加如下附加信息：

1. 當(dāng)前的時間日期
2. 發(fā)送該消息的類名和方法名
3. 日志等級
4. 日志內(nèi)容

實現(xiàn)起來非常簡單：

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

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

還可以讓來自不同類的日志信息輸出到不同的文件中：

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

可以看到，上面我們在fileName屬性中使用了${logger}布局呈現(xiàn)器。這樣將讓來自不同類的日志信息輸出到以類名區(qū)分的不同文件中，即輸出如下幾個日志文件：

• 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}布局呈現(xiàn)器，這個要求真是小菜一碟：

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

想要為每個員工生成不同的日志文件？${windows-identity}布局呈現(xiàn)器可以輕松搞定：

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

這樣，NLog將根據(jù)每個員工的登陸信息將日志輸出到單獨的文件中：

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

當(dāng)然還有更加復(fù)雜的情況。下面這個配置文件就為每個人每天生成一個單獨的日志文件，并存放至用時間區(qū)分的目錄中：

<target name="f" xsi:type="File" 

        filename="${shortdate}/${windows-identity:domain=false}.txt"/> 

這條配置信息將生成類似如下的一些日志文件：

1. 2006-01-01/Administrator.txt
2. 2006-01-01/MaryManager.txt
3. 2006-01-01/EdwardEmployee.txt
4. 2006-01-02/Administrator.txt
5. 2006-01-02/MaryManager.txt
6. 2006-01-02/EdwardEmployee.txt
7. ...

NLog提供了很多與定義的布局呈現(xiàn)器，在http://www.nlog-project.org/layoutrenderers.html 這個頁面中有詳細(xì)介紹。創(chuàng)建自己的布局呈現(xiàn)器也同樣簡單，依然是15-20行代碼的事，請參考NLog的文檔（documentation ）。

包含文件

有時我們需要將NLog的配置文件分割成幾個存放。NLog同樣支持在某一配置文件中對其他的配置文件進(jìn)行引用包含，然后在運行時一起處理。和NLog配置文件中其他部分一樣，我們可以使用熟悉的${var}標(biāo)記。這樣就方便根據(jù)不同環(huán)境設(shè)置智能裝載相應(yīng)的配置文件，例如如下示例降加載基于計算機(jī)名的配置文件：

<nlog> 

  ... 

  <include file="${basedir}/${machinename}.config"/> 

  ... 

</nlog> 

使用變量則可以方便地處理復(fù)雜的表達(dá)式，或者以統(tǒng)一的方式引用多次重復(fù)出現(xiàn)的表達(dá)式。我們可以使用<variable name="var" value="xxx" />表達(dá)式定義一個變量，定義之后該變量即可在各種布局呈現(xiàn)器中使用——同樣是${var}語法。例如下面的示例：

<nlog> 

  <variable name="logDirectory" value="${basedir}/logs/${shortdate}"/> 

  <targets> 

    <target name="file1" xsi:type="File" filename="${logDirectory}/file1.txt"/> 

    <target name="file2" xsi:type="File" filename="${logDirectory}/file2.txt"/> 

  </targets> 

</nlog>