Logo
HOWTO: Troubleshooting Visual Studio and Office add-ins

Author: Carlos J. Quintero (Microsoft MVP) Applies to: Microsoft Visual Studio .NET 2002
Date: February 2007   Microsoft Visual Studio .NET 2003
Updated: January 2014   Microsoft Visual Studio 2005
      Microsoft Visual Studio 2008
      Microsoft Visual Studio 2010
      Microsoft Visual Studio 2012
      Microsoft Visual Studio 2013
      Office applications
Introduction

This article provides information to troubleshoot common problems of add-ins for Visual Studio or Office applications (shared add-ins).

More Information

These are common problems that can happen on the machine of the developer or on the machine of the final user, in this order:

1. The add-in is not registered for the host application

The host application can be Visual Studio or some Office application, depending on the target of the add-in. The first thing to check when an add-in does not work is that the add-in is registered for the host application.

There are two scopes of registration:

  • For all users (machine level)
  • For the user who installed the add-in (user level)

When you run the wizard to create the initial code of the add-in, you are asked the scope of the registration, for example with a checkbox with the phrase "My add-in should be available to all users of the computer it was installed on, not just the person who install its". It is recommended that you register the add-in for all users (machine level) because in many organizations the person installing the add-in is an administrator, different to the person who is going to use the add-in. 

