How to customize MSI installer using Add-in Express ClickTwice custom actions

Let’s start with the conclusion:

You can deeply customize the UI and behavior of the MSI installer of your Add-in Express based Office extension using a ClickTwice custom action.

To see how this works, build the project below, install the add-in by starting the MSI installer, and have a closer look at that installer’s UI. Then uninstall the add-in, run the downloader, and notice the installer’s UI.

Below I describe how to create such a custom action on an example of a C# project.

ClickTwice

ClickTwice is a technology that lets you install and update an Add-in Express-based Office add-in over the web using an MSI-based installer. Publishing such an installer for the first time creates a ClickTwice application, which is an abstract construct having the attributes name (ClickTwice Application Name) and ID (ClickTwice Application ID). After the installer is published, you find these attributes in the version_info.xml file within the folder specified in the Publishing location field of the Publish dialog. This file provides all the information required for the two ClickTwice utility applications: downloader and updater. Customizing the ClickTwice application means creating a ClickTwice custom action that changes the behavior and UI of the downloader, updater or both.

For the sample project discussed below, the ClickTwice Application Name is ctcustomuiexample; the ClickTwice Application ID is “C23A2AC1341240F582A7417DD923FE7B“.

The downloader

The downloader is a native-code utility program designed for downloading and installing prerequisites (optionally) and a new add-in version. Add-in Express generates the downloader so that it is uniquely bound to the add-in (Office extension) you deploy. Add-in Express creates the downloader file with the same name as the ClickTwice application name. For the sample project described below, the downloader name is ctcustomuiexample.exe.

You can tune the downloader using the settings the Publish dialog provides.

To install an add-in for the first time, the user clicks a link pointing to the downloader generated for the add-in.

To update an add-in, you invoke the CheckForMsiUpdates method of the Add-in Express module. This method downloads and starts the new version’s downloader. For this to occur, the add-in must be installed using ClickTwice; this writes the information required for finding an update to adxloader.dll.manifest.

When started, the downloader uninstalls the previous add-in version, downloads the installer of the new add-in version, and starts it.

Creating and debugging a ClickTwice custom action

Creating a ClickTwice custom action to customize the downloader allows you to avoid fine-tuning your MSI installer using specialized installation software such as WiX or InstallShield. Instead, you can create a basic UI of your installer using such a product and use the .NET Framework to create a full-scale UI at run time.

Step #1. Create a class library project (Windows Classic Desktop) and add a ClickTwice module to the project. Handle the required events of the ClickTwice module. Build the assembly.

Step #2. In the Publish dialog, prepare the add-in installer for publishing. For the detailed steps, please see MSI web-based deployment – ClickTwice. On the screenshot below, notice the Publish location path; it will be used later.

Step #3. Click the Custom Actions button and specify the custom action assembly and its class.

Step #4. Next, you clear the Enable hash checking option in the Preferences dialog. Note that this option must be set when you publish a release version of the add-in.

Step #5. Publish the ClickTwice installer. This creates the following folder structure:

The folders created are as follows:

• MSIPublish – the default folder for publishing ClickTwice installers; contains version_info.xml – the file providing all the information required for ClickTwice
• 1033 – language-specific folder; contains version-specific folders
• 1.0.0 – version-specific folder; contains the downloader, MSI installer, and folders for the updater, custom actions, and prerequisites (if any)
• actions – this folder contains ClickTwice custom actions

Step #6. Now that the installer is published, navigate to the Build tab of the custom action project’s properties, and set the Output path so that it points to the folder where the custom action DLL is published. Say, for the project discussed, the path is

..\CTCustomUIExample\MSIPublish\1033\1.0.0\actions\

Step #7. Finally, specify the path to the downloader in the Start external program field; see the Debug tab of the project’s properties. The path specified for the sample project is

D:\CTCustomUIExample\CTCustomUIExample\MSIPublish\1033\1.0.0\ctcustomuiexample.exe

Step #8. Set the custom action assembly project as a startup project and start debugging it.

Step #9. Having completed debugging, you need to re-enable hash checking (see Step #4) and re-publish the installer.

Now you can deliver the new add-in version to customers.

The example

The sample add-in discussed here includes a ClickTwice custom action project. On how to create such a project, see Creating and debugging a ClickTwice custom action above.

The project contains a ClickTwice module, the Strings collection of which contains a string constant named productName. The module (and the Strings collection) can be localized.

The module handles the ADXClickTwiceModule.OnBeforeInstall and ADXClickTwiceModule.OnBeforeUninstall events to set/clear a flag. All the activity is performed in the ADXClickTwiceModule.OnInstallUIAction event. Depending on the value of the Message property of the event argument class, the code displays this or that form to create the UI of the installer.

Available downloads:

This sample add-in project was developed using Add-in Express for Office and .net:

ClickTwice Custom UI Example (C#)