SharePoint Config

Debugging in WSS 3.0 or MOSS is similar to debugging a standard ASP.NET application but there are several differences that can catch you out. In this post I will go through some of the basic techniques you can use to get more information than the “An unexpected error has occurred” message. These are:

1. Enabling detailed error messages
2. Attach a debugger to your code
3. Use Try-Catch statements
4. Use Debug and Trace statements
5. View the SharePoint Logs (using the LogViewer feature)

I’ll give a brief description of each below.

Enable detailed error messages

The first thing to do is to get more detail than the ever helpful “An unexpected error has occurred”. This can be done by making a couple of small changes to the web.config file for your SharePoint site. The first change is to change the SafeMode CallStack attribute to ‘true’. The second change is to set the customErrors mode in the system.web section to ‘On’ (or ‘RemoteOnly’). This will show ASP.NET exceptions that occur in web parts or user controls. For example:

<SafeMode MaxControls="200" CallStack="true" />
<system.web>
<customErrors mode="Off" />
</system.web>

Attach a debugger to your code

You can also attach a debugger to your SharePoint code so that you can step through the execution of you workflow, eventhandler or other custom code. To attach a debugger in Visual Studio select Debug > Attach to process and select the w3wp.exe (or OWSTIMER.exe for timer jobs) process. Alternatively you can automatically attach your debugger. There are a few points to note here:

• The code you are using to debug must be exactly the same as the executing assembly. This often catches people out in SharePoint development as the assembly SharePoint is using is often in a different location than the default build directory (i.e. in the bin directory in IIS or in the GAC). You may want to include a post build script to copy your assembly to the correct location to help automate this process. Also be careful when debugging assemblies that are in the GAC as you may need to do an iisreset to ensure ASP.NET uses the latest version of your assembly.
• The .pdb file needs to be in the same directory as the assembly to see line numbers. This is easy if you are using the bin directory of the website (recommended when developing), but you cannot copy these files directly into the GAC. You can get around this with the following steps:
  • Map a network drive to the GAC (C:\WINDOWS\assembly) folder. This allows you to see the actual folder structure and copy files into the folders as they appear on disk (opposed to the shell that is shown when browsing directly).
  • Copy the .pdb file into your assembly folder in the GAC_MSIL subfolder so that it sits next to the assembly dll.
• Activate features through the UI if you want to debug feature receivers. If you use the stsadm command line tool to automate feature deployment the w3wp process will be recycled so any debuggers will be detached. Activating these through the central admin or the site features page will ensure the w3wp process is running.

If your code is not on the local machine you can also attach a remote debugger to step through execution on another machine.

Use Debug and Trace statements

System.Diagnostics.Debug and Trace statements are another great way of tracking down errors in your code. As Debug calls are removed from release builds, these can be used extensively to help track down errors in development. To view these you can use tools such as DebugView to view messages on local or remote machines as shown below:

Use Try-Catch statements

As with standard ASP.NET applications, Try-Catch statements can help catch and log error messages that occur in your code. This can be combined with Debug and Trace statements to view or log errors, or display meaningful messages to the user. For example in a web control you might do the following:


protected override void Render(HtmlTextWriter writer)
{
try
{
// code that might cause an error
}
catch
{
Trace.Write(ex);
writer.Write(ex.Message);
}
}


View the SharePoint Logs

The raw SharePoint log files are extremely cluttered and hard to use but there is an alternative. The LogViewer feature on CodePlex lets you easily select a log file and view a filtered display of the items you are interested in. An example is shown below:

You can also tweak the information that is written to the SharePoint logs via the Diagnostic Logging link under Logging and Reporting in the operations section of Central Administration.

For more information see the following articles:

• Vincent Rothwell’s “Debugging tips for SharePoint”
• Debugging an ASP.NET Web Application