Logging an Unhandled Exception

Typical Goals

If your SharePoint solution encounters an unhandled exception, it is important to let the system administrator know about it. No matter how robustly your code performs during testing, the production environment can introduce variables that are beyond the control of your application. For example, lists and databases can be moved or deleted, disks can run out of space, and dependent assemblies can be removed or replaced. Writing an informative message to the event log can help the system administrator to resolve the problem.

Solution

The ILogger interface defines a method named LogToOperations that you can use to log unhandled exceptions directly to the Windows event log and the ULS trace log. This method provides several overloads that allow you to specify an integer identifier, a severity, a category, and a custom message in addition to the actual exception object. To log an unhandled exception, use the LogToOperations method in a catch block within your application logic.

Using the LogToOperations Method to Log Exceptions

The following code shows how to use the LogToOperations method to log an exception from within a catch block. This example assumes that you have added a reference to the Microsoft.Practices.SharePoint.Common.dll assembly, the Microsoft.Practices.ServiceLocation.dll assembly, and the Microsoft.SharePoint.dll assembly.

using Microsoft.Practices.ServiceLocation;
using Microsoft.Practices.SharePoint.Common.ServiceLocation;
using Microsoft.Practices.SharePoint.Common.Logging;
using Microsoft.SharePoint;

// ...

ILogger logger = SharePointServiceLocator.GetCurrent().GetInstance<ILogger>();

try 
{
   // Attempt a SharePoint operation.
}
catch (SPException ex)
{
   // Define your exception properties.
   string msg = "An error occurred while trying to retrieve the customer list";
   string category = @"SalesTool/Data";
   int eventID = 0;
   EventLogEntryType severity = EventSeverity.Error;

   // Log the exception.
   logger.LogToOperations(ex, msg, eventID, severity, category);
}

For more information about how to use the LogToOperations method, see Creating Log Entries.

Usage Notes

Logging unhandled exceptions is probably the most common scenario for using the SharePoint Logger. Although it is valuable for a system administrator to know that there are problems with a certain component, exception messages alone rarely suggest a clear course of action.

You can provide additional text when logging exceptions. Try to provide information that can help the administrator to identify what happened when the exception occurred. For example, the message "An unknown exception occurred while trying to retrieve product information from the product service. The exception message was: A time-out occurred." is much more helpful than "A time-out occurred."

Finally, to avoid flooding the event log, be selective about the exceptions that you log. For best practice guidance on managing exceptions, see Exception Management in SharePoint.