How to add custom dialogs in WiX installers

The WiX toolset provides a number of built-in dialogs that should be adequate for most installers. If, however, you need more flexibility when it comes to your MSI installer’s user interface, WiX provides the ability to build a custom UI of your setup project.

In this article, we’ll build a custom WiX setup project that will use the modern/metro style look and feel.

When the user clicks on the “Install Now” button, they will be prompted to enter their full name and email address.

Lastly, we’ll show a dialog to indicate the progress of the installation:

The WiX setup project

We’ll assume we already have an application for which we need an installer and only focus on creating the setup project. Start by creating a new WiX Setup project in Visual Studio:

The project wizard will create the initial Product.wxs WiX source file. For now we’ll only add a Feature element and a Fragment element that contains the product components. Change the mark-up in the file to the following:

Creating the first setup dialog

Next, we need to add a new WiX Installer File to the project. This file will be used to create the first dialog in the setup process.

Change the SetupDialog.wxs Installer file’s mark-up to the following:

<?xmlversion="1.0"encoding="UTF-8"?><Wixxmlns="http://schemas.microsoft.com/wix/2006/wi"><Fragment><UIId="SetupDialogUI"><PropertyId="Install">installbtn</Property><BinaryId="installbtn"SourceFile="images/installbtn.bmp"/><DialogRefId="ProgressDialog"/><TextStyleId="TahomaHeader"FaceName="Tahoma"Size="18"Bold="yes"/><TextStyleId="TahomaNormal"FaceName="Tahoma"Size="8"/><PropertyId="DefaultUIFont"Value="TahomaNormal"/><DialogId="SetupDialog"Width="400"Height="300"Title="Silly Software"><ControlId="background"Type="Bitmap"Text="bgPic"Height="300"Width="400"X="0"Y="0"TabSkip="no"/><ControlId="introText"Type="Text"X="75"Y="50"Width="350"Height="22"Transparent="yes"Text="{TahomaHeader}Welcome to Metro App setup."/><ControlId="explanationText"X="85"Y="100"NoWrap="no"RightAligned="no"Transparent="yes"Type="Text"Width="250"Height="100"Text="{TahomaNormal}To continue with the setup click on the Install button. If you choose not to install this application, click on the Cancel button to exit."/><ControlId="installButton"Type="PushButton"Text="[Install]"Height="62"Width="222"X="90"Y="180"Bitmap="yes"><PublishEvent="EndDialog"Value="Return"/></Control><ControlId="cancelButton"Type="PushButton"Text="[Cancel]"Height="40"Width="144"X="135"Y="245"Cancel="yes"Bitmap="yes"><PublishEvent="EndDialog"Value="Exit"/></Control></Dialog></UI><InstallUISequence><ShowDialog="SetupDialog"Before="ExecuteAction"/></InstallUISequence></Fragment></Wix>

You’ll notice that we set the UI element’s Id attribute to SetupDialogUI; this is the value we’ve specified in the UIRef Element of the Product.wxs file. Next, we have a Binary element that contains a reference to an image file in our setup project:

We’ll use this image for a button that the user will have to click to start the installation process. Next, we specify the fonts that our custom dialog will use by adding two TextStyle elements. The Dialog element is used to “build” your UI. The Height and Width attributes are required and are used to set the size of the dialog.

The Dialog element contains a number of Control elements which make up the dialog UI. The following control uses the Binary element we’ve included in the Product.wxs file to set a white background for our dialog:

You have to set the Bitmap attribute to Yes and set the Text attribute equal to the Id of the property that contains a reference to the Binary element, which in turn contains a reference to the image to use for the button e.g.:

Gathering user information

In this example, we would like the user to enter his name and e-mail address as part of the setup experience. To do this, we’ll add another Installer File to our project and call it UserRegDialog.wxs. Now, change its mark-up to the following:

