Create Outlook custom form in VB.NET, C#, C++.
Develop custom task panes for Outlook 2007 - 2000.

Add-in Express™
for Microsoft® Office and .net

Add-in Express Home >

How your Office extension loads into an Office application

Registry keys

Any Office extension - a COM add-in, Excel add-in, RTD server, or smart tag - must be installed and registered because Office looks for extensions in the registry. In other words, to get your add-in to work, 1) add-in files must be installed to a location accessible by the add-in users and 2) registry keys must be created that specify which Office application will load the add-in and which PC users may use the add-in. The necessity to create registry keys is the reason why you cannot use XCOPY deployment for a COM add-in, Excel XLL add-in, RTD server, or Smart tag.

Although Add-in Express creates all registry keys for you, you might need to find the keys when debugging your add-ins. The main intention of this section is to provide you with information on this.

Locating COM add-ins in the registry

Depending on the value of the RegisterForAllUsers property of the add-in module, the main registry entry of a COM add-in is located at:

{HKLM or HKCU}\Software\Microsoft\Office\{host}\AddIns\{your add-in ProgID}

If the RegisterForAllUsers property of the add-in module is true, the add-in is registered in HKEY_LOCAL_MACHINE, otherwise the key is located in HKEY_CURRENT_USER.

Pay attention to the LoadBehavior value defined in this key; typically, it is 3. If LoadBehavior is 2 when your run your add-in, this may be an indication of an unhandled exception at add-in startup.

The registry key above notifies the corresponding Office application that there's an add-in to load. FYI, the COM add-in is a COM object registered in

HKEY_CLASSES_ROOT\CLSID\{Add-in Express Project GUID}

Locating Excel UDF add-ins in the registry

Registering a UDF adds a value to the following key:

HKEY_CURRENT_USER\Software\Microsoft\Office\{Office version}.0\Excel\Options

The value name is OPEN or OPEN{n} where n is 1, if another UDF is registered, 2 - if there are two other XLLs registered, etc. The value contains a string, which is constructed in the following way:

str = "/R " + "" + pathToTheDll + ""

Add-in Express loader

All Office applications are unmanaged while all Add-in Express based add-ins are managed class libraries. Therefore, there must be some software located between Office applications and your add-ins. Otherwise, Office applications will not know of your .NET add-ins and other Office extensions. That software is called a shim. Shims are unmanaged DLLs that isolate your add-ins in a separate application domain.

When you install your add-in, the registry settings for the add-in will point to the shim. And the shim will be the first DLL examined by the host application when it starts loading your add-in or smart tag.

Add-in Express provides the shim of its own, called Add-in Express loader. The loader (adxloader.dll, adxloader64.dll) is a compiled shim not bound to any certain Add-in Express project. Instead, the loader uses the adxloader.dll.manifest file containing a list of .NET assemblies that must be registered. The loader's files (adxloader.dll, adxloader64.dll and adxloader.dll.manifest) must always be located in the Loader subdirectory of the Add-in Express project folder. When a project is being rebuilt or registered, the loader files are copied to the project's output directory. You can sign the loader with a digital signature and, in this way, create trusted COM extensions for Office.

Add-in Express loader manifest

The manifest (adxloader.dll.manifest) is the source of configuration information for the loader. Below, you see the content of a sample manifest file.


			<?xml version="1.0" encoding="utf-8"?>
              <configuration>
			  <assemblyIdentity name="MyAddin14, PublicKeyToken=f9f39773da5c568a" />
			  <loaderSettings generateLogFile="true" shadowCopyEnabled="true" 
			    privileges="user"> configFileName="app.config"
			  <logFileLocation>C:\MyLog.txt</logFileLocation>
			  </loaderSettings>
			</configuration>
			

The manifest file allows generating the log file containing useful information about errors on the add-in loading stage. The default location of the log file is {user profile}\Documents\Add-in Express\adxloader.log. You can change the location using the logFileLocation node; relative paths are also acceptable. The manifest file allows you to disable the Shadow Copy feature of the Add-in Express loader, which is enabled by default (see Deploying - shadow copy). The privileges attribute accepts the "user" string indicating that the Add-in Express based setup projects can be run with non-administrator privileges. Please, note, any other value will require administrator privileges to install your project. You should be aware that the value of this attribute is controlled by the RegisterForAllUsers property value of add-in and RTD modules (see Add-in Express Module basics). If RegisterForAllUsers is True and privileges="user", a standard user running the installer will be unable to install your Office extension. If RegisterForAllUsers is False and privileges="administrator", your Office extension will be installed for the administrator only.

In addition, you can run regsvr32 against the adxloader.dll. If a correct manifest file is located in the same folder, this will register all Add-in Express projects listed in the loader manifest.

How the loader works

Consider an ideal case, when all required files are supplied, registry keys are created and permissions are correct. If so, when the Office application discovers an appropriate registry key (see Locating COM Add-ins in the Registry), it finds the loader's DLL, loads it and calls a method implemented by the loader in accordance with COM rules. The loader initializes CLR (Common Language Runtime), reads the manifest, creates an AppDomain, loads your assembly into the domain, and creates an instance of your add-in module (this runs the constructor of the module). Then the loader generates the AddinInitialize and AddinStartupComplete events of the module, connects the module to events of the host application and waits for the event that specifies the end of the job. When such an event occurs, the loader disconnects the module from the host application events, and generates the AddinBeginShutdown and AddinFinalize events of the module (see also Custom Actions When Your COM Add-in Is Uninstalled).

Loader's log

If the manifest requires creating a log file (see the generateLogFile attribute at Add-in Express Loader Manifest), the log file is created in the location specified by the manifest or in {Documents}\Add-in Express\adxloader.log (default). Note that the log is re-created whenever you install/uninstall the add-in and when the Office application loads it.