You are viewing a plain text version of this content. The canonical link for it is here.
Posted to log4net-dev@logging.apache.org by ni...@apache.org on 2007/02/26 03:10:29 UTC
svn commit: r511694 [19/24] - in /logging/log4net/trunk: ./ doc/
doc/release/ doc/release/howto/ doc/release/manual/ xdocs/ xdocs/lib/
xdocs/src/ xdocs/src/release/ xdocs/src/release/howto/
xdocs/src/release/manual/ xdocs/src/stylesheets/
Modified: logging/log4net/trunk/xdocs/src/release/manual/configuration.xml
URL: http://svn.apache.org/viewvc/logging/log4net/trunk/xdocs/src/release/manual/configuration.xml?view=diff&rev=511694&r1=511693&r2=511694
==============================================================================
--- logging/log4net/trunk/xdocs/src/release/manual/configuration.xml (original)
+++ logging/log4net/trunk/xdocs/src/release/manual/configuration.xml Sun Feb 25 18:10:21 2007
@@ -17,39 +17,39 @@
-->
<document>
- <properties>
- <author email="nicko at apache dot org">Nicko Cadell</author>
- <title>log4net Manual - Configuration</title>
- </properties>
-
- <meta name="keywords" content="log4net configuration, log4net" />
-
- <body>
- <section id="main" name="log4net Manual - Configuration">
- <sectionMenu name="Contents" />
-
-
- <section id="config" name="Configuration">
- <p>
- Inserting log requests into the application code requires a fair amount of
- planning and effort. Observation shows that approximately 4 percent of code is
- dedicated to logging. Consequently, even moderately sized applications will
- have thousands of logging statements embedded within their code. Given their
- number, it becomes imperative to manage these log statements without the need
- to modify them manually.
- </p>
- <p>
- The log4net environment is fully configurable programmatically. However, it is
- far more flexible to configure log4net using configuration files. Currently,
- configuration files are written in XML.
- </p>
- <p>
- Let us give a taste of how this is done with the help of an imaginary
- application
- <span class="code">MyApp</span>
- that uses log4net.
- </p>
- <div class="syntax"><pre class="code">
+ <properties>
+ <author email="nicko at apache dot org">Nicko Cadell</author>
+ <title>Apache log4net Manual: Configuration</title>
+ </properties>
+
+ <meta name="keywords" content="log4net configuration, log4net" />
+
+ <body>
+ <section id="main" name="log4net Manual - Configuration">
+ <sectionMenu name="Contents" />
+
+
+ <section id="config" name="Configuration">
+ <p>
+ Inserting log requests into the application code requires a fair amount of
+ planning and effort. Observation shows that approximately 4 percent of code is
+ dedicated to logging. Consequently, even moderately sized applications will
+ have thousands of logging statements embedded within their code. Given their
+ number, it becomes imperative to manage these log statements without the need
+ to modify them manually.
+ </p>
+ <p>
+ The log4net environment is fully configurable programmatically. However, it is
+ far more flexible to configure log4net using configuration files. Currently,
+ configuration files are written in XML.
+ </p>
+ <p>
+ Let us give a taste of how this is done with the help of an imaginary
+ application
+ <span class="code">MyApp</span>
+ that uses log4net.
+ </p>
+ <div class="syntax"><pre class="code">
using Com.Foo;
// Import log4net classes.
@@ -58,101 +58,101 @@
public class MyApp
{
- // Define a static logger variable so that it references the
- // Logger instance named "MyApp".
- <strong>private static readonly</strong> ILog log = <strong>LogManager.GetLogger(typeof(MyApp));</strong>
-
- static void Main(string[] args)
- {
- // Set up a simple configuration that logs on the console.
- <strong>BasicConfigurator.Configure();</strong>
-
- log.Info("Entering application.");
- Bar bar = new Bar();
- bar.DoIt();
- log.Info("Exiting application.");
- }
+ // Define a static logger variable so that it references the
+ // Logger instance named "MyApp".
+ <strong>private static readonly</strong> ILog log = <strong>LogManager.GetLogger(typeof(MyApp));</strong>
+
+ static void Main(string[] args)
+ {
+ // Set up a simple configuration that logs on the console.
+ <strong>BasicConfigurator.Configure();</strong>
+
+ log.Info("Entering application.");
+ Bar bar = new Bar();
+ bar.DoIt();
+ log.Info("Exiting application.");
+ }
}</pre></div>
- <p>
- <span class="code">MyApp</span>
- begins by importing log4net related classes. It then defines a static logger
- variable with the name
- <span class="code">MyApp</span>
- which happens to be the fully qualified name of the class.
- </p>
- <p>
- <span class="code">MyApp</span>
- uses the following
- <span class="code">Bar</span>
- class:
- </p>
- <div class="syntax"><pre class="code">
+ <p>
+ <span class="code">MyApp</span>
+ begins by importing log4net related classes. It then defines a static logger
+ variable with the name
+ <span class="code">MyApp</span>
+ which happens to be the fully qualified name of the class.
+ </p>
+ <p>
+ <span class="code">MyApp</span>
+ uses the following
+ <span class="code">Bar</span>
+ class:
+ </p>
+ <div class="syntax"><pre class="code">
// Import log4net classes.
using log4net;
<b>namespace Com.Foo</b>
{
- public class Bar
- {
- <strong>private static readonly</strong> ILog log = <strong>LogManager.GetLogger(typeof(Bar));</strong>
-
- public void DoIt()
- {
- log.Debug("Did it again!");
- }
- }
+ public class Bar
+ {
+ <strong>private static readonly</strong> ILog log = <strong>LogManager.GetLogger(typeof(Bar));</strong>
+
+ public void DoIt()
+ {
+ log.Debug("Did it again!");
+ }
+ }
}</pre></div>
- <p>
- The invocation of the
- <span class="code">BasicConfigurator.Configure()</span>
- method creates a rather simple log4net setup. This method is hardwired to add
- to the <i>root</i> logger a
- <span class="code">ConsoleAppender</span>. The output will be formatted using a
- <span class="code">PatternLayout</span>
- set to the pattern
- <span class="code">"%-4timestamp [%thread] %-5level %logger %ndc - %message%newline"</span>.
- </p>
- <p>
- Note that by default, the <i>root</i> logger is assigned to
- <span class="code">Level.DEBUG</span>.
- </p>
- <p>
- The output of <span class="code">MyApp</span> is:
- </p>
- <source language="text"><![CDATA[
+ <p>
+ The invocation of the
+ <span class="code">BasicConfigurator.Configure()</span>
+ method creates a rather simple log4net setup. This method is hardwired to add
+ to the <i>root</i> logger a
+ <span class="code">ConsoleAppender</span>. The output will be formatted using a
+ <span class="code">PatternLayout</span>
+ set to the pattern
+ <span class="code">"%-4timestamp [%thread] %-5level %logger %ndc - %message%newline"</span>.
+ </p>
+ <p>
+ Note that by default, the <i>root</i> logger is assigned to
+ <span class="code">Level.DEBUG</span>.
+ </p>
+ <p>
+ The output of <span class="code">MyApp</span> is:
+ </p>
+ <source language="text"><![CDATA[
0 [main] INFO MyApp - Entering application.
36 [main] DEBUG Com.Foo.Bar - Did it again!
51 [main] INFO MyApp - Exiting application.]]></source>
- <p>
- As a side note, let me mention that in log4net child loggers link only to their
- existing ancestors. In particular, the logger named
- <span class="code">Com.Foo.Bar</span>
- is linked directly to the
- <i>root</i>
- logger, thereby circumventing the unused
- <span class="code">Com</span>
- or
- <span class="code">Com.Foo</span>
- loggers. This significantly increases performance and reduces log4net's memory
- footprint.
- </p>
- <p>
- The
- <span class="code">MyApp</span>
- class configures log4net by invoking
- <span class="code">BasicConfigurator.Configure()</span>
- method. Other classes only need to import the
- <span class="code">log4net</span>
- namespace, retrieve the loggers they wish to use, and log away.
- </p>
- <p>
- The previous example always outputs the same log information. Fortunately, it
- is easy to modify
- <span class="code">MyApp</span>
- so that the log output can be controlled at run-time. Here is a slightly
- modified version.
- </p>
- <div class="syntax"><pre class="code">
+ <p>
+ As a side note, let me mention that in log4net child loggers link only to their
+ existing ancestors. In particular, the logger named
+ <span class="code">Com.Foo.Bar</span>
+ is linked directly to the
+ <i>root</i>
+ logger, thereby circumventing the unused
+ <span class="code">Com</span>
+ or
+ <span class="code">Com.Foo</span>
+ loggers. This significantly increases performance and reduces log4net's memory
+ footprint.
+ </p>
+ <p>
+ The
+ <span class="code">MyApp</span>
+ class configures log4net by invoking
+ <span class="code">BasicConfigurator.Configure()</span>
+ method. Other classes only need to import the
+ <span class="code">log4net</span>
+ namespace, retrieve the loggers they wish to use, and log away.
+ </p>
+ <p>
+ The previous example always outputs the same log information. Fortunately, it
+ is easy to modify
+ <span class="code">MyApp</span>
+ so that the log output can be controlled at run-time. Here is a slightly
+ modified version.
+ </p>
+ <div class="syntax"><pre class="code">
using Com.Foo;
// Import log4net classes.
@@ -161,1047 +161,1047 @@
public class MyApp
{
- private static readonly ILog log = LogManager.GetLogger(typeof(MyApp));
+ private static readonly ILog log = LogManager.GetLogger(typeof(MyApp));
- static void Main(string[] args)
- {
- // BasicConfigurator replaced with XmlConfigurator.
- <strong>XmlConfigurator.Configure(new System.IO.FileInfo(args[0]));</strong>
-
- log.Info("Entering application.");
- Bar bar = new Bar();
- bar.DoIt();
- log.Info("Exiting application.");
- }
+ static void Main(string[] args)
+ {
+ // BasicConfigurator replaced with XmlConfigurator.
+ <strong>XmlConfigurator.Configure(new System.IO.FileInfo(args[0]));</strong>
+
+ log.Info("Entering application.");
+ Bar bar = new Bar();
+ bar.DoIt();
+ log.Info("Exiting application.");
+ }
}</pre></div>
- <p>
- This version of
- <span class="code">MyApp</span>
- instructs the
- <span class="code">XmlConfigurator</span>
- to parse a configuration file and set up logging accordingly. The path to the
- configuration file is specified on the command line.
- </p>
- <p>
- Here is a sample configuration file that results in exactly same output as the
- previous
- <span class="code">BasicConfigurator</span>
- based example.
- </p>
- <source language="xml"><![CDATA[
+ <p>
+ This version of
+ <span class="code">MyApp</span>
+ instructs the
+ <span class="code">XmlConfigurator</span>
+ to parse a configuration file and set up logging accordingly. The path to the
+ configuration file is specified on the command line.
+ </p>
+ <p>
+ Here is a sample configuration file that results in exactly same output as the
+ previous
+ <span class="code">BasicConfigurator</span>
+ based example.
+ </p>
+ <source language="xml"><![CDATA[
<log4net>
- <!-- A1 is set to be a ConsoleAppender -->
- <appender name="A1" type="log4net.Appender.ConsoleAppender">
+ <!-- A1 is set to be a ConsoleAppender -->
+ <appender name="A1" type="log4net.Appender.ConsoleAppender">
- <!-- A1 uses PatternLayout -->
- <layout type="log4net.Layout.PatternLayout">
- <conversionPattern value="%-4timestamp [%thread] %-5level %logger %ndc - %message%newline" />
- </layout>
- </appender>
-
- <!-- Set root logger level to DEBUG and its only appender to A1 -->
- <root>
- <level value="DEBUG" />
- <appender-ref ref="A1" />
- </root>
+ <!-- A1 uses PatternLayout -->
+ <layout type="log4net.Layout.PatternLayout">
+ <conversionPattern value="%-4timestamp [%thread] %-5level %logger %ndc - %message%newline" />
+ </layout>
+ </appender>
+
+ <!-- Set root logger level to DEBUG and its only appender to A1 -->
+ <root>
+ <level value="DEBUG" />
+ <appender-ref ref="A1" />
+ </root>
</log4net>]]></source>
- <p>
- Suppose we are no longer interested in seeing the output of any component
- belonging to the
- <span class="code">Com.Foo</span>
- package. The following configuration file shows one possible way of achieving
- this.
- </p>
- <source language="xml"><![CDATA[
+ <p>
+ Suppose we are no longer interested in seeing the output of any component
+ belonging to the
+ <span class="code">Com.Foo</span>
+ package. The following configuration file shows one possible way of achieving
+ this.
+ </p>
+ <source language="xml"><![CDATA[
<log4net>
- <!-- A1 is set to be a ConsoleAppender -->
- <appender name="A1" type="log4net.Appender.ConsoleAppender">
+ <!-- A1 is set to be a ConsoleAppender -->
+ <appender name="A1" type="log4net.Appender.ConsoleAppender">
- <!-- A1 uses PatternLayout -->
- <layout type="log4net.Layout.PatternLayout">
- <!-- Print the date in ISO 8601 format -->
- <conversionPattern value="%date [%thread] %-5level %logger %ndc - %message%newline" />
- </layout>
- </appender>
-
- <!-- Set root logger level to DEBUG and its only appender to A1 -->
- <root>
- <level value="DEBUG" />
- <appender-ref ref="A1" />
- </root>
-
- <!-- Print only messages of level WARN or above in the package Com.Foo -->
- <logger name="Com.Foo">
- <level value="WARN" />
- </logger>
+ <!-- A1 uses PatternLayout -->
+ <layout type="log4net.Layout.PatternLayout">
+ <!-- Print the date in ISO 8601 format -->
+ <conversionPattern value="%date [%thread] %-5level %logger %ndc - %message%newline" />
+ </layout>
+ </appender>
+
+ <!-- Set root logger level to DEBUG and its only appender to A1 -->
+ <root>
+ <level value="DEBUG" />
+ <appender-ref ref="A1" />
+ </root>
+
+ <!-- Print only messages of level WARN or above in the package Com.Foo -->
+ <logger name="Com.Foo">
+ <level value="WARN" />
+ </logger>
</log4net>]]></source>
- <p>
- The output of
- <span class="code">MyApp</span>
- configured with this file is shown below.
- </p>
- <source language="text">
+ <p>
+ The output of
+ <span class="code">MyApp</span>
+ configured with this file is shown below.
+ </p>
+ <source language="text">
2000-09-07 14:07:41,508 [main] INFO MyApp - Entering application.
2000-09-07 14:07:41,529 [main] INFO MyApp - Exiting application.</source>
- <p>
- As the logger
- <span class="code">Com.Foo.Bar</span>
- does not have an assigned level, it inherits its level from
- <span class="code">Com.Foo</span>, which was set to WARN in the configuration
- file. The log statement from the
- <span class="code">Bar.DoIt</span>
- method has the level DEBUG, lower than the logger level WARN. Consequently,
- <span class="code">DoIt()</span>
- method's log request is suppressed.
- </p>
- <p>
- Here is another configuration file that uses multiple appenders.
- </p>
- <source language="C#"><![CDATA[
+ <p>
+ As the logger
+ <span class="code">Com.Foo.Bar</span>
+ does not have an assigned level, it inherits its level from
+ <span class="code">Com.Foo</span>, which was set to WARN in the configuration
+ file. The log statement from the
+ <span class="code">Bar.DoIt</span>
+ method has the level DEBUG, lower than the logger level WARN. Consequently,
+ <span class="code">DoIt()</span>
+ method's log request is suppressed.
+ </p>
+ <p>
+ Here is another configuration file that uses multiple appenders.
+ </p>
+ <source language="C#"><![CDATA[
<log4net>
- <appender name="Console" type="log4net.Appender.ConsoleAppender">
- <layout type="log4net.Layout.PatternLayout">
- <!-- Pattern to output the caller's file name and line number -->
- <conversionPattern value="%5level [%thread] (%file:%line) - %message%newline" />
- </layout>
- </appender>
-
- <appender name="RollingFile" type="log4net.Appender.RollingFileAppender">
- <file value="example.log" />
- <appendToFile value="true" />
- <maximumFileSize value="100KB" />
- <maxSizeRollBackups value="2" />
-
- <layout type="log4net.Layout.PatternLayout">
- <conversionPattern value="%level %thread %logger - %message%newline" />
- </layout>
- </appender>
-
- <root>
- <level value="DEBUG" />
- <appender-ref ref="Console" />
- <appender-ref ref="RollingFile" />
- </root>
+ <appender name="Console" type="log4net.Appender.ConsoleAppender">
+ <layout type="log4net.Layout.PatternLayout">
+ <!-- Pattern to output the caller's file name and line number -->
+ <conversionPattern value="%5level [%thread] (%file:%line) - %message%newline" />
+ </layout>
+ </appender>
+
+ <appender name="RollingFile" type="log4net.Appender.RollingFileAppender">
+ <file value="example.log" />
+ <appendToFile value="true" />
+ <maximumFileSize value="100KB" />
+ <maxSizeRollBackups value="2" />
+
+ <layout type="log4net.Layout.PatternLayout">
+ <conversionPattern value="%level %thread %logger - %message%newline" />
+ </layout>
+ </appender>
+
+ <root>
+ <level value="DEBUG" />
+ <appender-ref ref="Console" />
+ <appender-ref ref="RollingFile" />
+ </root>
</log4net>]]></source>
- <p>
- Calling the enhanced <span class="code">MyApp</span> with the this configuration file will output the
- following on the console.
- </p>
- <source language="text"><![CDATA[
+ <p>
+ Calling the enhanced <span class="code">MyApp</span> with the this configuration file will output the
+ following on the console.
+ </p>
+ <source language="text"><![CDATA[
INFO [main] (MyApp.cs:16) - Entering application.
DEBUG [main] (Bar.cs:12) - Doing it again!
INFO [main] (MyApp.cs:19) - Exiting application.]]></source>
- <p>
- In addition, as the <i>root</i> logger has been allocated a second appender, output
- will also be directed to the
- <span class="code">example.log</span>
- file. This file will be rolled over when it reaches 100KB. When roll-over
- occurs, the old version of
- <span class="code">example.log</span>
- is automatically moved to
- <span class="code">example.log.1</span>.
- </p>
- <p>
- Note that to obtain these different logging behaviors we did not need to
- recompile code. We could just as easily have logged to an email address,
- redirected all
- <span class="code">Com.Foo</span>
- output to an NT Event logger, or forwarded logging events to a remote log4net
- server, which would log according to local server policy.
- </p>
- <p>
- For more examples of configuring appenders using the <span class="code">XmlConfigurator</span>
- see the <a href="../config-examples.html">Example Appender Configuration</a>
- document.
- </p>
-
- <section id="attributes" name="Configuration Attributes">
- <p>
- The log4net configuration can be configured using assembly-level attributes rather than
- specified programmatically.
- </p>
- <ul>
- <li>
- <b>XmlConfiguratorAttribute</b>
- <p>
- The <span class="code">log4net.Config.XmlConfiguratorAttribute</span> Allows the
- <span class="code">XmlConfigurator</span> to be configured using the following properties:
- </p>
- <ul>
- <li>
- <b>ConfigFile</b>
- <p>
- If specified, this is the filename of the configuration file to use with the
- <span class="code">XmlConfigurator</span>. This file path is relative to the
- application base directory (<span class="code">AppDomain.CurrentDomain.BaseDirectory</span>).
- </p>
- <p>
- This property cannot be used in conjunction with the
- <span class="code">ConfigFileExtension</span> property.
- </p>
- </li>
- <li>
- <b>ConfigFileExtension</b>
- <p>
- If specified, this is the extension for the configuration file. The assembly
- file name is used as the base name with the this extension appended. For example
- if the assembly is loaded from the a file <span class="code">TestApp.exe</span>
- and the <span class="code">ConfigFileExtension</span> property is set to
- <span class="code">log4net</span> then the configuration file name is
- <span class="code">TestApp.exe.log4net</span>. This is equivalent to setting the
- <span class="code">ConfigFile</span> property to <span class="code">TestApp.exe.log4net</span>.
- </p>
- <p>
- The path to the configuration file is build by using the application base
- directory (<span class="code">AppDomain.CurrentDomain.BaseDirectory</span>),
- the assembly file name and the configuration file extension.
- </p>
- <p>
- This property cannot be used in conjunction with the
- <span class="code">ConfigFile</span> property.
- </p>
- </li>
- <li>
- <b>Watch</b>
- <p>
- If this flag is specified and set to <span class="code">true</span>
- then the framework will watch the configuration file and will reload the config
- each time the file is modified.
- </p>
- </li>
- </ul>
- <p>
- If neither of the <span class="code">ConfigFile</span> or <span class="code">ConfigFileExtension</span>
- properties are specified, the application configuration file (e.g. <span class="code">TestApp.exe.config</span>)
- will be used as the log4net configuration file.
- </p>
- <p>
- Example usage:
- </p>
- <div class="syntax"><pre class="code">
+ <p>
+ In addition, as the <i>root</i> logger has been allocated a second appender, output
+ will also be directed to the
+ <span class="code">example.log</span>
+ file. This file will be rolled over when it reaches 100KB. When roll-over
+ occurs, the old version of
+ <span class="code">example.log</span>
+ is automatically moved to
+ <span class="code">example.log.1</span>.
+ </p>
+ <p>
+ Note that to obtain these different logging behaviors we did not need to
+ recompile code. We could just as easily have logged to an email address,
+ redirected all
+ <span class="code">Com.Foo</span>
+ output to an NT Event logger, or forwarded logging events to a remote log4net
+ server, which would log according to local server policy.
+ </p>
+ <p>
+ For more examples of configuring appenders using the <span class="code">XmlConfigurator</span>
+ see the <a href="../config-examples.html">Example Appender Configuration</a>
+ document.
+ </p>
+
+ <section id="attributes" name="Configuration Attributes">
+ <p>
+ The log4net configuration can be configured using assembly-level attributes rather than
+ specified programmatically.
+ </p>
+ <ul>
+ <li>
+ <b>XmlConfiguratorAttribute</b>
+ <p>
+ The <span class="code">log4net.Config.XmlConfiguratorAttribute</span> Allows the
+ <span class="code">XmlConfigurator</span> to be configured using the following properties:
+ </p>
+ <ul>
+ <li>
+ <b>ConfigFile</b>
+ <p>
+ If specified, this is the filename of the configuration file to use with the
+ <span class="code">XmlConfigurator</span>. This file path is relative to the
+ application base directory (<span class="code">AppDomain.CurrentDomain.BaseDirectory</span>).
+ </p>
+ <p>
+ This property cannot be used in conjunction with the
+ <span class="code">ConfigFileExtension</span> property.
+ </p>
+ </li>
+ <li>
+ <b>ConfigFileExtension</b>
+ <p>
+ If specified, this is the extension for the configuration file. The assembly
+ file name is used as the base name with the this extension appended. For example
+ if the assembly is loaded from the a file <span class="code">TestApp.exe</span>
+ and the <span class="code">ConfigFileExtension</span> property is set to
+ <span class="code">log4net</span> then the configuration file name is
+ <span class="code">TestApp.exe.log4net</span>. This is equivalent to setting the
+ <span class="code">ConfigFile</span> property to <span class="code">TestApp.exe.log4net</span>.
+ </p>
+ <p>
+ The path to the configuration file is build by using the application base
+ directory (<span class="code">AppDomain.CurrentDomain.BaseDirectory</span>),
+ the assembly file name and the configuration file extension.
+ </p>
+ <p>
+ This property cannot be used in conjunction with the
+ <span class="code">ConfigFile</span> property.
+ </p>
+ </li>
+ <li>
+ <b>Watch</b>
+ <p>
+ If this flag is specified and set to <span class="code">true</span>
+ then the framework will watch the configuration file and will reload the config
+ each time the file is modified.
+ </p>
+ </li>
+ </ul>
+ <p>
+ If neither of the <span class="code">ConfigFile</span> or <span class="code">ConfigFileExtension</span>
+ properties are specified, the application configuration file (e.g. <span class="code">TestApp.exe.config</span>)
+ will be used as the log4net configuration file.
+ </p>
+ <p>
+ Example usage:
+ </p>
+ <div class="syntax"><pre class="code">
// Configure log4net using the .config file
<b>[assembly: log4net.Config.XmlConfigurator(Watch=true)]</b>
// This will cause log4net to look for a configuration file
// called TestApp.exe.config in the application base
// directory (i.e. the directory containing TestApp.exe)
// The config file will be watched for changes.
- </pre></div>
- <div class="syntax"><pre class="code">
+ </pre></div>
+ <div class="syntax"><pre class="code">
// Configure log4net using the .log4net file
<b>[assembly: log4net.Config.XmlConfigurator(ConfigFileExtension="log4net",Watch=true)]</b>
// This will cause log4net to look for a configuration file
// called TestApp.exe.log4net in the application base
// directory (i.e. the directory containing TestApp.exe)
// The config file will be watched for changes.
- </pre></div>
- <p>
- This attribute may only be used once per assembly.
- </p>
- </li>
- </ul>
- <p>
- Using attributes can be a clearer method for defining where the application's
- configuration will be loaded from. However it is worth noting that attributes
- are purely passive. They are information only. Therefore if you use configuration
- attributes you must invoke log4net to allow it to read the attributes. A simple
- call to <span class="code">LogManager.GetLogger</span> will cause the attributes
- on the calling assembly to be read and processed. <strong>Therefore it is imperative
- to make a logging call as early as possible during the application start-up, and
- certainly before any external assemblies have been loaded and invoked.</strong>
- </p>
- </section>
-
- <section id="files" name="Configuration Files">
- <p>
- Typically the log4net configuration is specified using a file. This file can
- be read in one of two ways:
- </p>
- <ul>
- <li>Using the .NET <span class="code">System.Configuration</span> API</li>
- <li>Reading the file contents directly</li>
- </ul>
-
- <section id="dot-config" name=".config Files">
- <p>
- The <span class="code">System.Configuration</span> API is only available if the
- configuration data is in the application's config file; the file named
- <i>MyApp.exe.config</i> or <i>Web.config</i>. Because the <span class="code">System.Configuration</span>
- API does not support reloading of the config file the configuration settings
- cannot be watched using the <span class="code">log4net.Config.XmlConfigurator.ConfigureAndWatch</span>
- methods. The main advantage of using the <span class="code">System.Configuration</span>
- APIs to read the configuration data is that it requires less permissions than accessing
- the configuration file directly.
- </p>
- <p>
- The only way to configure an application using the <span class="code">System.Configuration</span>
- APIs is to call the <span class="code">log4net.Config.XmlConfigurator.Configure()</span> method or
- the <span class="code">log4net.Config.XmlConfigurator.Configure(ILoggerRepository)</span> method.
- </p>
- <p>
- In order to embed the configuration data in the .config file the section name must be
- identified to the .NET config file parser using a <span class="code">configSections</span> element.
- The section must specify the <span class="code">log4net.Config.Log4NetConfigurationSectionHandler</span>
- that will be used to parse the config section. This type must be fully assembly qualified
- because it is being loaded by the .NET config file parser not by log4net. The correct
- assembly name for the log4net assembly must be specified.
- The following is a simple example configuration file that specifies the correct
- section handler to use for the log4net section.
- </p>
- <source language="xml"><![CDATA[
+ </pre></div>
+ <p>
+ This attribute may only be used once per assembly.
+ </p>
+ </li>
+ </ul>
+ <p>
+ Using attributes can be a clearer method for defining where the application's
+ configuration will be loaded from. However it is worth noting that attributes
+ are purely passive. They are information only. Therefore if you use configuration
+ attributes you must invoke log4net to allow it to read the attributes. A simple
+ call to <span class="code">LogManager.GetLogger</span> will cause the attributes
+ on the calling assembly to be read and processed. <strong>Therefore it is imperative
+ to make a logging call as early as possible during the application start-up, and
+ certainly before any external assemblies have been loaded and invoked.</strong>
+ </p>
+ </section>
+
+ <section id="files" name="Configuration Files">
+ <p>
+ Typically the log4net configuration is specified using a file. This file can
+ be read in one of two ways:
+ </p>
+ <ul>
+ <li>Using the .NET <span class="code">System.Configuration</span> API</li>
+ <li>Reading the file contents directly</li>
+ </ul>
+
+ <section id="dot-config" name=".config Files">
+ <p>
+ The <span class="code">System.Configuration</span> API is only available if the
+ configuration data is in the application's config file; the file named
+ <i>MyApp.exe.config</i> or <i>Web.config</i>. Because the <span class="code">System.Configuration</span>
+ API does not support reloading of the config file the configuration settings
+ cannot be watched using the <span class="code">log4net.Config.XmlConfigurator.ConfigureAndWatch</span>
+ methods. The main advantage of using the <span class="code">System.Configuration</span>
+ APIs to read the configuration data is that it requires less permissions than accessing
+ the configuration file directly.
+ </p>
+ <p>
+ The only way to configure an application using the <span class="code">System.Configuration</span>
+ APIs is to call the <span class="code">log4net.Config.XmlConfigurator.Configure()</span> method or
+ the <span class="code">log4net.Config.XmlConfigurator.Configure(ILoggerRepository)</span> method.
+ </p>
+ <p>
+ In order to embed the configuration data in the .config file the section name must be
+ identified to the .NET config file parser using a <span class="code">configSections</span> element.
+ The section must specify the <span class="code">log4net.Config.Log4NetConfigurationSectionHandler</span>
+ that will be used to parse the config section. This type must be fully assembly qualified
+ because it is being loaded by the .NET config file parser not by log4net. The correct
+ assembly name for the log4net assembly must be specified.
+ The following is a simple example configuration file that specifies the correct
+ section handler to use for the log4net section.
+ </p>
+ <source language="xml"><![CDATA[
<?xml version="1.0" encoding="utf-8" ?>
<configuration>
- <configSections>
- <section name="log4net" type="log4net.Config.Log4NetConfigurationSectionHandler, log4net" />
- </configSections>
- <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>
+ <configSections>
+ <section name="log4net" type="log4net.Config.Log4NetConfigurationSectionHandler, log4net" />
+ </configSections>
+ <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>
</configuration>]]></source>
- <p>
- In the above example the <span class="code">log4net</span> assembly is specified.
- This assembly must be located where the .NET runtime can find it. For example it could
- be located in the same directory as the application. If the log4net assembly is stored in
- the GAC then the fully qualified assembly name must be specified including the culture,
- version and public key.
- </p>
- <p>
- When using the .config file to specify the configuration the section name and
- XML element name must be <span class="code">log4net</span>.
- </p>
- </section>
-
- <section id="reading" name="Reading Files Directly">
- <p>
- The XmlConfigurator can directly read any XML file and use it to configure log4net.
- This includes the application's .config file; the file named <i>MyApp.exe.config</i>
- or <i>Web.config</i>. The only reason not to read the configuration file directly is if the
- application does not have sufficient permissions to read the file, then the configuration
- must be loaded using the .NET configuration APIs (see above).
- </p>
- <p>
- The file to read the configuration from can be specified using any of
- the <span class="code">log4net.Config.XmlConfigurator</span> methods that
- accept a <span class="code">System.IO.FileInfo</span> object. Because the
- file system can be monitored for file change notifications the
- <span class="code">ConfigureAndWatch</span> methods can be used to monitor
- the configuration file for modifications and automatically reconfigure log4net.
- </p>
- <p>
- Additionally the <span class="code">log4net.Config.XmlConfiguratorAttribute</span>
- can be used to specify the file to read the configuration from.
- </p>
- <p>
- The configuration is read from the <span class="code">log4net</span> element
- in the file. Only one <span class="code">log4net</span> element can be specified
- in the file but it may be located anywhere in the XML hierarchy. For example it
- may be the root element:
- </p>
- <source language="xml"><![CDATA[
+ <p>
+ In the above example the <span class="code">log4net</span> assembly is specified.
+ This assembly must be located where the .NET runtime can find it. For example it could
+ be located in the same directory as the application. If the log4net assembly is stored in
+ the GAC then the fully qualified assembly name must be specified including the culture,
+ version and public key.
+ </p>
+ <p>
+ When using the .config file to specify the configuration the section name and
+ XML element name must be <span class="code">log4net</span>.
+ </p>
+ </section>
+
+ <section id="reading" name="Reading Files Directly">
+ <p>
+ The XmlConfigurator can directly read any XML file and use it to configure log4net.
+ This includes the application's .config file; the file named <i>MyApp.exe.config</i>
+ or <i>Web.config</i>. The only reason not to read the configuration file directly is if the
+ application does not have sufficient permissions to read the file, then the configuration
+ must be loaded using the .NET configuration APIs (see above).
+ </p>
+ <p>
+ The file to read the configuration from can be specified using any of
+ the <span class="code">log4net.Config.XmlConfigurator</span> methods that
+ accept a <span class="code">System.IO.FileInfo</span> object. Because the
+ file system can be monitored for file change notifications the
+ <span class="code">ConfigureAndWatch</span> methods can be used to monitor
+ the configuration file for modifications and automatically reconfigure log4net.
+ </p>
+ <p>
+ Additionally the <span class="code">log4net.Config.XmlConfiguratorAttribute</span>
+ can be used to specify the file to read the configuration from.
+ </p>
+ <p>
+ The configuration is read from the <span class="code">log4net</span> element
+ in the file. Only one <span class="code">log4net</span> element can be specified
+ in the file but it may be located anywhere in the XML hierarchy. For example it
+ may be the root element:
+ </p>
+ <source language="xml"><![CDATA[
<?xml version="1.0" encoding="utf-8" ?>
<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>
+ <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>]]></source>
- <p>
- Or it may be nested within other elements:
- </p>
- <source language="xml"><![CDATA[
+ <p>
+ Or it may be nested within other elements:
+ </p>
+ <source language="xml"><![CDATA[
<?xml version="1.0" encoding="utf-8" ?>
<configuration>
- <configSections>
- <section name="log4net" type="System.Configuration.IgnoreSectionHandler" />
- </configSections>
- <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>
+ <configSections>
+ <section name="log4net" type="System.Configuration.IgnoreSectionHandler" />
+ </configSections>
+ <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>
</configuration>]]></source>
- <p>
- The above example shows how the configuration data can be embedded
- inside a .config file even though the file is being read directly
- by log4net. An important note is that the .NET config file parser
- will throw an exception if it finds an element that has not been
- registered using the <span class="code">configSections</span> element.
- Therefore in the above example the <span class="code">log4net</span>
- section name is registered, but the type specified to handle the
- section is <span class="code">System.Configuration.IgnoreSectionHandler</span>.
- This is a built-in class that indicates that another method for reading
- the config section will be employed.
- </p>
- </section>
-
- </section>
-
- <section id="syntax" name="Configuration Syntax">
- <p>
- log4net includes a configuration reader that parses an XML DOM, the
- <span class="code">log4net.Config.XmlConfigurator</span>. This section defines the
- syntax accepted by the configurator.
- </p>
- <p>
- This is an example of a valid XML configuration. The root element
- must be <span class="code"><log4net></span>. Note that this does not mean
- that this element cannot be embedded in another XML document. See the section above
- on <a href="#configuration.files">Configuration Files</a> for more information
- on how to embed the XmlConfigurator XML in a configuration file.
- </p>
- <source language="xml"><![CDATA[
+ <p>
+ The above example shows how the configuration data can be embedded
+ inside a .config file even though the file is being read directly
+ by log4net. An important note is that the .NET config file parser
+ will throw an exception if it finds an element that has not been
+ registered using the <span class="code">configSections</span> element.
+ Therefore in the above example the <span class="code">log4net</span>
+ section name is registered, but the type specified to handle the
+ section is <span class="code">System.Configuration.IgnoreSectionHandler</span>.
+ This is a built-in class that indicates that another method for reading
+ the config section will be employed.
+ </p>
+ </section>
+
+ </section>
+
+ <section id="syntax" name="Configuration Syntax">
+ <p>
+ log4net includes a configuration reader that parses an XML DOM, the
+ <span class="code">log4net.Config.XmlConfigurator</span>. This section defines the
+ syntax accepted by the configurator.
+ </p>
+ <p>
+ This is an example of a valid XML configuration. The root element
+ must be <span class="code"><log4net></span>. Note that this does not mean
+ that this element cannot be embedded in another XML document. See the section above
+ on <a href="#configuration.files">Configuration Files</a> for more information
+ on how to embed the XmlConfigurator XML in a configuration file.
+ </p>
+ <source language="xml"><![CDATA[
<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>
+ <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>]]></source>
- <p>
- The <span class="code"><log4net></span> element supports the following attributes:
- </p>
- <div class="table">
- <table cellspacing="0">
- <colgroup>
- <col style="text-align: left; white-space: nowrap; width: 7em" />
- <col style="text-align: left;" />
- </colgroup>
- <tr>
- <th>Attribute</th>
- <th>Description</th>
- </tr>
- <tr>
- <td>debug</td>
- <td>
- Optional attribute. Value must be either <span class="code">true</span> or <span class="code">false</span>.
- The default value is <span class="code">false</span>. Set this attribute to <span class="code">true</span>
- to enable internal log4net debugging for this configuration.
- </td>
- </tr>
- <tr>
- <td>update</td>
- <td>
- Optional attribute. Value must be either <span class="code">Merge</span> or <span class="code">Overwrite</span>.
- The default value is <span class="code">Merge</span>. Set this attribute to <span class="code">Overwrite</span>
- to reset the configuration of the repository being configured before applying this configuration.
- </td>
- </tr>
- <tr>
- <td>threshold</td>
- <td>
- Optional attribute. Value must be the name of a level registered on the repository.
- The default value is <span class="code">ALL</span>. Set this attribute to limit the messages
- that are logged across the whole repository, regardless of the logger that the message is logged to.
- </td>
- </tr>
- </table>
- </div>
- <p>
- The <span class="code"><log4net></span> element supports the following child elements:
- </p>
- <div class="table">
- <table cellspacing="0">
- <colgroup>
- <col style="text-align: left; white-space: nowrap; width: 7em" />
- <col style="text-align: left;" />
- </colgroup>
- <tr>
- <th>Element</th>
- <th>Description</th>
- </tr>
- <tr>
- <td>appender</td>
- <td>
- Zero or more elements allowed. Defines an appender.
- </td>
- </tr>
- <tr>
- <td>logger</td>
- <td>
- Zero or more elements allowed. Defines the configuration of a logger.
- </td>
- </tr>
- <tr>
- <td>renderer</td>
- <td>
- Zero or more elements allowed. Defines an object renderer.
- </td>
- </tr>
- <tr>
- <td>root</td>
- <td>
- Optional element, maximum of one allowed. Defines the configuration of the root logger.
- </td>
- </tr>
- <tr>
- <td>param</td>
- <td>
- Zero or more elements allowed. Repository specific parameters
- </td>
- </tr>
- </table>
- </div>
-
- <section id="appenders" name="Appenders">
- <p>
- Appenders may only be defined as child elements of the <span class="code"><log4net></span>
- element. Each appender must be uniquely named. The implementing type for the appender must be specified.
- </p>
- <p>
- This example shows an appender of type <span class="code">log4net.Appender.ConsoleAppender</span> being
- defined. The appender will be known as <i>ConsoleAppender</i>.
- </p>
- <source language="xml"><![CDATA[
+ <p>
+ The <span class="code"><log4net></span> element supports the following attributes:
+ </p>
+ <div class="table">
+ <table cellspacing="0">
+ <colgroup>
+ <col style="text-align: left; white-space: nowrap; width: 7em" />
+ <col style="text-align: left;" />
+ </colgroup>
+ <tr>
+ <th>Attribute</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td>debug</td>
+ <td>
+ Optional attribute. Value must be either <span class="code">true</span> or <span class="code">false</span>.
+ The default value is <span class="code">false</span>. Set this attribute to <span class="code">true</span>
+ to enable internal log4net debugging for this configuration.
+ </td>
+ </tr>
+ <tr>
+ <td>update</td>
+ <td>
+ Optional attribute. Value must be either <span class="code">Merge</span> or <span class="code">Overwrite</span>.
+ The default value is <span class="code">Merge</span>. Set this attribute to <span class="code">Overwrite</span>
+ to reset the configuration of the repository being configured before applying this configuration.
+ </td>
+ </tr>
+ <tr>
+ <td>threshold</td>
+ <td>
+ Optional attribute. Value must be the name of a level registered on the repository.
+ The default value is <span class="code">ALL</span>. Set this attribute to limit the messages
+ that are logged across the whole repository, regardless of the logger that the message is logged to.
+ </td>
+ </tr>
+ </table>
+ </div>
+ <p>
+ The <span class="code"><log4net></span> element supports the following child elements:
+ </p>
+ <div class="table">
+ <table cellspacing="0">
+ <colgroup>
+ <col style="text-align: left; white-space: nowrap; width: 7em" />
+ <col style="text-align: left;" />
+ </colgroup>
+ <tr>
+ <th>Element</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td>appender</td>
+ <td>
+ Zero or more elements allowed. Defines an appender.
+ </td>
+ </tr>
+ <tr>
+ <td>logger</td>
+ <td>
+ Zero or more elements allowed. Defines the configuration of a logger.
+ </td>
+ </tr>
+ <tr>
+ <td>renderer</td>
+ <td>
+ Zero or more elements allowed. Defines an object renderer.
+ </td>
+ </tr>
+ <tr>
+ <td>root</td>
+ <td>
+ Optional element, maximum of one allowed. Defines the configuration of the root logger.
+ </td>
+ </tr>
+ <tr>
+ <td>param</td>
+ <td>
+ Zero or more elements allowed. Repository specific parameters
+ </td>
+ </tr>
+ </table>
+ </div>
+
+ <section id="appenders" name="Appenders">
+ <p>
+ Appenders may only be defined as child elements of the <span class="code"><log4net></span>
+ element. Each appender must be uniquely named. The implementing type for the appender must be specified.
+ </p>
+ <p>
+ This example shows an appender of type <span class="code">log4net.Appender.ConsoleAppender</span> being
+ defined. The appender will be known as <i>ConsoleAppender</i>.
+ </p>
+ <source language="xml"><![CDATA[
<appender name="ConsoleAppender" type="log4net.Appender.ConsoleAppender" >
- <layout type="log4net.Layout.PatternLayout">
- <conversionPattern value="%date [%thread] %-5level %logger [%ndc] - %message%newline" />
- </layout>
+ <layout type="log4net.Layout.PatternLayout">
+ <conversionPattern value="%date [%thread] %-5level %logger [%ndc] - %message%newline" />
+ </layout>
</appender>]]></source>
-
- <p>
- The <span class="code"><appender></span> element supports the following attributes:
- </p>
- <div class="table">
- <table cellspacing="0">
- <colgroup>
- <col style="text-align: left; white-space: nowrap; width: 7em" />
- <col style="text-align: left;" />
- </colgroup>
- <tr>
- <th>Attribute</th>
- <th>Description</th>
- </tr>
- <tr>
- <td>name</td>
- <td>
- Required attribute. Value must be a string name for this appender. The name must be unique
- among all the appenders defined in this configuration file. This name is used by the
- <span class="code"><appender-ref></span> element of a Logger to reference an appender.
- </td>
- </tr>
- <tr>
- <td>type</td>
- <td>
- Required attribute. Value must be the type name for this appender. If the appender is
- not defined in the log4net assembly this type name must be fully assembly qualified.
- </td>
- </tr>
- </table>
- </div>
- <p>
- The <span class="code"><appender></span> element supports the following child elements:
- </p>
- <div class="table">
- <table cellspacing="0">
- <colgroup>
- <col style="text-align: left; white-space: nowrap; width: 7em" />
- <col style="text-align: left;" />
- </colgroup>
- <tr>
- <th>Element</th>
- <th>Description</th>
- </tr>
- <tr>
- <td>appender-ref</td>
- <td>
- Zero or more elements allowed. Allows the appender to reference other appenders.
- Not supported by all appenders.
- </td>
- </tr>
- <tr>
- <td>filter</td>
- <td>
- Zero or more elements allowed. Defines the filters used by this appender.
- </td>
- </tr>
- <tr>
- <td>layout</td>
- <td>
- Optional element, maximum of one allowed. Defines the layout used by this appender.
- </td>
- </tr>
- <tr>
- <td>param</td>
- <td>
- Zero or more elements allowed. Appender specific parameters.
- </td>
- </tr>
- </table>
- </div>
-
- <p>
- For examples of configuring appenders see the
- <a href="example-config-appender.html">Example Appender Configuration</a>
- document.
- </p>
-
- <section id="filters" name="Filters">
- <p>
- Filters elements may only be defined as children of <span class="code"><appender></span> elements.
- </p>
- <p>
- The <span class="code"><filter></span> element supports the following attributes:
- </p>
- <div class="table">
- <table cellspacing="0">
- <colgroup>
- <col style="text-align: left; white-space: nowrap; width: 7em" />
- <col style="text-align: left;" />
- </colgroup>
- <tr>
- <th>Attribute</th>
- <th>Description</th>
- </tr>
- <tr>
- <td>type</td>
- <td>
- Required attribute. Value must be the type name for this filter. If the filter is
- not defined in the log4net assembly this type name must be fully assembly qualified.
- </td>
- </tr>
- </table>
- </div>
- <p>
- The <span class="code"><filter></span> element supports the following child elements:
- </p>
- <div class="table">
- <table cellspacing="0">
- <colgroup>
- <col style="text-align: left; white-space: nowrap; width: 7em" />
- <col style="text-align: left;" />
- </colgroup>
- <tr>
- <th>Element</th>
- <th>Description</th>
- </tr>
- <tr>
- <td>param</td>
- <td>
- Zero or more elements allowed. Filter specific parameters.
- </td>
- </tr>
- </table>
- </div>
-
- <p>
- Filters form a chain that the event has to pass through. Any filter along the way can accept the event
- and stop processing, deny the event and stop processing, or allow the event on to the next filter.
- If the event gets to the end of the filter chain without being denied it is implicitly accepted and will be logged.
- </p>
- <source language="xml"><![CDATA[
+
+ <p>
+ The <span class="code"><appender></span> element supports the following attributes:
+ </p>
+ <div class="table">
+ <table cellspacing="0">
+ <colgroup>
+ <col style="text-align: left; white-space: nowrap; width: 7em" />
+ <col style="text-align: left;" />
+ </colgroup>
+ <tr>
+ <th>Attribute</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td>name</td>
+ <td>
+ Required attribute. Value must be a string name for this appender. The name must be unique
+ among all the appenders defined in this configuration file. This name is used by the
+ <span class="code"><appender-ref></span> element of a Logger to reference an appender.
+ </td>
+ </tr>
+ <tr>
+ <td>type</td>
+ <td>
+ Required attribute. Value must be the type name for this appender. If the appender is
+ not defined in the log4net assembly this type name must be fully assembly qualified.
+ </td>
+ </tr>
+ </table>
+ </div>
+ <p>
+ The <span class="code"><appender></span> element supports the following child elements:
+ </p>
+ <div class="table">
+ <table cellspacing="0">
+ <colgroup>
+ <col style="text-align: left; white-space: nowrap; width: 7em" />
+ <col style="text-align: left;" />
+ </colgroup>
+ <tr>
+ <th>Element</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td>appender-ref</td>
+ <td>
+ Zero or more elements allowed. Allows the appender to reference other appenders.
+ Not supported by all appenders.
+ </td>
+ </tr>
+ <tr>
+ <td>filter</td>
+ <td>
+ Zero or more elements allowed. Defines the filters used by this appender.
+ </td>
+ </tr>
+ <tr>
+ <td>layout</td>
+ <td>
+ Optional element, maximum of one allowed. Defines the layout used by this appender.
+ </td>
+ </tr>
+ <tr>
+ <td>param</td>
+ <td>
+ Zero or more elements allowed. Appender specific parameters.
+ </td>
+ </tr>
+ </table>
+ </div>
+
+ <p>
+ For examples of configuring appenders see the
+ <a href="example-config-appender.html">Example Appender Configuration</a>
+ document.
+ </p>
+
+ <section id="filters" name="Filters">
+ <p>
+ Filters elements may only be defined as children of <span class="code"><appender></span> elements.
+ </p>
+ <p>
+ The <span class="code"><filter></span> element supports the following attributes:
+ </p>
+ <div class="table">
+ <table cellspacing="0">
+ <colgroup>
+ <col style="text-align: left; white-space: nowrap; width: 7em" />
+ <col style="text-align: left;" />
+ </colgroup>
+ <tr>
+ <th>Attribute</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td>type</td>
+ <td>
+ Required attribute. Value must be the type name for this filter. If the filter is
+ not defined in the log4net assembly this type name must be fully assembly qualified.
+ </td>
+ </tr>
+ </table>
+ </div>
+ <p>
+ The <span class="code"><filter></span> element supports the following child elements:
+ </p>
+ <div class="table">
+ <table cellspacing="0">
+ <colgroup>
+ <col style="text-align: left; white-space: nowrap; width: 7em" />
+ <col style="text-align: left;" />
+ </colgroup>
+ <tr>
+ <th>Element</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td>param</td>
+ <td>
+ Zero or more elements allowed. Filter specific parameters.
+ </td>
+ </tr>
+ </table>
+ </div>
+
+ <p>
+ Filters form a chain that the event has to pass through. Any filter along the way can accept the event
+ and stop processing, deny the event and stop processing, or allow the event on to the next filter.
+ If the event gets to the end of the filter chain without being denied it is implicitly accepted and will be logged.
+ </p>
+ <source language="xml"><![CDATA[
<filter type="log4net.Filter.LevelRangeFilter">
- <levelMin value="INFO" />
- <levelMax value="FATAL" />
+ <levelMin value="INFO" />
+ <levelMax value="FATAL" />
</filter>]]></source>
- <p>
- This filter will deny events that have a level that is lower than <span class="code">INFO</span>
- or higher than <span class="code">FATAL</span>.
- All events between <span class="code">INFO</span> and <span class="code">FATAL</span> will be logged.
- </p>
- <p>
- If we want to only allow messages through that have a specific substring (e.g. 'database')
- then we need to specify the following filters:
- </p>
- <source language="xml"><![CDATA[
+ <p>
+ This filter will deny events that have a level that is lower than <span class="code">INFO</span>
+ or higher than <span class="code">FATAL</span>.
+ All events between <span class="code">INFO</span> and <span class="code">FATAL</span> will be logged.
+ </p>
+ <p>
+ If we want to only allow messages through that have a specific substring (e.g. 'database')
+ then we need to specify the following filters:
+ </p>
+ <source language="xml"><![CDATA[
<filter type="log4net.Filter.StringMatchFilter">
- <stringToMatch value="database" />
+ <stringToMatch value="database" />
</filter>
<filter type="log4net.Filter.DenyAllFilter" />]]></source>
- <p>
- The first filter will look for the substring 'database' in the message text of the event.
- If the text is found the filter will accept the message and filter processing will stop,
- the message will be logged. If the substring is not found the event will be passed to
- the next filter to process. If there is no next filter the event would be implicitly
- accepted and would be logged. But because we don't want the non matching events to be
- logged we need to use a <span class="code">log4net.Filter.DenyAllFilter</span>
- that will just deny all events that reach it. This filter is only useful at the end of the filter chain.
- </p>
- <p>
- If we want to allow events that have either 'database' or 'ldap' in the message text we can use the following filters:
- </p>
- <source language="xml"><![CDATA[
+ <p>
+ The first filter will look for the substring 'database' in the message text of the event.
+ If the text is found the filter will accept the message and filter processing will stop,
+ the message will be logged. If the substring is not found the event will be passed to
+ the next filter to process. If there is no next filter the event would be implicitly
+ accepted and would be logged. But because we don't want the non matching events to be
+ logged we need to use a <span class="code">log4net.Filter.DenyAllFilter</span>
+ that will just deny all events that reach it. This filter is only useful at the end of the filter chain.
+ </p>
+ <p>
+ If we want to allow events that have either 'database' or 'ldap' in the message text we can use the following filters:
+ </p>
+ <source language="xml"><![CDATA[
<filter type="log4net.Filter.StringMatchFilter">
- <stringToMatch value="database"/>
+ <stringToMatch value="database"/>
</filter>
<filter type="log4net.Filter.StringMatchFilter">
- <stringToMatch value="ldap"/>
+ <stringToMatch value="ldap"/>
</filter>
<filter type="log4net.Filter.DenyAllFilter" />]]></source>
- </section>
-
- <section id="layouts" name="Layouts">
- <p>
- Layout elements may only be defined as children of <span class="code"><appender></span> elements.
- </p>
- <p>
- The <span class="code"><layout></span> element supports the following attributes:
- </p>
- <div class="table">
- <table cellspacing="0">
- <colgroup>
- <col style="text-align: left; white-space: nowrap; width: 7em" />
- <col style="text-align: left;" />
- </colgroup>
- <tr>
- <th>Attribute</th>
- <th>Description</th>
- </tr>
- <tr>
- <td>type</td>
- <td>
- Required attribute. Value must be the type name for this layout. If the layout is
- not defined in the log4net assembly this type name must be fully assembly qualified.
- </td>
- </tr>
- </table>
- </div>
- <p>
- The <span class="code"><layout></span> element supports the following child elements:
- </p>
- <div class="table">
- <table cellspacing="0">
- <colgroup>
- <col style="text-align: left; white-space: nowrap; width: 7em" />
- <col style="text-align: left;" />
- </colgroup>
- <tr>
- <th>Element</th>
- <th>Description</th>
- </tr>
- <tr>
- <td>param</td>
- <td>
- Zero or more elements allowed. Layout specific parameters.
- </td>
- </tr>
- </table>
- </div>
- <p>
- This example shows how to configure a layout that uses the <span class="code">log4net.Layout.PatternLayout</span>.
- </p>
- <source language="xml"><![CDATA[
+ </section>
+
+ <section id="layouts" name="Layouts">
+ <p>
+ Layout elements may only be defined as children of <span class="code"><appender></span> elements.
+ </p>
+ <p>
+ The <span class="code"><layout></span> element supports the following attributes:
+ </p>
+ <div class="table">
+ <table cellspacing="0">
+ <colgroup>
+ <col style="text-align: left; white-space: nowrap; width: 7em" />
+ <col style="text-align: left;" />
+ </colgroup>
+ <tr>
+ <th>Attribute</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td>type</td>
+ <td>
+ Required attribute. Value must be the type name for this layout. If the layout is
+ not defined in the log4net assembly this type name must be fully assembly qualified.
+ </td>
+ </tr>
+ </table>
+ </div>
+ <p>
+ The <span class="code"><layout></span> element supports the following child elements:
+ </p>
+ <div class="table">
+ <table cellspacing="0">
+ <colgroup>
+ <col style="text-align: left; white-space: nowrap; width: 7em" />
+ <col style="text-align: left;" />
+ </colgroup>
+ <tr>
+ <th>Element</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td>param</td>
+ <td>
+ Zero or more elements allowed. Layout specific parameters.
+ </td>
+ </tr>
+ </table>
+ </div>
+ <p>
+ This example shows how to configure a layout that uses the <span class="code">log4net.Layout.PatternLayout</span>.
+ </p>
+ <source language="xml"><![CDATA[
<layout type="log4net.Layout.PatternLayout">
- <conversionPattern value="%date [%thread] %-5level %logger [%ndc] - %message%newline" />
+ <conversionPattern value="%date [%thread] %-5level %logger [%ndc] - %message%newline" />
</layout>]]></source>
-
- </section>
- </section>
-
- <section id="root" name="Root Logger">
- <p>
- Only one root logger element may only be defined and it must be a child of <span class="code"><log4net></span> element.
- The root logger is the root of the logger hierarchy. All loggers ultimately inherit from this logger.
- </p>
- <p>
- An example root logger:
- </p>
- <source language="xml"><![CDATA[
+
+ </section>
+ </section>
+
+ <section id="root" name="Root Logger">
+ <p>
+ Only one root logger element may only be defined and it must be a child of <span class="code"><log4net></span> element.
+ The root logger is the root of the logger hierarchy. All loggers ultimately inherit from this logger.
+ </p>
+ <p>
+ An example root logger:
+ </p>
+ <source language="xml"><![CDATA[
<root>
- <level value="INFO" />
- <appender-ref ref="ConsoleAppender" />
+ <level value="INFO" />
+ <appender-ref ref="ConsoleAppender" />
</root>]]></source>
-
- <p>
- The <span class="code"><root></span> element supports no attributes.
- </p>
- <p>
- The <span class="code"><root></span> element supports the following child elements:
- </p>
- <div class="table">
- <table cellspacing="0">
- <colgroup>
- <col style="text-align: left; white-space: nowrap; width: 7em" />
- <col style="text-align: left;" />
- </colgroup>
- <tr>
- <th>Element</th>
- <th>Description</th>
- </tr>
- <tr>
- <td>appender-ref</td>
- <td>
- Zero or more elements allowed. Allows the logger to reference appenders by name.
- </td>
- </tr>
- <tr>
- <td>level</td>
- <td>
- Optional element, maximum of one allowed. Defines the logging level for this logger.
- This logger will only accept event that are at this level or above.
- </td>
- </tr>
- <tr>
- <td>param</td>
- <td>
- Zero or more elements allowed. Logger specific parameters.
- </td>
- </tr>
- </table>
- </div>
- </section>
-
- <section id="loggers" name="Loggers">
- <p>
- Logger elements may only be defined as children of the <span class="code"><log4net></span> element.
- </p>
- <p>
- An example logger:
- </p>
- <source language="xml"><![CDATA[
+
+ <p>
+ The <span class="code"><root></span> element supports no attributes.
+ </p>
+ <p>
+ The <span class="code"><root></span> element supports the following child elements:
+ </p>
+ <div class="table">
+ <table cellspacing="0">
+ <colgroup>
+ <col style="text-align: left; white-space: nowrap; width: 7em" />
+ <col style="text-align: left;" />
+ </colgroup>
+ <tr>
+ <th>Element</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td>appender-ref</td>
+ <td>
+ Zero or more elements allowed. Allows the logger to reference appenders by name.
+ </td>
+ </tr>
+ <tr>
+ <td>level</td>
+ <td>
+ Optional element, maximum of one allowed. Defines the logging level for this logger.
+ This logger will only accept event that are at this level or above.
+ </td>
+ </tr>
+ <tr>
+ <td>param</td>
+ <td>
+ Zero or more elements allowed. Logger specific parameters.
+ </td>
+ </tr>
+ </table>
+ </div>
+ </section>
+
+ <section id="loggers" name="Loggers">
+ <p>
+ Logger elements may only be defined as children of the <span class="code"><log4net></span> element.
+ </p>
+ <p>
+ An example logger:
+ </p>
+ <source language="xml"><![CDATA[
<logger name="LoggerName">
- <level value="DEBUG" />
- <appender-ref ref="ConsoleAppender" />
+ <level value="DEBUG" />
+ <appender-ref ref="ConsoleAppender" />
</logger>]]></source>
-
- <p>
- The <span class="code"><logger></span> element supports the following attributes.
- </p>
- <div class="table">
- <table cellspacing="0">
- <colgroup>
- <col style="text-align: left; white-space: nowrap; width: 7em" />
- <col style="text-align: left;" />
- </colgroup>
- <tr>
- <th>Attribute</th>
- <th>Description</th>
- </tr>
- <tr>
- <td>name</td>
- <td>
- Required attribute. Value must be the name of the logger.
- </td>
- </tr>
- <tr>
- <td>additivity</td>
- <td>
- Optional attribute. Value may be either <span class="code">true</span> or <span class="code">false</span>.
- The default value is <span class="code">true</span>. Set this attribute to <span class="code">false</span>
- to prevent this logger from inheriting the appenders defined on parent loggers.
- </td>
- </tr>
- </table>
- </div>
- <p>
- The <span class="code"><logger></span> element supports the following child elements:
- </p>
- <div class="table">
- <table cellspacing="0">
- <colgroup>
- <col style="text-align: left; white-space: nowrap; width: 7em" />
- <col style="text-align: left;" />
- </colgroup>
- <tr>
- <th>Element</th>
- <th>Description</th>
- </tr>
- <tr>
- <td>appender-ref</td>
- <td>
- Zero or more elements allowed. Allows the logger to reference appenders by name.
- </td>
- </tr>
- <tr>
- <td>level</td>
- <td>
- Optional element, maximum of one allowed. Defines the logging level for this logger.
- This logger will only accept event that are at this level or above.
- </td>
- </tr>
- <tr>
- <td>param</td>
[... 394 lines stripped ...]