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. For more information about application-level projects, see .
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.
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.
You can also insert Try...Catch statements around code that might throw an exception. For more information about using Try...Catch statements, seeand .
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.
There are two types of disabling that Office applications use for add-ins: hard disabling and soft 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 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" (http://support.microsoft.com/default.aspx?scid=kb;en-us;310519).