Building a ClickOnce/MSI Hybrid Setup package

The Syndictaed Client Experiences (SCE) Starter Kit contains customizable deployment resources which address the following requirements:

1. Application upgrades - it should be easy to rapidly and robustly deliver fixes and new features
2. Bootstrapping .NET 3.0 - automatically deliver the .NET runtime to users who do not have it installed
3. Workflow integration - creating deployment packages should be an integrated part of your build process

Because no single technology address all of these needs, the SCE Starter Kit provides a hybrid ClickOnce/MSI approach for application deployment.

This document shows how to build a set up package that can be deployed to end users that will install a SCE Sample Reader, Subscription Center (if needed), and .NET 3.0 (if needed).

The package will contain:

• ClickOnce installer for a SCE Sample Reader
• Prerequisite msi installer (typically Subscription Center). This checks for and installs Subscription Center (if needed). SubscriptionCenter.msi can be found at http://windowsclient.net/wpf/starter-kits/sce/SubscriptionCenter.msi
• Hybrid msi installer. This does shell integration work that cannot be done through ClickOnce (such as registering file extensions) and adds the manifest and other such files for Sample Reader/Subscription Center integration.
• A bootstrap package that will install .NET 3.0 in the event that .NET 3.0 (or any subsequent version) is not installed.

Overview

Application Installation and Upgrades via ClickOnce

Historically, Windows applications have been deployed via MSI files. Although this technology is robust and transactional, application authors had to handle many aspects of application upgrades.

ClickOnce is a deployment technology that allows you to create self-updating Windows-based applications that can be installed as well as updated with minimal user interaction. ClickOnce deployment overcomes three major issues inherent in deployment:

• Ease of updating applications. With ClickOnce deployment, you can provide updates automatically. Only those portions of the application that have changed are downloaded, then the full, updated application is reinstalled from a new side-by-side folder.
• Impact to the user's computer. With ClickOnce deployment, each application is self-contained and cannot interfere with other applications.
• Security permissions. ClickOnce deployment allows non-administrative users to install and grants only those Code Access Security permissions necessary for the application.

ClickOnce is also well integrated into the Visual Studio development environment. Once configured, building and deploying an application update is easy.

Bootstrapping the .NET 3.0 Runtime

The application installer must detect if the runtime is installed, and if not, seamlessly install it on the user’s behalf. ClickOnce cannot be used in this case since the runtime requires administrative privileges during installation. An MSI based bootstrapper is utilized to wrap a ClickOnce deployment.

The SCE Starter Kit includes a pre-built bootstrapper with the following features:

1. Brandable - you can include your own resources to customize the installation UI
2. Progress tracking - tracks the progress of .NET installation so users know what to expect
3. Customizable slideshow - create a series of HTML based slides that are displayed during the installation process. This makes installation more interesting for the end user, and allows you to highlight the cool features of your application.

Desktop Integration

SCE apps take advantage of desktop integration. For example, when you save a story, it is saved as a custom file type. If this file type has been associated with your application, double-clicking on this file will open the file in your application. The file will also be displayed on the desktop with your application icon.

To take advantage of desktop integration, a separate installer is used to register the extensions:

1. Desktop integration – your application file type will be associated your application
2. Invoking your ClickOnce application – when a user double clicks on a file associated with your application, the system will actually invoke your application via the registered extensions.

The extensions areinstalled via an MSI during the initial install as part of the integrated installer.

Workflow Integration

Publishing and updating an application via ClickOnce is simple. The Windows Installer XML (WIX) toolkit allows you to declaratively create the MSI for the application extensions which handles desktop integration. The SCE Starter Kit contains a WIX project that requires you to change a handful of application specific definitions.

Prerequisites

This document assumes you have MSBuild and Visual Studio integration for WIX.

The necessary tools can be found at http://sourceforge.net/project/showfiles.php?group_id=105970&package_id=168888

1. Download and install the latest ProjectAggregator.*.msi
2. Download and install the latest wix.*.msi (do not download the WIX binaries or WIX sources)

Once installed you can treat .wixproj files like .csproj files. i.e. You can open them in Visual Studio or build them from the command line with msbuild.exe

Building a ClickOnce Installer

