| Author: |
Carlos J. Quintero (Microsoft MVP) |
Applies to: |
Microsoft Visual Studio .NET 2002 |
| Date: |
February 2007 |
|
Microsoft Visual Studio .NET 2003 |
| |
|
|
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)
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:
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#:
