[轉]NLog學習筆記二：深入學習

配置文件

NLog所有的配置信息都可以寫到一個單獨的xml文件中，也可以在程序代碼中進行配置。

配置文件位置

啟動的時候，NLog會試圖查找配置文件完成自動配置，查找的文件依次如下（找到配置信息則結束查詢）：

1. 應用程序的標准配置文件（通常為applicationname.exe.config）
2. 應用程序所在目錄中的applicationname.exe.nlog文件
3. 應用程序所在目錄中的NLog.config文件
4. NLog.dll所在目錄中的NLog.dll.nlog文件
5. 環境變量NLOG_GLOBAL_CONFIG_FILE所指向的文件

對於ASP.NET應用程序，NLog將自動按照順序搜索下列路徑：

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. 應用程序所在目錄中的applicationname.exe.nlog文件
2. 應用程序所在目錄中的NLog.config文件
3. NLog.dll所在目錄中的NLog.dll.nlog文件

配置文件形式

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

1. 嵌入到*.exe.config或web.config等標准配置文件中
2. 單獨的配置文件NLog.config

對於第一種形式，我們使用了標准化的configSection機制。這樣配置文件將類似如下所示：

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

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

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

例如：

<?xml version="1.0" encoding="utf-8" ?> <configuration> <!--***configSections節點必須位於頂部--> <configSections> <section name="nlog" type="NLog.Config.ConfigSectionHandler, NLog" requirePermission="false" /> </configSections> <startup> <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.5" /> </startup> <nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <targets> <target name="logfile" xsi:type="File" fileName="file.txt" /> </targets> <rules> <logger name="*" minlevel="Info" writeTo="logfile" /> </rules> </nlog> </configuration>

代碼中配置

NLog也可以通過編程配置，代碼如下：

