Deploying per-machine Office extensions via an MSI installer

This is part 3 of the deployment series that provides step-by-step instructions for deploying your per-machine Office extensions via an MSI installer. I recommend that you start with reading Part 1 that gives a brief overview of all deployment technologies.

Step 1. Set RegisterForAllUsers = true

If you deploy an COM add-in, RTD server or smart tag on the per-machine basis, set the RegisterForAllUsers property of your add-in module, RTD server module, or smart tag module to True. An Excel add-in (XLL add-in or Automation add-in) can be only registered on the per-user basis, see Deploying a per-user Office extension via an MSI installer.

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 32-bit 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 32-bit Office 2000-2016 only and will not work in 64-bit Office 2010-2016. Similarly, if you use a 64-bit component, you have to compile the project for the x64 platform but your Office extension will work in 64-bit 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 fields (Title, Description, Product name and Company) and click the Next button.

On the next step, you choose the localization of the installer UI, the file name and output directory.

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 item and make sure that the DefaultLocation property refers to a folder accessible by all users on the PC.

By default, the setup wizard sets the DefaultLocation property to the Program Files folder as follows:

    [ProgramFilesFolder][Manufacturer]\[ProductName]

Even if your COM add-in, RTD server or smart tag is registered for all users on the machine, it may not start for users that have no permissions to access the folder where it is installed.

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 yoursetup project:

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

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

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

Where:

{Assembly name} is the assembly name of your COM add-in, RTD server or smart tag.

If any of the above mentioned custom actions is missing in the Custom actions editor, you need to add it.  Please pay attention to the /privileges command line switch, its value should be set to “admin“.

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=On /RunActionsAsInvoker=true

Where:

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

This executable patches the .MSI just generated 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 on the dialog asking for elevated privileges. This UAC dialog pops up when the user runs the .MSI installer that the setup project generates. Elevated permissions are required for your Office extension to be registered for all users.

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 is checked, Visual Studio will generate the setup.exe (bootstrapper) file, which includes all information about the prerequisites. Running the setup.exe is essential for installing the prerequisites.

Step 8.  Build the setup project

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

Step 9.  Running the installer

The user should have administrative permissions and run the setup.exe (not .MSI).

Running the setup.exe ensures that:

• the installer process will be run with elevated permissions on UAC-enabled systems; elevated permissions are required to register your COM add-in or RTD server for all users on the PC
• the prerequisites you selected for your project will be installed before your Office extension is installed

If you run the MSI, you’ll get one of the following results:

• for the user with standard user permissions – the prerequisites will not install, your extension won’t be registered because administrator privileges are required
• for the user with administrative permissions – the extension will be installed but it might not run if any of the prerequisites was not previously installed

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 the setup project. 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 opens a dialog prompting to 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.