Logging Application Block
This page provides an overview of the Enterprise Library Logging Application Block. An application block is reusable and extensible source code-based guidance that simplifies development of common logging functionality in .NET Framework applications.
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
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.
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.
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.
[C#] 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); [Visual Basic] Dim logEntry As New LogEntry() logEntry.EventId = 100 logEntry.Priority = 2 logEntry.Message = "Informational message" logEntry.Categories.Add("Trace") logEntry.Categories.Add("UI Events") Logger.Write(logEntry)
This release of the Logging Application Block includes the following new features:
- The RollingFlatFileTraceListener class. This class allows you to control the size and age of a text log file. It either overwrites the existing file or creates a new file depending on criteria that you configure.
- Integration with WCF. You can now integrate the Logging Application Block with applications that use WCF.
- An enhanced version of the TimeStampToken class. Earlier releases of the Logging Application Block only allowed timestamps to be logged in UTC time. In this release, the timestamp token now supports a local: prefix that indicates that the timestamp should be displayed in local time.
- The ReflectedPropertyToken class. This release of the Logging Application Block supports a new formatting token that allows you to log custom properties on custom classes that either derive from the LogEntry class or modify it.
To use the Logging Application Block, you need 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.
The Logging Application Block was designed to achieve the following goals:
- Meet the performance requirements for the application block by ensuring that the application block's code has minimal overhead compared to custom code that uses the System.Diagnostics namespace directly.
- Take advantage of the capabilities provided by the .NET Framework's System.Diagnostics namespace.
- Make message routing more flexible than in earlier releases by simplifying the model for distributing log entries.
- Encapsulate the logic that performs the most common application logging tasks, minimizing the need for custom logging-related code.
- Make sure that the application block is easily and highly configurable.
- Make sure that the application block is extensible.
Figure 1 illustrates the design of the Logging Application Block.
Figure 1. Design of the Logging Application Block
The LogEntry class encapsulates content and associated properties for the information an application sends to the application block for logging. Your client code creates new log entries and sets properties such as the message, title, priority, severity, and event ID. Other properties, such as the process name, process ID, and ThreadId, are populated by the application block. A LogEntry object also contains the ExtendedProperties property. This property is a collection of name/value pairs that allows you to place arbitrary string information into the LogEntry object. You can also create a custom LogEntry object by creating a class that derives from the LogEntry class.
Note You must either create new formatters and trace listeners or modify the existing ones to support your custom LogEntry class.
A LogEntry object has a collection of categories. The application block determines the destination for the log entry by its categories. You can also prevent the application from writing log entries with a designated category by using category filters.
Note Client code can also pass information to the Logging Application Block without constructing a LogEntry object by using overloads of the Logger.Write method that do not require a LogEntry object. The application block will construct a LogEntry object for its internal use.
The Logger class is a façade that sends a log entry to one or more destinations. The client code sends the information to the Logger instance, which then sends the LogEntry to an instance of the LogWriter class.
The LogWriter instance checks the filters to see if the LogEntry object should be discarded or sent to any of the trace sources. The filters are implementations of the ILogFilter interface. You specify the filter implementations in the configuration information. If the LogEntry object passes through the filters, the LogWriter instance sends it to each trace source identified by a name that matches one of the LogEntry object's categories.
Note Whenever a LogEntry object fails within the LogWriter instance, the LogWriter instance writes a LogEntry object to the ErrorSource special trace source. The EventID is always the LogWriterFailureEventID. The EventID number is 6352.
The application block relies on the LogSource class to route LogEntry objects. The LogWriter instance has a collection of LogSource objects that correspond to the sources defined in the configuration file. The application block uses the collection of categories in a LogEntry object to determine the LogSource object to use for writing the LogEntry. Categories map directly to LogSource object names.
The LogWriter object also has three special LogSource objects. The AllEventsLogSource object receives all LogEntry objects. The NotProcessedLogSource object receives any LogEntry object that contains a category that does not have an associated LogSource object. The ErrorsLogSource object receives information about errors or warnings that occur while the Logging Application Block code is executing. It does not process errors or warnings from the application code.
Each trace source contains a (potentially empty) collection of trace listeners. A trace listener is a class that derives from the abstract class TraceListener in the System.Diagnostics namespace. Examples of trace listeners are the event log, a text file, and Message Queuing. Although any TraceListener instance will work with the Logging Application Block, only those trace listeners that are provided with the Logging Application Block can format a LogEntry object. The trace listeners that the .NET Framework provides can be used by the Logging Application Block but they only send strings.
The Logging Application Block trace listeners do not require a LogEntry object or a formatter to be instantiated. Instead, you can construct them by including the necessary information in the configuration file. The FormattedEventLogTraceListener, the FlatFileTraceListener, and the WmiTraceListener trace listeners use the same configuration information as the System.Diagnostics trace listeners. This means you can configure your application to use these three trace listeners in the <system.diagnostics> configuration section of your configuration file.
The MsmqTraceListener, FormattedDatabaseListener, and EmailTraceListener trace listeners require more configuration information. For example, the EmailTraceListener trace listener requires the destination e-mail address, the SMTP server name, and related e-mail information. You can configure your application to use these trace listeners by including the appropriate information in the configuration file. However, because these trace listeners require more information than the System.Diagnostics trace listeners do, you cannot configure them in the <system.diagnostics> configuration section. Instead, you should use the <listeners> section located in the Logging Application Block configuration section. You can also construct these trace listeners in code and pass the required configuration information as parameters to their constructors.
The application block populates the collection of trace listeners from the application configuration data. The LogSource object sends the LogEntry object to each trace listener in the collection.
You can define configuration settings that control filtering of LogEntry objects. Filtering a LogEntry object prevents the application block from sending it to any trace source. The application block includes three types of filters. The CategoryFilter filters LogEntry objects by their category collection. The PriorityFilter filters LogEntry objects by their priority property. The LogEnabledFilter is a global filter that applies to all LogEntry objects in an application. With it, you can turn on and turn off logging. You can also create your own trace sources. Use the configuration console to list them in the application block's configuration information.
Log entry information must often be formatted before it is written to the destination. Application block trace listeners that derive from the FormattedTraceListenerBase class format the log entry information before writing it to a destination. The application block includes two classes for formatting LogEntry information. (You can also build your own formatters.) The TextFormatter class converts the LogEntry into a text string. The contents of the string are determined by replacing tokens in the template property of the TextFormatter configuration information in your application configuration file. The BinaryLogFormatter class uses the .NET Framework BinaryFormatter to serialize and deserialize the LogEntry in binary format. It should be used with the Message Queuing distributor service.
The Logging Application Block has been developed as a result of analyzing common enterprise development challenges and successful solutions to these challenges. However, because each application is unique, you will not find this application block suitable for every application. To evaluate this application block and determine its applicability to your projects, Microsoft suggests you dedicate at least half of a day to explore the application block. The following is a suggested evaluation approach:
- Download Enterprise Library.
- Install Enterprise Library and compile all application blocks and tools.
- Read the "Introduction" and "Scenarios and Goals" sections of the documentation.
- Compile and run the QuickStart samples, and read through the related "QuickStart Walkthroughs" and "Key Scenarios" sections of the documentation.
- If the application block looks like a good fit for your application, try implementing a simple use case in your application or in a throw-away prototype application using the application block.
Enterprise Library, like many patterns & practices deliverables, is associated with a community site. On this community site, you can post questions, provide feedback, or connect with other users for sharing ideas. Community members can also help Microsoft plan and test future deliverables, and download additional content such as extensions and training material.
Questions? Comments? Suggestions? To provide feedback about this application block, or to get help with any problems, please visit the Enterprise Library Community site. The community site is the preferred feedback and support channel because it allows you to share your ideas, questions, and solutions with the entire community.
Enterprise Library is a guidance offering, designed to be reused, customized, and extended. It is not a Microsoft product. Code-based guidance is shipped "as is" and without warranties. Customers can obtain support through Microsoft Support Services for a fee, but the code is considered user-written by Microsoft support staff. For more information about our support policy, see the Enterprise Library home page.