Creating Trace Messages

The ILogger interface defines a method named TraceToDeveloper. The default implementation of this method writes a message to the ULS trace log. Like the LogToOperations method, the TraceToDeveloper method provides several overloads that accept exceptions, integer event identifiers, severity levels, and diagnostic areas and categories along with your messages. However, while the LogToOperations method is aimed at system administrators, the TraceToDeveloper method is aimed at developers or advanced administrators who cannot attach a debugger to a production environment and therefore must rely on trace logs to identify the sources of problems.

Note

The ULS trace logs are located in the LOGS folder in the SharePoint installation root directory. The SharePoint installation root directory, also known as the "SharePoint root", is by default located at C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\14.

The following code examples show how you can use different overloads of the TraceToDeveloper method. To log a message without specifying any additional information, simply pass in your message string as a parameter to the TraceToDeveloper 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>();

// Create a simple trace message.
string msg = "The current user does not have a valid PartnerID";
logger.TraceToDeveloper(msg);

If you are reporting an event to the trace log, you may want to include an integer event ID with your trace message. This can help developers who are searching for instances of a particular issue in the trace logs. The best practice approach is to use enumerated values or constants for event IDs in your solutions. The following example assumes that you have created an enumeration of integer values named TraceLogEventId.

// Create a trace message with an event ID.
logger.TraceToDeveloper(msg, (int) TraceLogEventId.MissingPartnerID);

If you want to specify a severity level in your trace message, use the TraceSeverity enumeration. This is a SharePoint-specific enumeration that is defined in the Microsoft.SharePoint.Administration namespace.

Note

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

// Create a trace message with a trace severity level.
logger.TraceToDeveloper(msg, TraceSeverity.High);

Note

It is important to carefully choose the TraceSeverity value, because SharePoint administrators will usually apply "event throttling" settings that limit what appears in the ULS trace logs by severity and by category. For more information about the TraceSeverity enumeration, see TraceSeverity Enumeration on MSDN.

You can also specify values for diagnostic area and category when you create a trace message. To specify an area and category, pass a string parameter with the format "area/category" to the TraceToDeveloper method.

// Create a trace message with a diagnostic area and category.
string area = "Custom Area"
string category = "Data";
string areaCategory = string.Format("{0}/{1}", area, category);
Logger.TraceToDeveloper(msg, areaCategory);

Note

If you are going to specify a category value, you must pass in a string in the format "area/category". The SharePoint Logger will throw an exception if the value is not in this format.

Other overloads of the TraceToDeveloper method allow you to specify various combinations of these properties.

Like the LogToOperations method, the TraceToDeveloper method provides several overloads that you can use to handle exceptions, as shown in the following code example.

Exception ex = …

// Trace an exception. 
logger.TraceToDeveloper(ex);

// Trace an exception with an additional error message.
logger.TraceToDeveloper(ex, msg);

// Trace an exception with an additional error message and 
// an application-defined event ID.
logger.TraceToDeveloper(ex, msg, (int) EventLogEventId.SkuNotFound);

// Trace an exception with an additional error message, an event ID,
// a trace severity level, and an area/category string.
logger.TraceToDeveloper(ex, msg, (int) EventLogEventId.SkuNotFound, 
     TraceSeverity.High, areaCategory);

// Trace an exception with an event ID, a trace severity level, and
// an area/category string. 
logger.TraceToDeveloper(ex, (int) EventLogEventId.SkuNotFound, 
     TraceSeverity.Verbose, areaCategory);