using NLog; using NLog.Config; using NLog.Targets; using System; using System.Collections.Generic; using System.Linq; using System.Text; using System.Threading.Tasks; namespace NLogConsoleDemo { /// <summary> /// 測試在代碼中配置NLog /// </summary> class Program { static void Main(string[] args) { // Step 1. Create configuration object var config = new LoggingConfiguration(); // Step 2. Create targets and add them to the configuration var consoleTarget = new ColoredConsoleTarget(); config.AddTarget("console", consoleTarget); var fileTarget = new FileTarget(); config.AddTarget("file", fileTarget); // Step 3. Set target properties consoleTarget.Layout = @"${date:format=HH\:mm\:ss} ${logger} ${message}"; fileTarget.FileName = "${basedir}/file.txt"; fileTarget.Layout = "${message}"; // Step 4. Define rules var rule1 = new LoggingRule("*", LogLevel.Debug, consoleTarget); config.LoggingRules.Add(rule1); var rule2 = new LoggingRule("*", LogLevel.Debug, fileTarget); config.LoggingRules.Add(rule2); // Step 5. Activate the configuration LogManager.Configuration = config; // Example usage Logger logger = LogManager.GetLogger("Program"); logger.Trace("trace log message"); logger.Debug("debug log message"); logger.Info("info log message"); logger.Warn("warn log message"); logger.Error("error log message"); logger.Fatal("fatal log message"); Console.ReadLine(); } } }

目標（Targets）

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

1. name - 輸出目標的名稱
2. type - 輸出目標的類型，例如“File”、“DataBase”、“Mail”等。若我們為配置文件指定了命名空間，則該屬性名為xsi:type。

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

例如：“File”輸出目標接受一個名為fileName的參數，用來指定輸出文件的名稱；而“Console”輸出目標則接受一個名為error的參數，表示是否用標准錯誤輸出（stderr）代替標准輸出（stdout）。

關於文件目標的詳細介紹請查看File target，關於目標類型的詳細介紹請查看Targets。

規則（Rules）

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

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

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

一些例子：

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

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

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

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

 來自於命名空間Name.Space下任意類的任意日志信息將被發送至輸出目標f3和f4。

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

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

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

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

可用的日志等級如下（降序排序）：

• Fatal：致命異常信息，非常嚴重的錯誤。
• Erorr：錯誤信息，用於記錄異常。
• Warn：警告信息，用於記錄不正確的，但程序還可以允許的行為。
• Info：信息類型的消息，用於記錄一般的操作。
• Debug：一般用來調試程序，用於記錄查詢、用戶認證、session過期等。
• Trace：最常見的記錄信息，一般用於普通輸出，例如：開始於哪個方法，結束於哪個方法。

布局和布局渲染器（Layouts and layout renderers）

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

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

1. 當前的時間日期
2. 發送該消息的類名和方法名
3. 日志等級
4. 日志內容

實現起來非常簡單：

<target name="c" xsi:type="Console" layout="${longdate} | ${callsite} | ${level} | ${message}"/> 

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

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

 默認的layout屬性值： ${longdate}|${level:uppercase=true}|${logger}|${message} ，關於布局的詳細介紹請查看Layouts。

關於布局渲染器的詳細介紹請查看Layout Renderers，此處介紹幾個常用的：

• ${date:universalTime=Boolean:format=String:culture=Culture}：當前日期和時間。
• ${shortdate:universalTime=Boolean}：表示格式為 yyyy-MM-dd 的短日期。 
• ${longdate:universalTime=Boolean}：表示格式為 yyyy-MM-dd HH\:mm\:ss.ffff  的長日期格式。 universalTime 設置是否輸出UTC時間代替本地時間，默認為 false 。 例如：2016-02-19 10:33:49.9398
• ${level}：表示日志等級。  uppercase  值設置大小寫，默認為 false ，即首字母大寫，其余字母小寫。例如（依次為默認、大寫）：Trace、TRACE
• ${logger}：表示日志記錄器的名稱，也就是方法 LogManager.GetLogger("Program")  的參數值。例如：Program
• ${message}：表示日志消息。例如：  logger.Trace("Sample trace message");  ，則結果為：Sample trace message
• ${machinename}：表示服務器名稱，即計算機名稱。
• ${newline}：表示換行。
• ${exception:innerFormat=String:maxInnerExceptionLevel=Integer:innerExceptionSeparator=String:separator=String:format=String}：表示異常信息。 format - 設置輸出格式，必須是異常的屬性：Message、Type、ShortType、ToString、Method、StackTrace、Data，默認值為Message； innerFormat - 設置內部異常的輸出格式，可選值：Message, Type, ShortType, ToString, Method, StackTrace； maxInnerExceptionLevel - 設置包含在輸出中的最大內部異常個數，默認為0； innerExceptionSeparator - 設置內部異常之間的分隔符，默認為換行； separator - 設置用於連接格式中的多個數據，默認為一個空格，例如： ${exception:format=message,tostring} ，則用一個空格分隔message和string。

包含文件

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

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

可選屬性， ignoreErrors="true" ，默認為 false ，可以設置當包含的文件未找到或格式不正確時是否拋出異常。當設置為 true 時，使用 Troubleshooting logging節點記錄錯誤。

變量（Variables）

變量被用於定義復雜的表達式，或者多次重復出現的表達式。例如：

<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>

變量需要在使用前聲明，否則初始化配置時將失敗。

但是，自從NLog 4.1以后，使用  ${var:var1} 代替 ${var1} ，例如：

<nlog>
  <variable name="user" value="admin" /> <variable name="password" value="realgoodpassword" /> <targets> <target name="debug" type="Debug" layout="${message} and ${var:user}=${var:password}" /> </targets> <rules> <logger name="*" minlevel="Debug" writeTo="debug" /> </rules> </nlog>

 自動重新配置（Autonatic reconfiguration）

配置文件在程序啟動的時候被自動讀取。程序長時間的運行過程中，有時可能想要改變日志等級，而不停止應用程序。NLog可以監控配置文件，在配置文件發生改變后重新讀取。需要如下設置：

<nlog autoReload="true"> ... </nlog>

 注意：包含的文件發生改變也會導致重新加載。

日志功能排錯（Troubleshooting logging）

有時雖然已經配置好了NLog，可是有些時候應用程序仍舊會出現一些難以理解的問題，例如沒有任何日志輸出。其中最常見的原因就是ASP.NET的權限——ASP.NET的aspnet_wp.exe或w3wp.exe可能沒有對NLog配置文件中指定目錄的寫入權限。NLog對於其自身運行中發生的異常有着很強的監測能力。如下設定可以將這些監測結果輸出至指定位置，或是對這些異常進行相應的處理（默認設定將忽略自身異常）：

• <nlog throwExceptions="true" />- 當NLog自身擲出異常時，該選項可以將異常擲回日志的調用者。在開發過程中，這個設定將變得非常有用，能夠迅速幫助我們定位異常的位置以及原因。而當程序開發結束並部署到應用環境時，應該盡快設定throwExceptions為false，免得NLog自身的異常導致整個應用程序的崩潰。
• <nlog internalLogFile="file.txt" />- 讓NLog將自身運行過程中的日志信息（包括可能出現的異常）寫入到文件中。
• <nlog internalLogLevel="Trace|Debug|Info|Warn|Error|Fatal" /> - 選擇寫入內部日志的記錄等級。該等級設定的越高，相應的輸出日志文件將越小。
• <nlog internalLogToConsole="false|true" /> - 將內部日志信息發送至控制台。
• <nlog internalLogToConsoleError="false|true" /> - 將內部日志信息發送至標准異常輸出（stderr）。

異步處理和包裝器（Asynchronous processing and wrapper targets）

NLog的包裝器和復合輸出目標特性讓我們能夠修改輸出目標的默認行為，這種修改體現在如下幾個方面：

• 異步處理（向目標輸出將用單獨的線程處理）
• 異常時自動重試
• 負載平衡
• 緩存 
• 過濾 
• 備用輸出目標（主輸出目標失敗時啟用備用輸出目標）

只要在配置文件中將若干個target節點嵌套起來，即可完成對包裝器或復合輸出目標的定義。嵌套深度沒有任何限制。例如為某個輸出目標添加異步處理以及異常自動重試功能，只要按照如下代碼配置NLog即可：

<targets> 
  <target name="n" xsi:type="AsyncWrapper"> <target xsi:type="RetryingWrapper"> <target xsi:type="File" fileName="${file}.txt"/> </target> </target> </targets> 

 異步處理特性極為常用，因此NLog提供了一種簡寫方式——即 <targets async="true" /> ，這樣該輸出目標將自動應用AsyncWrapper包裝器。

擴展（Extendsions）

關於擴展的詳細信息請查看Extending NLog。

參考文檔

1. https://github.com/NLog/NLog/wiki/Configuration-file
2. http://www.cnblogs.com/dflying/archive/2006/12/06/584426.html