This documentation is archived and is not being maintained.

Debugging in Document-Level Projects

Note Required applications

The features in this topic are available only if you have the required applications installed.

For more information, see Features Available by Product Combination.

  • One of these development environments:

    VSTO 2005


    Visual Studio Team System

  • Microsoft Office 2003

You can debug document-level projects for Microsoft Office Word 2003 and Microsoft Office Excel 2003 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 more information about document-level projects, see Office Solutions Architecture Overview.


Close any open instances of Word or Excel before you build and debug to avoid conflicts.

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 becoming corrupted. If this happens, you can delete the corrupted template and it will automatically be recreated the next time you open Word. However, any macros that were stored in the 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 a Process.

Word Locks While Open in Visual Studio

When Word is open in Visual Studio, it locks the default 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, such as modifying the toolbars or menus, you cannot save those changes because 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 and prevent application-level changes.

For more information, see the Knowledge Base article "PRB: Prompt to Save When Using Word as an Automation Server" (;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.

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

Microsoft Visual Studio 2005 Tools for the Microsoft Office System 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" (;en-us;310519).

See Also