How to deploy and debug Office add-in
for Outlook, Word, Excel 2019 - 2003

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

Add-in Express Home > Add-in Express for Office and .NET > Online Guide > Tips and notes > Deploying and debugging tips

Deploying and debugging tips

Breakpoints are not hit when debugging

This problem occurs when you debug an add-in project targeting to .NET Framework 2.0-3.5 in VS 2010-2015. The reason is the debugger, which doesn't know what .NET Framework version your add-in uses.

To find out that info, the debugger checks the .config file of the executable, which is the host application in your case. The examples of configuration file names are outlook.exe.config and excel.exe.config; if such a file exists, it is located in the Office folder; say, for Office 2003, the folder is C:\Program Files\Microsoft Office\OFFICE11. If the .config file is missing or it doesn't point to a specific .NET Framework version, the debugger uses the debugging engine of .NET Framework 4.0.

To help the debugger, you can create (or modify) the .config file(s) for the Office application(s) installed on your PC. You do this using the Host Configuration command of the COM add-in module; create an empty COM add-in project, if required.

Please pay attention: if the .config file of any given Office application points to a specific .NET Framework version, that .NET Framework version will be used by all .NET-based Office extensions loaded by the Office application.

Don't use message boxes when debugging

Showing /closing a message box is accompanied by moving the focus off and back on to the host application window. When processing those actions, the host application generates a number of events (available for you through the corresponding object models). Therefore, showing a message box may mask the real flaw of events and you will just waste your time on fighting with windmills. We suggest using System.Diagnostics.Debug.WriteLine and the DebugView utility available on the Microsoft web site.

Conflicts with Office extensions developed in .NET Framework 1.1

In the general case, two Office extensions based on .NET Framework 1.1 and 2.0-3.5, will not work together. That occurs because of these facts:

  • Before they introduced .NET Framework 4.0, two .NET Framework versions could not be loaded in the same Windows process. If there were two Office extensions written in .NET Framework 1.1 and 2.0 (3.0 and 3.5 are just extensions of 2.0), the first extension loads its .NET Framework version and the second extension is obliged to use the same .NET Framework. Now, with NET Framework 4.0, an add-in based on .NET Framework 1.1 will prevent add-ins based on .NET Framework 2.0 from loading and vice-versa.
  • There are Breaking Changes between .NET Framework 1.1 and 2.0.

We suggest checking the environments in which your would-be add-in will work. First off, you need to look for a .config file(s) for the host application of your add-in. The examples of configuration file names are outlook.exe.config and excel.exe.config. If such a file exists, it is located in the Office folder; say, for Office 2003, the folder is C:\Program Files\Microsoft Office\OFFICE11. Open such a file in any text editor and see if a .NET Framework version is specified; if it is specified, then all extensions loaded by that host application(s) use the specified .NET Framework version.

If you spotted an extension using different .NET Framework version, then, in the worst case, you will need either to turn it off, or use the same .NET Framework version in your project.

However, all of the things above will not help because the end user may install an add-in based on the other .NET Framework version after you install your add-in, smart tag, etc. So, a simple conclusion is never use Visual Studio 2003 to develop Office extensions.

Always check the log file (see Get details about add-in loading) for the CLR version that is used for your add-on. If you run into a situation of two conflicting add-ins, you can try to create a .config file pointing to a .NET Framework version of your choice and copy that file to the Office folder on the target machine. To create such a file on your PC, you use the Host Configuration command of the COM add-in module. When you are done, don't forget to use the Host Configuration command again to restore the state. Other ways are to turn the conflicting add-in off, or use the same .NET Framework version in your project.

For all users or for the current user?

COM add-ins, RTD servers and Smart tags can be registered either for the user whose permission are used to run the installer or for all users on the machine. That's why the corresponding module types provide the RegisterForAllUsers property. (to access it in the Properties window, click the designer surface of the add-in module or RTD server module). Registering for all users means writing to HKLM and therefore the user registering a per-machine extension must have administrative permissions. Accordingly, RegisterForAllUsers = Flase means writing to HKCU (=for the current user) and therefore such an Office extension can be registered by a standard user.

Add-ins deployed via ClickOnce can write to HKCU only.

The setup project wizard analyzes RegisterForAllUsers and creates a setup project that is ready to install the files mentioned in Files to deploy to the following default locations:

RegisterForAllUsers = True RegisterForAllUsers = Flase
[ProgramFilesFolder][Manufacturer]\[ProductName] [AppDataFolder][Manufacturer]\[ProductName]

All other Office extensions can be installed for the current user only.

Updating on the fly

It isn't possible to update an Office extension on the fly. That's because Office loads the extension and to unload it and free its resources, you have to close the host application(s) of the extension.

User Account Control (UAC) on Windows Vista and above

UAC should be turned on Vista; it should be set to the default level in subsequent Windows versions. This is necessary when you install a COM add-in for all users on the PC, that is, when the RegisterForAllUsers property of the add-in module is true. If UAC is off on vista (no SP), a per-user add-in (RegisterForAllUsers = false) installed by an administrator will not work. On Vista SP1 and subsequent Windows versions, a per-user add-in won't work if the host application is elevated. These are restrictions built in Windows.

How to find if Office 64-bit is installed on the target machine

