Create custom Windows Installer (MSI)
setup projects for Office add-in in Visual Studio

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

Add-in Express Home > Add-in Express for Office and .NET > Online Guide > Deploying Office add-ins > Windows Installer setup projects (.msi)

Windows Installer setup projects

Add-in Express enables developers to build Windows Installer based setup projects for their Office extensions in two ways:

Installation Software Products Supported by Add-in Express

Supported are:

  • Visual Studio Installer in VS 2010, 2013 and 2015. This tool is built in VS 2010. For VS 2013, you need to install this extension; for VS 2015, see here. There's no such extension for VS 2012.
  • InstallShield in VS 2010, 2012, 2013 and 2015. Supported are the Professional edition and higher; the Limited and Express editions are not supported. Make sure that the edition that you install gets listed on the About dialog window (see menu Help | About in the IDE).
  • WiX (Windows Installer XML) Toolset in VS 2010, 2012, 2013 and 2015. Make sure that the WiX version that you install gets listed on the About dialog window (see menu Help | About in the IDE).

Add-in Express doesn’t directly support installation software products that don't integrate with the Visual Studio IDE. To deploy an add-in using such an installation software product, you need to "translate" instructions we publish in Creating a Visual Studio Installer setup project manually to the "language" of the product. A "translated" instruction is available for Advanced Installer; see here.

Creating a setup project using Setup Project Wizard

To help you create an installer for your Office plug-in, Add-in Express provides the setup project wizard accessible via menu Project | Create Setup Project in Visual Studio. Another way to run the wizard is shown in the screenshot.

Let's run the setup project wizard for the sample project described in Writing Microsoft Outlook COM add-in. The below describes creating a standard setup project in Visual Studio. You may also want to check Creating a WiX setup project.

Creating an Office add-in's setup project in Visual Studio

The setup project wizard provides an extra step when creating a WiX based setup project; see Multiple-Language Setup Projects and Dual-Purpose Setup Projects.

Creating a setup project using the Add-in Express wizard

Specify the file name, localization and output directory for your setup project.

Specify the file name, localization and output directory for your setup project

The wizard creates and adds the following setup project to your Office add-in solution:

A sample setup project for an Office add-in

The wizard creates the following entries in the Application Folder of your setup project (see menu View | Editor | File System):

Entries in the Application Folder of your setup project

Also, the following custom actions are created for your setup project. They will be performed on the end-user's machine to register your add-in after installation and unregister it before uninstallation:

Custom actions are created for your setup project

Creating a Visual Studio Installer setup project for an Office add-in manually

You can create a Visual Studio Installer setup project manually; follow the steps below. To manually create a setup project for any other installation software product, you need to "translate" the steps below to the "language" of the product that you use.

Note that you can check all the below-mentioned settings if you create a setup project using the setup project wizard.

Add a new setup project

Right-click the solution item and choose Add | New Project.

In the Add New Project dialog box, select the Setup Project item and click OK.

Adding a new setup project to your Visual Studio solution

This adds a new setup project to your solution.

File system editor

Right-click the setup project item and choose View | File System in the context menu.

Application folder \ Default location

Select the Application Folder item and specify its DefaultLocation property as follows:

  • If the RegisterForAllUsers property of the module is true, set DefaultLocation = [ProgramFilesFolder][Manufacturer]\[ProductName]
  • If the RegisterForAllUsers property of the module is false or, if you deploy a smart tag or Excel UDF, set DefaultLocation = [AppDataFolder][Manufacturer]\[ProductName]

Primary output

Right-click the Application Folder item and choose Add | Project Output to add the add-in's assembly to your setup project.

Adding the add-in's assembly to your setup project

In the Add Project Output Group dialog box, select the Primary Output item of your Add-in/RTD Server/Smart Tag project and click OK.

Add Primary Output dialog

For the sample add-in described in How to develop Microsoft Office COM add-in, this adds the following entries to the Application Folder of the setup project:

Primary output added

Select AddinExpress.MSO.2005.tlb (or AddinExpress.MSO.2003.tlb in Visual Studio 2003) and, in the Properties window, set the Exclude property to True. If you use version-neutral interops, exclude the VB6EXT.OLB file in the same way.

Excluding the .tlb file

Always exclude all .TLB and .OLB files from the setup project except for .TLBs that you create yourself.

Project-depended resources

Now you add all resources (e.g. assemblies, dlls or any resources) required for your project.

Add-in Express Loader and manifest

Add the adxloader.dll and adxloader.dll.manifest files from the 'Loader' subfolder of the add-in project directory to the 'Application Folder' of the setup project.

Note. For an XLL add-in, the loader names include the assembly name, say, adxloader.MyXLLAddin1.dll.

The Add-in Express Loaders are added

Add-in Express registrator

Add {Add-in Express}\Redistributables\adxregistrator.exe to the Application Folder.

Custom actions editor

Right-click the setup project item and choose View | Custom Actions in the context menu.

Add custom actions

Add new custom actions to the Install, Rollback, Uninstall sections of your setup project. Use adxregistrator.exe as an item for the custom actions.

Adding custom actions to your setup project

Custom actions arguments

Add the strings below to the Arguments properties of the following custom actions:

  • Install

    /install="{assembly name}.dll" /privileges={user OR admin}
  • Rollback

    /uninstall="{assembly name}.dll" /privileges={user OR admin}
  • Unistall

    /uninstall="{assembly name}.dll" /privileges={user OR admin}

If a COM add-in or RTD server is installed on the per-user basis, or if you deploy a smart tag or an Excel UDF, the value of the privileges argument above is user. If a COM add-in or RTD server is installed on the per-machine basis, in other words, if the RegisterForAllUsers property of the corresponding module is true, the value of the privileges argument above is admin.

Say, for an add-in described in Developing Microsoft Office COM add-ins, the Arguments property for the Install custom action contains the following string:

/install="MyAddin1.dll" /privileges=user

Dependencies

Right-click the Detected Dependencies section of the setup project and choose Refresh Dependencies in the context menu. Also, exclude all dependencies that are not required for your setup project.

Launch conditions

Right-click the setup project item and choose View | Launch Conditions on the context menu.

Make sure that the .NET Framework launch condition specifies a correct .NET Framework version and correct download URL. Note that we recommend using launch conditions rather than prerequisites because installing a prerequisite usually requires administrative permissions and in this way installing a per-user Office extension may result in installing the extension for the administrator, but not for the user who ran the installer.

Prerequisites

Right-click the setup project and open the Properties dialog.

If administrative permissions are required to install prerequisites, then for a per-user Office extension, the elevation dialog will be shown on UAC-enabled systems. If the administrator's credentials are entered in this situation, then the installer will be run on behalf of the administrator and therefore, the Office extension will be installed for the administrator, not for the user who originally ran the installer.

Click the Prerequisites button and, in the Prerequisites dialog box, select required prerequisites.

Final touch

Rebuild the setup project. Specify the following command line in the PostBuildEvent property of the setup project:

  • If the RegisterForAllUsersProperty of the module is false or if that property is missing:

    {Add-in Express}\Bin\adxPatch.exe %BuiltOuputPath% /UAC=Off

  • If the RegisterForAllUsersProperty of the module is true:

    {Add-in Express}\Bin\adxPatch.exe %BuiltOuputPath% /UAC=On

  • The executable – adxPatch.exe – also provides the /RunActionsAsInvoker parameter. If set to true (default), it specifies that adxRegistrator.exe used as a custom action will be run with the privileges of the user who launches the installer.

    Now build the setup project, copy all setup files to the target PC and run the .msi file to install the add-in. However, to install prerequisites, you will need to run setup.exe.