Creating Log Entries

The ILogger interface defines a method named LogToOperations. Operations is another term for administrators and the tools that they use to monitor applications. When you log an event to operations, you should provide information that can help IT professionals understand how to remedy the problem. The information should be valuable and comprehensible to a systems administrator, even if the message is simply that the system behaved in an unexpected way that requires advanced debugging.

The default implementation of the LogToOperations method writes a message to both the Windows event log and the ULS trace log. The method provides several overloads that you can use to specify an event identifier, a severity, and a diagnostic area and category along with your message. All method overloads also append contextual information to the log entry, such as the user identity and the current URL, where applicable.

To log a message without specifying any additional information, simply pass in your message string as a parameter to the LogToOperations method.

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

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

// Log an event with a message.
string msg = "The current user does not have a valid PartnerID";
logger.LogToOperations(msg);

When you log an event, you may want to include an integer event ID with the event message. This can help system administrators to reference the issue and locate other instances of the same problem. It is good practice to use enumerated values or constants for event IDs in each solution that you develop. The following example assumes that you have created an enumeration of integer values named EventLogEventId.

// Log an event with a message and an event ID.
logger.LogToOperations(msg, (int)EventLogEventId.MissingPartnerID);

You may also want to specify a severity level. To do this, you can use the EventSeverity enumeration. This defines the severity levels used by SharePoint for the event log: ErrorCritical, Error, Warning, Information, and Verbose. The EventSeverity enumeration also contains various deprecated values that you should not use.

Note

The logger has several method overloads that accept a SandboxEventSeverity argument instead of an EventSeverity argument. Because the EventSeverity enumeration is not permitted in the sandbox, the SandboxEventSeverity provides a parallel enumeration structure that you can use within sandboxed code. If you use the SandboxEventSeverity enumeration, logging will succeed, regardless of whether your code runs inside or outside the sandbox.

// Log an event with a message and a severity level.
logger.LogToOperations(msg, EventSeverity.Error);

// Log an event with a message, an event ID, and a severity level.
logger.LogToOperations(msg, (int) EventLogEventId.MissingPartnerID,
                       EventSeverity.Error);

Specifying a severity level enables system administrators to filter the Windows event log. For example, an administrator might want to view all messages with severity level Error without scrolling through many more trivial messages.

Note

The previous release of the SharePoint Guidance Library used EventLogEntryType instead of EventSeverity enumeration for events. This was because SharePoint 2007 did not expose any methods that write to the Windows event log, so the logger wrote to the event log using standard .NET Framework methods and enumerations. In this release, the SharePoint object model includes methods that you can use to directly write to the Windows event log. Because of this, the interface was changed to be consistent with the severity levels used by SharePoint 2010.
It is important to carefully choose the EventSeverity value, because SharePoint administrators will usually apply "event throttling" settings that limit what appears in the Windows event logs by severity and by category. For more information about the EventSeverity enumeration, see EventSeverity Enumeration on MSDN.

Finally, in most cases, you should include values for diagnostic area and category when you log an event. Again, this can help system administrators to filter the event log to find only those events that are relevant to the issue under investigation. In the Windows event log, the area corresponds to the event source name and the category corresponds to the task category. To specify an area and category, you must pass a string parameter with the format "area/category" to the LogToOperations method.

// Log an event with a message, an event ID, a severity level, and a category.
string area = "Custom Area"
string category = "Execution";
string areaCategory = string.Format("{0}/{1}", area, category);
logger.LogToOperations(msg, (int) EventLogEventId.MissingPartnerID,
                       EventSeverity.Error, areaCategory);

If you do not specify a value for the diagnostic area and category when you log an event, the SharePoint Logger will set the area value to Patterns and Practices and the category value to SharePoint Guidance.

Note

You can also pass an exception directly to the LogToOperations method. For a scenario-based example of exception logging, see Logging an Unhandled Exception.

For more information about the EventSeverity enumeration, see EventSeverity Enumeration on MSDN.