NLog類庫使用探索——詳解配置

1 配置文件的位置(Configuration file locations)

    通過在啟動的時候對一些常用目錄的掃描，NLog會嘗試使用找到的配置信息進行自動的自我配置。

1.1 單獨的*.exe客戶端

    單獨的客戶端，NLog將在以下目錄搜索配置信息：

1. 標准的程序配置文件（通常為 程序名.exe.config）
2. 程序目錄下的程序名.exe.nlog文件
3. 程序目錄下的NLog.config文件
4. NLog.dll所在目錄下的NLog.dll.nlog文件 （在Nlog沒有導入GAC情況下）

1.2 ASP.NET程序

    在ASP.NET項目中搜索的目錄包括：

1. 標准的web程序配置文件web.config
2. 和web.config在同一目錄下的web.nlog文件
3. 程序目錄下的NLog.config文件
4. NLog.dll所在目錄下的NLog.dll.nlog文件 （在Nlog沒有導入GAC情況下）
5. 如果定義了NLOG_GLOBAL_CONFIG_FILE環境變量，則該變量所指向的文件

1.2 硬件設備類庫（.NET Compact Framework）

    .NET Compact Framework不支持程序配置文件（*.exe.config）和環境變量，因此NLog將只會掃描這些地方：

1. 程序目錄下的NLog.config文件
2. NLog.dll所在目錄下的NLog.dll.nlog文件 （在Nlog沒有導入GAC情況下）

1.4 小結

      從上面來看，不管哪個我們把配置文件命名為NLog.config，放在應用程序的目錄下，肯定都可以掃描到，哈哈。

2 配置文件的格式(Configuration file format)

   2.1  NLog支持兩種配置文件格式

1. 配置信息嵌入在.NET應用程序標准的*.exe.config或者web.config文件里
2. 保存在獨立文件里

   第一種就是我們熟悉的常規配置，使用configSections

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

    如果是第二種，是一個單獨的Xml文件的話，需要按如下配置：

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

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

    需要說明的是，根節點是<nlong></nlong>,兩個命名空間是可選的，但是為了智能感應，你還是把它寫上吧。

2.1 子元素的配置

• <targets /> – defines log targets/outputs ，聲明目標
• <rules /> – defines log routing rules ，聲明規則
• <extensions /> – loads NLog extensions from the *.dll file  加載dll擴展（其實我不懂，沒用過）
• <include /> – includes external configuration file   包含外部配置文件
• <variable /> – sets the value of a configuration variable 為配置變量賦值

     需要說明的是前兩個元素，也就是targets和rules是必需配置的，其余是可選的，應該用於更復雜的配置上，我個人沒用過還。

3 輸出目標(Targets )

      第一篇文章已經介紹過，應該不用再解釋，具體輸出到那個目標的詳細配置，參見文檔：https://github.com/nlog/NLog/wiki/Targets

4 路由規則(Rules)

   <rules />區域定義了日志的路由規則。每一個路由表項就是一個<logger />元素。<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")。

5 上下文布局信息(Layouts and layout renderers)

     NLog最強大的功能之一就是使用布局（layouts）的能力。語法為：“${屬性}”為標記所包圍的文本所組成。這個標記也就是所謂的“布局生成器（layout renderers），我們可以用它來把一些上下文相關的信息插入到日志信息中。布局可以應用在許多地方，比如可以被用在控制輸出到屏幕或寫入文件信息的格式，也可以用在控制文件名。

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

• 當前的日期和時間
• 產生日志信息的類和方法的名字
• 日志等級
• 日志內容

利用Layout來實現很簡單：，前面已經提到過：

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

使用Layout控制輸出的文件名：

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

使用日期來區分日志文件。如果使用${shortdate}布局生成器：

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

更多的布局生成器參考官方文檔：

https://github.com/nlog/NLog/wiki/Layout%20Renderers

6 包含配置文件(Include files)

    我們有這樣的需求，不想讓NLog.cofige文件太大，太多，讀起來太累，我們可以把它分割下。如何分割成若干小的config呢？使用include簡單完成。

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

制定了要包含的config小文件位置就行。

7 變量(Variables)

配置文件中也可以定義變量，直接上例子，很明了：

//聲明語法

<variable name="var" value="xxx" />

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

