Debugging in Application-Level Projects
Important This document may not represent best practices for current development, links to downloads and other resources may no longer be valid. Current recommended version can be found here. ArchiveDisclaimer

Debugging in Application-Level Projects

You can debug application-level 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 debugging application-level projects. For more information about Visual Studio debugging tools, see Debugging in Visual Studio. For more information about application-level projects, see Office Solutions Architecture Overview.

Starting and Stopping the Debugger

You can start debugging an application-level project in the same way that you start debugging other Visual Studio projects; for example, you can press the F5 key. When you start debugging your project, a new process for the targeted Office application is started and the add-in is loaded. When you stop the debugger, the debugger terminates the application process abruptly, or detaches if you have the debugger set to detach.

When you start debugging an application-level project, the F10 and F11 keys 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 a breakpoint or an exception in code. In application-level projects, Visual Studio does not have control over the Office application's main function. However, after debugging is in progress, F10 and F11 have the same functions as in Visual Basic and C# projects. For more information, see Debugging Shortcut Keys, Brief Scheme.

Displaying Exceptions

If an add-in created with Visual Studio Tools for Office throws an exception, the Microsoft Office application continues without displaying the exception. Set the debugger to break on all exceptions if you want to see when add-in exceptions are thrown. For more information, see How to: Handle Errors in Office Projects.

You can also insert Try...Catch statements around code that might throw an exception. For more information about using Try...Catch statements, see How to: Test Code with a Try…Catch Block in Visual Basic and How to: Handle an exception using Try/Catch (C# Programmers Reference).

Debugging Disabled Add-ins

Microsoft Office applications can disable add-ins that behave unexpectedly while they are being loaded. An Office application disables add-ins to prevent problematic code from loading every time the application starts. However, it is also easy to cause unexpected behavior during normal debugging. For information about enabling add-ins, see How to: Re-enable an Application-Level Add-in That Has Been Disabled.

There are two types of disabling that Office applications use for add-ins: hard disabling and soft disabling.

Hard Disabling

Hard disabling occurs when code that runs while the add-in is loaded causes the application to close unexpectedly, or when you stop the debugger while the constructor or the Startup event handler is executing. If a Microsoft Office 2003 application hard disables an add-in created by using Visual Studio Tools for Office, the application disables both the add-in and AddinLoader.dll. AddinLoader.dll is used to load add-ins created by using Visual Studio Tools for Office. As a result, all add-ins created by using Visual Studio Tools for Office for that Office 2003 application are prevented from loading for the current user.

If a Microsoft Office 2007 application hard disables an add-in created by using Visual Studio Tools for Office, the application disables only the add-in that caused the failure. The application does not disable AddinLoader.dll. As a result, other add-ins created by using Visual Studio Tools for Office for that Office 2007 application will continue to load.

Soft Disabling

Soft disabling occurs when an add-in throws an unhandled exception in the constructor or the Startup event handler and the Microsoft Office application does not unexpectedly close. The Office application might disable only the current add-in from loading for the current user. When an Office application soft disables an add-in, it sets the value of the LoadBehavior registry entry for the add-in to 2. The LoadBehavior entry is located under the following registry key: HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\<application name>\Addins\<add-in name>

Troubleshooting Add-ins Using a Log File and Error Messages

Visual Studio Tools for Office 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 for application-level projects. You can turn the options on by adding and setting environment variables. To display each error in a message box, set the VSTO_SUPPRESSDISPLAYALERTS variable to 0 (zero). You can suppress the messages by setting the variable to 1 (one). To write the errors to a log file, set the VSTO_LOGALERTS variable to 1 (one). Visual Studio Tools for Office creates the log file in the folder that contains the application manifest. The default name is <Manifestname>.manifest.log. To stop logging errors, 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

© 2016 Microsoft