SharePoint Development Practices and Techniques

Using debugging tools

While creating a custom solution, you can and probably will use Microsoft Visual Studio to debug your code in your development environment if you experience any issues or unexpected behavior. You might even use Visual Studio to do some debugging to simply get a better understanding of what’s happening behind the scenes in SharePoint. The Visual Studio Debugger is not the only way to understand and troubleshoot SharePoint and your custom components, though. Other tools that you can use include:

• Unified Logging Service (ULS) and Windows event logs
• The Developer Dashboard
• Fiddler and other network monitoring tools

Working with ULS and Windows event logs

The ULS logs are SharePoint’s own dedicated log files. Whenever there is problem with a SharePoint environment, the first place a SharePoint developer or administrator should look for information is in the ULS logs. One of the advantages of the ULS logs is that they can be used for troubleshooting in all types of environments. Regardless of whether problems are occurring in a development environment, in a test or integration environment, or in a production environment, ULS logs should contain valuable pointers to what’s happening.

By default, the ULS logs are stored on the file system of every SharePoint server in the <Program Files Directory>\Common Files\Microsoft Shared\Web Server Extensions\15\LOGS folder, which is the LOGS folder under the SharePoint root folder. By going into Configure Diagnostic Logging on the Monitoring page in Central Administration, it is possible to specify the folder where the ULS logs are stored. Administrators can change the number of days logs are kept and the total amount of disk space that can be used by the logs. If you are troubleshooting a server that wasn’t configured by you and the logs are not in the LOGS folder in the SharePoint root folder, you can browse to the Configure Diagnostic Logging page to find out where the log files are stored on the server. The page can also be used to change the severity of the events that are logged both to the ULS logs and to the Windows event logs. Flood protection can be enabled to make sure that SharePoint events won’t flood the Windows event logs.

The ULS logs are text files that are quite difficult to read and that usually contain a lot of data. To more easily read events in the ULS logs and also to search, sort, and filter the ULS logs, the ULS Viewer is a must-have tool for everyone who has to troubleshoot SharePoint. The ULS Viewer can be downloaded from MSDN at http://archive.msdn.microsoft.com/ULSViewer and is an .exe file that has to be run on the SharePoint server. It will enable you to start and stop traces and to search through the logs by using a well-organized user interface instead of a text file.

Troubleshooting information for a SharePoint environment can also be found in the Windows event logs. On the server, the Windows event logs can be consulted by opening up the Event Viewer. There is some overlap in the information between the ULS logs and the Windows Event Viewer, but both also contain specific information that can be valuable for finding the source of the problem.

When an error occurs in SharePoint, an error message will be displayed in the user interface that contains what is referred to as a correlation ID. A correlation ID is a GUID that uniquely identifies a particular request. The correlation ID is generated by the SharePoint web server that receives the request. Every event that is part of the request is tagged with the same ID, and the ID even persists across different servers in the farm. For instance, if a request was sent to a SharePoint web server, it will be generated on that server and it will mark all entries in the ULS log that are part of the request with that particular correlation ID. If, as part of the request, some managed metadata has to be requested from the Managed Metadata service that runs on a dedicated application server, the same correlation ID can be found in the ULS logs on that application server. You can even use the correlation ID to trace the request on the server that is running SQL Server by using SQL Profiler to filter out requests related to the ID.

When an end user encounters an error in a SharePoint environment, that user will usually see an error message that contains a correlation ID. Even though the ID is of no use to the user himself, users can be asked to include the ID when they place a call to a helpdesk. Having the ID of the user’s faulty request can help administrators and developers find out what went wrong with the user’s request and help solve the issue.

Correlation IDs aren’t just generated for faulty requests; they are generated for all requests. To find the correlation ID for a successful request, you can use the Developer Dashboard.

Using the Developer Dashboard

The Developer Dashboard was introduced in SharePoint 2010 to show performance and tracing information for a SharePoint page in a control on the page itself. In SharePoint 2013, the Developer Dashboard has been dramatically improved. The dashboard is no longer a control on a page; it opens in a separate dedicated window. The dashboard also no longer just contains information about the latest request but contains information about several requests, so that you can compare them if you want to and more easily get an overview. The information on the Developer Dashboard is a lot more detailed than it was in SharePoint 2010. For instance, you can now easily see the SQL requests and the time it took to process them, the different scopes and execution times, service calls, and also all ULS log entries that are related to the selected request. All this can really help you to identify any potential problems related to a request, because you have all the information SharePoint collected about the requests in a single place.

By default, the Developer Dashboard is disabled. You can enable it by using Windows PowerShell. The Windows PowerShell cmdlet only supports On or Off; the OnDemand parameter has been deprecated, although On now pretty much acts the way OnDemand did in SharePoint 2010; it displays an icon in the upper-right corner that allows you to open up the Developer Dashboard. The Windows PowerShell cmdlet to turn on the Developer Dashboard is displayed in Listing 2-3.

Listing 2-3 Changing the mode of the Developer Dashboard

Add-PSSnapin Microsoft.SharePoint.PowerShell -ErrorAction "SilentlyContinue"
$DevDashboardSettings = [Microsoft.SharePoint.Administration.SPWebService]:: '
ContentService.DeveloperDashboardSettings
$DevDashboardSettings.DisplayLevel = 'On'
$DevDashboardsettings.Update()

Figure 2-5 shows the Developer Dashboard after the welcome page of an out-of-the-box team site has been loaded. On the dashboard, you can see different tabs for server information, scopes, SQL info, ULS information, and a lot more. The Server Info tab contains the total execution time for the page, the current user, whether the page is published, and the correlation ID. The SQL tab also shows the execution time for all database queries and for all methods. By using the dashboard you can not only see how long a page took to load just the out-of-the-box functionality on it, but you can also see how long it takes your custom component to load. You can identify whether your code executes any expensive methods or database queries.

Figure 2-5 The Developer Dashboard

To write information from your own custom solution to the Developer Dashboard you can either execute your code in an OnInit or Render override, or you can wrap your code in an SPMonitoredScope block. Only code from farm solutions can send information to the Developer Dashboard; the contents of sandboxed solutions or apps cannot send information to the dashboard.