See http://msdn2.microsoft.com/en-us/library/t71a733d(VS.80).aspx for an overview of ClickOnce.
See http://msdn2.microsoft.com/en-us/library/31kztyey(VS.80).aspx for instructions on deploying an app via ClickOnce.

Before deploying your app, make sure that you have changed the appropriate properties and fields in the Sample Reader application. See the Appendix A at the end of this document for reference.

To publish your app using Visual Studio:

1. Go to the “Publish” tab found in the properties of the Sample Reader project.
2. Click on the “Options” button to bring up the “Publish Options” dialog. Make sure that the “Publish Name” field matches the “CompanyName” setting in the “Settings” tab and that the “Product Name” field matches “ApplicationName” setting in the “Settings” tab.
3. Run the Publish Wizard and publish your app to your deployment server.
4. Following the publish, follow the installer prompts in the “publish.htm” page or run the .application that is created when you publish your app. This step is necessary as you will need the ClickOnce shortcut to the application for the msi installer package later on.

Help for hosting WPF apps on a server:

1. Configure the server to be able to host WPF apps. http://msdn2.microsoft.com/en-us/library/ms752346.aspx
2. In IIS, make sure Execute Permissions is “Scripts Only”. This enable download of .exe.config. (rt click on website in IIS -> Properties -> Virtual Directory Tab)
3. Publish your ClickOnce binaries as .deploy. This will ensure that users will be able to download all necessary files during installation. To publish binaries as .deploy, click the “Options” button mentioned in the above step #2 and make sure “Rename all application files using the ‘.deploy’ file extension” is checked.

Building the Hybrid MSI Installer

ClickOnce has a limitation with shell integration. ClickOnce applications cannot receive command line arguments and therefore cannot register as handlers for file types. A workaround is to register a helper executable that:

1. Is invoked with a command line
2. Writes the command line to a shared location
3. Invokes the ClickOnce application which will read and delete its command line from the shared location.

The hybrid installer is an MSI that registers such a helper executable (SceDfshim.exe) on behalf of a ClickOnce application and then launches the applications ClickOnce installer.

SceDfshim.exe is invoked with SceDfshim.exe <clickonce-shortcut> <scereader-application-path>\cmdline.txt <arguments>

The Sample Reader application then launches and reads <scereader-application-path>\cmdline.txt for its command line.

To build the hybrid msi:

1. Open x:\bar\code\Setup\HybridInstall\HybridInstall.sln in Visual Studio (Release config).
2. Copy the Sample Reader Start Menu shortcut from the Programs menu (the shortcut should have a .appref-ms extension) to x:\bar\code\Setup\HybridInstall
3. Populate\change the appropriate fields as indicated in Appendix B of this document.
4. Specify the name of the msi package by going to the "General" tab in the properties of the HybridInstall.wixproj and specifying "Output name". Make sure that "msi" is selected as the output type.
5. Build the project. It should output an msi package x:\bar\code\bin\Release\NameOfYourMSI.msi

   Please note that sometimes the WiX project fails to open in VS. If you encounter this issue, you can work around it by opening the .wxs file in Notepad, making the appropriate edits, and then building the solution with msbuild using the command line with the command "[%Windir%]\Microsoft.NET\Framework\v3.5\MSBuild.exe /t:rebuild /p:Configuration=release HybridInstall.sln". The output can be found in ..\..\bin\Release

To build an upgrade hybrid msi:

This enables you to create a new hybrid msi that will install over a previous installation. For more details on the definitions and mentioned below, see appendix B.

Run the steps to build a hybrid msi detailed above and make sure you change:

• ProductCode guid definition
• ProductVersion definition (make sure you change major or minor entry i.e. 1.0.0.0 -> 1.1.0.0)
• ProductDescription definition (i.e. Sample Reader 1.0 -> Sample Reader 1.1)

Creating the Bootstrapped Package

Included in the Sample Reader project is a bootstrapper that downloads and installs .net 3.0 if needed. To generate a bootstrap package from your MSI installer:

From a Visual Studio command prompt:

