Debugging Web Parts

This programming task is a simple walkthrough of setting up your system to debug a Web Part project.


Microsoft Visual Studio .NET

Microsoft Windows SharePoint Services

Note For debugging to work correctly, you must install and run Microsoft Visual Studio .NET on a server running Windows SharePoint Services. Also, you must have file write access in the file system directory mapped to the SharePoint virtual server. For a default site, this means you must be able to modify files in C:\Inetpub\wwwroot and its subdirectories.


Web Part developers use Microsoft Visual Studio .NET as a tool to build Web Part assemblies. These assemblies are fundamentally no different from regular ASP.NET Web control assemblies written in managed code. After these controls are written, the next step is to test and debug them.

There are three high-level steps to debugging your Web Part:

  • Setting breakpoints
  • Attaching to the ASP.NET process
  • Debugging (stepping through code)

Step 1: Setting breakpoints

This section will help you set up the appropriate files and the SharePoint site for debugging.

Note The following steps assume that the Web Part assembly you are debugging is on the default SharePoint site.

  • Open your Web Part project in Visual Studio .NET.
  • Check project settings to make sure that the compiled assembly is located in the \bin folder of the SharePoint site.
    • Right-click the project name in Solution Explorer, and then click Properties.
    • Click Configuration Properties, and then check the value for Output Path to make sure that this is %your drive letter%\InetPub\WWWRoot\bin\
  • Make sure that the Web Part assembly and type are enabled in the SafeControls list.

    • Open the web.config file located at %your drive letter%\InetPub\WWWRoot\.

    • Search for the <SafeControls> tag.

    • Make sure that your assembly is already listed in a <SafeControl> tag; if is it not, add the following line within the SafeControls list.

      <SafeControl Assembly="%your assembly's full name%,
      Version=%your assembly's version%,
      Culture=%your assembly's culture%,
      PublicKeyToken=%your assembly's Public key token%"
      Namespace="%your assembly's full Namespace%"
      TypeName= "*"
      Safe= "True" />

      For more information on how to create a <SafeControl> tag for a Web Part, see "Register your Web Part as a Safe Control" in the Creating a Basic Web Part programming task.

  • Set breakpoints alongside the appropriate lines of code.
    • Select the line at which you want to break; for example, you can start with the CreateChildControls or RenderWebPart methods.
    • Right-click the line, and then click Insert Breakpoint.

Step 2: Attaching to the ASP.NET process

After successfully opening the project and setting the appropriate breakpoints, you are ready to start debugging the assembly. Before you can debug, you need to attach to the w3wp.exe process. There are two ways to do this.

To manually attach to the process

  • Set up a Web Part Page with the Web Part you want to debug on your local SharePoint server.
  • Attach the debugger to the ASP.NET process: w3wp.exe.
    • On the Debug menu, click Processes.
    • Select the Show system processes and Show processes in all sessions check boxes.
    • In the Available Processes list, select w3wp.exe, and then click Attach.
    • In the Attach to Process dialog box, select Common Language Runtime, and then click OK.
    • Click Close. You are now ready to step through your code.

To use a start-up page and automatically attach to the process

  • Right-click the project name in Solution Explorer, and then click Properties.
  • Click Configuration Properties, and then click Debugging.
  • Under Debuggers, set Enable ASP.NET Debugging to True.
  • Under Start Action, set Debug Mode to URL, and then set Start URL to the URL of the Web Part Page that uses your Web Part.
  • Click OK, and then save your project.
  • Open the web.config file for your site.
  • Within the <system.web> tag, find the <compilation batch="false"/> tag, and then change it to <compilation batch="false" debug="true"/>.
  • Save your changes.
  • On the Debug menu, click Start. The debugger should launch the browser with your Web Part Page, attach to the process, and allow you to debug automatically.

Step 3: Debugging (stepping through code)

After attaching to the w3wp.exe process, you are now ready to step through the code. Request the page with the target part in it. As the page and the part renders, depending on where the breakpoint is set, you will notice that the control switches to the Visual Studio debugger. After the control is in the debugger, you can step through the code and identify the problem by using the debugger's available functionality.

To see the call stack when an error occurs instead of being redirected to the error page

  • Open the web.config file for your site.
  • In the web.config file, search for the <SharePoint> tag.
  • In the <SharePoint> tag, locate the <SafeMode MaxControls="50" CallStack="false"/> tag and change it to <SafeMode MaxControls="50" CallStack="true"/>.
  • In the web.config file, search for the <System.Web> tag.
  • Within the <System.Web> tag, locate the <customErrors> tag and change it to <customErrors mode="Off">.

Note While debugging, fixing and recompiling your assembly, you may (if you are not generating a new version number for every recompilation) get an error saying that Visual Studio was unable to replace the output dynamic-link library (DLL) after compilation. This is because the w3wp.exe process has placed a lock on the old copy of your DLL located in the \InetPub\WWWRoot\bin directory. To fix this problem, end the w3wp.exe process using the Task Manager and recompile your code.