Deploying per-user Office extensions via an MSI installer

This is part 2 of the series that covers all possible ways of deploying Add-in Express based Office extensions. Part 1 provided a brief overview of the available deployment technologies and now we are going to have a close look into deploying per-user Office extensions via an MSI installer.

Step 1. Set RegisterForAllUsers = false

If you develop a per-user COM add-in, RTD server or smart tag, set the RegisterForAllUsers property of the add-in module, RTD server module, or smart tag module to False. If you develop an Excel add-in (XLL add-in or Automation add-in) go to Step 2 below.

Before you modify the RegisterForAllUsers property, you must unregister the add-in project on your development PC and make sure that adxloader.dll.manifest is writable.

To access the RegisterForAllUsers property in the Properties window, click the designer surface of the module:

Step 2. Build your project

To support 32-bit and 64-bit Office, set the Platform target property to “Any CPU” before building your project.

If you use a 32bit component in your Office extension (say a native-code DLL, ActiveX DLL , or .NET assembly), you have to compile it for the x86 platform. Please keep in mind that such an Office extension will work in 32bit Office 2000-2016 only and will not work in 64bit Office 2010-2016. Similarly, if you use a 64bit component, you have to compile the project for the x64 platform but your Office extension will work in 64bit Office 2010-2016 only.

Summing up, if you use a bitness-aware component, your extension will work for Office versions of that bitness only.

Step 3. Create a setup project

Add-in Express provides the setup project wizard accessible via Project | Create Setup Project menu in Visual Studio as well as via the context menu of the project item in the Solution Explorer window (shown below).

In the New Setup Project Wizard dialog box fill in all the necessary fields (Title, Description, Product name and Company) and click the Next button.

On the next step you specify the localization of the installer UI, the file name and output directory of your setup project.

Click the Finish button. This creates a new setup project.

Step 4. Check the DefaultLocation property

Select your setup project in the Solution Explorer window and open the File System editor using menu View | Editor | File System. Select the Application Folder node and check the DefaultLocation property. By default, the setup wizard sets the DefaultLocation property to the user’s application data folder as follows:

    [AppDataFolder][Manufacturer]\[ProductName]

Step 5. Check custom actions

Select your setup project in the Solution Explorer window and open the Custom Actions Editor.The following custom actions must be present in your setup project:

    Install: adxregistrator.exe /install=” {Assembly name}.dll” /privileges=user

    Rollback: adxregistrator.exe /uninstall=” {Assembly name}.dll” /privileges=user

    Uninstall: adxregistrator.exe /uninstall=” {Assembly name}.dll” /privileges=user

Where:

{Assembly name} is the assembly name of your Office extension, such as COM add-in, RTD server, Smart tag, XLL, or Excel Automation add-in.

If any of the custom actions is missing, you need to add it. Pay attention to the /privileges command line switch, it must be set to user.

Step 6. Set PostBuildEvent

Select your setup project in the Solution Explorer window and edit the PostBuildEvent property as follows:

    “{Add-in Express}\Bin\adxpatch.exe” “$(BuiltOuputPath)” /UAC=Off /RunActionsAsInvoker=true

Where:

{Add-in Express} is the full path to the installation folder of Add-in Express.

This executable patches the generated .MSI in the following ways:

• it hides the “For Me” and “For Everyone” choice in the installer UI. Hiding these options is required because the installer will fail if the user running the installer doesn’t have permissions to install for all users on the PC.
• it turns off the dialog asking for administrative privileges; the UAC dialog pops up when a non-admin user runs the installer. Switching off the dialog is necessary because a per-user Office extension cannot require administrative permissions.

The option /RunActionsAsInvoker=true specifies that the installer will be run with the privileges of the user who started the installer and not with the system privileges.

Step 7. Add prerequisites (optional)

Open your setup project properties (menu Project | Properties) and click the Prerequisites button. This opens the Prerequisites dialog:

If you add any prerequisites to your setup project and the Create setup program to install prerequisite components option in the Prerequisites dialog box is checked, Visual Studio will generate the setup.exe (bootstrapper) file, which will comprise all information about the prerequisites. Running the setup.exe is essential for the prerequisites to get installed. But see Step 9 below.

Step 8. Build the setup project

Build your setup project and deliver all generated files to the target PC.

Step 9. Running the installer

Please keep in mind that installation / uninstallation of an Office extension requires closing the host application.

To run the installer on the PC, you need to choose whether to run the .MSI or setup.exe. Let’s consider both options.

When the setup.exe is launched, it checks whether the prerequisites are already installed. If a prerequisite is missing, the bootstrapper installs that component. If all the prerequisites are already installed, the .MSI installer launches.

When the .MSI is launched, the extension will be installed but might not run if any prerequisite is missing.

If you deploy prerequisites requiring administrative permissions, the end user will get an UAC dialog asking for administrator credentials. But entering the administrator credentials will install your Office extension for the administrator and not for the current user. Because it is impossible to impersonate the user running the installer after admin credentials are provided, this makes combinations of per-user Office extensions and prerequisites almost useless.

Step 10. Installing a new version of the Office extension

You need to change the assembly version of your Office extension as well as the version of the setup project and rebuild it. The user needs to uninstall the previous version before installing the new one.

Don’t change the Product code property of your setup project. By default, when you change the Version property of your setup project, Visual Studio shows a dialog recommending that you change the Product code. Click No or Cancel in this dialog because if you change the Product code, you will get a new Office extension installer, consequently the previous version of your extension may uninstall incorrectly when the user launches the new version installation.