As you know the 64-bit version of Office 2010, 2013, 2016 and 2019 can be installed on 64-bit Windows only. If Outlook is installed on the target PC, then the value below exists in this registry key:

Outlook 2010 - 2019:
Key: HKLM\SOFTWARE\Microsoft\Office\{14 or 15}.0\Outlook
Value name: Bitness
That value can be "x64" or "x86"; "x64" means Outlook 64-bit is installed.

If Outlook is not installed, you can check the following values in the following 64-bit registry key:

Excel, Word, PowerPoint 2010 - 2019:
Key: HKLM\Microsoft\Office\{14 or 15}.0\{application}\InstallRoot
Value name: Path
If that value exists, then the corresponding 64-bit application is installed.

Deploying Word add-ins

If your add-in delivers custom or customizes built-in command bars in any Word version, it isn't recommended setting the RegisterForAllUsers property of the add-in module to True. Since Word saves custom command bars and controls to normal.dot, every user has its own copy of command bars saved to their normal.dot. And when the administrator uninstalls the add-in, the command bars will be removed for the administrator only. See also Word add-ins, command bars, and normal.dot and How command bars and their controls are created and removed?

InstallAllUsers property of the setup project

The InstallAllUsers property sets the default state of the "Install {setup project title} for yourself, or for anyone who uses this computer" group of option buttons (they are "Everyone" and "Just me") in the installer. This group, however, is hidden by the executable mentioned in the PostBuildEvent property of the setup project generated by Add-in Express. This is done because to install your Office extension for all users on the machine you need to use the RegisterForAllUsers property of the corresponding module (add-in module, RTD module, etc.). To find that property, open the module's designer, click its surface and see the Properties window. See also Deploying Word add-ins.

Deploying add-ins - shadow copy

The Add-in Express Loader uses the ShadowCopy-related properties and methods of the AppDomain class. When you run your Add-in Express based add-in, the host application loads the Add-in Express Loader DLL referenced in the registry. The Add-in Express Loader DLL does the following:

  • It finds your add-in DLLs in the DLL Cache. If there are no add-in DLLs in the cache it copies all .NET DLLs to the cache (including dependencies). The cache folder is located in c:\Documents and Settings\<user name>\Local Settings\Application Data\assembly\dl<number>. If all add-in DLLs (including dependencies) already exist in the cache, it compares their versions. If the versions are not the same, it copies new DLLs to the cache.
  • It loads the add-in DLLs from the cache.

You can see how the add-in versioning influences the add-in loading. This approach (it is built into .NET, as you see) allows you to replace add-in DLLs when the add-in is loaded. The disadvantage is numerous files located in the cache. As far as we know, Microsoft doesn't provide a solution for this problem. You may think you can remove these files in an add-in's uninstall custom action. But you remove the files from the current profile only.

Deploying - "Everyone" option in a COM Add-in MSI package

The Everyone option of the MSI installer doesn't have any effect on the Add-in Express based COM add-ins and RTD servers. See also InstallAllUsers property of the setup project.

Deploying Office extensions

Make sure that Windows and Office have all updates installed: Microsoft closes their slips and blunders with service packs and other updates. Keep an eye on Visual Studio updates, too.

If you deploy a per-user Office extension such as a per-user COM add-in or RTD server having RegisterForAllUsers= False in their modules as well as an Excel UDF or smart tag) and no prerequisites requiring administrative permissions are used, a standard user can install the Office extension by running the .MSI file. If you deploy a per-machine Office extension (a COM add-in or RTD server having RegisterForAllUsers= True in their modules) or if prerequisites requiring administrative permissions are used, an administrator must run the bootstrapper (setup.exe).

ClickOnce application cache

The cache location is visible in the COM Add-ins dialog. It may have the following look:


			C:\Documents and Settings\user\Local Settings\Apps\2.0\NCPNO3QK.0KJ\
			ONNRMXC3.ALM\add-..d-in_5c073faf40955414_0001.0000_2a2d23ab74b720da

Currently, we don't know if there is a decent way to clear the cache. Read more about deploying Office add-ins with Add-in Express ClickOnce solution.

ClickOnce deployment

Make sure that your IIS is allowed to process .application files. For instance, on one of our PCs, we had to edit the urlscan.ini file created by UrlScan. The only change was adding the .application extension to the AllowExtensions list. The full file name is C:\WINDOWS\system32\inetsrv\urlscan\urlscan.ini.

Customizing dialogs when updating the add-in via ClickOnce

ClickOnce doesn't provide any opportunity to customize or hide dialogs and messages shown while the user updates your add-in.

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.

Bypassing the AlwaysInstallElevated policy

When you install a per-user Office extension on a PC on which the AlwaysInstallElevated policy is set, the installer will run with the system privileges, and not with the privileges of the user who launches the installer. The policy is described on MSDN.

When this occurs you find the following line in adxregistrator.log (see Get details about add-in registration/unregistration):


Process Owner: System

It isn't possible to bypass this policy programmatically. You need to turn it off explicitly. As the description suggests you can do this by modifying a value in HKCU.

If you use an Express edition of Visual Studio

In Visual Studio Express, you need to right-click the designer surface of the module and choose Register Add-in Express Project in the context menu:

Registering Add-in Express project in Visual Studio Express

Useful resources

If you didn't find the answer to your questions on this page, please see the HOWTOs section:

Commandbar and controls tips <<

>> Excel UDF and RTD tips