--- configuration.xml.orig 2005-01-17 19:25:50.000000000 -0700 +++ configuration.xml 2005-06-07 10:56:25.454025300 -0600 @@ -1,6 +1,7 @@ @@ -205,10 +206,10 @@ ]]>

- Suppose we are no longer interested in seeing the output of any component + Suppose we are no longer interested in seeing the output of any component belonging to the Com.Foo - package. The following configuration file shows one possible way of achieving + package. The following configuration file shows one possible way of achieving this.

- + - + @@ -246,7 +247,7 @@ As the logger Com.Foo.Bar does not have an assigned level, it inherits its level from - Com.Foo, which was set to WARN in the configuration + Com.Foo, which was set to WARN in the configuration file. The log statement from the Bar.DoIt method has the level DEBUG, lower than the logger level WARN. Consequently, @@ -264,7 +265,7 @@ - + @@ -275,7 +276,7 @@ - + @@ -283,7 +284,7 @@ ]]>

- Calling the enhanced MyApp with the this configuration file will output the + Calling the enhanced MyApp with the this configuration file will output the following on the console.

- In addition, as the root logger has been allocated a second appender, output + In addition, as the root logger has been allocated a second appender, output will also be directed to the example.log - file. This file will be rolled over when it reaches 100KB. When roll-over + file. This file will be rolled over when it reaches 100KB. When roll-over occurs, the old version of example.log is automatically moved to example.log.1.

- 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, + 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 Com.Foo - output to an NT Event logger, or forwarded logging events to a remote log4net + output to an NT Event logger, or forwarded logging events to a remote log4net server, which would log according to local server policy.

For more examples of configuring appenders using the XmlConfigurator - see the Example Appender Configuration + see the Example Appender Configuration document.

- +
+

+ The log4net library does not make any assumptions about its + environment. In particular, there are no default log4net appenders. + Under certain well-defined circumstances however, the static + constructor of the LogManager class will attempt to automatically + configure log4net. The .NET runtime guarantees that the static + initializer of a class will run once and only once as soon as the + class is referenced for the first time. +

+

+ The default initialization process is very useful in environments + where the exact entry point to the application depends on the + runtime environment. for example, the same .NET library may be used + as part of a stand-alone application, called from a windows service, + or as part of a .NET web application. +

+

+ The exact default initialization algorithm is defined as follows: +

    +
  1. + Setting the log4net.defaultInitOverride + application setting to any other value then "false" + (case-insensitive) will cause log4net to skip the default + initialization procedure (this procedure). +
    2. +
  2. + Set the resource string variable to the value of the + log4net.configuration application + setting. This setting can be set in the assembly (e.g. + myAssembly.dll.config), application (e.g. web.config) or machine + (e.g. machine.config) configuration file. In case the + log4net.configuration property is not + defined, then the remainder of the default initialization + procedure (this procedure) is skipped. +
    3. +
  3. + Attempt to convert the resource variable to a URI. If the + resource variable cannot be converted to a URI, for example due + to a UriFormatException, then the remainder of the default + initialization procedure (this procedure) is skipped. +
    4. +
  4. + If no URI could not be found, abort default initialization. + Otherwise, configure log4net from the URI. +
    5. +
+

+

+ The XmlConfigurator will be used to parse the URL to configure + log4net. +

+
+

The log4net configuration can be configured using assembly-level attributes rather than @@ -331,32 +385,32 @@ ConfigFile

If specified, this is the filename of the configuration file to use with the - XmlConfigurator. This file path is relative to the + XmlConfigurator. This file path is relative to the application base directory (AppDomain.CurrentDomain.BaseDirectory).