<?xmlversion="1.0"encoding="UTF-8"?><Wixxmlns="http://schemas.microsoft.com/wix/2006/wi"><Fragment><UIId="UserRegDialogUI"><PropertyId="Proceed">proceedbtn</Property><BinaryId="proceedbtn"SourceFile="images/proceedbtn.bmp"/><BinaryId="headerPic"SourceFile="images/header.bmp"/><DialogId="UserRegDialog"Width="400"Height="300"Title="Silly Software : User Registration"><ControlId="background"Type="Bitmap"Text="bgPic"Height="300"Width="400"X="0"Y="0"TabSkip="no"/><ControlId="header"Type="Bitmap"Text="headerPic"Height="50"Width="400"X="0"Y="0"TabSkip="no"/><ControlId="headerText"Type="Text"X="65"Y="10"Width="350"Height="40"Transparent="yes"Text="{TahomaBig}User Registration"/><ControlId="explanationText"X="85"Y="75"NoWrap="no"RightAligned="no"Transparent="yes"Type="Text"Width="250"Height="100"Text="{TahomaNormal}Before you can use this awesome product, you need to register. If you choose not to install this application, click on the Cancel button to exit."/><ControlId="nameLabel"Type="Text"X="85"Y="120"Height="17"Width="65"Transparent="yes"Text="{TahomaNormal}Your Full Name:"/><ControlId="nameTextbox"Type="Edit"X="150"Y="117"Height="17"Width="120"Property="FULLNAMEProperty"/><ControlId="emailLabel"Type="Text"X="85"Y="140"Height="17"Width="65"Transparent="yes"Text="{TahomaNormal}Your E-mail:"/><ControlId="emailTextbox"Type="Edit"X="150"Y="137"Height="17"Width="120"Property="EMAILProperty"/><ControlId="proceedButton"Type="PushButton"Text="[Proceed]"Height="62"Width="222"X="90"Y="180"Bitmap="yes"><PublishEvent="DoAction"Value="RegistrationInfoCustomAction">1</Publish><PublishEvent="EndDialog"Value="Return">1</Publish></Control><ControlId="cancelButton"Type="PushButton"Text="[Cancel]"Height="40"Width="144"X="135"Y="245"Cancel="yes"Bitmap="yes"><PublishEvent="EndDialog"Value="Exit"/></Control></Dialog></UI><InstallUISequence><ShowDialog="UserRegDialog"After="SetupDialog"/></InstallUISequence></Fragment><Fragment><BinaryId="CustomActionBinary"SourceFile="$(var.RegistrationInfoCustomAction.TargetDir)$(var.RegistrationInfoCustomAction.TargetName).CA.dll"/><CustomActionId="RegistrationInfoCustomAction"BinaryKey="CustomActionBinary"DllEntry="SaveUserInfo"/></Fragment></Wix>

The mark-up is pretty straight forward, but the most import bit which we’ll need to pay attention to is the proceedButton Control element. You’ll notice it contains a child Publish element whose Event attribute is set to DoAction and its Value attribute is set to the Id of the CustomAction element further down in the file. This will cause the custom action to execute as soon as the user clicks the Proceed button on the UI.

The custom action will use the emailTextbox and nameTexbox control elements’ Property attribute values to save the information the user entered.

Creating the custom action

The last step will be to create a custom action that will save the user’s registration information to a text file. Add a new C# Custom Action Project to your Visual Studio solution:

In the CustomAction.cs file, change the CustomAction1 methods’ name to SaveUserInfo and add the following code to it:

This technology is now available for our custom development services only. Based on the Add-in Express for Office core, it is designed for building custom-tailored Office add-ins with far less coding than you usually have to do. Plus, it includes all Add-in Express features such as True RAD, visual designers, Outlook view and form regions, etc.

Get the best platform for building version-neutral, fast and easy deployable plug-ins by using Add-in Express projects templates, visual designers, components and wizards in combination with a perfect Delphi compiler.

This is an extension for Visual Studio that allows developers to quickly create WiX-based setup projects in a familiar Visual Studio way.

The Designer for WiX Toolset lets you forget the plain Windows Installer XML and concentrate on your deployment logic. It integrates several editors with the Visual Studio IDE and provides a set of vdproj designers to configure the file system, registry, user interface, custom actions, launch conditions and more for your setup projects.

The innovative technology for customizing Outlook views and forms. It is included in all Add-in Express for Office products and can be used to extend Outlook views, e-mail, task and appointment windows, To-Do bar, Reading and Navigation panes with your own custom sub-panes.

Microsoft and the Office logo are trademarks or registered trademarks of Microsoft Corporation in
the United States and/or other countries. All other trademarks are property of their respective owners.