MSI-based web deployment
for per-user and per-machine Office add-ins

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 > MSI web-based deployment - ClickTwice :)

MSI web-based deployment - ClickTwice :)

ClickTwice is designed to help you deploy and update per-user and per-machine add-ins over the web. This technology allows using your favorite installer to create an .MSI installer. For instance, you can develop your setup project in Visual Studio, see Creating MSI installers for Office add-ins.

On this page you will find information pertaining to:

• Introduction to ClickTwice
• Publishing the Office add-in project with ClickTwice :)
• Files generated by ClickTwice :)
• Updating an Office extension via ClickTwice :)
• Customizing ClickTwice installations
• Step-by-step samples

Introduction to ClickTwice

You start with publishing the installer. Open the Publish dialog to specify the .MSI file to be published, the URL from which the add-in and updates will be installed, provide certificate info, select prerequisites and choose options. You can customize the installation process by providing a custom action DLL containing a ClickTwice module; that class provides a programmatic interface to the ClickTwice functionality.

Clicking the Publish button prepares the files required for your add-in to be deployed and organizes them in several folders within the specified folder (local). There are several important files to note:

• A downloader; it is an unmanaged executable that Add-in Express generates. If no prerequisites are specified, it downloads the .MSI file and runs it. The file name of the downloader is set to the name of your project, such as myaddin1.exe.
• A bootstrapper (setup.exe), which is generated only if prerequisites are defined. In this case the downloader launches setup.exe, waits for the prerequisites to get installed; and then downloads and runs the .MSI.
• Am XML file containing version information about updates.

You copy the complete folder structure including the files described above and prerequisites to a location, which is accessible by the end user via the specified URL. Then you provide the user with a link pointing to the downloader. The user clicks the link, the browser downloads the downloader and starts it. If prerequisites are specified, the downloader starts setup.exe and waits for the prerequisites to be installed. This ends up with the downloader downloading the .MSI and running it. Finally, the add-in gets installed.

Publishing an update modifies the XML file and puts the new bootstrapper, downloader and .MSI to separate folders in the same local folder. You copy the folder to the location accessible by end users. When your add-in invokes the CheckForMsiUpdates() method, it downloads the XML file and checks the version information. If there's a new update, it returns the URL of the downloader. You download the file and start it.

Publishing the Office add-in project

Build the add-in project and choose Publish ADX Project in the project context menu or in the Project menu.

The features described below can be run from the command prompt; see Publishing from the Command Prompt.

This opens the Publish dialog discussed in the next section.

Installer file

Specifying the path to a .MSI installer in the Publish dialog fills in info fields in the upper part of the dialog.

Publishing location

You may publish the installer to a file share or FTP server; publishing to an IIS is not supported. When publishing the installer, the Publishing location can be a file path or a path to an FTP server. By default, the Publish wizard suggests publishing your application to the MSIPublish subfolder in the project directory. In Publishing location, enter the location using one of the following formats:

• To publish to a file share, enter the path using either a UNC path such as \\Server\ApplicationName or a file path, say C:\Deploy\ApplicationName.
• To publish to an FTP server, enter the path using the format ftp://ftp.domain.com/ApplicationName.

Installation URL

The location from which users download and run the installer may differ from the location where you initially published it. For example, in some organizations, a developer might publish an application to a staging server, and then an administrator can move the application to a web server. In this case, you can use the Installation URL field to specify the Web server to which users will go to download the installer. This step is necessary for Add-in Express to know where to check for updates. In Installation URL, enter the installation location using a fully qualified URL in the format http://www.domain.com/ApplicationName, or a UNC path using the format \\Server\ApplicationName.

Note. If Publishing location and Installation URL are the same, Installation URL will be empty when you open the Publish wizard next time.

Icon file

You can specify an icon in the Icon file field. The icon will be shown in the downloader window, which is displayed when the installer is downloaded from the installation location.

Custom Actions

You use the Custom Actions dialog to specify a custom action .DLL(s). To create a custom action .DLL, create a class library project and add a ClickTwice module to the project; see the Add New Item dialog of the project. To customize the installation process, you handle the events provided by ClickTwice.

