Log4NET

[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方法中使用的格式是一樣。

它們的性能要好於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" ?>

</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個屬性：

ConfigFile 配置文件的名字，文件路徑相對於應用程序目錄(AppDomain.CurrentDomain.BaseDirectory)。ConfigFile屬性不能和ConfigFileExtension屬性一起使用。
ConfigFileExtension 配置文件的擴展名，文件路徑相對於應用程序的目錄。ConfigFileExtension屬性不能和ConfigFile屬性一起使用。
Watch 如果將Watch屬性設置爲true，就會監視配置文件。當配置文件發生變化的時候，就會重新加載。
如果ConfigFile和ConfigFileExtension都沒有設置，則使用應用程序的配置文件(AppName.exe.config)。

舉例：

[assembly: log4net.config.XmlConfigurator(Watch=true)]
//監視默認的配置文件，AppName.exe.config

[assembly: log4net.config.XmlConfigurator(ConfigFileExtension="log4net",Watch=true)]
//監視配置文件，AppName.exe.log4net

[assembly: log4net.config.XmlConfigurator(ConfigFile="log4net.config")]
//使用配置文件log4net.config，不監視改變。
[assembly: log4net.config.XmlConfigurator(Watch=true)]
//監視默認的配置文件，AppName.exe.config

[assembly: log4net.config.XmlConfigurator(ConfigFileExtension="log4net",Watch=true)]
//監視配置文件，AppName.exe.log4net

[assembly: log4net.config.XmlConfigurator(ConfigFile="log4net.config")]
//使用配置文件log4net.config，不監視改變。

3.2.2 獲取日誌對象

log4net.ILog logger = log4net.LogManager.GetLogger("LoggerName");

LogManager還有其他多個方法，比如檢查指定日誌是否存在，返回所以日誌對象等等。

特別的，如果日誌名在配置文件中不存在，GetLogger方法會創建一個日誌對象，它會繼承它的父類的屬性。例如"x.y.z"會繼承"x.y"的屬性，如果沒有"x.y"就繼承"x"的屬性，如果連"x"也沒有，會繼承root的屬性。

3.2.3 使用日誌對象

獲取日誌對象後，使用它是很簡單的，只要調用對應的Debug, Info等方法就可以了。不過有一件事要說一下，我們以Debug爲例。

if (log.isDebugEnabled) {log.Debug(...)}

文檔上是這麼說的“如果Debug功能不被使用，就不會有參數構造上的開銷。但是，另一方面，如果logger的Debug功能被起用，就會有倆倍的開銷用於評估logger是否被起用：一次是判斷debugEnabled，一次是判斷debug是否被啓用。但這不是極重的負擔，因爲評估logger的時間只有整個log語句執行時間的1%。”

也就是說Debug方法會先判斷Debug是否啓用，再記錄日誌。使用isDebugEnabled，是否會帶來性能提升，是要看情況的。

3.3 一些配置的例子

配置文件的結構可以參照3.1節，這裏只給出部分元素的使用實例。

3.3.1 <filter>

1) 日誌等級過濾器

其中，日誌等級WARN,FATAL必須大寫。

2) 字符串過濾器

上面的例子，只輸出日誌信息中包含字符串"Warn"或"Error"的才輸出。最後的DenyAllFilter會阻止所有的日誌信息。

過濾器還有一個AcceptOnMatch屬性，默認爲true，表示匹配的時候提交日誌事件。設置成false的時候，不同類型的過濾器是不一樣的。StringMatchFilter會不提交日誌事件，造成匹配的日誌信息不被輸出。

StringMatchFilter還有一個RegexToMatch屬性，用來設置正則表達式。

3.3.2 <appender>

1) AdoNetAppender 將日誌寫入到Sql Server數據庫

數據庫表的Create語句：

CREATE TABLE [dbo].[Log] (
    [Id] [int] IDENTITY (1, 1) NOT NULL,
    [Date] [datetime] NOT NULL,
    [Thread] [varchar] (255) NOT NULL,
    [Level] [varchar] (50) NOT NULL,
    [Logger] [varchar] (255) NOT NULL,
    [Message] [varchar] (4000) NOT NULL,
    [Exception] [varchar] (2000) NULL
)

配置文件：

我經過測試，使用<param>元素，和<parameter>元素都可以，還可以混合使用。對於<parameter>等元素，log4net的文檔上並沒有說，但文檔的例子中卻在用。我個人感覺很多類屬性都可以做標籤用，並不限於文檔中說的那幾個。

上面只是Sql Server的配置，其他數據庫見文檔：http://logging.apache.org/log4net/release/config-examples.html

2) Console 輸出到控制檯

target默認是輸出到標準輸出流的(Console.out)，這裏輸出到標準錯誤輸出流(Console.Error)。

3) ColoredConsoleAppender 高亮輸出到控制檯

上例中，高於等於ERROR的日誌都會用指定的前景色和背景色顯示。也可以有多個<mapping>

4) FileAppender 輸出到文件

上面是一個複雜的FileAppender，其實除了File屬性，其他的屬性都是可選的。這個屬性值可以使用系統的環境變量，上面就用到了系統的臨時文件夾${Tmp}。也可以像layout的Header屬性那樣使用轉義字符串，像這樣：

注意文件名要符合操作系統的命名規範。

layout的Footer屬性，因爲沒有將type設置爲PatternString，所以不能使用轉義字符串。所以要想換行就只有用xml實體了，
表示換行回車/n/r。layout的Header和Footer在很多Appender中是沒有用的，比如ConsoleAppender和AdoAppender。

FileAppender的AppendToFile表示日誌寫入文件的方式是追加還是覆蓋，默認是true，追加。Encoding用來設置文件編碼，不知道問什麼我測試的時候，好像不起作用。lockingModel沒搞懂，大概是多進程操做同一個日誌文件的時候用的吧。

5) RollingFileAppender 輸出到可滾動的文件

RollingFileAppender繼承自FileAppender，FileAppender的屬性，它都可以用。一個簡單的例子：

上例中，如果log.txt的文件大小超過100KB，就會把log.txt做備份，備份文件名爲log.txt.1,log.txt.2……。但是備份文件的最大數是10個。

本文來自CSDN博客，轉載請標明出處：http://blog.csdn.net/lyjcn/archive/2009/08/11/4432833.aspx

工作中用到的腳本合集

通過f-string編寫簡潔高效的Python格式化輸出代碼

24-5-18 X

無線路由連接局域網

StarUML 手冊

hql 語法

Log4NET

Android 調用WCF

https://yachay.unat.edu.pe/blog/index.php?comment_area=format_blog&comment_component=blog&comment_co

linux以太網驅動總結