ThreeWave Installing COM Add-Ins

This page discusses COM Add-Ins And Installation Policies
ShortFadeBar

Introduction

Distributing COM Add-Ins to other users on other machines requires some forethought regarding access and security. Information about a COM Add-In (CAI) is stored in System Registry in either of two keys. If the CAI is for the current user only (or configured on a per-user basis for each user of a machine), the information is stored in the HKEY_CURRENT_USER (HKCU) region of the registry. CAIs in HKCU are displayed in the COM Add-Ins dialog and can be loaded and unloaded by the user. If the CAI is configured for the machine as a whole, its information is stored in the HKEY_LOCAL_MACHINE (HKLM) region of the registry. These add-ins can be loaded and unloaded only by their own interface or by direct manipulation of the System Registry. They do not appear in the COM Add-Ins dialog. This restriction is to prevent one user from modifying a setting that affects all users of the machine.

This page assumes that you are familiar with the System Registry and the RegEdit Registry Editor program. Changing System Registry Keys and Values can be dangerous. If you change or delete the wrong key, applications may behave incorrectly or not start. In the worst case, Windows itself may not start. It is strongly recommended that you make a backup copy of the Registry before changing it. Windows itself also keeps backup copies of the last known good Registries, so you can restore to a previous version of the Registry during the Windows startup procedure. Typically, this is done by pressing the F2 or F12 key during the BIOS load screen when you computer first starts.

SectionBreak

Typical Installation Process

Unless you use a dedicated installation program such as InstallShield or Setup Factory, the typical method of installation of a CAI on another machine is to copy the DLL to the target machine, run the RegSvr32 program to register the CAI with Windows, and then add the CAI to Excel via the COM Add-Ins dialog box. On most systems, you must be logged on to an account with adminstrator privileges in order to run the RegSvr32 program. If you are using a dedicated installer like InstallShield or Setup Factory, all of the steps outlined on this page can be automated with the setup program. Consult your program's documentation.

REGSVR32 - The RegSvr32 program is a utility provided by Windows to register ActiveX DLL and OCX component files with Windows. In the case of components written with Visual Basic 6, it calls a procedure that Visual Basic writes for you that creates and updates the appropriate System Registry keys for your component. You run RegSvr32 from the Run item on the Windows Start menu. The syntax, in summary, is
RegSvr32 "C:\YourPath\YourFile.dll"
To unregister a component and remove its registry keys, use the syntax:
RegSvr32 "C:\YourPath\YourFile.dll" /u
The /u switch tells RegSvr32 to unregister the component. Unregistering a component removes it from the System Registry but does not actually delete any files.

SectionBreak

Configuring A COM Add-In Per User Without Administrator Privileges

To configure the CAI for an individual user without administrative privileges, you must directly modify the System Registry. Note that modifying the System Registry can be dangerous. If you delete or modify the wrong Key or Value, applications may behave incorrectly or not start. In the worst case, Windows itself may not start. Take caution when modifying the System Registry. First, log on to the system with an account with administrator privileges and RegSvr32 the DLL file. If you attempt to RegSvr32 the DLL and you don't have administrator privileges, RegSvr32 may fail with an error 0x80004005, which is an "unspecified error", providing no meaningful information. At its core, this error indicates a security violation. Once you have run RegSvr32 with administrative privileges, follow the steps below.

  • Log on to the machine as the appropriate user.
  • Go to the Windows Start menu, choose Run and enter RegEdit to start the Registry Editor program.
  • In the Registry Editor, navigate to the key HKEY_CURRENT_USER\Software\Microsoft\Office. If necessary, create a Key named Excel under the Office key if one does not already exist.
  • Under the Excel Key, create a Key named AddIns if it does not already exist.
  • In the AddIns key, create a Key named YourAddIn.ProgID where YourAddIn is the name of the DLL file (without the path and without the '.dll' extension) and ProgID is the name of the class in the add-in that contains the OnConnection and related events, or the class that implements the IDTExtensibility2 interface. This is the name of the Add In Designer object in your add in.
  • In this key, create a String Value named FriendlyName and enter a name for your add-in. Then create a String Value named Description and enter a short description of your add in. Finally, create a DWORD value named LoadBehavior and give it a value of 3.
  • Close the Registry Editor and open Excel. Since you specified a LoadBehavior of 3, the add in will automatically load when Excel starts. You can load and unload the CAI via the COM Add-Ins dialog box. If you do not have a COM Add-Ins item on your Tools menu, you need to add it. Click here for instructions.
  • You will need to repeat these steps for each user on the machine.

