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.

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 then 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. It is better to detach from the process before stopping the debugger, so that you can quit Word and Excel in the normal way.

During sessions of heavy debugging, repeatedly stopping the debugger and causing Word to close suddenly can lead to Normal.dot becoming corrupted. If this happens, you can delete the corrupted Normal.dot template and it will automatically be recreated the next time you open Word. However, any macros that were stored in the Normal.dot template are not recreated.

If you want to stop the debugger and still work in an open document or worksheet, first detach the debugger from the process, and then stop the debugger. For more information, see How to: Detach All Processes.

Word Locks Normal.dot While Open in Visual Studio

When Word is open in Visual Studio, it locks the default template Normal.dot. 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, such as modifying the toolbars or menus, you cannot save those changes because Normal.dot 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 Normal.dot 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 2007 Projects Based on the Word 97-2003 Document (*.doc) Format

To debug a Word 2007 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 (2007 System).

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 Using a Log File and Error Messages

Visual Studio Tools for Office can write all errors to a log file. By default, this option is turned off for Word and Excel projects. You can turn this option on by adding the environment variable VSTO_LOGALERTS and setting the value to 1 (one). Visual Studio Tools for Office creates the log file in the output folder where the solution document is created, or, if that fails, in the %TEMP% folder. The default name of the log file is <Documentname>.doc.log for Word and <Documentname>.xls.log for Excel. You can stop logging errors by setting the variable to 0 (zero).

Visual Studio Tools for Office displays each error in a message box by default for Word and Excel projects. You can make Visual Studio Tools for Office stop displaying error messages by adding the environment variable VSTO_SUPPRESSDISPLAYALERTS and setting the value to 1 (one). To display error messages, set the variable to 0 (zero).

For information about setting environment variables in Microsoft Windows XP, see "How To Manage Environment Variables in Windows XP" (https://support.microsoft.com/default.aspx?scid=kb;en-us;310519).

See Also

Tasks

How to: Handle Errors in Office Projects

Concepts

Deploying Office Solutions (2003 System)

Deploying Office Solutions (2007 System)

Creating Office Solutions in Visual Studio

Office Solution Build Process Overview

Other Resources

Debugging in Visual Studio

Building and Debugging Office Solutions