Debugging Office Projects
You can debug Office projects by using the same Microsoft Visual Studio tools you use for other Visual Studio projects. Visual Studio debugger features, such as the ability to insert breakpoints and view variables in the Locals window, are also available when you debug Office projects. For more information about Visual Studio debugging tools, see Debugging in Visual Studio.
Tip
To simplify debugging, close any open instances of the Office application before you build and debug it.
Applies to: The information in this topic applies to document-level projects and application-level projects for Office 2013 and Office 2010. 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?.
Starting and Stopping the Debugger
You can start debugging an Office project just like you start debugging other Visual Studio projects; for example, you can press the F5 key. When you start debugging an application-level add-in project, a new process for the targeted Office application is started and the add-in is loaded. When you start debugging a document-level project, the document or workbook opens in a new Word or Excel process.
When you stop the debugger, the debugger terminates the application process abruptly, or detaches if you have the debugger set to detach. All other documents that are opened in the terminated Office application process 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 the Office application in the normal way. You can also detach from the process first if you still want to work with an open document or worksheet after stopping the debugger.
If you are debugging a document-level customization for Word, 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.
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.
Displaying Exceptions
Because of the way that managed code interacts with unmanaged code, Visual Studio does not display errors that are thrown by Microsoft Office applications. For example, if an add-in created by using Office development tools in Visual Studio throws an exception, the Microsoft Office application continues without displaying an error. To see these errors, set the debugger to break on common language runtime exceptions. For more information, see How to: Break When an Exception is Thrown.
If you set the debugger to break on common language runtime exceptions, all exceptions will now break into the debugger, including ones that you have handled and some first-chance exceptions from the runtime itself, which might not be relevant to your project. Errors referring to msosec not being found appear in every project, but are safe to ignore. These msosec exceptions will not affect your solution.
You can also use Try...Catch statements around your methods to catch exceptions.
By default, Visual Studio also does not display Just-In-Time debugging errors for Office projects; however, you can enable this feature so that you can see the errors that are raised. For more information, see Just-In-Time Debugging in Visual Studio.
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.
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.
Debugging Cached Datasets in a Document-Level Project
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..
Debugging Disabled Add-ins
Microsoft Office applications can disable add-ins that behave unexpectedly. A Microsoft Office application disables add-ins to prevent problematic code from loading every time that the application starts. However, it is also easy to cause unexpected behavior during typical debugging. For information about how to re-enable add-ins, see How to: Re-enable an Add-in That Has Been Disabled.
There are two types of disabling that Microsoft Office applications use for add-ins: hard disabling and soft disabling.
Hard Disabling
Hard disabling can occur when an add-in causes the application to close unexpectedly. It might also occur on your development computer if you stop the debugger while the Startup event handler in your add-in is executing. When an add-in is hard disabled, it appears in the Disabled Items list in the application.
If an Office application hard disables an add-in created by using Office development tools in Visual Studio, the application disables only the add-in that caused the failure. Other add-ins created by using Office development tools in Visual Studio for that Office application will continue to load.
Soft Disabling
Soft disabling can occur when an add-in produces an error that does not cause the application to unexpectedly close. For example, an application might soft disable an add-in if it throws an unhandled exception while the Startup event handler is executing. When an add-in is soft disabled, it appears in the Inactive Application Add-ins list in the application, and the application changes the value of the LoadBehavior registry entry for the add-in to indicate that it is unloaded. For more information about the LoadBehavior registry entry, see Registry Entries for Application-Level Add-Ins.
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.
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 deployment manifest for the add-in, or in the folder that contains the document or workbook that is associated with the customization. If that fails, the Visual Studio Tools for Office runtime creates the log file in the local %TEMP% folder. For application-level add-ins, the default name is add-in name.vsto.log. For document-level projects, 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: Re-enable an Add-in That Has Been Disabled