Preferences

Click the Preferences button to open the Preferences dialog.

The dialog allows you to specify several UI-related options such as showing the Windows installer UI during installation / uninstallation. The Generate multi-language prerequisites option is only available if the installer is created using a multi-language setup project; see Multiple-Language Installers. Also, you may choose to sign the version_info.xml file with a certificate specified in the Publish dialog.

Also, it allows specifying an arbitrary string such as the URL of a web page. That string will be returned by the CheckForMSIUpdates() method, see Updating an Office Extension via ClickTwice :). This allows implementing custom update logics, welcome pages, information pages, etc.

It allows specifying the editions to be checked when the plug-in invokes the CheckForMSIUpdates() method.

The settings specified in the Publish dialog can be used to publish the add-in from the command line; see Publishing from the Command Prompt.

This page allows specifying FTP login parameters.

Prerequisites

Open the Prerequisites dialog and select the prerequisites required by your Office extension.

If the MSI installer was created by a multi-language setup project setup project (see Multiple-Language Installers) and if the Generate multi-language prerequisites check box is selected (see section Preferences above), choosing prerequisites in the form above creates prerequisites for the specified languages.

You must choose the following prerequisites for installing on a clean PC:

• the .NET Framework version you used when developing your Office extension
• Windows Installer 3.1 or 4.5

Certificate

To sign the installation files, select a certificate from the certificate store, browse for the existing certificate file or create a new certificate. Specify the URL of a time-stamp server (optional).

Clicking Publish

When everything is ready, click the Publish button. This generates files discussed below.

See also Publishing from the Command Prompt.

Files generated by ClickTwice :)

In the process of publishing controlled by the Publish wizard, you specify the .MSI installer to be published as well as the location where subsequent updates of your Office extension will be located. The wizard generates the folder structure demonstrated in the screenshot below:

Below, we describe every folder shown in the screenshot.

Folder MSIPublish

The root folder of the folder structure created by the Publish wizard is the MSIPublish folder; you can specify any other folder, of course. version-info.xml describes all updates available for the given product. A sample version-info.xml is shown below:

<?xml version="1.0" encoding="utf-8"?>
<application name="myaddin1" version="1.1">
  <product language="1033">
    <version name="1.0.0" installationUrl="http://www.MySite.com/Installers/" productCode="{C8E0C7A6-CCC9-478F-AB75-5C65F8941801}" languages="1033" updateType="bootstrapper" edition="Public">
      <files msi="MyAddin1Setup(1.0.0)" hash="8B1CBD881C66D9A743678CFB59DF7C7A">
        <file hash="5CAACD634626FF0F1C7C98F1AB98284C">MyAddin1Setup(1.0.0).msi</file>
        <file hash="5B260FAAEEB364413E138A98213F72BF" prerequisite="true">prerequisites\setup.exe</file>
      </files>
      <preferences>
        <showInstallUI>true</showInstallUI>
        <showUninstallUI>false</showUninstallUI>
        <webPage>
        </webPage>
        <showDownloaderWindow>true</showDownloaderWindow>
        <showRunningApplicationsWarning>true</showRunningApplicationsWarning>
        <supportedEditions>Public</supportedEditions>
      </preferences>
    </version>
    <version name="2.0.0" installationUrl="http://www.MySite.com/Installers/" productCode="{C8E0C7A6-CCC9-478F-AB75-5C65F8941801}" languages="1033" updateType="bootstrapper" edition="Public">
      <files msi="MyAddin1Setup(2.0.0)" hash="8A9CC018D3FC81B6200CA52D9849B679">
        <file hash="2C7F78781A44E5F723FD0A3733458E4F">MyAddin1Setup(2.0.0).msi</file>
        <file hash="5B260FAAEEB364413E138A98213F72BF" prerequisite="true">prerequisites\setup.exe</file>
      </files>
      <preferences>
        <showInstallUI>true</showInstallUI>
        <showUninstallUI>false</showUninstallUI>
        <webPage>
        </webPage>
        <showDownloaderWindow>true</showDownloaderWindow>
        <showRunningApplicationsWarning>true</showRunningApplicationsWarning>
        <supportedEditions>Public</supportedEditions>
      </preferences>
    </version>
  </product>