1. cd x:\bar\code\Setup\Bootstrapper
2. build.cmd <optional-path-to-prerequisite-msi> <path-to-input-msi> <path-to-output-exe>
   
   <path-to-output-exe> is the .exe that will be generated by build.cmd
   
   e.g. build.cmd SubscriptionCenter.msi
   ..\..\bin\Release\SampleSceReaderSetup_v1.0.msi
   ..\..\bin\Release\SampleSceReaderSetup_v1.0.exe
   
   SubscriptionCenter.msi can be downloaded here. (Right-click on the link and select “Save Target As” and save as SubscriptionCenter.msi)

Branding the Bootstrapped Package

x:\bar\code\Setup\Bootstrapper\src\BootStrap\install.1033.xml contains an install script that describes what the branding assets are and how the installer is to use them.

x:\bar\code\Setup\Bootstrapper\src\Branding\... contains all the branding assets for the bootstrapped installer. They are basically html files and images that can be edited or replaced. More adventurous souls may even add extra files to the branding folder but will have to update the manifests x:\bar\code\Setup\Bootstrapper\src\Bootstrap\install.1033.xml and x:\bar\code\Setup\Bootstrapper\src\PrologSetup.exe.sed.

The .sed file is an IExpress script that generates the moral equivalent of a self extracting zip archive

What Should I customize or brand?

Everything. All the customization points exist in the files below and are pretty well commented in the files themselves. Just open them browse and edit whatever makes sense.

1. x:\bar\code\Setup\Bootstrapper\src\Branding\...
2. x:\bar\code\Setup\Bootstrapper\src\Bootstrap\install.1033
3. x:\bar\code\Setup\Install\Install.wxs

Appendix A - What to edit in SceReaderSample.csproj

Open the Sample Reader solution, right click on SceReaderSample project, and select “Properties”.

1. Settings Tab
   • ApplicationName - A string that represents the application name. This setting will affect the location of the application data directory.
   • ChannelPortName - A string that represents a unique name for the channel that the application uses to connect to the Subscription Center. It is up to you to guarantee the uniqueness of this value. In general, a name that combines the application name and publisher name is sufficient.
   • CompanyName - A string that represents the name of the company that is publishing the application. This setting will influence the location of the application data directory.
   • DataFeedUri - A string that points to the location of the master feed.
   • DataUpdateFrequency - The frequency (as a System.TimeSpan value) at which the application checks for feed updates.
   • SavedDataExtension - The file extension used to save stories to disk. This file extension is also used when sending stories in e-mail from the application. When you create an installer package, make sure that this file type is associated with the application.
2. Application Tab
   • Assembly name – The name of your assembly should be unique.

Appendix B - What to edit in HybridInstall.wxs

1. Replace any "PUT-GUID-HERE" with a unique guid.
   
   Once you deploy an MSI you will need to keep records of the MSI’s GUID for as long as you support the application.
   

   WIX expects unique GUIDs of the form aabbccdd-eeff-gghh-iijj-kkllmmnnoopp where each letter pair is a hex number. See http://msdn2.microsoft.com/en-us/library/ms241442(VS.80).aspx for creating GUID’s from within the Visual Studio IDE. Alternatively http://www.somacon.com/p113.php has a nice online GUID generator

2. Definitions: At the top of Hybrid.wxs there are several definitions. Every definition should be customized to provide the best installer. The following are the most important definitions and a guideline as to how they should be changed to create a unique, valid hybrid msi installer. See HybridInstall.wxs for more detail.
   • ClickOnceUri – The path to the sample reader .application on your deployment server.
   • FeedUri - Path to the master feed for the sample reader application. Needs to match the DataFeedUri setting in the Settings tab of the Sample Reader application's project.
   • PublisherName - Needs to match the CompanyName setting in the Settings tab of the Sample Reader application's project.
   • PublisherPath - Needs to match the CompanyName setting in the Settings tab of the Sample Reader application's project.
   • ApplicationName - Needs to match the ApplicationName setting in the Settings tab of the Sample Reader application's project.
   • ProductName - This names the hybrid msi installer as seen in Add/Remove programs.
   • ProductPath - Needs to match the ApplicationName setting in the Settings tab of the Sample Reader application's project.
   • ProductExe - The name of the ClickOnce shortcut for the Sample Reader application.
   • DocFileExtension - Needs to match the SavedDataExtension setting in the Settings tab of the Sample Reader application's project.
   • DocProgId - Make this a unique name.
   • DocContentType - Make the .story name unique.