!!!! This Page is still under development. Please check back later. Thank you !!!!

Commons Logging User Guide

Contents

  1. Introduction
  2. Quick Start
    1. Configurating Commons Logging
    2. Configuring for the System.Diagnostics.Trace
    3. Configuring Log4Net
    4. Configuring Enterprise Library Logging framework
  3. Assemblies included in the Standard Distribution
    1. Dotnet.Commons.Logging.dll
      1. Dotnet.Commons.Logging.Log4net.dll
      2. Dotnet.Commons.Logging.LAB.dll
  4. Extending Commons Logging
    1. Contract
    2. Creating a Logger Implementation
    3. Creating A LogFactory Implementation

_

1. Introduction

The Commons Logging component provides a unified ILog interface that acts as a light-weight and independent abstraction of other logging frameworks. It allows developers to utilize a common logging API, while maintaining the freedom to utilize many different third-party logging implementations such as Log4Net or NLog. The Commons Logging API insulates the application and protects it from becoming coupled to a specific logging implementation.

Ported from the Jakarta Commons Logging and modified for the .Net framework, the component provides a small set of C# classes and interfaces that an application imports and relies upon to remove any compile-time and run-time dependencies on any particular logging implementations.

The Logging component allows developers to declaratively configure the logging implementation and the library will dynamically discover which implementation is being used. An application that utilizes the Commons Logging API does not have to be modified when the logging implementation is changed; this is the greatest benefit of such a component.

_

2. Quick Start

The quickest way to get familiar with the Commons Logging is to examine the Dotnet.Commons.Logging.Test application that is included in the Dotnet Commons Logging release package. It has an extensive test suite to for testing all the different logger implementations. It can also serve as an effective learning tool to understand how to configure and use the Commons Logging API.

Coupled with this guide, the basic configurations and usage of the Commons Logging is explained and demonstrated. You would be able to become familiar with the Commons Logging within a very short time.

_

2.1 Configurating Commons Logging

To define which logging framework to use in your application, you will need to set the logger property in your application configuration file (App.Config for windows application and web.config for ASP.Net). Below are examples of the settings required for Commons Logging to utilise various loggers:

1. Commons Logging internal SimpleLogger:
<appSettings>
	<add key="Dotnet.Commons.Logging.LogFactory" 
		 value="Dotnet.Commons.Logging.Impl.SimpleLoggerFactory" />	     
          :
</appSettings>


2. Configuring for System.Diagnostics.Trace class:
<appSettings>	
	<!-- use System.Diagnostic.Trace logging -->  
	<add key="Dotnet.Commons.Logging.LogFactory" 
	     value="Dotnet.Commons.Logging.Impl.SystemTraceLoggerFactory" />
            :
</appSettings>


3. Configuring for Log4net:
<appSettings>
	<!-- use log4net logging framework -->
	<add key="Dotnet.Commons.Logging.LogFactory" 
	     value="Dotnet.Commons.Logging.Impl.Log4NetFactory,Dotnet.Commons.Logging.Log4net" />
            :
</appSettings>


4. Configuring for Microsoft Enterprise Library:
<appSettings>
	<!-- use EntLib Logging Application Block -->
	<add key="Dotnet.Commons.Logging.LogFactory" 
	     value="Dotnet.Commons.Logging.Impl.LABFactory,Dotnet.Commons.Logging.LAB" />
</appSettings>


We have seen in the above examples of how Commons Logging can be configured to select which logging implementations to use. It is also possible to programmatically configure Commons Loggings to select or even switch the logging framework.

For example, to programmatically select Log4net as the logging framework to use, one would only need to add the following line of code:
	Dotnet.Commons.Logging.ILog log = LogFactory.GetLogger(typeof(YourClass), 
                     LogFactory.GetFactory("Dotnet.Commons.Logging.Impl.Log4NetFactory",
                                                     "Dotnet.Commons.Logging.Log4net"));


where YourClass is the class the in which the logging is required.

_

2.2 Configuring for the System.Diagnostics.Trace

System.Diagnostics.Trace class is provided as part of the .Net BCL. It provides a set of methods and properties that help you trace the execution of your code

Commons Logging provides a Logger implementation which utilises this class to perform logging functionality.

System.Diagnostics.Trace sends messages to objects called listeners that receive and process these messages. For more information, see Trace listeners.

