[C#] 我的log4net使用手冊（完善中）

1. log4net簡介

log4net是.Net下一個非常優秀的開源日誌記錄組件。log4net記錄日誌的功能非常強大。它可以將日誌分不同的等級，以不同的格式，輸出到不同的媒介。Java平台下，它還有一個姐妹組件——log4j。

log4net的下載地址：http://logging.apache.org/log4net/download.html

 

2. log4net的組成

log4net主要由五部分組成，分別為Appenders、Filters、Layouts、Loggers和Object Renders。

2.1 Appenders

Appenders用來定義日誌的輸出方式。它還可以通過配置Filters和Layout來實現日誌的過濾和輸出格式。

它的輸出方式有： AdoNetAppender 將日誌記錄到資料庫中。可以採用SQL和預存程序兩種方式。 AnsiColorTerminalAppender 將日誌高亮輸出到ANSI終端。 AspNetTraceAppender  能用asp.net中Trace的方式查看記錄的日誌。 BufferingForwardingAppender 在輸出到子Appenders之前先緩衝日誌事件。 ConsoleAppender 將日誌輸出到應用程式控制台。 EventLogAppender 將日誌寫到Windows Event Log。 FileAppender 將日誌輸出到檔案。 ForwardingAppender 發送日誌事件到子Appenders。 LocalSyslogAppender 將日誌寫到local syslog service (僅用於UNIX環境下)。 MemoryAppender 將日誌存到記憶體緩衝區。 NetSendAppender 將日誌輸出到Windows Messenger service.這些日誌資訊將在使用者終端的對話方塊中顯示。 OutputDebugStringAppender 將日誌輸出到Debuger，如果程式沒有Debuger，就輸出到系統Debuger。如果系統Debuger也不可用，將忽略訊息。 RemoteSyslogAppender 通過UDP網路通訊協定將日誌寫到Remote syslog service。 RemotingAppender 通過.NET Remoting將日誌寫到遠程接收端。 RollingFileAppender 將日誌以復原檔案的形式寫到檔案中。 SmtpAppender 將日誌寫到郵件中。 SmtpPickupDirAppender 將訊息以檔案的方式放入一個目錄中，像IIS SMTP agent這樣的SMTP代理就可以閱讀或發送它們。 TelnetAppender 用戶端通過Telnet來接受日誌事件。 TraceAppender 將日誌寫到.NET trace 系統。 UdpAppender 將日誌以無串連UDP資料報的形式送到遠程宿主或用UdpClient的形式廣播。

2.2 Filters

使用過濾器可以過濾掉Appender輸出的內容。過濾器有以下幾種： DenyAllFilter 阻止所有的日誌事件被記錄 LevelMatchFilter 只有指定等級的日誌事件才被記錄 LevelRangeFilter 日誌等級在指定範圍內的事件才被記錄 LoggerMatchFilter Logger名稱匹配，才記錄 PropertyFilter 訊息匹配指定的屬性值時才被記錄 StringMathFilter 訊息匹配指定的字串才被記錄

2.3 Layouts

Layout用於控制Appender的輸出格式，可以使線性也可以使XML。一個Appender只能有一個Layout。

最常用的Layout應該是使用者自訂格式的PatternLayout，其次是SimpleLayout和ExceptionLayout。然後還有4個Layout，其中有兩個是輸出Xml的Layout，但是中文會有問題。

ExceptionLayout需要給Logger的方法傳入Exception對象作為參數才起作用，否則就什麼也不輸出。輸出的時候會包含Message和Trace

最後說一下PatterLayout的格式化字串：

Conversion Pattern Name	Effect
a	等價於appdomain
appdomain	引發日誌事件的應用程式定義域的易記名稱。（我在使用中一般是可執行檔的名字。）
c	等價於 logger
C	等價於 type
class	等價於 type
d	等價於 date
date	發生日誌事件的本地時間。 使用 %utcdate 輸出UTC時間。date後面還可以跟一個日期格式，用大括弧括起來。例如：%date{HH:mm:ss,fff}或者%date{dd MMM yyyy HH:mm:ss,fff}。如果date後面什麼也不跟，將使用ISO8601 格式 。 日期格式和.Net中DateTime類的ToString方法中使用的格式是一樣。 另外log4net還有3個自己的格式Formatter。 它們是 "ABSOLUTE", "DATE"和"ISO8601"分別代表 AbsoluteTimeDateFormatter,DateTimeDateFormatter和Iso8601DateFormatter。例如：%date{ISO8601}或%date{ABSOLUTE}。 它們的效能要好於ToString。
exception	異常資訊 日誌事件中必須存了一個異常對象，如果日誌事件不包含沒有異常對象，將什麼也不輸出。異常輸出完畢後會跟一個換行。一般會在輸出異常前加一個換行，並將異常放在最後。
F	等價於 file
file	發生日誌請求的原始碼檔案的名字。 警告：只在調試的時候有效。調用本地資訊會影響效能。
identity	當前活動使用者的名字(Principal.Identity.Name). 警告：會影響效能。（我測試的時候%identity返回都是空的。）
l	等價於 location
L	等價於 line
location	引發日誌事件的方法（包括命名空間和類名），以及所在的源檔案和行號。 警告：會影響效能。沒有pdb檔案的話，只有方法名，沒有源檔案名稱和行號。
level	日誌事件等級
line	引發日誌事件的行號 警告：會影響效能。
logger	記錄日誌事件的Logger對象的名字。 可以使用有效位數規範控制Logger的名字的輸出層級，預設輸出全名。 注意，精度符的控制是從右開始的。例如：logger 名為 "a.b.c"， 輸出模型為%logger{2} ，將輸出"b.c"。
m	等價於 message
M	等價於 method
message	由應用程式提供給日誌事件的訊息。
mdc	MDC (舊為：ThreadContext.Properties) 現在是事件屬性的一部分。 保留它是為了相容性，它等價於 property。
method	發生日誌請求的方法名（只有方法名而已）。 警告：會影響效能。
n	等價於 newline
newline	分行符號
ndc	NDC (nested diagnostic context)
p	等價於 level
P	等價於 property
properties	等價於 property
property	輸出事件的特殊屬性。例如： %property{user} 輸出user屬性。屬性是由loggers或appenders添加到時間中的。 有一個預設的屬性"log4net:HostName"總是會有。 %property將輸出所以的屬性 。 （我除了知道可以用它獲得主機名稱外，還不知道怎麼用。）
r	等價於 timestamp
t	等價於 thread
timestamp	從程式啟動到事件發生所經過的毫秒數。
thread	引發日誌事件的線程，如果沒有線程名就使用線程號。
type	引發日誌請求的類的全名。. 可以使用精度控制符。例如： 類名是 "log4net.Layout.PatternLayout", 格式模型是 %type{1} 將輸出"PatternLayout"。（也是從右開始的。） 警告：會影響效能。
u	等價於 identity
username	目前使用者的WindowsIdentity。（類似：HostName/Username） 警告：會影響效能。
utcdate	發生日誌事件的UTC時間。後面還可以跟一個日期格式，用大括弧括起來。例如：%utcdate{HH:mm:ss,fff}或者%utcdate{dd MMM yyyy HH:mm:ss,fff}。如果utcdate後面什麼也不跟，將使用ISO8601 格式 。 日期格式和.Net中DateTime類的ToString方法中使用的格式是一樣。 另外log4net還有3個自己的格式Formatter。 它們是 "ABSOLUTE", "DATE"和"ISO8601"分別代表 AbsoluteTimeDateFormatter,DateTimeDateFormatter和Iso8601DateFormatter。例如：%date{ISO8601}或%date{ABSOLUTE}。 它們的效能要好於ToString。
w	等價於 username
x	等價於 ndc
X	等價於 mdc
%	%%輸出一個百分比符號

關於調用本地資訊（caller location information）的說明：

%type %file %line %method %location %class %C %F %L %l %M 都會調用本地資訊。這樣做會影響效能。本地資訊使用System.Diagnostics.StackTrace得到。.Net 1.0 不支援System.Diagnostics.StackTrace 類。

本地資訊在偵錯模式下可以正常擷取，在非偵錯模式下可能擷取不到，或只能擷取一部分。（根據我的測試，其實是需要有一個程式資料庫（.pdb）檔案。）

%property 這個東西中的屬性好像是要用代碼來設定(除了預設屬性log4net:HostName)。

逸出字元的修飾符：

Format modifier	left justify	minimum width	maximum width	comment
%20logger	false	20	none	如果logger名不足20個字元，就在左邊補空格。
%-20logger	true	20	none	如果logger名不足20個字元，就在右邊補空格。
%.30logger	NA	none	30	超過30個字元將截斷。
%20.30logger	false	20	30	logger名要在20到30之間，少了在左邊補空格，多了截斷。
%-20.30logger	true	20	30	logger名要在20到30之間，少了在右邊補空格，多了截斷。

 

2.4 Loggers

Logger是直接和應用程式互動的組件。Logger只是產生日誌，然後由它引用的Appender記錄到指定的媒介，並由Layout控制輸出格式。

Logger提供了多種方式來記錄一個日誌訊息，也可以有多個Logger同時存在。每個執行個體化的Logger對象對被log4net作為具名實體（Named Entity）來維護。log4net使用繼承體系，也就是說假如存在兩個Logger，名字分別為a.b.c和a.b。那麼a.b就是a.b.c的祖先。每個Logger都繼承了它祖先的屬性。

下面說一下日誌的等級，它們由高到底分別為：

OFF > FATAL > ERROR > WARN > INFO > DEBUG  > ALL 

其中OFF表示停用所以日誌記錄，ALL表示所有日誌都可以記錄。

Logger實現的ILog介面，ILog定義了5個方法（Debug,Inof,Warn,Error,Fatal）分別對不同的日誌等級記錄日誌。這5個方法還有5個重載。我們以Debug為例說明一下，其它的和它差不多。

ILog中對Debug方法的定義如下：

void Debug(object message);

void Debug(object message, Exception ex);

還有一個布爾屬性：

bool IsDebugEnabled { get; }

如果使用Debug(object message, Exception ex)，則無論Layout中是否定義了%exception，預設配置下日誌都會輸出Exception。包括Exception的Message和Trace。如果使用Debug(object message)，則無論如何日誌是不會輸出Exception的，因為沒有啊。

最後還要說一個LogManager類，它用來管理所應得Logger。它的GetLogger靜態方法，可以獲得設定檔中相應的Logger：

log4net.ILog log = log4net.LogManager.GetLogger("logger-name");

 

2.5 Object Renders

我對Object Renders的理解是這樣的。它將告訴logger如何把一個對象轉化為一個字串記錄到日誌裡。（你可能注意到了，ILog中定義的介面接收的參數是Object，而不是String。）

例如你想把Orange對象記錄到日誌中，但此時logger只會調用Orange預設的ToString方法而已。所以要定義一個OrangeRender類實現log4net.ObjectRender.IObjectRender介面，然後註冊它。這時logger就會知道如何把Orange記錄到日誌中了。

不過我沒有測試過，具體怎麼做還是看文檔吧。

 

2.6 Repository

Repository主要用於日誌對象組織圖的維護。如果你不想自己擴充log4Net的話，可以用不找它。但我還是覺得應該提一下。

 

3.  在程式中使用log4net

在使用log4net前要先做一些配置的工作。配置工作可以在設定檔中完成也可以再程式中用程式碼完成。我們主要講在設定檔中如何配置log4net，因為這樣更方便靈活，而且還不用重新編譯代碼。至於如何使用代碼進行配置，請查看文檔和後面參考中的串連。

3.1 定義設定檔

log4net的配置可以放在應用程式的預設設定檔中（app.config或web.config），也可以再你自己的設定檔中。

如果用Visual Studio來編輯設定檔，它對log4net的標籤是不會智能提示和自動補全的。當然也不是不可能，看這裡：

http://www.cnblogs.com/didasoft/archive/2007/07/23/log4net_xsd.html

這裡要感謝Jerry同學，為我們提供的xsd schema。

廢話少說，先看一個完整的設定檔的例子：

<?xml version="1.0" encoding="utf-8" ?>

<configuration>

  <configSections> 
    <section name="log4net" 
             type="log4net.Config.Log4NetConfigurationSectionHandler, log4net-net-1.2.10" /> 
  </configSections>

  <log4net>

    <root> 
      <level value="WARN" /> 
      <appender-ref ref="LogFileAppender" /> 
      <appender-ref ref="ConsoleAppender" /> 
    </root>

    <logger name="testApp.Logging"> 
      <level value="DEBUG"/> 
    </logger>

    <appender name="LogFileAppender" 
              type="log4net.Appender.FileAppender" > 
      <param name="File" value="log-file.txt" /> 
      <param name="AppendToFile" value="true" />

      <layout type="log4net.Layout.PatternLayout"> 
        <param name="Header" value="[Header]&#13;&#10;"/> 
        <param name="Footer" value="[Footer]&#13;&#10;"/> 
        <param name="ConversionPattern" 
               value="%d [%t] %-5p %c [%x]  - %m%n" /> 
      </layout>

      <filter type="log4net.Filter.LevelRangeFilter"> 
        <param name="LevelMin" value="DEBUG" /> 
        <param name="LevelMax" value="WARN" /> 
      </filter>

    </appender>

    <appender name="ConsoleAppender" 
              type="log4net.Appender.ConsoleAppender" > 
      <layout type="log4net.Layout.PatternLayout"> 
        <param name="ConversionPattern" 
               value="%d [%t] %-5p %c [%x] - %m%n" /> 
      </layout> 
    </appender>

  </log4net> 
</configuration>

如果log4net的配置不是放在應用程式的設定檔裡，而是在自己定義的檔案裡，<configSection>節點裡的<section>節點是不需要的。

下面對其中的標籤元素做一下說明。

3.1.1 <log4net>

所有的配置都要在<log4net>元素裡定義。

支援的屬性：

debug	可選，取值是true或false，預設是false。設定為true，開啟log4net的內部調試。
update	可選，取值是Merge(合并)或Overwrite(覆蓋)，預設值是Merge。設定為Overwrite，在提交配置的時候會重設已經配置過的庫。
threshold	可選，取值是repository（庫）中註冊的level，預設值是ALL。

支援的子項目：

appender	0或多個
logger	0或多個
renderer	0或多個
root	最多一個
param	0或多個

3.1.2 <root>

實際上就是一個根logger，所有其它logger都預設繼承它。root元素沒有屬性。

支援的子項目：

appender-ref	0個或多個，要引用的appender的名字。
level	最多一個。 只有在這個層級或之上的事件才會被記錄。
param	0個或多個， 設定一些參數。

3.1.3 <logger>

支援的屬性：

name	必須的，logger的名稱
additivity	可選，取值是true或false，預設值是true。設定為false時將阻止父logger中的appender。

支援的子項目：

appender-ref	0個或多個，要引用的appender的名字。
level	最多一個。 只有在這個層級或之上的事件才會被記錄。
param	0個或多個， 設定一些參數。

3.1.4 <appender>

定義日誌的輸出方式，只能作為 log4net 的子項目。name屬性必須唯一，type屬性必須指定。

支援的屬性：

name	必須的，Appender對象的名稱
type	必須的，Appender對象的輸出類型

支援的子項目：

appender-ref	0個或多個，允許此appender引用其他appender，並不是所以appender類型都支援。
filter	0個或多個，定義此app使用的過濾器。
layout	最多一個。定義appender使用的輸出格式。
param	0個或多個， 設定Appender類中對應的屬性的值。

實際上<appender>所能包含的子項目遠不止上面4個。

3.1.5 <layout>

布局，只能作為<appender>的子項目。

支援的屬性：

type	必須的，Layout的類型

支援的子項目：

param

0個或多個， 設定一些參數。

3.1.6 <filter>

過濾器，只能作為<appender>的子項目。

支援的屬性：

type	必須的，Filter的類型

支援的子項目：

param

0個或多個， 設定一些參數。

3.1.7 <param>

<param>元素可以是如何元素的子項目。

支援的屬性：

name	必須的，取值是父物件的參數名。
value	可選的，value和type中，必須有一個屬性被指定。value是一個能被轉化為參數值的字串。
type	可選的，value和type中，必須有一個屬性被指定。type是一個類型名，如果type不是在log4net程式集中定義的，就需要使用全名。

支援的子項目：

param

0個或多個， 設定一些參數。

3.2 使用設定檔

3.2.1 關聯設定檔

log4net預設關聯的是應用程式的設定檔(AppName.exe.config)，可以使用程式集自訂屬性來進行設定。下面來介紹一下這個自訂屬性：log4net.Config.XmlConifguratorAttribute。

XmlConfiguratorAttribute有3個屬性：</