SectionBreak

Installing The Add In At The Machine Level

Rather than installing the COM Add-In for each user, you can install the CAI for all users of the machine. All users of the machine will have the Add In loaded. However, you will not be able to load or unload the CAI via the COM Add-Ins dialog. This restriction is designed to prevent one user from making a change that affects all users of the machine. A well designed CAI will have a user interface element such as a menu item or command bar button to unload the add in.

Note that you must be logged on to an account with administrative privileges in order to install the CAI at the machine level since you are modifying a protected region of the System Registry. If you attempt to modify the HKEY_LOCAL_MACHINE region of the registry without being logged on as an administrator, you will likely receive security errors.

First, register the DLL with Windows using the RegSvr32 program.

To configure the CAI for all users of the machine, follow the steps below.

  • Go to the Windows Start menu, choose Run and enter RegEdit to start the Registry Editor program.
  • In the Registry Editor, navigate to the Key HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Office.
  • If necessary, create a Key named Excel under the Office Key.
  • Under the Excel Key, create a Key named AddIns if it does not exist.
  • Under the AddIns Key, create a Key named YourAddIn.ProgID where YourAddIn is the name of the DLL (without any path information and without the '.dll' extension) and ProgID is the name of the class in the DLL that contains the OnConnection and related events or the class that implements the IDTExtensibility2 interface.
  • Within this key, create a String Value named FriendlyName and assign a name to the Add In.
  • Create a String Value named Description and enter a short description of the Add In.
  • Create a DWORD Value named LoadBehavior and give it a value of 3.
  • Close the Registry Editor and start Excel. Since you set the LoadBehavior setting to 3, the Add In will load when Excel starts. You will not see this CAI in the COM Add Ins dialog because it is configured for the entire machine, not just the individual user. Individual users are not allowed to load or unload COM Add Ins that are configured in HKEY_LOCAL_MACHINE to prevent one user from making a change that affects all users of the machine.

SectionBreak

Automation AddIns (Excel 2002 And Later)

When you use RegSvr32 to register your COM Add In with Windows, the componenet is automatically added to the HKEY_CLASSES_ROOT region of the registry, and functions defined in classes of that CAI are accessible directly from worksheet cells. To enable functions in an Automation/COM Add In, open the standard Add Ins dialog (not the COM Add-Ins dialog) and click the Automation button. This will present you with a very long list of available components. Scroll down to your Automation Add In, which will be listed as the name of the DLL file (without any path information and without the '.dll' extension) followed by the class containing the functions. If you have more than one class that expose functions, you will see one entry in the list for each class. Check your item(s) and they will appear in the list of standard Add Ins. Once you have done this, you can use those functions directly in worksheet cells without qualifying their names. Components and functions in the Automation Add Ins are available to all users, regardless of the user that installed the add in.

Automation Add Ins were introduced in Excel 2002 and are not available in earlier versions.

SectionBreak

Additonal Resources For COM Add-Ins

Adding The COM Add-Ins Menu Item
Automation Add-Ins
Distribution And Security Issues Of COM Add-Ins
COM Add-Ins In Excel 2007
COM Add-Ins, Getting The DLL Name Of
COM Add-Ins, Installer (download zip file)

This page last updated: 23-August-2007

-->