There are two mechanisms of registration:

  • COM registration (any Visual Studio version and Office applications):
    • The DLL must be registered as an ActiveX (COM) component.
    • The add-in must be registered for the host application using a registry entry in the hive HKEY_LOCAL_MACHINE (for all users) or HKEY_CURRENT_USER (current user). For example:

      For Microsoft Frontpage, user who installed the add-in:
      HKEY_CURRENT_USER\Software\Microsoft\Office\FrontPage\Addins\MyAddIn.Connect

      For Microsoft Visual Studio .NET 2003, all users:
      HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\7.1\Addins\MyAddIn.Connect

      Where MyAddIn.Connect is the ProgId of the Connect class of the add-in. The host application locates registered add-ins checking its "AddIns" registry entries (in both HKEY_LOCAL_MACHINE and HKEY_CURRENT_USER hives), getting the ProgIds, going to the HKEY_CLASSES_ROOT to locate the ProgID, getting its CLSID (such as {449E0007-4AB0-4C95-9FE1-EB442BB24FDF}) and going to HKEY_CLASSES_ROOT\CLSID\<clsid>\InprocServer32 to retrieve the path to the physical dll of the add-in.
  • XML registration (Visual Studio 2005 and higher):
    • A XML file with the extension .AddIn must be placed in one of the folders listed in the "Tools", "Options" window, "Environment", "Add-In/Macros Security" section. Some of the folders are for all users (such as %ALLUSERSPROFILE%\Application Data\Microsoft\MSEnvShared\AddIns) while others are only for the current user (such as "%VSMYDOCUMENTS%\AddIns, where %VSMYDOCUMENTS% refers to the folder "Visual Studio 2005\Addins" inside the Documents folder of the user). See: INFO: Default .AddIn file locations for Visual Studio add-ins.
    • The XML file has an <Assembly> tag whose value is the location of the assembly of the add-in. Your setup must set this value after the user has selected an installation folder.

For Visual Studio add-ins, you can check if the add-in is registered through the Add-In Manager ("Tools", "Add-In Manager"), which shows all registered add-ins (COM or XML, for all users or for the current user).

For Office applications, the Add-In Manager for COM add-ins varies from application to application (notice that Office applications offer COM-addins and add-ins that are not COM-based):

  • For Microsoft Frontpage 2003, go to the "Tools", "Add-ins" menu.
  • For Microsoft Word 2003, go to the "Tools", "COM Add-ins" menu.
  • For Microsoft Outlook 2003, go to the "Tools", "Options" window, "Other" tab, "Advanced Options" button, "COM Add-Ins" button.
  • For Microsoft Excel 2003, follow the instructions of the link above.

So, if your add-in does not appear in the Add-In Manager of the host application the cause could be:

  • It is an add-in registered only for the user who installs it (rather than an add-in registered for all users) and the person installing it is not the same than the person using it.
  • It is a COM add-in and the setup did not register it as a COM component. Notice that on the development machine, the add-in wizard registers the add-in for COM, but on the deployment machine your setup must do it.
  • It is a COM add-in but it is not registered for the host application. Notice that on the development machine, the add-in wizard creates these entries, but on the deployment machine your setup must do it.
  • It is a XML-based Visual Studio 2005 or higher add-in but the XML file is not in one of the folders where Visual Studio locates add-ins (which are listed in the "Tools", "Options" window, "Environment" section, "Macros/Add-Ins Security). Notice that on the development machine, the add-in wizard creates that file, but on the deployment machine your setup must do it.
  • It is a XML-based Visual Studio 2005 or higher add-in but the <assembly> tag of XML file does not specify the correct location of the assembly Dll.
  • It is a XML-based Visual Studio 2005 or higher add-in but the <HostApplication>\<Version> tag does not match the actual version of the IDE (8.0 for Visual Studio 2005, 9.0 for Visual Studio 2008, etc.).
  • It is a COM add-in for Office registered for all users (machine level). Office does not show COM add-ins registered for all users in the COM Add-In Manager. See: PRB: Visual Studio .NET Shared Add-in Is Not Displayed in Office COM Add-ins Dialog Box. This is not an error, then.
  • It is a COM add-in for Office and you used Visual Studio 2005 to create it. See: FIX: Add-ins, smart documents, or smart tags that you create by using Microsoft Visual Studio 2005 do not run in Office.
  • The add-in crashed when the host application tried to load it, it prompted you to remove it from the list of available add-ins and you accepted. In this case the add-in is no longer registered for the host application, you must reinstall it (Visual Studio add-ins) or go to the About window, "Disabled Items" button to re-enable it (Office add-ins).
  • It is an add-in for Visual Studio 2008 and the .AddIn file for XML registration is put in the folder %ALLUSERSDOCUMENTS%\Microsoft\MSEnvShared\AddIns (introduced by Visual Studio 2008, it didn't exist in Visual Studio 2005), which, due to a bug, is not searched by Visual Studio 2008. See: INFO: Default .AddIn file locations for Visual Studio add-ins.
  • There is a reported problem that happens when MSXML 6.0 is not installed correctly. In this case the Add-In Manager doesn't show any XML-based add-in (using an .AddIn file for registration). It shows only registry-based add-ins. So, if the Add-In Manager is empty when it should show several installed add-ins (not only yours), try reinstalling MSXML 6.0.

You can use monitoring tools to spy what registry entries or folders the application host uses when it shows the Add-In Manager. See the article HOWTO: Using the Process Monitor (ProcMon) tool to diagnose Visual Studio add-ins problems

2. The add-in crashes when loaded (Visual Studio shows a message box with an exception caused by the add-in giving the chance of removing it)

The sequence of steps until a managed (.NET) add-in is loaded and the code of the add-in is executed is the following:

  • Visual Studio reads registration information (Registry-based registration or XML-based registration) to locate the add-in DLL.
  • Visual Studio creates an AppDomain (or uses one already created) for managed add-ins.
  • The .NET Common Language Runtime (CLR) performs some verifications (verify, versioning, security, strong name, etc.) with the add-in assembly.
  • The .NET CLR loads the addin assembly into the AppDomain.
  • Visual Studio gets the type of the class specified in the registration information (typically the Connect class), which must implement the IDTExtensibility2 interface and optionally the IDTCommandTarget interface.
  • Given some circumstances (not always), Visual Studio creates an instance of such type and:
    • Calls the OnConnection method with the connectMode parameter set to the ext_ConnectMode.ext_cm_UISetup value.
    • Calls the OnDisconnection method with the ext_DisconnectMode.ext_dm_UISetupComplete value.
    • Destroys the instance (it is not reused for the next step).

    This step is intended to give the add-in the chance of a one-time initialization of commands and permanent user interface (see HOWTO: Use correctly the OnConnection method of a Visual Studio add-in).
  • Visual Studio creates an instance of such type and:
    • Calls the OnConnection method with the connectMode parameter set to some of these values, depending on the case:
      • ext_ConnectMode.ext_cm_Startup
      • ext_ConnectMode.ext_cm_AfterStartup
      • ext_ConnectMode.ext_cm_CommandLine

So, the exception can be caused:

  • In the code of the add-in (once the add-in DLL was located and loaded successfully by Visual Studio):
    • In the constructor of the Connect class, if it has code (normally it's empty).
    • In the entry points of the Connect class:
      • In the implemented methods of the IDTExtensibility2 interface: OnConnection, OnDisconnection, etc.
      • In the implemented methods of the IDTCommandTarget interface: QueryStatus, Exec.

    Ensure that you use exception handlers (try/catch blocks) in every method of the Connect class and show the full stack trace to locate the offending code, because Visual Studio only shows the exception name and description.

    In some cases the code of an add-in can crash Visual Studio forcing it to close or restart (without showing the exception text or error number that caused the problem). This is usually caused by internal bugs of Visual Studio, the add-in just triggers the problem. For example, an add-in creating or manipulating commandbars can crash Visual Studio 2008 Development Edition or Team Suite if the "Code Analisys Tools" component was not selected in the custom setup when installing the product.

  • Outside of the code of the add-in (before the add-in DLL is even loaded):
    • When Visual Studio tries to locate the add-in DLL with the name and path specified in the registration. For example:
      • The DLL doesn't exist (it was deleted, or never built).
      • The DLL exists, but its name doesn't match the name used in the registration.
      • The DLL exists, but its path doesn't match the path used in the registration.

      In these cases you get:
      • If the file pointed by the COM registration (InProcServer32 value) can not be found:
        • "The system cannot find the file specified" (Error Number 80070002)
      • If the file pointed by the XML registration (<Assembly> tag of .AddIn file) can not be found:
        • "The system cannot find the file specified" (Error Number 80070002) if the value of the <Assembly> tag contains a path.
        • "Unspecified error" (Error Number 80004005) if the value of the <Assembly> tag doesn't contain a path (it contains just the name of the add-in DLL).
    • When the CLR tries to load the add-in assembly (see the article INFO: CLR HRESULT errors loading add-ins).
      • The .NET assembly is corrupt, has a wrong version, can not be verified, is not correctly signed (strong name), is not secure, doesn't have FullTrust, etc. You can use the tools of the .NET Framework SDK such as sn.exe, peverify.exe, etc. to validate the assembly. In these cases you will get a strange COM error number such as for example:
        • 8013141A (CORSEC_E_INVALID_STRONGNAME): this one is related to strong name validation failed.
        • 8013150A (COR_E_SECURITY): this one is related to lack of FullTrust permission, such as when executing the add-in from a network shared location rather than from hard disk.
        • 8013101B (COR_E_NEWER_RUNTIME): this one happens when the add-in is compiled with a CLR not supported by the Visual Studio version where it is loaded. For example, if you compile the add-in with Visual Studio 2010 using CLR 4.0 and you try to load it in Visual Studio 2005/2008 (both only support CLR 2.0).
      • The add-in references a DLL that can not be found. In this case you get also "The system cannot find the file specified" (Error Number 80070002).
      • Some assembly referenced by the add-in has one the problems described above and the CLR can not load it. You can try removing references not provided by the .NET Framework to diagnose this case.
    • When Visual Studio tries to locate the type of the connect class.
      • The namespace and/or class name of the connect class specified in the XML registration / COM registration doesn't match the actually one declared in the source code. In this case you get <Unknown Error> Error Number 80131522 (which is COR_E_TYPELOAD).
      • The Connect class is not COM-visible (this is required even for add-ins using XML-based registration). In this case you get "No such interface supported" (Error Number 80004002). Ensure that Connect class is Public and that you have the ComVisible(True) applied at assembly level, or at least at class level (to the Connect class).

3. The add-in is loaded, but commands, buttons or toolbars are not created

If the add-in is for Visual Studio, see this article:

HOWTO: Adding buttons, commandbars and toolbars to Visual Studio .NET from an add-in

4. The commands are created, but they disappear on the next session

If the add-in is for Visual Studio, see this article:

INFO: Visual Studio .NET Add-In Commands Disappear On Next Session.

5. The commands and buttons are created, but they appear disabled

Ensure that your add-in implements the IDTCommandTarget interface and its QueryStatus method. You must return vsCommandStatus.vsCommandStatusSupported + vsCommandStatus.vsCommandStatusEnabled for your commands. See this article:

HOWTO: Adding buttons, commandbars and toolbars to Visual Studio .NET from an add-in

6. The commands and buttons are created, but clicking on them do nothing

Ensure that your add-in implements the IDTCommandTarget interface and its Exec method. See this article:

HOWTO: Adding buttons, commandbars and toolbars to Visual Studio .NET from an add-in

7. The event handlers of the add-in stop working after a while

If you are using C#, see this article:

PRB: Visual Studio .NET events being disconnected from add-in.

 



Go to the 'Visual Studio Extensibility (VSX)' web site for more articles like this (Articles section)


Top