Introduction to the Logging Application Block

Article
07/14/2010

Retired Content
This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
The latest Enterprise Library information can be found at the Enterprise Library site.

The Enterprise Library Logging Application Block simplifies the implementation of common logging functions. Developers can use the Logging Block to write information to a variety of locations:

The event log
An e-mail message
A database
A message queue
A text file
A WMI event
Custom locations using application block extension points

Note

The Enterprise Library – January 2006 release now includes an instrumentation subsystem in the Enterprise Library Core. Because the current release of the application block now focuses on logging, its name has been changed from the Logging and Instrumentation Application Block to the Logging Application Block.

The application block provides a consistent interface for logging information to any destination. Your application code does not specify the destination for the information. Configuration settings determine whether the application block writes the logging information and the location for that information. This means that operators as well as developers can modify logging behavior without changing application code.

The Logging Application Block helps with application development in a number of ways:

It helps maintain consistent logging practices, both within an application and across the enterprise.
It eases the learning curve for developers by using a consistent architectural model.
It provides implementations that you can use to solve common application logging tasks.
It is extensible, supporting custom implementations of components that format and write event information.

Common Scenarios

Developers frequently write applications that require logging functionality. Typically, these applications format and log information in response to application events. For example, developers often write code to log information in response to unexpected conditions, such as an application exception, or failure to connect to a database. Developers also write code to trace application flow through components during the execution of an application use case or scenario.

Applications need to write information either locally or over the network. In some cases, you may have to collate events from multiple sources into a single location.

The Logging Application Block simplifies application development by providing a small set of easy-to-use classes and methods that encapsulate many of the most common logging scenarios. These scenarios include:

Populating and logging event information.
Including context information in the event.
Tracing application activities.

Each task is handled in a consistent manner, abstracting the application code from the specific logging providers.

For more information about the scenarios that the Logging Application Block can help you with, see Scenarios and Goals.

Example Application Code

The following code shows how to populate and raise an event in your application**.** The LogEntry object has a priority of 2 and belongs to both the Trace and UI Events categories.

LogEntry logEntry = new LogEntry();
logEntry.EventId = 100;
logEntry.Priority = 2;
logEntry.Message = "Informational message";
logEntry.Categories.Add("Trace");
logEntry.Categories.Add("UI Events");

Logger.Write(logEntry);

'Usage
Dim logEntry As LogEntry = New LogEntry()
logEntry.EventId = 100
logEntry.Priority = 2
logEntry.Message = "Informational message"
logEntry.Categories.Add("Trace")
logEntry.Categories.Add("UI Events")

Logger.Write(logEntry)

Audience Requirements

This guide is intended for software architects, software developers, and policy makers. To benefit fully from this guide, you should understand the following technologies:

Microsoft Visual Studio 2005 development system
Microsoft .NET Framework 2.0

Highlights of This Release

The January 2006 release of the Logging Application Block has been revised to take advantage of the System.Diagnostics namespace in the .NET Framework 2.0. In particular, it relies heavily on the TraceListener class and the CorrelationManager class. The application block also includes the following changes to simplify the architectural model:

Simplified model. There are no longer any distribution strategies. In scenarios where you previously used custom distribution strategies, you can now use specific trace listeners.
A LogEntry object can now belong to more than one category.
You can now create your own filters. Filters screen events before the Logging Application Block sends the events to the trace listeners. The application block includes filters that allow you to discard events that are of no interest based on their category and/or their priority. This release of the application block also lets you create custom filters to filter events using your own criteria.
You can now query filters from your own code to see whether particular events should be logged. This means you can avoid building log entries, which can adversely affect performance, when the application block is not configured to log those entries.

Migrating to the January 2006 Release

The following information explains the changes you have to make to migrate from the earlier release of the Logging and Instrumentation Application Block to the January 2006 release of the Logging Application Block:

