Log For log4net (三) — 配置语法

接上篇

注：这是log4net配置文档的最后一部份，描述了配置文档的语法

对于其中的renderer的意义不是很清楚

原文地址：log4net Manual - Configuration

log4net使用log4net.Config.XmlConfigurator配置读取器来解析XML，这一部分描述XmlConfigurator的语法

下面是一个有效的XML配置，根元素必须是<log4net>，这并不意味着这个元素不能嵌入到其他元素里面。详见配置文件节。

<log4net>

    <appender name="ConsoleAppender" type="log4net.Appender.ConsoleAppender" >

        <layout type="log4net.Layout.PatternLayout">

            <conversionPattern value="%date [%thread] %-5level %logger [%ndc] - %message%newline" />

        </layout>

    </appender>

    <root>

        <level value="INFO" />

        <appender-ref ref="ConsoleAppender" />

    </root>

</log4net>

<log4net>节支持下列属性

debug：可选属性，值为true或者false，默认为false。指定为true时允许log4net的内部调试
update：可选属性，值为Merge或者Overwrite，默认为Merge。指定为Overwrite时将在应用此配置之前重置库中的配置。
threshold：可选属性，值必须是已在库中已注册的等级名，默认为ALL。这个属性用来在整个库中限制需要记录的等级，不管记录到任何地方。
<log4net>支持下列子元素

appender：0或者多个，定义记录方式（appender）
logger：0或者多个，定义记录器（logger）的配置。
renderer：0或者多个，定义一个对象renderer（不知道怎么意思）
root：0个或者1个，定义根记录器
param：0或者多个，库特定参数。

Appenders

Appenders只可以定义为<log4net>元素的子元素，每个appender（记录方式）都必须被唯一的命名，appender的实现类型也必须制定。下面的例子定义了一个log4net.Appender.ConsoleAppender类型的记录器，即控制台记录方式

<appender name="ConsoleAppender" type="log4net.Appender.ConsoleAppender" >

    <layout type="log4net.Layout.PatternLayout">

        <conversionPattern value="%date [%thread] %-5level %logger [%ndc] - %message%newline" />

    </layout>

</appender>

<appender>节支持下列属性

name：必须属性，字符串表示的appender名称，名称必须在所有记录方式中唯一，它在记录器的<appender-ref>元素中被引用，用来指定记录方式。
type：必须属性，值为记录器类型名，如果记录器不在log4net组件集中，必须给出完整的组件集名称。
<appender>节支持下列子元素
appender-ref：0或者多个，允许记录方式引用其他记录方式，不被所有记录方式支持。
filter：0或者多个，定义记录方式的过滤器
layout：0个或者1个，定义记录方式的布局
param：0或者多个，记录方式特定参数。

例子参见Example Appender Configuration文档

Filters（过滤器）

filter只可以定义为<appender>元素的子元素

<filter>节支持下列属性
type：必须属性，值为过滤器的类型名称。如果过滤器不在log4net组件集中，必须给出完整的组件集名称。
<filter>节支持下列子元素
param：0或者多个，filter特定参数

过滤器组成一个串来规定能够通过的事件，每个过滤器能够指定接受和处理的事件、拒绝和停止处理的事件或者允许事件到下一个过滤器。如果事件达到filter串的尽头而且没有被拒绝，那么它将被隐式的被记录器接受。

<filter type="log4net.Filter.LevelRangeFilter">

    <levelMin value="INFO" />

    <levelMax value="FATAL" />

</filter>

这个过滤器将会拒绝等级低于INFO或者高于FATAL的事件，其他事件包括INFO和FATAL将会被记录。
如果我们只想允许消息中包含特定字符（如“database”）的事件被记录，那么可以使用下面的过滤器

<filter type="log4net.Filter.StringMatchFilter">

    <stringToMatch value="database" />

</filter>

<filter type="log4net.Filter.DenyAllFilter" />

上面的例子中，第一个过滤器将会检查时间消息中是否包含“database”，如果包含，过滤器将接受消息并停止过滤，事件被记录。如果不包含，事件被传递到下一个过滤器处理，如果没有下一个过滤器，时间会被隐式的记录。如果我们不想不符合过滤要求的事件被隐式记录，可以在最后加上log4net.Filter.DenyAllFilter，他将拒绝所有到达它的事件。

