Debugging Extensions for the SharePoint Tools in Visual Studio

You can debug SharePoint tools extensions in the experimental instance or the regular instance of Visual Studio. If you need to troubleshoot the behavior of an extension, you can also modify registry values to display additional error information and to configure how Visual Studio executes SharePoint commands.

Debugging Extensions in the Experimental Instance of Visual Studio

To safeguard your Visual Studio development environment from accidental corruption by untested extensions, the Visual Studio SDK provides an alternative Visual Studio instance, called the experimental instance, that you can use to install and test extensions. You develop new extensions by using the regular instance of Visual Studio, but you debug and run them in the experimental instance. For more information, see Experimental Instance of Visual Studio.

If you use a VSIX project to deploy your extension, and the VSIX project is the startup project in your solution, Visual Studio automatically installs and runs the extension in the experimental instance when you debug your solution. The startup project is the project that starts when you debug a solution that contains multiple projects. For more information about using a VSIX project to deploy your extension, see Deploying Extensions for the SharePoint Tools in Visual Studio. For more information about startup projects, see How to: Choose the Startup Project.

For examples that demonstrate how to debug various types of extensions in the experimental instance of Visual Studio, see the following walkthroughs:

• Walkthrough: Extending a SharePoint Project Item Type

• Walkthrough: Creating a Custom Action Project Item with an Item Template, Part 1

• Walkthrough: Creating a Custom Deployment Step for SharePoint Projects

• Walkthrough: Extending Server Explorer to Display Web Parts

• Walkthrough: Calling into the SharePoint Client Object Model in a Server Explorer Extension

Debugging Extensions in the Regular Instance of Visual Studio

If you want to debug your extension project in the regular instance of Visual Studio, first install the extension in the regular instance. Then, attach the debugger to a second Visual Studio process. After you are finished, you can remove the extension so that it no longer loads on the development computer.

To install the extension

1. Close all instances of Visual Studio.

2. In the build output folder for the extension project, double-click the .vsix file.

3. In the Visual Studio Extension Installer dialog box, select the edition of Visual Studio that you want to install the extension to, and then click Install.

   Visual Studio installs the extension files to %UserProfile%\AppData\Local\Microsoft\VisualStudio\10.0\Extensions\author name\extension name\version. The last three folders in this path are constructed from the Author, Name, and Version elements in the extension.vsixmanifest file for the extension.

4. After Visual Studio installs the extension, click Close.

To debug the extension

1. Start Visual Studio with administrator privileges and open the extension project. The following steps refer to this instance of Visual Studio as the first instance.

2. Start another instance of Visual Studio with administrator privileges. The following steps refer to this instance of Visual Studio as the second instance.

3. Switch to the first instance of Visual Studio.

4. On the Debug menu, click Attach to Process.

5. In the Available Processes list, click devenv.exe. This entry refers to the second instance of Visual Studio; this is the instance you want to debug your project extension in.

6. Click Attach.

   Visual Studio runs the extension project in debug mode.

7. Switch to the second instance of Visual Studio.

8. Create a new SharePoint project that loads your extension. For example, if you are debugging an extension for list definition project items, create a List Definition project.

9. Perform whatever steps are required to test your extension code.

10. When you are finished debugging the extension, close the second instance of Visual Studio.

To remove the extension

1. In Visual Studio, on the Tools menu, click Extension Manager.

   The Extension Manager dialog box opens.

2. In the list of extensions, click the name of the extension, and then click Uninstall.

3. In the dialog box that appears, click Yes to confirm that you want to uninstall the extension.

4. Click Restart Now to complete the uninstallation.

Debugging SharePoint Commands

If you want to debug a SharePoint command that is part of a SharePoint tools extension, you must attach the debugger to the vssphost4.exe process. This is the 64-bit host process that executes SharePoint commands. For more information about SharePoint commands and vssphost4.exe, see Calling into the SharePoint Object Models.

To attach the debugger to the vssphost4.exe process

1. Start debugging your extension in the experimental instance of Visual Studio or the regular instance of Visual Studio by following the instructions above.

2. In the instance of Visual Studio in which you are running the debugger, on the Debug menu, click Attach to Process.

3. In the Available Processes list, click vssphost.exe.

   Note

   If vssphost.exe does not appear in the list, you must start the vssphost4.exe process in the instance of Visual Studio in which you are running the extension. Typically, you do this by performing an action that causes Visual Studio to connect to the SharePoint site on the development computer. For example, Visual Studio starts vssphost4.exe when you expand a site connection node (a node that displays a site URL) under the SharePoint Connections node in the Server Explorer window, or when you add certain SharePoint project items, such as List Instance or Event Receiver items, to a SharePoint project.

4. Click Attach.

5. In the instance of Visual Studio that is being debugged, perform the steps that are required to execute your command.

Modifying Registry Values to Help Debug SharePoint Tools Extensions

When you debug an extension of the SharePoint tools in Visual Studio, you can modify values in the registry to help you troubleshoot the extension. The values exist under the HKEY_CURRENT_USER\Software\Microsoft\VisualStudio\10.0\SharePointTools key. These values do not exist by default.

To help troubleshoot any extension of the SharePoint tools, you can set the EnableDiagnostics value. The following table describes this value.

If your extension includes a SharePoint command, you can set additional values to help troubleshoot the command. The following table describes these values.

See Also

Concepts

Deploying Extensions for the SharePoint Tools in Visual Studio

Other Resources

Extending the SharePoint Tools in Visual Studio