The configuration format has changed. The default storage location for the January 2006 release is the application configuration file. The June 2005 release stored the Logging Application Block configuration data in the loggingConfiguration.config file. For a description of how to migrate your existing configuration information for use with Enterprise Library – January 2006, see Migration Information.
The Severity property of the LogEntry class is now a TraceEventType enumeration instead of an Int32 integer. Using the TraceEventType enumeration improves interoperability with the System.Diagnostics namespace. Any code that uses the Severity property should be updated to use the TraceEventType enumeration. If you want to use numeric values, the Priority property is still of type Int32.
If you used the Message Queuing distribution strategy in your applications, you will need to modify your configuration to use the MsmqTraceListener class. You can configure your application using the Enterprise Library Configuration Console. You must also choose which categories are sent to the Message Queuing trace listener on the client. The AllEvents trace source and the NotProcessed trace source work well in this situation because they eliminate the need to configure every category on the client. They are specified in the <specialSources/> element in the configuration file for the Logging Application Block. For more information, see Entering Configuration Information.
To use the CorrelationManager class, the ActivityId property is now a GUID and it is no longer maintained on the stack. This means that a request can have only one activity ID.
Log sinks now derive from the .NET Framework TraceListener class. To reflect this change, log sinks are now referred to as "trace listeners." If you are using custom trace listeners in your application, you will have to modify them to derive from the System.Diagnotics.TraceListener class. It is also possible to derive them the application block's CustomTraceListener abstract class. This class derives from the TraceListener class and includes support for formatting log messages.

System Requirements

To use the Logging Application Block, you need the following:

Microsoft Windows 2000, Windows XP Professional, or Windows Server 2003 operating system
Microsoft .NET Framework 2.0
Microsoft Visual Studio 2005 development system (any of the following editions):
- Microsoft Visual Studio 2005 Standard Edition
- Microsoft Visual Studio 2005 Professional Edition
- Microsoft Visual Studio 2005 Team Edition for Software Developers
- Microsoft Visual Studio 2005 Team Edition for Software Testers
- Microsoft Visual Studio 2005 Team Edition for Software Architects
- Microsoft Visual Studio 2005 Team Suite
Stores to maintain log messages. If you are using the MsmqTraceListener trace listener to store log messages, you need a message queue. If you are using the DatabaseTraceListener trace listener to store log messages, you need a database server. If you are using the EmailTraceListener trace listener to store log messages, you need an SMTP server.

Logging Application Block Dependencies

The Logging Application Block depends on other code included in the Enterprise Library:

Core library functionality. The Enterprise Library Core provides services such as instrumentation and configuration, and is a shared dependency of all Enterprise Library application blocks. The core library functionality is contained in the assembly Microsoft.Practices.EnterpriseLibrary.Common.dll.
The ObjectBuilder subsystem. The ObjectBuilder subsystem performs all the repetitive and necessary tasks for creating and disposing of object instances, while still providing a high level of flexibility. Enterprise Library uses the ObjectBuilder subsystem for tasks such as injecting configuration into block classes and connecting instrumentation classes to application blocks. The ObjectBuilder subsystem is contained in the assembly Microsoft.Practices.ObjectBuilder.dll.

Depending on the specific functionality you require from the Logging Application Block, you may also require the Data Access Application Block, which the Logging Application Block uses for the database trace listener. You can also use the Logging Application Block with the Exception Handling Application Block to log formatted exception information. In this case, it is the Exception Handling Application Block that depends on the Logging Application Block. For more information, see the Exception Handling Application Block documentation.

The recommended way to modify the configuration settings for the Logging Application Block is to use the Enterprise Library Configuration Console.

Logging Application Block Documentation

In addition to the introduction, the documentation contains the following topics:

Developing Applications with the Logging Application Block. This topic explains how to download and install the Logging Application Block so that you can use it in your applications. It also explains how to add application code to the application block where required. This topic includes two subtopics. The first subtopic, Configuration, describes how to configure the application block to perform common tasks. The second subtopic, Key Scenarios, demonstrates how to use the application block to perform the most common logging operations.
Design of the Logging Application Block. This topic explains the decisions that went into designing the application block and the rationale behind those decisions.
Extending and Modifying the Logging Application Block. This topic explains how to extend the application block by creating your own custom trace listeners and how to modify the source code.
Deployment and Operations. This topic explains how to deploy and update the application block's assemblies and also contains information about configuration.
QuickStarts. This topic explains how to install and configure the QuickStart applications. This section contains a series of walkthroughs that demonstrate how to incorporate common logging operations in an application.

More Information

For more information, see the following patterns & practices guides:

Retired Content
This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
The latest Enterprise Library information can be found at the Enterprise Library site.