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: Creating a Custom Action Project Item with an Item Template, Part 1
Walkthrough: Creating a Custom Deployment Step for SharePoint Projects
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
Close all instances of Visual Studio.
In the build output folder for the extension project, double-click the .vsix file.
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.
After Visual Studio installs the extension, click Close.
To debug the extension
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.
Start another instance of Visual Studio with administrator privileges. The following steps refer to this instance of Visual Studio as the second instance.
Switch to the first instance of Visual Studio.
On the Debug menu, click Attach to Process.
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.
Click Attach.
Visual Studio runs the extension project in debug mode.
Switch to the second instance of Visual Studio.
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.
Perform whatever steps are required to test your extension code.
When you are finished debugging the extension, close the second instance of Visual Studio.
To remove the extension
In Visual Studio, on the Tools menu, click Extension Manager.
The Extension Manager dialog box opens.
In the list of extensions, click the name of the extension, and then click Uninstall.
In the dialog box that appears, click Yes to confirm that you want to uninstall the extension.
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
Start debugging your extension in the experimental instance of Visual Studio or the regular instance of Visual Studio by following the instructions above.
In the instance of Visual Studio in which you are running the debugger, on the Debug menu, click Attach to Process.
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.
Click Attach.
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.
Value |
Description |
|---|---|
EnableDiagnostics |
REG_DWORD that specifies whether diagnostic messages are displayed in the Output window. To display diagnostic messages, set this value to 1. To stop displaying messages, set this value to 0 or delete this value. To write messages to the Output window from a SharePoint tools extension, use the SharePoint project service. For more information, see Using the SharePoint Project Service. |
If your extension includes a SharePoint command, you can set additional values to help troubleshoot the command. The following table describes these values.
Value |
Description |
|---|---|
AttachDebuggerToHostProcess |
REG_DWORD that specifies whether to display a dialog box that enables you to attach the debugger to vssphost4.exe as soon as it starts. This is useful if the command that you want to debug is executed by vssphost.exe immediately after it starts, and there is not enough time to manually attach the debugger before the command is executed. To display the dialog box, vssphost4.exe calls the Debugger.Break method when it starts. To enable this behavior, set this value to 1. To turn off this behavior, set this value to 0 or delete this value. If you set this value to 1, you may also want to increase the HostProcessStartupTimeout value to give yourself enough time to attach the debugger before Visual Studio expects vssphost4.exe to signal that it started successfully. |
ChannelOperationTimeout |
REG_DWORD that specifies the time, in seconds, that Visual Studio waits for a SharePoint command to execute. If the command does not execute in time, a SharePointConnectionException is thrown. The default is 120 seconds. |
HostProcessStartupTimeout |
REG_DWORD that specifies the time, in seconds, that Visual Studio waits for vssphost4.exe to signal that it started successfully. If vssphost4.exe does not signal a successful start in time, a SharePointConnectionException is thrown. The default is 60 seconds. |
MaxReceivedMessageSize |
REG_DWORD that specifies the maximum allowed size, in bytes, of WCF messages that are passed between Visual Studio and vssphost4.exe. The default is 1,048,576 bytes (1 MB). |
MaxStringContentLength |
REG_DWORD that specifies the maximum allowed size, in bytes, of strings that are passed between Visual Studio and vssphost4.exe. The default is 1,048,576 bytes (1 MB). |
See Also
Concepts
Deploying Extensions for the SharePoint Tools in Visual Studio