8 自動再配置(Automatic reconfiguration)

    聽起來確實挺不好理解的。但是確實也沒什么。換句簡單的話來說，當我們一旦啟動程序，這時候NLog.config文件被讀取后，知道程序再啟動都不會再讀取配置文件了。假如我們不想停掉程序，比如說服務器哪能說停就停哈。這就用上這個配置了，這個配置功能是，一旦你對配置文件修改，程序將會重新讀取配置文件，也就是自動再配置。直接上代碼：

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

9 日志排錯(Troubleshooting logging)

       程序沒問題了，日志卻出了問題。這個該怎么辦，到底是哪里不正確了？假如日志本身除了bug該如何解決？這就需要日志排錯。把日志的錯誤信息寫入日志。

• <nlog throwExceptions="true" />    
• <nlog internalLogFile="file.txt" />- 設置internalLogFile屬性可以讓NLog把內部的調試和異常信息都寫入指定文件里。
• <nlog internalLogLevel="Trace|Debug|Info|Warn|Error|Fatal" /> - 決定內部日志的級別，級別越高，輸出的日志信息越簡潔。
• <nlog internalLogToConsole="false|true" /> - 是否把內部日志輸出到標准控制台。
• <nlog internalLogToConsoleError="false|true" /> - 是否把內部日志輸出到標准錯誤控制台 (stderr)。

      設置throwExceptions屬性為“true”可以讓NLog不再阻擋這類異常，而是把它們拋給調用者。在部署是這樣做可以幫我們快速定位問題。一旦應用程序已經正確配置了，我們建議把throwExceptions的值設為“false”，這樣由於日志引發的問題不至於導致應用程序的崩潰。

10、異步處理(Asynchronous processing )

       原理也不多說，直接上代碼，使其具備異步處理能力。

<nlog>
  <targets async="true">
    <!-- all targets in this section will automatically be asynchronous -->
  </targets>
</nlog>

11 缺省封裝(Default  wrappers)

    我們希望用同一種封裝來處理所有的目標，比如說增加緩沖和/或自動重試功能。

   NLog為此提供了專門的語法：<default-wrapper />。你只要把這個元素放在<targets />區域里，然后所有的目標都會自動加載同一個封裝目標。需要注意的是<default-wrapper />只對當前這個<targets />區域有效，而你可以使用多個<targets />區域，這樣你就可以把目標分組並用不同的封裝目標處理。

<nlog>  
  <targets>  
    <default-wrapper xsi:type="BufferingWrapper" bufferSize="100"/>  
    <target name="f1" xsi:type="File" fileName="f1.txt"/>  
    <target name="f2" xsi:type="File" fileName="f2.txt"/>  
  </targets>  
  <targets>  
    <default-wrapper xsi:type="AsyncWrapper">  
      <wrapper-target xsi:type="RetryingWrapper"/>  
    </default-wrapper>  
    <target name="n1" xsi:type="Network" address="tcp://localhost:4001"/>  
    <target name="n2" xsi:type="Network" address="tcp://localhost:4002"/>  
    <target name="n3" xsi:type="Network" address="tcp://localhost:4003"/>  
  </targets>  
</nlog>

上面的例子里我們定義了兩個緩沖文件目標和三個異步以及自動重試網絡目標。

12 缺省目標參數（Default target parameters）

     其實缺省就是把分散的統一在一個區域來定義，僅僅是個語法糖問題，缺省參數自然是把參數相同的抽象出來放到一個區域，統一定義罷了。下面代碼是等價的。

<nlog> 
  <targets> 
    <target name="f1" xsi:type="File" fileName="f1.txt" keepFileOpen="false"/> 
    <target name="f2" xsi:type="File" fileName="f2.txt" keepFileOpen="false"/> 
    <target name="f3" xsi:type="File" fileName="f3.txt" keepFileOpen="false"/> 
  </targets> 
</nlog>

<nlog>
  <targets>
    <default-target-parameters xsi:type="File" keepFileOpen="false"/>
    <target name="f1" xsi:type="File" fileName="f1.txt"/>
    <target name="f2" xsi:type="File" fileName="f2.txt"/>
    <target name="f3" xsi:type="File" fileName="f3.txt"/>
  </targets>
</nlog>