Design of the SharePoint Logger

The ILogger Interface

The ILogger interface is designed to accommodate most logging scenarios and to help developers target their messages to either system administrators or developers.

The implementation of the ILogger interface should be retrieved through the SharePoint service locator. The default implementation is the SharePointLogger class, but it is possible to register different logging implementations.

The SharePointLogger Class

The SharePointLogger class is a straightforward implementation of the ILogger interface. The class is composed of two replaceable components that implement the IEventLogLogger interface and the ITraceLogger interface. The interfaces do the following:

• The IEventLogLogger interface records events that are meant for system administrators. By default, this interface is implemented by the EventLogLogger class. This class writes log messages to the Windows event log.
• The ITraceLogger interface records the trace information that is used by application developers. By default, this interface is implemented by the TraceLogger class. This class writes trace messages to the SharePoint Unified Logging System (ULS). If you prefer to write to a different trace log, such as the ASP.NET trace log, you can create and register a custom ITraceLogger interface.

The SharePointLogger class has the following responsibilities:

• Forward the log messages to the appropriate logger. Messages targeted at operations are sent to both the class that implements the IEventLogLogger interface and the class that implements the ITraceLogger interface. Messages targeted solely at developers are only sent to the class that implements the ITraceLogger.
• Enrich the log message with contextual information. Messages with contextual information, such as the current URL and the name of the currently logged on user, save troubleshooting time.
• Format exceptions into a human readable message. Messages in the log files must be that are readable by humans.
• Provide a high level of robustness in case the logging fails. If a message cannot be written to the event logger implementation, a LoggingException is thrown that contains both the original log message and the reason for the logging failure. No exception is thrown if a message cannot be written to the trace logger implementation. Instead, the SharePointLogger class will attempt to write a message to the event logger implementation to indicate that the trace has failed.

The following diagram shows the class hierarchy of the SharePoint logger implementation.

Class hierarchy of the SharePoint logger implementation

Note

In the diagram, the arrows link classes to the interfaces that they implement. The diamonds show containment of components. The design choice of containing functionality instead of inheriting it through the type hierarchy is referred to as composition. Composition produces flexible designs and increases the opportunity for component reuse.

The event log and trace logger implementations perform the details of writing administrative and diagnostic messages.

If you need additional functionality or flexibility, you can extend the SharePointLogger by inheriting from it or from the BaseLogger class, by creating a custom ILogger implementation or by building on another logging framework.

The EventLogLogger Class

The EventLogLogger class writes entries to the Windows event log. This class is configured as the default implementation of the IEventLogLogger interface that is used by the SharePoint logger.

Because the user account may not have sufficient privileges to write to the global event log, the Log method of the EventLogLogger class executes with elevated privileges. This means that it uses the configured application pool service account privileges.

The EventLogLogger class uses the value Office SharePoint Server as the default event source name for events logged to the Windows event log. This event source name is already used by the Office SharePoint Server. You should configure a custom event source name before logging messages to operations. If you do not set a custom event source name, a warning will also be logged that a custom event source name should be configured.

You can configure your application to use a custom event source name by using the IConfigManager interface. With the IConfigManager interface you can set the value of the Microsoft.Practices.SPG.Common.EventSourceName in the current farm's property bag to the event source you want to use. For more information on how to set a property using the IConfigManager interface, see Adding and Updating Configuration Settings.

Note

It is recommended that you set the Microsoft.Practices.SPG.Common.EventSourceName property of the current SPFarm object. This allows the logger to find the property in all SharePoint contexts, including the case when feature receivers are called during a command-line installation operation. In the command-line installation, there is no current site, site collection or Web application.

The TraceLogger Class

The TraceLogger class writes tracing data to the ULS trace log. This class is configured as the default implementation of the ITraceLogger interface that is used by the SharePoint logger.

The TraceLogger class uses an auxiliary static class that is named UlsTraceProvider. This class encapsulates the details of writing to the ULS trace log. The TraceLogger class is based on an implementation that is discussed in Trace Log Example on MSDN.

The SharePoint logger uses the ULS trace log because it allows developers to see their own diagnostic messages in the context of the trace messages that are generated by SharePoint. The ULS logs to a file in a structured format. It is possible to open this file in Notepad; however, ULS log files are usually large. It is often easier to use a ULS Viewer to read these log files. For example, the ULS Log Viewer on CodePlex is a community driven effort to create an ULS Log Viewer for SharePoint.

For more information about the ULS trace log, see Trace Logs on MSDN.

Customizing the SharePoint Logger

The SharePoint logger implementation uses the SharePoint service locator to access the EventLogLogger class and the TraceLogger class. With service location, you can replace the default logging and tracing components if you need more flexibility or want to reuse a logging component that you already have. For example, during unit testing you can customize logging so that the logging information becomes part of the unit test's output.

For more information about the SharePoint service locator, see The SharePoint Service Locator.

Service location occurs at three points of the logger's design.

• The IEventLogLogger interface is mapped by default to the EventLogLogger class.
• The ITraceLogger interface is mapped by default to the TraceLogger class.
• The ILogger interface is mapped by default to the SharePointLogger class.

You can customize logging and tracing by reconfiguring any of these type mappings.

• If you want to change the way that event logging is handled, replace the EventLogLogger class with a new class that implements the IEventLogLogger interface.
• If you want to change the way that trace logging is handled, replace the TraceLogger class with a new class that implements the ITraceLogger interface. For example, you can log to the ASP.Net trace log.
• If you want to slightly modify the way the SharePointLogger class handles logging, you can create a class that derives from it. It has virtual methods for most operations, so you can override most of its behavior.
• If you want full control over how logging and tracing are handled, replace the SharePointLogger class with a new class that derives from the BaseLogger class or that directly implements the ILogger interface.

Use the IServiceLocatorConfig interface to configure your application to use your new custom logger. For an example of how to replace a service using configuration, see Getting Services from the SharePoint Service Locator.

Note

Callers should invoke the logging interface types (such as ILogger) and not the logging implementation types (such as the SharePointLogger class) directly.

To customize the event source name for the SharePoint logger, see the discussion of the EventLogLogger class earlier in this topic.

Home page on MSDN | Community site