Below is an example how the System.Diagnostics.Trace can be configured in the App.config or web.config file:
  <system.diagnostics>
    <trace autoflush="true" indentsize="4">
	<listeners>
		<add name="configConsoleListener"
			type="System.Diagnostics.ConsoleTraceListener" />

		<add name="OutputDebugListener" 
			type="Dotnet.Commons.Logging.TraceListeners.OutputDebugStringTraceListener, Dotnet.Commons.Logging" />
			
		<add name="LogFileListener"
			type="System.Diagnostics.TextWriterTraceListener"
			initializeData="D:\Temp\Dotnet.Commons.Logging.SystemTraceLog.log" />

		<add name="RollOverTextWriterTraceListener"
			type="Dotnet.Commons.Logging.TraceListeners.RollOverTextWriterTraceListener,Dotnet.Commons.Logging" 
			initializeData="D:\Temp\Dotnet.Commons.Logging.RollOverTraceLog.log" />

	</listeners>
    </trace>
  </system.diagnostics>


For information of how to configure a new trace listener, see Configure Trace Listener.

_

2.3 Configuring Log4net

Log4net is a very commonly used logging implementation (as well as being the one of the out-of-the-box logging implementations supported by Commons Loggin), so a few details are presented herein to get the developer/integrator going. Please see the Log4net homepage for more details on Log4net and it's configuration.

2.3.1 Configuring Log4net in Application Configuration file

Log4net configuration settings can be added to a typical Application config file (app.config or web.config).

An example below outlines a typical Log4net config settings:
<configSections>
 
    <!--
    =============================================
    Log4Net config section
    =============================================
    -->
    <section name="log4net" type="log4net.Config.Log4NetConfigurationSectionHandler, log4net" />
 
</configSections>
 
<appSettings>
    <!--
    ===========================================================================
    This is the only Application Setting needed for Dotnet.Commons.Logging
    ===========================================================================
    -->
    <add key="Dotnet.Commons.Logging.LogFactory"
        value="Dotnet.Commons.Logging.Impl.Log4NetFactory,Dotnet.Commons.Logging.Log4Net" />
 
</appSettings>
 
 
<!--
=============================================
Log4Net specific  Configuration
=============================================
-->
<log4net>
    <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="FrameworkAppender" type="log4net.Appender.FileAppender">
        <file value="nstruts.log" />
        <layout type="log4net.Layout.PatternLayout">
            <conversionPattern value="%date [%thread] %-5level %logger [%ndc] - %message%newline" />
        </layout>
    </appender>
    <root>
        <level value="ALL" />
        <appender-ref ref="ConsoleAppender" />
    </root>
    <logger name="YouAppsNamespace">
        <level value="TRACE" />
        <appender-ref ref="FrameworkAppender" />
    </logger>
</log4net>

You can learn more about configuring Log4net from their website at: Log4net Config example page.

2.3.2 Configuring Commons Logging to use Log4net Programmatically

Commons Logging also provides additional utility functions to allow configuring log4net programmatically. This is demonstrated as follow:
     ILog log = LogFactory.GetLogger(typeof(Log4NetTest), 
                 LogFactory.GetFactory("Dotnet.Commons.Logging.Impl.Log4NetFactory",
                                       "Dotnet.Commons.Logging.Log4net"));


     Dotnet.Commons.Logging.Utils.Log4netUtils.ChangeConfigFile(@"..\log4netConfigs\SpecificLoggingSettings.config");

_

2.4 Configuring Enterprise Library Logging framework


_

Assemblies included in the Standard Distribution

Dotnet.Commons.Logging.dll
This assembly contains the core Commons Logging APIs, and the default LogFactory implementation as well as the built-in Logger implementations for the internal SimpleLogger and System.Diagnostics.Trace.
Dotnet.Commons.Logging.Log4net.dll
This assembly contains the implementations for the Log4net logger.
Dotnet.Commons.Logging.LAB.dll
This assembly contains the implementations for the Microsoft Enterprise Library logger.

_

Extending Commons Logging

The Commons Logging is designed to encourage extensions to be created that add functionality. Typically, extensions to Commons Logging fall into two categories:
  1. new Logger implementations that provide new bridges to logging systems
  2. new LogFactory implementations that provide alternative discovery strategies

Contract

To create an ILog implementation for your chosen Logging Framework, you will need to create 2 new classes:
  1. xxxLogger
  2. xxxLogFactory
where xxx is the name of the logging framework you would want to implement the Logging interface.

Creating a Logger Implementation

To integrate a third party logging framework with the Commons Logging, a logger is required to provide an implementation of the ILog interface. The logger must inherit from Dotnet.Commons.Logging.Logger.

Creating A LogFactory Implementation

A LogFactory will also need to be created. The LogFactory must inherit from Dotnet.Commons.Logging.LogFactory.

Last edited May 2, 2007 at 2:15 AM by surendra, version 13

Comments

No comments yet.