Client Profile Configuration Designer "How To" Series – Configuring the UI (Part 3 of 4)
Configuring the Setup Payload
Now that we have designed the installation experience for the setup package,
we can move on to the payload side. This is divided in three distinct areas:
- Package-wide Settings
Used to configure settings such as the product code, uninstall support, web deployment settings, license agreement, automatic launch of an application after setup and install conditions.
- Prerequisites
Allows the import of preconfigured products the application depends on, like the .NET Framework 3.5 SP1, the .NET Framework Client Profile, or any prerequisite that’s available from the Windows SDK.
- Chained Installers
Multiple setup binaries can be configured for sequential installation, supporting EXE, MSI and ClickOnce packages.
We’ll spend some time exploring those three areas.
Package-wide Settings
When selecting Setup package in tree view at the left of the Payload editor, all the configurable settings are displayed in the form of collapsible regions.
We’ll cover all of those briefly. More information about particular settings can be found on MSDN.
General Settings
Used to configure the product code, which is the unique identifier for a product, and the reboot behavior:
Uninstall Support
The bootstrapper supports “chained uninstall” where installed products can be uninstalled completely. For example, when chaining a couple of MSIs together, the “chained uninstall” support can aggregate the uninstall of those MSIs by means of a single Add/Remove Programs (ARP) entry that invokes a cached copy of the bootstrapper, uninstalling the (marked) installers in reverse order. Use of an ARP entry is optional as the uninstaller can be invoked from the command-line as well.
Enabling/disabling uninstall support over here will also enable/disable more granular uninstall settings for the individual chained installers. In other words, this is a global setting.
Notice the pushpins next to several Add/Remove Programs fields. These indicate the fields that are localizable. When the pushpin is pressed, the field won’t get localized (e.g. if the application title doesn’t require localization).
Note: Enabling chained uninstall doesn’t automatically suppress possible ARP entry creation by individual chained installers. Using command-line arguments the creation of an ARP entry should be suppressed manually. For Windows Installer packages, this can be achieved by setting "ARPSYSTEMCOMPONENT=1" as a command-line argument for the installation (see further).
Web Deployment
This global setting makes it possible to publish the setup package to a web server when it’s built. Two options are available: FTP and file share publication. Below we’ll use FTP to illustrate this functionality. First we specify the publication URL, which is used by the bootstrapper to download setup packages at runtime. Next, the folder corresponding to that publication address needs to be selected.
Finally, we can enable the creation of a link page which will cause the build system to create an HTML page linking to the uploaded setup.exe self-extracting executable.
Once we’ve enabled those settings, an additional build flavor will become available in the build dropdown in the toolbar.
We’ll explore publication a bit more at the end of this tutorial.
License Agreement
License agreements can be selected on a per-culture basis and are optional.
Note: If no license agreement is included, and none of the prerequisites included a license agreement, but a Pre-installation page has been included, that page won’t be shown at runtime.
Launch Application after Installation
To launch an application automatically upon (successful) completion of the installation, a location of an executable on the target machine can be specified, as well as command-line arguments. To specify such a location, shell variables need to be used to ensure correctness across target machines, e.g. by using %ProgramFiles%.
When this setting is enabled but the Finish page doesn’t include a "Start application" checkbox, the application will be started always. Similarly, when no Finish page is included, the application will always start. Obviously, when having a Finish page with "Start application" checkbox, the user is in control.
Install Condition Declarations
Declaration of install conditions is an advanced feature, allowing to control the behavior of the bootstrapper with regards to the installation of individual chained installers. This global setting allows declaring install conditions that will be used on a per-installer basis to define install checks. Essentially, install conditions retrieve values from the system that will be used in comparisons to determine behavior on individual chained installers.
Although we don’t use this feature directly for the Configurator setup itself, we’ll give a quick overview of supported types:
File Checks
Recursively searches for a file in a certain (relative or absolute) folder. The version of the file found can be used in an install check.
Registry Checks
Retrieves a value from the registry that can be used in an install check to compare it with a certain value, or for an existence/non-existence based check.
The tool contains a mini read-only registry editor to help selecting a registry key.
Registry-to-file Checks
Uses a value found in the registry as a pointer to a file which is subsequently used in a file check.
Windows Installer Checks
Checks the presence of a certain Windows Installer on the machine.
To obtain the product code, a Windows Installer Product browser is included in the tool:
Global Assembly Cache Checks
A Global Assembly Cache check determines the presence of an assembly in the GAC.
The tool includes a local GAC browser to extract an assembly’s info easily:
External Checks
An external check is an executable that gets included in the setup package whose execute code can be used in an install check to determine installation behavior. This allows custom logic to be used for install checks.
Prerequisites
Prerequisites are pre-defined products that get installed before the chained installers are executed:
Clicking the Add prerequisite dialog shows a list of available and currently included prerequisites:
The prerequisites displayed in the dialog are populated from three locations:
- The current user’s "Documents\Client Profile Configuration Designer\Packages" folder.
- The tool’s layout reference folder’s "Packages" subfolder, as pointed at in
| Key: |
HKLM\SOFTWARE\Microsoft\AH Setup Designer |
| Value: |
LayoutReference |
- The Windows SDK’s storage location for generic bootstrapper packages, as pointed at in
| Key: |
HKLM\SOFTWARE\Microsoft\GenericBootstrapper\3.5 |
| Value: |
Path |
For the Configurator’s setup project, we’ll select .NET Framework 3.5. Notice this automatically calculates dependencies and inclusions:
Pressing OK will import the prerequisites by physically copying the files that make up the definition of the prerequisites and any dependent files to our project folder:
We copy the prerequisites over so that the project becomes self-contained and we can build it on whatever machine that has MSBuild and the setup build targets and tasks installed.
Once the prerequisites have been imported, the install order displayed in the tool will show up the inferred installation order:
Chained Installers
Next we’ll add chained installers to our package. There are four supported types of packages we can add:
- Windows Installer .MSI files.
- Setup executables, such as self-extracting executables.
- ClickOnce deployments, specifying the URL to the .application file.
- Loose packages (see further).
We’ll start by adding the self-extracting EXE containing the Configurator’s setup MSI and supporting files that were built using Decatur.
When pressing OK, the file will be copied to our project, also inferring some security settings (see further):
The new install order now looks like:
Obviously the chained installers appear in the list after the prerequisites (what’s in a name?).
Now we can configure the installer-specific settings:
General Settings
Depending on the type of the imported installer, some of the following configuration options will be available:
Setup Package
Allows re-importing the setup package. In addition, the package can opt-in to chained uninstall if enabled on the global package level (see earlier):
File Security
The bootstrapper can carry out file verification before attempting to install. Using “File security” the public key (for Authenticode signed packages) and SHA1 hash can be specified or calculated (this happens automatically).
Web Deployment
If you don’t want to deploy the package in the generated self-extracting executable – to optimize for download speed – each individual package file can be marked for download from a server. The “Publish package during build” option is only available if the general package-wide web deployment settings are configured, as illustrated below. Otherwise, a download URL can be specified manually.
Install Settings
For install settings, four configuration options are available:
Install Settings
Here the install arguments and log file name can be specified. The log file is most useful for ClickOnce or MSI packages. In this particular case, we specify /x:. as the install argument to extract the self-extracting EXE to the working directory. This will allow us (see further) to subsequently invoke the MSI that’s inside the self-extracting EXE.
Install Progress Calculation
The boostrapper calculates overall setup progress based on settings for the individual commands across all products. Therefore it’s important to provide an accurate installation size (in bytes) as this is used as the primary mechanism to weigh the contributions of individual installer to the overall progress.
For executable packages, the progress bar space is filled based on a timer-based heuristic. As we’re just extracting a couple of megabytes, we set this to 5 seconds.
Exit Codes
The exit code of an installer invocation determines the action the bootstrapper should take subsequently. We accept the default settings where 0 indicates success and the default (any code not specified above) is Failure. Valid result actions are Success, Success and Reboot, Failure and Failure and Reboot. All messages that can be specified here are also localizable through the IDE with the aid of the localization bar aforementioned.
Install Conditions
We won’t use install conditions for the Configurator setup for illustrative purposes, here’s a sample of how to declare an install condition. The properties listed in the grid are built-in properties in addition to the ones defined earlier with the “Install conditions declarations” functionality on the global package level.
Uninstall Settings
Uninstall settings on the level of chained installers are only available if:
- The global settings enable uninstall support
- The package opts in to uninstall (see General Settings -> Setup Package)
We don’t use chained uninstall for the Configurator as we’re in the degenerate case of having only a single MSI which can control its own uninstall. Assuming we did opt-in to it, those are the uninstall settings available: