Debugging in Document-Level Projects
You can debug document-level projects for Microsoft Office Word and Microsoft Office Excel using the same Visual Studio tools you use for other projects. When you run the project in Debug mode, Visual Studio starts Word or Excel, and the debugger attaches to everything that is running in the same process with Word or Excel. For more information about Visual Studio debugging tools, see Debugging in Visual Studio.
Tip
Close any open instances of Word or Excel before you build and debug to avoid conflicts.
Applies to: The information in this topic applies to document-level projects for the following applications: Excel 2007 and Excel 2010; Word 2007 and Word 2010. For more information, see Features Available by Office Application and Project Type.
.gif "link to video")
For a related video demonstration, see How Do I: Debug a VSTO Application?.
F10 and F11 Behavior
When you start debugging an Office project, F10 and F11 do not have the same behavior as when you start debugging other Visual Basic or C# projects. In Visual Basic or C# projects, the debugger stops on the main function; in Office projects, Visual Studio does not have control over the Office application's main function. However, during debugging, F10 and F11 do have the same functions as in Visual Basic and C# projects. For more information, see Debugging Shortcut Keys, Brief Scheme.
Stopping the Debugger
When you start debugging a document or workbook, the document or workbook opens in a new Word or Excel process. When you stop the debugger, the debugger terminates the Word or Excel process abruptly, or detaches if you have the debugger set to detach. All other documents or workbooks that are opened in a Word or Excel process that is terminated are also closed without warning, and any unsaved changes are lost. This might include all documents or workbooks that are opened while the debugger is running.
Typically, it is better to detach from the process before stopping the debugger, so that you can quit Word and Excel in the normal way. You can also detach from the process first if you still work in an open document or worksheet after stopping the debugger. For more information about detaching from the process, see How to: Detach All Processes.
During sessions of heavy debugging, repeatedly stopping the debugger and causing Word to close suddenly can lead to the Normal template becoming corrupted. If this happens, you can delete the corrupted Normal template and it will automatically be recreated the next time you open Word. However, any macros that were stored in the Normal template are not recreated.
Word Locks the Normal Template While Open in Visual Studio
When Word is open in Visual Studio, it locks the default Normal template. When you run your solution for debugging, a copy of Word is opened in another process. If you make application-level customizations to the open copy of Word, you cannot save those changes because the Normal template is locked by the process that is open inside Visual Studio.
At run time, Word opens separate instances of documents in a single process, so it is not as likely that one open document will lock the Normal template and prevent application-level changes.
For more information, see the Knowledge Base article "PRB: Prompt to Save Normal.dot When Using Word as an Automation Server" (https://support.microsoft.com/default.aspx?scid=kb;en-us;285885).
Debugging Cached Datasets
Every time you build a project, the dataset is emptied and recreated. If you want to debug a cached dataset, you must open the document outside of Visual Studio and then attach the debugger.
Debugging Word Document Projects Based on the Word 97-2003 Document (*.doc) Format
To debug a Word Document project based on Word 97-2003 Document (*.doc) format, you must add the project folder to the trusted folder list. For more information on how to do this, see Granting Trust to Documents.
Source Control
Debug properties are not shared among multiple users under source control. Visual Basic and C# projects store the debugging properties in a user-specific file (<ProjectName>.vbproj.user or <ProjectName>.csproj.user), and this file is not under source control. If more than one person is debugging, each person must enter debug properties manually.
Command Line Arguments
If the Start Action on the Debug property page is set to Start Project, Visual Studio does not use command line arguments when debugging the project, even if you have specified command line arguments as start options. If you want to use command line arguments when you start debugging, you must select a Start Action other than Start Project.
Troubleshooting Installation Errors by Using the Event Viewer
The Visual Studio Tools for Office runtime writes messages to the Event Viewer in Windows for all exceptions that are thrown when you install or uninstall Office solutions. You can use these messages to resolve installation and deployment problems. For more information, see Event Logging for Office Solutions.
Troubleshooting Startup Errors by Using a Log File and Error Messages
The Visual Studio Tools for Office runtime can write all errors that occur during startup to a log file or display each error in a message box. By default, these options are turned off. You can turn the options on by creating environment variables.
To display each error in a message box, create an environment variable named VSTO_SUPPRESSDISPLAYALERTS and set it to 0 (zero). You can suppress the messages by deleting the environment variable or setting it to 1 (one).
To write the errors to a log file, create an environment variable named VSTO_LOGALERTS and set it to 1 (one). The Visual Studio Tools for Office runtime creates the log file in the folder that contains the document or workbook that is associated with the customization, or, if that fails, in the local %TEMP% folder. The name of the log file is document name.extension.log, such as ExcelWorkbook1.xlsx.log. To stop logging errors, delete the environment variable or set it to 0 (zero).
See Also
Tasks
How to: Handle Errors in Office Projects
Concepts
Office Solution Build Process Overview