Logging an Exception to Operations
Typical Goals
In this scenario, you want to log an exception to the Windows event log and the ULS trace log. Typically, this is an unhandled exception that the system administrator needs to know about.
Solution
In Visual Studio, add a reference to the SharePoint Guidance Library, Microsoft.Practices.SPG.Common.dll. Use the SharePoint service locator to get a reference to a Microsoft.Practices.SPG.Common.Logging.ILogger interface and invoke the LogToOperations method. Pass the exception that you want to log as an argument to the LogToOperations method.
Logging an Exception
The following code demonstrates how to log an exception.
try
{
/// ... a SharePoint operation ...
}
catch (SPException sharePointException)
{
ILogger logger = SharePointServiceLocator.Current.GetInstance<ILogger>();
logger.LogToOperations(sharePointException);
}
The LogToOperations method records the exception in the Windows event log and the ULS trace log.
Usage Notes
Typically, logging exceptions to operations is done for unhandled exceptions. Although the exception message rarely provides a clear course of action, it is valuable for a system administrator to know that there are problems with a certain component and that a developer might have to look at it. Be selective about the exceptions that are logged.
You can provide additional text when logging exceptions. Try to provide information that can help identify what happened when the exception occurred. For example, the exception "An unknown exception occurred while trying to retrieve product information from the product service. The exception message was: A timeout occurred" is much more helpful to operations than "A timeout occurred".
The LogToOperations method has overloaded versions that allow you to specify optional information for the exception you are logging. You can include the following:
- An application-specific error string of your choice
- An integer event ID
- An event-log entry type that distinguishes warnings from errors
- A string that denotes a category
The following are examples of exception logging that use the different overloads of the LogToOperations method.
// ILogger logger = ...
// Exception ex = ...
// string msg = ...
// string category = ...
// Log an exception with an additional error message.
logger.LogToOperations(ex, msg);
// Log an exception with an additional error message and
// an application-defined event ID.
logger.LogToOperations(ex, msg, (int) EventLogEventId.SkuNotFound);
// Log an exception with an additional error message, a default event ID,
// an event-log entry type, and a category string.
logger.LogToOperations(ex, msg, 0, EventLogEntryType.Error, category);
// Log an exception with a default event ID, an event-log entry type, and
// a category string.
logger.LogToOperations(ex, 0, EventLogEntryType.Warning, category);
For more information about the EventLogEntryType enumeration, see EntryLogEntryType Enumeration on MSDN.