Client Profile Configuration Designer “How To” Series – Configuring the UI (Part 1 of 4)

Creating the Project

Creating a setup project is as easy as clicking File, New. Specify the company and product name, which will be used to generate default settings. A subfolder will be created in the specified location:

An empty project with default settings will be created:

The process to create a complete setup package looks as follows:

1. Define the UI experience for the installation.
2. Configure settings for the installation.
3. Add prerequisites to the installation, e.g. the .NET Framework Client Profile.
4. Add installers to the chained installation, e.g. a Windows Installer file, an executable setup package or a ClickOnce deployment URL.
5. Build the package using the integrated MSBuild support.
6. Deploy the package.

We’ll walk through each of these steps below.

Define the UI Experience for the Installation

The UI experience is defined through a built-in designer, allowing customization of all “pages” displayed during setup:

Using the buttons in the toolbar on top of the tree view, pages can be hidden from setup. Only the Progress page is mandatory. We’ll start by taking a look at the Common settings that acts as the “master page” for setup.

Notice how the tabs on top of the designer correspond to the pages displayed in the tree view. A break-down of the designer:

• Tabs allow developers to navigate between designers for the individual pages.
• The colored bar on the left indicates possible localization conflicts that occur because of alignment properties.
• At the bottom, the user can toggle between Designer and Markup mode. The latter shows the skin representation that will be consumed by the bootstrapper.
• In the bottom right corner, localization can be configured.

Below the Markup view is displayed:

This view is read-only; all customizations need to be applied through the designer, which exposes all customization points that are available.

We’ll begin by redesigning the Common settings first. Selecting a UI-element in the designer populates the property grid in the bottom right corner of the tool:

For example, we can change the title caption’s Text property or the Font. Notice that caption elements can be localized by toggling the localization bar below. This way, string tables can be generated for all cultures that the user wants to support for the generated setup package. We won’t use localization in this particular case, but the dialog to add or remove cultures looks as follows:

Back to the Common settings, we want to add a background image to the project. To do this, click somewhere on a non-occupied place in the designer, and go back to the property grid:

Click the ellipsis button and select an image. After some straightforward drag-and-drop operations we end up with the following Common settings:

On the Pre-installation page, we rearrange and resize a few controls and end up with:

This also illustrates the localization conflict indication. As the Accept and Decline buttons grow to the left – since they are right-aligned and “anchored” to the right border of the window – and the Print button grows to the right – since it is left-aligned and “anchored” to the left border of the window, a localization conflict can occur if the strings for “Print”, “Accept”, “Decline” grow. In this particular case, the risk for such a conflict is low as there’s enough space between the controls, but similar problems can occur when rearranging the positioning of captions and other controls.
Similarly we design the Progress page:

This one is a bit special because of format strings being used for the caption. In this case, a place-holder is required for the installation percentage, which is populated by a sample value of 20. The use of format string is illustrated on the right (%g stands for global percentage, which is the weighed aggregate of installation and download percentages).

On this page, we also can use a browser control – which by default is enabled, it was already removed in the screenshot above (removing a control can be done using DEL or by setting the Visible property to False) – to display any sequence of HTML pages at runtime. Upon selection of a browser control, a task pane is displayed on the right-hand side of the designer:

Using the toolbar at the top, pages and supporting files (e.g. images, CSS files) can be added to the browser. In addition, the order of pages can be modified and the repeat setting can be toggled. The page flipping period can be configured through the property grid:

The pages displayed in the browser are added on a per-culture basis. Below is an illustration of adding pages to the browser control, including a support file (the image displayed on the page). Selecting a page shows a live preview in the browser control and the file can be tweak using Notepad by right-clicking the page in the task pane and selecting “Edit with Notepad”.

We won’t cover the rollback page, error page, cancelled page or reboot page as those are trivial to design and move on to the Finish page instead:

Here we have on additional control at our service to allow the user to start the installed application when clicking the finish button. This control only works when corresponding settings are made in the payload authoring, as we’ll discuss further on. To complete our coverage of the UI designer, a couple of additional features are outlined below:

 

• Grid lines can be enabled through the toolbar to aid in positioning of controls.
• Alignment can be controlled through the toolbar as well, while alignment on selected controls is indicated by a little adorner.
• Locked controls are indicated using adorners. Controls from the Common settings are locked when designing other setup pages.
• The positioning information is shown below in the status bar. The position indicator also reveals the alignment.

Previewing the UI

Now we’re ready designing the UI, we can invoke the setup debugger to get a preview.
To launch the preview, press the first button in the build and debug toolbar:

Invoking the preview mode actually builds the entire setup package, looping in a special product definition that contains a debugger installer that will communicate with the tool over a named pipe to control the transitioning between setup pages. This said, the real bootstrapper is used to provide the preview, in order to provide a WYSIWYG experience.
At the bottom of the window, the feedback from MSBuild is displayed in the Output window:

Once the build completes successfully, the debugger toolbar becomes visible:

The buttons will be used to control the display of various pages. For example, pressing Succeed will cause setup to transition to the Finish page, while Fail will inject a failure in the debuggee causing setup to transition to the Error page. The (immune) reboot page can be brought up similarly.

In the meantime the bootstrapper will have started, displaying our UI definition for the Pre-Install page (if we have defined one obviously):

When clicking accept, the installer will move to the Progress page and the designer will switch to the same page so that the user can do a designer-to-runtime comparison making sure everything is rendered as expected. The debugger toolbar will now be fully available:

Waiting for an answer from the debugger, the Progress page will move to 100% and stay there till the user chooses the following action by clicking any of the three action buttons on the toolbar.

For example, we click Succeed setup and the debugger will move to the Finish page:

Clicking Finish terminates the debugging session. We’re now confident the UI definition is what we like it to be and can move on to configure the payload settings for our setup package.