- This property cannot be used in conjunction with the + This property cannot be used in conjunction with the ConfigFileExtension property.

  • ConfigFileExtension

    - If specified, this is the extension for the configuration file. The assembly + 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 TestApp.exe and the ConfigFileExtension property is set to - log4net then the configuration file name is + log4net then the configuration file name is TestApp.exe.log4net. This is equivalent to setting the ConfigFile property to TestApp.exe.log4net.

    - The path to the configuration file is build by using the application base - directory (AppDomain.CurrentDomain.BaseDirectory), + The path to the configuration file is build by using the application base + directory (AppDomain.CurrentDomain.BaseDirectory), the assembly file name and the configuration file extension.

    - This property cannot be used in conjunction with the + This property cannot be used in conjunction with the ConfigFile property.

    • @@ -364,14 +418,14 @@ Watch

    If this flag is specified and set to true - then the framework will watch the configuration file and will reload the config + then the framework will watch the configuration file and will reload the config each time the file is modified.

    If neither of the ConfigFile or ConfigFileExtension - properties are specified, the application configuration file (e.g. TestApp.exe.config) + properties are specified, the application configuration file (e.g. TestApp.exe.config) will be used as the log4net configuration file.

    @@ -409,7 +463,7 @@ certainly before any external assemblies have been loaded and invoked.

    - +

    Typically the log4net configuration is specified using a file. This file can @@ -419,14 +473,14 @@

  • Using the .NET System.Configuration API
  • Reading the file contents directly
    • - +
    -

    +

    The System.Configuration API is only available if the - configuration data is in the application's config file; the file named - MyApp.exe.config or Web.config. Because the System.Configuration - API does not support reloading of the config file the configuration settings - cannot be watched using the log4net.Config.XmlConfigurator.ConfigureAndWatch + configuration data is in the application's config file; the file named + MyApp.exe.config or Web.config. Because the System.Configuration + API does not support reloading of the config file the configuration settings + cannot be watched using the log4net.Config.XmlConfigurator.ConfigureAndWatch methods. The main advantage of using the System.Configuration APIs to read the configuration data is that it requires less permissions than accessing the configuration file directly. @@ -472,15 +526,15 @@ version and public key.

    - When using the .config file to specify the configuration the section name and + When using the .config file to specify the configuration the section name and XML element name must be log4net.

    - +

    - The XmlConfigurator can directly read any XML file and use it to configure log4net. - This includes the application's .config file; the file named MyApp.exe.config + The XmlConfigurator can directly read any XML file and use it to configure log4net. + This includes the application's .config file; the file named MyApp.exe.config or Web.config. 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). @@ -489,7 +543,7 @@ The file to read the configuration from can be specified using any of the log4net.Config.XmlConfigurator methods that accept a System.IO.FileInfo object. Because the - file system can be monitored for file change notifications the + file system can be monitored for file change notifications the ConfigureAndWatch methods can be used to monitor the configuration file for modifications and automatically reconfigure log4net.

    @@ -538,7 +592,7 @@ ]]>

    - The above example shows how the configuration data can be embedded + 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 @@ -550,19 +604,19 @@ the config section will be employed.

    - +
    - +

    - log4net includes a configuration reader that parses an XML DOM, the + log4net includes a configuration reader that parses an XML DOM, the log4net.Config.XmlConfigurator. This section defines the syntax accepted by the configurator.

    This is an example of a valid XML configuration. The root element must be <log4net>. Note that this does not mean - that this element cannot be embedded in another XML document. See the section above + that this element cannot be embedded in another XML document. See the section above on Configuration Files for more information on how to embed the XmlConfigurator XML in a configuration file.

    @@ -662,7 +716,7 @@ - +

    Appenders may only be defined as child elements of the <log4net> @@ -678,7 +732,7 @@ ]]> - +

    The <appender> element supports the following attributes:

    @@ -696,7 +750,7 @@ name 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 + among all the appenders defined in this configuration file. This name is used by the <appender-ref> element of a Logger to reference an appender. @@ -749,13 +803,13 @@ - +

    - For examples of configuring appenders see the - Example Appender Configuration + For examples of configuring appenders see the + Example Appender Configuration document.

    - +

    Filters elements may only be defined as children of <appender> elements. @@ -802,11 +856,11 @@ - +

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

    ]]>

    This filter will deny events that have a level that is lower than INFO - or higher than FATAL. + or higher than FATAL. All events between INFO and FATAL will be logged.

    - If we want to only allow messages through that have a specific substring (e.g. 'database') + If we want to only allow messages through that have a specific substring (e.g. 'database') then we need to specify the following filters:

    ]]>

    - 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 + 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 log4net.Filter.DenyAllFilter that will just deny all events that reach it. This filter is only useful at the end of the filter chain.

    @@ -849,7 +903,7 @@     ]]>
    - +

    Layout elements may only be defined as children of <appender> elements. @@ -904,10 +958,10 @@ ]]> - +

    - +

    Only one root logger element may only be defined and it must be a child of <log4net> element. @@ -921,7 +975,7 @@ ]]> - +

    The <root> element supports no attributes.

    @@ -960,7 +1014,7 @@
    - +

    Logger elements may only be defined as children of the <log4net> element. @@ -973,7 +1027,7 @@ ]]> - +

    The <logger> element supports the following attributes.

    @@ -1038,7 +1092,7 @@
    - +

    Renderer elements may only be defined as children of the <log4net> element. @@ -1048,7 +1102,7 @@

    ]]> - +

    The <renderer> element supports the following attributes.

    @@ -1085,7 +1139,7 @@ The <renderer> element supports no child elements.

    - +

    Parameter elements may be children of many elements. See the specific elements above for details. @@ -1095,7 +1149,7 @@

    ]]> - +

    The <param> element supports the following attributes.

    @@ -1128,7 +1182,7 @@ Optional attribute. One of value or type attributes must be specified. The value of this attribute is a type name to create and set as the value of the - parameter. If the type is not defined in the log4net assembly this type name must + parameter. If the type is not defined in the log4net assembly this type name must be fully assembly qualified. @@ -1171,7 +1225,7 @@ all the components included in the log4net assembly.

    - For 3rd party components please see their relevant API reference for + For 3rd party components please see their relevant API reference for details of the properties available.

    @@ -1198,7 +1252,7 @@
    - +