如果我们希望记录消息中包含“database”或者“ldap”的事件，可以使用下列过滤器

<filter type="log4net.Filter.StringMatchFilter">

    <stringToMatch value="database"/>

</filter>

<filter type="log4net.Filter.StringMatchFilter">

    <stringToMatch value="ldap"/>

</filter>

<filter type="log4net.Filter.DenyAllFilter" />

Layouts

Layout只可以定义为<appender>元素的子元素

<layout>节支持下列属性
type：必须属性，值为layout的类型名称。如果过滤器不在log4net组件集中，必须给出完整的组件集名称。
<layout>节支持下列子元素
param：0或者多个，filter特定参数

下面的例子表示了怎样使用log4net.Layout.PatternLayout来配置布局。

<layout type="log4net.Layout.PatternLayout">

    <conversionPattern value="%date [%thread] %-5level %logger [%ndc] - %message%newline" />

</layout>

Root Logger（根记录器）

root logger只可以定义为<log4net>元素的子元素，它在记录器层次结构的根部，其他记录器都继承自他。

根记录器的例子

<root>

    <level value="INFO" />

    <appender-ref ref="ConsoleAppender" />

</root>

<root>节不支持属性
<root>节支持下列子元素
appender-ref：0或者多个，允许记录器通过记录方式的名称引用记录方式
level：0个或者1个，定义记录器的记录等级，记录器只记录大于或等于这一等级的事件
param：0或者多个，记录器特定参数

Loggers（记录器）

logger只可以定义为<log4net>元素的子元素
一个记录器的例子

<logger name="LoggerName">

    <level value="DEBUG" />

    <appender-ref ref="ConsoleAppender" />

</logger>

<logger>节支持下列属性
name：必须属性，制定记录器的名称
additivity：可选属性，值为true或者false，默认为true。指定为false时将禁止记录器继承父记录器的记录方式。
<logger>节支持下列子元素
appender-ref：0或者多个，允许记录器通过记录方式的名称引用记录方式
level：0个或者1个，定义记录器的记录等级，记录器只记录大于或等于这一等级的事件
param：0或者多个，记录器特定参数

Renderers（映射？）不太懂

Renderer只可以定义为<log4net>元素的子元素
一个renderer例子

<renderer renderingClass="MyClass.MyRenderer" renderedClass="MyClass.MyFunkyObject" />

<renderer>节支持下列属性
renderingClass：必须属性，值为该renderer的类型名称，如果类型不在log4net组件集中，必须给出完整的组件集名称。它是为被render的类型负责的类型
renderedClass：必须属性，值为该renderer的目标类型名称，如果类型不在log4net组件集中。它是被render的的类型。

<renderer>节支持子元素

Parameters（参数）

parameter只可以定义为<log4net>元素的子元素
一个parameter例子

<param name="ConversionPattern" value="%date [%thread] %-5level %logger [%ndc] - %message%newline" />

<param>节支持下列属性
name：必须属性，值为传递到父对象中的parameter的名称
value：可选属性，该属性的值是一个被转换成参数（parameter）的值的字符串。
type：可选属性，该属性的值是一个用来创建和设置参数（parameter）的值的类型名称。如果类型不在log4net组件集中，必须给出完整的组件集名称。
value和type必须制定其中一个
<param>节支持下列子元素
param：0或者多个，参数特定参数
一个使用嵌套参数元素的例子

<param name="evaluator" type="log4net.spi.LevelEvaluator">

    <param name="Threshold" value="WARN"/>

<param>

扩展参数

配置参数直接映射对象的可写属性，可用的属性依赖于被配置对象的实际类型。log4net SDK文档包含了log4net组件集中所有部件的API参考。

紧凑参数语法

所有的参数可以使用参数名作为他们的元素名
例如

<param name="evaluator" type="log4net.spi.LevelEvaluator">

    <param name="Threshold" value="WARN"/>

<param>

可以写成

<evaluator type="log4net.spi.LevelEvaluator">

    <threshold value="WARN"/>

<evaluator>