Add-in Express™
for Microsoft® Office and .netAdd-in Express Home > Add-in Express for Office and .NET > Online Guide > Tips and notes > COM add-in tips
COM add-in tips
On this page you will find some tips and tricks related to building Office add-ins in Visual Studio related to registering /unregistering the add-in,
getting help with COM objects, properties and methods, delays at add-in start-up etc.
Getting help with COM objects, properties and methods
To get assistance with host applications' objects, their properties, and methods as well as help info, use the Object Browser.
Go to the VBA environment (in the host application, choose menu Tools | Macro | Visual Basic Editor or just press {Alt+F11}),
press {F2}, select the host application in the topmost combo and/or specify a search string in the search combo. Select a
class /property /method and press {F1} to get the help topic that relates to the object.
An exception when registering /unregistering the add-in
When your add-in is registered and unregistered, Add-in Express creates an instance of the module. Because in this
situation the module isn't loaded by the host application, you can't use any Office-related classes. If the code isn't
prepared for this, it will break. If it breaks when you uninstall the add-in, you'll have to clean the registry either
manually or using a registry cleaner program.
The same applies to class-level initializers; they are executed even before the module constructor is run.
To initialize your add-in, you need to use the AddinInitialize event of the module. It fires when Office loads the add-in.
Note, however, that for Ribbon-enabled Office applications, the first event that the module fires is OnRibbonBeforeCreate.
The add-in doesn't work
If your Office COM add-in does not work, check out:
The add-in is not registered,
An assembly required by your add-in cannot be loaded,
An exception at add-in start-up, and
Your add-in has fallen to Disabled Items.
The add-in is not registered
If LoadBehavior is 2, this may be an indication of an unhandled exception at add-in startup. Check
Registry keys.
An assembly required by your add-in cannot be loaded
Possible reasons are:
- the assembly is missing in the installer
- the user starting the host application doesn't have permissions for the folder where the add-in was installed; say,
a per-machine add-in is installed to a user's Application Data folder and another user loads the add-in
- the PublicKeyToken of your add-in assembly doesn't correspond to the PublicKeyToken mentioned in the Add-in Express Loader Manifest.
See below.
How to find the PublicKeyToken of the add-in
You can find it in the setup project, which must be already built. Click on your add-in primary output in the setup project and, in the Properties window,
expand the KeyOutput property and see the PublicKeyToken property value.
An exception at add-in start-up
If an exception occurs in the constructor of the add-in module, or when module-level variables are initialized,
Office will interrupt the loading sequence and set LoadBehavior of your add-in to 2. See
Registry keys.
Your add-in has fallen to Disabled Items
If your add-in fires exceptions at startup or causes the host application to crash, the host application (or the end-user)
may block the add-in and move it to the Disabled Items list. To find the list, in Office 2000-2003, go to "Help", then "About".
At the bottom of the About dialog, there is the Disabled Items button. Check it to see if the add-in is listed there (if so,
select it and click Enable). In the Ribbon UI of Office 2007, you find that list on the Add-ins tab of the Office Menu |
{host application} Options dialog. In the Ribbon UI of Office 2010, the Add-ins tab can be found in the File | Options dialog.
After you get the Disabled Items dialog, you select the add-in and click Enable.
Delays at add-in start-up
If you use the WebViewPane layout of your Outlook forms, please check WebViewPane.
Try clearing the DLL cache, see Deploying add-ins - shadow copy.
Maybe you will be able to identify the source of the problem by turning off other COM add-ins and Smart Tags in the host application.
If your host application is Excel, turn off all Excel add-ins, too. You can also try turning off your antivirus software.
Also check Office 2003 Resource Kit.
COM Add-ins dialog
In Office 2010 you click File Tab | Options and, on the Add-ins tab, choose COM Add-ins in the Manage dropdown and click Go.
In version 2007 of Word, Excel, PowerPoint and Access you click the Office Menu button, then click {Office application} options and
choose the Add-ins tab. Now choose COM Add-ins in the Manage dropdown and click Go. In all other Office applications, you need to add
the COM Add-ins command to a toolbar or menu of your choice. To do so, follow the steps below:
- Open the host application (Outlook, Excel, Word, etc.).
- On the Tools menu, click Customize.
- Click the Commands tab.
- In the Categories list, click the Tools category.
- In the Commands list, click COM Add-Ins and drag it to a toolbar or menu of your choice.
In Office 2000-2003, the COM Add-ins dialog shows only add-ins registered in HKCU. In Office 2007-2010, HKLM-registered add-ins are
shown too. See also Registry keys.
What is ProgId?
ProgID - Program Identifier. This is a textual name that represents a server object. It consists of the project name and the class name,
like MyServer.MyClass. You find it in ProgIDAttribute of an ADX Module. For instance:
...
'Add-in Express Add-in Module
<GuidAttribute("43F48D82-7C6F-4705-96BB-03859E881E2C"), _
ProgIdAttribute("MyAddin1.AddinModule")> _
Public Class AddinModule
Inherits AddinExpress.MSO.ADXAddinModule
...
We found the definition of ProgID in The COM / DCOM Glossary. On that page, you can find
other COM-related terms and their definitions.
FolderPath Property is missing in Outlook 2000 and XP
The function returns the same value as the MAPIFolder.FolderPath property available in Outlook 2003 and higher.
Private Function GetFolderPath(ByVal folder As Outlook.MAPIFolder) _
As String
Dim path As String = ""
Dim toBeReleased As Boolean = False
Dim tempObj As Object = Nothing
While folder IsNot Nothing
path = "\" + folder.Name + path
Try
tempObj = folder.Parent
Catch
'permissions aren't set
tempObj = Nothing
Finally
If toBeReleased Then
Marshal.ReleaseComObject(folder)
Else
'the caller will release the folder passed
toBeReleased = True
End If
folder = Nothing
End Try
'The parent of a root folder is of the Outlook.Namespace type
If TypeOf tempObj Is Outlook.MAPIFolder Then
folder = CType(tempObj, Outlook.MAPIFolder)
End If
End While
If tempObj IsNot Nothing Then Marshal.ReleaseComObject(tempObj)
If path <> "" Then path = Mid$(path, 2)
Return path
End Function
Word add-ins, command bars, and normal.dot
Word saves changes in the UI to normal.dot: move a toolbar to some other location and its position will be saved to normal.dot when Word quits. The
same applies to add-ins: their command bars are saved to this file. See some typical support cases related to Word add-ins and normal.dot below.
- For reasons of their own, some organizations use read-only normal.dots. In this case, installing the add-in raises a warning, when Word tries to save
normal.dot and finds that it is read-only.
- The user can set the Prompt to Save Normal Template flag located on the Save tab in the Tools | Options menu and in this way decide whether to save
normal.dot or not. This may lead to a mess: some command bars and controls are saved while others are not.
- Other companies store lots of things in their normal.dot files making them too big in size; saving such files requires extra time.
- We have had scenarios in which normal.dot is moved or deleted after the add-in is installed; naturally, command bars disappear as well.
You may think that using temporary command bars in these cases is a way out, but this may not be your case, see
How command bars and their controls are created and removed? We know the only workaround:
don't use normal.dot in a way, which wasn't designed by Microsoft. Normal.dot is a per-user thing. Don't deprive the user of the ability to customize the Word UI.
Move all excessive things to other templates. Always insist on clearing the Prompt to Save Normal Template flag. If it is possible, of course...
Custom actions when your COM add-in is uninstalled
When the add-in is being unregistered, the BeforeUninstallControls and AfterUninstallControls events occur. You can use them for,
say, removing "hanging" command bars from Word or restoring any other state that should be restored when your add-in is uninstalled.
Visual styles in your forms
Just call System.Windows.Forms.Application.EnableVisualStyles() in your add-in module, say in the AddinInitialize event.
How to develop the modular architecture of your COM and XLL Add-in?
Let's suppose that your COM add-in should conditionally provide (or not provide) some feature: let's call it MyFeature. You could create
a class library project, add an ADXAddinAdditionalModule using the Add New Item dialog of your add-in project, and implement the feature.
Then you create a setup project that could, at your choice, either register the assembly using the vsdrpCOM option in the Register
parameter of the assembly, or create appropriate keys in HKCU. Note that the former way may require the administrative privileges for the user.
Now the class library can write the ProgID of the ADXAddinAdditionalModule into the app.config file of the add-in. When the add-in starts,
it can read the app.config, create an ADXAddinAdditionalModuleItem and add it to the Modules collection of the ADXAddinModule class. The best
place is the AddinInitialize event of the add-in module. For instance:
Friend WithEvents MyFeature As _
AddinExpress.MSO.ADXAddinAdditionalModuleItem
Private Sub AddinModule_AddinInitialize( _
ByVal sender As Object, ByVal e As System.EventArgs) _
Handles Me.AddinInitialize
Dim MyFeatureProgId As String = System.Configuration. _
ConfigurationManager.AppSettings("MyFeatureProgId")
If MyFeatureProgId IsNot Nothing Then
Me.MyFeature = _
New AddinExpress.MSO.ADXAddinAdditionalModuleItem(Me.components)
Me.MyFeature.ModuleProgID = MyFeatureProgId
Me.Modules.Add(Me.MyFeature)
End If
End Sub
If your ADXAddinAdditionalModule contains Ribbon controls, you will need to use the OnRibbonBeforeCreate event of the add-in module.
The same approach is applicable for the Excel XLL add-ins. Just use proper
class types in the sample above.
Accessing public members of your COM add-in from another add-in or application
You can always access a public property or method defined in the add-in module via the following path:
HostApp.COMAddins.Item({the ProgID of your add-in}).Object.MyPublicPropertyOrMethod(MyParameter)
The ProgID value above can be found in the ProgID attribute of the add-in module. Note that you access the MyPublicPropertyOrMethod above
through late binding - see System.Type.InvokeMember. You can also find a number of samples in this document. And you can search our
forums for more samples. See also What is ProgID?
Note. If you didn't find the answer to your questions on this page, please see the
HOWTOs section:
Back to Add-in Express for Office and .NET homepage | 
