Debugging Web Parts

 

Suraj Poozhiyil
Microsoft Corporation

May 2003

Applies to:
   Microsoft® Windows® SharePoint™ Services 2.0
   Microsoft Visual Studio® .NET

Summary: Learn how to use Microsoft Visual Studio .NET to debug an existing Web Part assembly. (5 pages)

Contents

Introduction
Opening the Project and Setting Break Points
Attaching to the ASP.NET (W3wp) Process
Debugging
Tips and Tricks
Developing and Debugging from a Remote Computer
Problems Saving Output
Conclusion

Introduction

You can use Microsoft Visual Studio .NET to build Web Part assemblies. These assemblies are the same as ASP.NET server control assemblies written in managed code. After you write these controls, the next step is to test and debug them. This paper describes how to configure your system to debug a custom Web Part project.

Prerequisites

  • Familiarity with Microsoft Windows SharePoint Services 2.0.
  • Knowledge about how to create a Web Part
  • Familiarity with the Web Part infrastructure
  • Completed Web Part project to debug.

System Requirements

To debug a Web Part assembly, you need:

  • Windows SharePoint Services 2.0
  • Visual Studio .NET (version 7.0 or 7.1)
  • Write access to the file system directory mapped to the virtual server running Windows SharePoint Services (for example, C:\Inetpub\wwwroot and its subdirectories).
  • Permissions to debug the ASP.Net process

Opening the Project and Setting Break Points

To begin, start Visual Studio, load your project, set up the appropriate files, and set up the SharePoint site for debugging.

**Note   **The following procedure assumes that the Web Part assembly uses the default SharePoint site for debugging.

To Set Up a Site for Debugging

  1. Click Start, point to All Programs, point to Microsoft Visual Studio .NET, and then click Microsoft Visual Studio .NET.

  2. In Visual Studio .NET, click File, and then click Open.

  3. Browse to the Web Part project that you want to debug, and then click Open.

  4. Right-click the project name, and then click Properties.

  5. In the navigation tree, double-click Configuration Properties.

  6. Under Outputs, verify that the value for Output Path matches the following line:

    local_drive:\InetPub\WWWRoot\bin\

  7. Ensure that the Web Part assembly and type are enabled in the Safe Controls list. To do this, follow these steps:

    1. In Windows Explorer, browse to the following folder:

      local_drive:\InetPub\WWWRoot\bin\.

    2. Double-click the Web.config file.

    3. In the Web.config file, search for the <SafeControls> tag.

    4. Verify that your assembly is listed as a safe control. If it is not listed as a safe control, add the following line to the Safe Controls list.

      <SafeControl Assembly="assembly_name, Version=assembly_version,
      Culture=assembly_culture, PublicKeyToken=assembly_public_key_token"
      Namespace="assembly_namespace" TypeName="*" Safe="True"/>
      
  8. Save and close the file.

To Set Break Points

  1. Use Visual Studio.NET to open the code files for your custom Web Parts.

  2. In one of your custom Web Parts file, right-click a line where you want to add a break point, and then click Insert Break Point. For example, you may want to insert a break point in the RenderWebPart method.

    Repeat this step to set break points at all appropriate locations in the file.

  3. Repeat steps 1 and 2 to set break points in each of your custom Web Part files.

Attaching to the ASP.NET (W3wp) Process

After you successfully open the project and set the appropriate breakpoints, the next step is to attach to the W3wp.exe process.

To Attach to the ASP.NET Process:

  1. Create a Web Part Page on the default SharePoint site.
  2. Add the Web Part to the page.
  3. Attach the debugger to the W3wp process. To do this, follow these steps:
  4. On the Debug menu in Visual Studio .NET, click Processes.
    1. Verify that the Show system processes check box is selected.
    2. Verify that the Show processes in all sessions check box is selected.
    3. Under Available Processes, click W3wp.exe in the Process list, and then click Attach.
    4. Under Choose the program types that you want to debug, select Common Language Runtime, and then click OK.
    5. Click Close.

Debugging

After attaching to the W3wp process, you can debug the code. To do this, use Internet Explorer to open the test page that includes the new Web Part. As the page renders, the control switches to the Visual Studio debugger (depending on the location of the break point). You can now use the debugging mode to check the Web Part functionality.

Tips and Tricks

Debugging Web Part code can help identify potential code bugs, but debugging does not address all potential problems. For example, when the Web Part Page refers to an assembly that cannot be found, debugging may not address the problem. If this is the case, you can use the following two strategies to isolate the problem.

Using the CallStack Attribute

Windows SharePoint Services overrides the CallStack attribute. This attribute is located in the Web.config file. The CallStack attribute controls whether a call stack and an exception message are displayed when a system-level exception occurs while ASP.NET processes a request to send a page to all local and remote clients. By default, Windows SharePoint Services disables the CallStack attribute and displays a limited set of exceptions to prevent information disclosure. To receive a call stack and an exception message when an exception occurs, enable the CallStack attribute.

To enable the CallStack attribute

  1. In Windows Explorer, browse to the following folder:

    local_drive:\InetPub\WWWRoot\bin\

  2. Double-click the Web.config file.

  3. In the Web.config file, search for the <SharePoint> element.

  4. In the <SharePoint> element, locate the <SafeMode MaxControls="50" CallStack="false"/> tag and change it to <SafeMode MaxControls="50" CallStack="true"/>.

  5. Save and close the file.

When exceptions occur, you now receive ASP.NET exception messages with stack trace information.

**Note   **The CallStack attribute enables this functionality for all local and remote clients.

Using Tracing in ASP.NET

You can use the tracing feature in ASP.NET to monitor the environment of the server on which you are programming. You can use tracing on a specific page or for an entire application. You can use tracing on a local server computer without enabling it for remote clients.

To enable ASP.NET tracing on a local server

  1. In Windows Explorer, browse to the following folder:

    local_drive:\InetPub\WWWRoot\bin\.

  2. Double-click the Web.config file.

  3. In the Web.config file, search for the <system.web> element.

  4. In the <system.web> element, add the following line:

    <trace enabled="true" pageOutput="true"/>
    
  5. Save and close the file.

The environment information now appears at the bottom of the test page that includes the Web Part. For more information about how to use tracing in ASP.NET, visit the following MSDN Web site: .NET Framework Developer's Guide: ASP.NET Trace.

Developing and Debugging from a Remote Computer

To use a remote computer to develop and debug, follow these steps.

**Note   **To follow these steps, you must have a client computer running Visual Studio .NET (Computer_A) and a server computer running Windows SharePoint Services (Server_B).

  1. On Server_B, share the directory that hosts the SharePoint virtual server. By default, the Windows SharePoint Services virtual server is mapped to the following directory:

    local_drive:\InetPub\wwwroot

  2. Ensure that you have Read and Write permissions for this directory and its sub-directories.

  3. On Server_B, share the directory in which the Microsoft.SharePoint.dll file is located. By default, the Microsoft.SharePoint.dll file is located in the following directory:

    local_drive:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\60\ISAPI

  4. Make sure that you have Read permission for this directory.

  5. On Computer_A, follow these steps:

    1. Click Start, point to All Programs, point to Microsoft Visual Studio .NET, and then click Microsoft Visual Studio .NET.

    2. On the File menu in Visual Studio .NET, click Open.

    3. Browse to the Web Part project that you want to debug, and then click Open.

    4. Right-click the project name, and then click Properties.

    5. In the navigation tree, double-click Configuration Properties.

    6. Under Outputs, verify that the value for Output Path matches the following line:

      remote_drive_on_Server_B:\InetPub\WWWRoot\bin\

    7. In Windows Explorer, browse to the following folder:

      remote_drive_on_Server_B:\InetPub\WWWRoot\bin\.

    8. Double-click the Web.config file.

    9. In the Web.config file, search for the <SafeControls> tag.

    10. Verify that your assembly is listed as a Safe Control. If not, add the following line to the Safe Controls list.

      <SafeControl Assembly="assembly_name, Version=assembly_version,
      Culture=assembly_culture, PublicKeyToken=assembly_public_key_token"
      Namespace="assembly_namespace" TypeName="*" Safe="True"/>
      
    11. Save and close the file.

  6. On Server_B, install and configure the remote debugging services.

For more information about remote debugging, visit the following MSDN Web site: Visual Studio: Setting Up Remote Debugging.

Problems Saving Output

When you debug or modify an assembly, you may receive the following error message:

Unable to replace file_name.dll after compilation.

This behavior may occur if the W3wp.exe process locks the old copy of the assembly located in the InetPub\WWWRoot\bin directory. To resolve this issue, use Task Manager to end the W3wp.exe process, recompile the assembly, and then resume the debugging process.

Conclusion

Web Parts for Windows SharePoint Services are ASP.NET server controls. Therefore, the process for debugging Web Parts is similar to the process for debugging ASP.NET server controls.