| Author: |
Carlos J. Quintero (Microsoft MVP) |
Applies to: |
Microsoft Visual Studio .NET 2002 |
| Date: |
February 2007 |
|
Microsoft Visual Studio .NET 2003 |
| Updated: |
March 2009 |
|
Microsoft Visual Studio 2005 |
| |
|
|
Microsoft Visual Studio 2008 |
| |
|
|
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 (Visual Studio .NET 2002, 2003, 2005 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 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 add-in but the XML file is not in
one of the folders where Visual Studio 2005 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 / 2008 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 / 2008 add-in but <HostApplication>\<Version> tag
does not match the actual version of the IDE (8.0 for Visual Studio 2005, 9.0
for Visual Studio 2008).
- 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. In this case
you get "The system cannot find the file specified" (Error Number 80070002) if
the file pointed by the COM registration (InProcServer32 value) or by the XML
registration (<Assembly> tag of .AddIn file) can not be found. 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.
- When the CLR tries to load the add-in assembly.
- 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: this one is related to strong name validation failed.
- 8013150A: 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.
- 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).
- 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 back to the 'Resources for Visual Studio .NET extensibility' section for more articles like this
You can code, design, locate code and document your apps much faster using VB.NET, C#, C++ or Visual J#:
