Share via


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 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.

Applies to: The information in this topic applies to application-level projects for Microsoft Office 2010 and the 2007 Microsoft Office system. For more information, see Features Available by Office Application and Project Type.

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 Office development tools in Visual Studio 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. 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. For more information, see Event Logging for Office Solutions.

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, if that fails, in the local %TEMP% folder. The default name is add-in name.vsto.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

Other Resources

Building and Debugging Office Solutions

Programming Application-Level Add-Ins