</application>
			

Language-specific folders (MSIPublish\1033)

Folder 1033 in the screenshot below is named according to the language code of the installer UI. A list of language codes (or Locale Ids) can be found here. Every language-specific folder contains one or more version-specific folder.

Version-specific folders (MSIPublish\1033\1.0.0 & 2.0.0)

These folders are named according to the version of your .MSI installer; see the Version property of the setup project in VS. You see the content of such a folder in the screenshot below:

The folder contains:

• the .MSI installer you specified.
• an unmanaged executable that Add-in Express generates. The executable is called downloader. If no prerequisites are specified, it downloads the .MSI file from {Installation URL}/{Language code}/{Version} and runs it. If prerequisites are specified, it launches setup.exe located in the prerequisites folder, waits for the prerequisites to get installed; and then downloads and runs the .MSI. The file name of the downloader is set to the name of your project, such as myaddin1.exe.
• the prerequisites folder (only if prerequisites are specified).

Prerequisites Folder (MSIPublish\1033\1.0.0 & 2.0.0\prerequisites)

This folder is only created if you specify prerequisites.

Config Folders (Configs\ClickTwice\1033\1.0.0 & 2.0.0)

Such folders are only generated if the corresponding check box is selected on the Publisher page of the Preferences dialog; see section Preferences above. A config folder contains two files:

See also Publishing from the Command Prompt.

Updating an Office extension via ClickTwice :)

Every Add-in Express module provides the CheckForUpdates method. When your Office extension calls it, the version_info.xml is downloaded via HTTP and parsed. If there are no updates, CheckForUpdates returns an empty string. If there are new updates, CheckForUpdates finds the latest update and returns either the URL of the corresponding setup.exe (if it exists) or the downloader.

Note.To implement custom update logics, welcome pages, information pages, etc., you may choose CheckForUpdates to return a URL of your choice; see Preferences.

The code sample below demonstrates installing a new version of your COM add-in programmatically; the user clicks a Ribbon button to initiate the process.

			private void adxRibbonButton1_OnClick(object sender, 
			   AddinExpress.MSO.IRibbonControl control, bool pressed)
			{
			   if (this.IsMSINetworkDeployed() && this.IsMSIUpdatable())
			   {
				  string updateUrl = this.CheckForMSIUpdates(); 
				  if (!String.IsNullOrEmpty(updateUrl)) 
				  {
					 if (MessageBox.Show("A new version of the add-in was detected. " + 
						"Would you like to install the update?",   
						this.AddinName, MessageBoxButtons.YesNo,   
						MessageBoxIcon.Question) == DialogResult.Yes)   
					 {
						this.LaunchMSIUpdates(updateUrl);
					 }
				  }
			   } 
			}  
			

The code is based on four methods.

• IsMSINetworkDeployed - returns True if the application was installed via ClickTwice :).
• IsMSIUpdatable - returns True if the user is permitted to update the application. In Vista or Windows 7, it is always True. If the application was installed for all users and the current user is not an administrator, the UAC popup will ask for administrator credentials.
• CheckForMSIUpdates - returns an empty string if there are no updates in the location specified in the Installation URL field of the Publish dialog. If a new version of the add-in is available, CheckForMSIUpdates returns one of the following strings: a URL or UNC path (the URL can be a link to setup.exe or the application downloader), or the value specified in the Download page for updates in the Preferences dialog (see Preferences).
• LaunchUpdates - downloads and installs the updates.

Customizing ClickTwice installations

You can download Web Authoring Example (ClickTwice) . This is a C# project demonstrating the use of advanced ClickTwice features. If you write in VB.NET, you can use any C# to VB.NET code converter available on the web.

Step-by-step samples

Please check the following articles:

• Deploying an Office extension via ClickTwice :)
• Updating an Office extension via ClickTwice :)