Debugging in Application-Level Projects
Applies to |
|---|
The information in this topic applies only to the specified Visual Studio Tools for Office projects and versions of Microsoft Office. Project type
Microsoft Office version
For more information, see Features Available by Application and Project Type. |
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 you debug application-level projects. For more information about Visual Studio debugging tools, see Debugging in Visual Studio. For more information about application-level projects, see Architecture of Application-Level Add-Ins.
.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 application-level project just like 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. For more information, see Debugging Shortcut Keys, Brief Scheme.
Displaying Exceptions
If an add-in created by using 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 how to use 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# Programming Guide).
Debugging Disabled Add-ins
Microsoft Office applications can disable add-ins that behave unexpectedly when they are being loaded. 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 occurs when code that runs when 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 Microsoft Office application are prevented from loading for the current user. For more information about AddinLoader.dll, see Architecture of Application-Level Add-Ins.
If a 2007 Microsoft Office system 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. 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 application might disable only the current add-in from loading for the current user. When an 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>. For more information about this registry key, see Registry Entries for Application-Level Add-Ins.
Troubleshooting Add-ins 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 application manifest. The default name is <Manifestname>.manifest.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
How to: Handle Errors in Office Projects
Concepts
Programming Application-Level Add-Ins