How to deploy and debug Office 2010 - 2000
add-in / plug-in in VB.NET, C#, C++ - tips

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 in Visual Studio 2010

This problem occurs when you debug an add-in project targeting to .NET Framework 2.0-3.5 in VS 2010. 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 general case, two Office extensions based on .NET Framework 1.1 and 2.0 (or higher), will not work together. That occurs because of three 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.
  • You can't influence the order in which Office extensions are loaded; however, you can choose all Office extensions to use the same.NET Framework version - see below.

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 Loader's log) 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 and RTD servers can be registered either for the current user (the user the permissions of which are used to run the installer) or for all users on the machine. That's why the corresponding module types provide the RegisterForAllUsers property. 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 Vista, Windows 7 and Windows Server 2008

The User Account Control (UAC) should be turned on Vista; it should be set to the default level on windows 2008 Server and Windows 7. 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. Note that when UAC is off, a per-user add-in (RegisterForAllUsers = false) installed by an administrator will not work. This is restriction of systems with UAC.

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 pre-requisites 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).

Note that if a standard user runs setup.exe on Vista, Windows 7 or Windows 2008 Server with UAC turned on, the elevation dialog may pop up and this may end with installing the add-in to the admin profile. In such a case, the add-in will not be available for the standard user. But on the other hand, this installs pre-requisites and makes possible installing the Office extension for the standard user by running the .MSI file.

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.

Note. 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

Back to Add-in Express for Office and .NET homepage
See Also