Creating a standard setup project using WiX Designer

Today, I’ll walk you through how to use the Designer for WiX Toolset to create a standard WiX setup package for a desktop application. Along the way, we’ll utilize the user interface editor to add a custom screen to the installer.

KEY ASSUMPTION #1: I assume for this exercise that you already have an application ready to go. If not, all you need to do is create a WinForm application… or better yet, an Add-in Express based COM Add-in project. After you do this, you are ready to proceed.

KEY ASSUMPTION #2: You have downloaded and installed the WiX Designer. Here’s is a download link:
www.add-in-express.com/downloads/wix-designer.php

KEY ASSUMPTION #3: You have downloaded and installed the WiX Toolset.

• Add a WiX Setup Project to your solution
• Making required modifications to the WiX template
• Edit the File System
• Modify a WiX setup package using a familiar VS method
• Build the WiX setup project, test, and revise until ready

Add a WiX Setup Project to your solution

With Visual Studio open and desktop application in-hand, we need to add a WiX Setup Project to the solution. You can do this by….

1. Right-clicking the current solution and clicking Add > New Project from the context menu.
2. In the Add New Project dialog, click the WiX Toolset node. Then select the Setup Project template.

3. Name your WiX setup project whatever you like (I’m keeping the default name of SetupProject1) and click OK to add the setup project to the solution.

Visual Studio will add the setup project and open the Product.wxs file.

Making required modifications to the WiX template

In a perfect world, this step would not be needed. But this is not a perfect world and we don’t control the WiX template. Thus, a couple of modifications are needed before proceeding as you might expect. After you make these changes, you can fully utilize the WiX Designer’s feature set in the manner you expect with VDPROJ setup packages.

Edit Product.wxs

Now is a good time to mention that you need to make a small edit to Product.wxs. Here is the before and after of the relevant XML:

This small modification will produce a single .msi file when you compile your WiX setup project. If you do not make this modification, the build process will create a separate .CAB file.

Note, you will always need to make this change as the WiX template omits the EmbedCab attribute by default.

Edit the File System

The WiX Designer exists to allow you to build WiX-based setup packages without any need to be a WiX expert. That said, a partnership must exist between the developer and the WiX Designer. Meaning, you need to use the WiX Designer’s File System Editor to change the target installation folder.

To change the target folder, complete these steps:

1. In the Solution Explorer window, right-click the SetupProject1 project. In the context menu, select View WiX Editors > File System Editor.

2. In the File System Editor, right-click the Program Files Folder and click the Delete command. Be sure to keep the Application Folder.

3. Now select the Application Folder and change its DefaultLocation property.

You want to use tokens to define the folder location. The tokens are self explanatory and you can build a folder structure according to your requirements. Above, I’ve specified what I believe to be a best practice for a per-machine (or all users) installation. If you want to change the install to per user, you need to use the LocalAppDataFolder token instead of ProgramFilesFolder. For the sake of comparison…

• Per-Machine install: [ProgramFilesFolder][Manufacturer]\[ProductName]
• Per-User install: [LocalAppDataFolder][Manufacturer]\[ProductName]

With these edits complete, you can now proceed in the same manner as you would with the (now) old Visual Studio setup projects (.VDPROJ).

Modify a WiX setup project using a familiar Visual Studio method

If you have built one or more setup packages using the ever-so-sadly-deprecated Visual Studio setup project, all the following will be familiar to you. I want to point out that this is the magic of the WiX Designer. There is no learning curve. Do you doubt me? Let’s go through some of the editors.

Using the File System editor to referencing project output

Open the File System editor by clicking its icon in the Solution Explorer:

Of course you can also right-click and use the context menus as I explained previously.
Within the editor, right-click the Application Folder and select Add > Project Output to display the Add Project Output Group dialog box.

In this dialog, select the Primary Output and click OK. You have now added your application’s DLL or EXE. During install, it will reside in the location you set in Application Folder’s DefaultLocation property (set earlier).

Adding additional screens to the setup project

Click the User Interface editor icon…

…and you will see the default screen flow for the WiX setup is plain jane vanilla…

What you see is the screen flow for two types of installations: standard and administrative. You can create different screen flows for each or make the match. It’s up to you!

Let’s add a Welcome screen to the Start task:

1. Right click the Start node under Install.
2. Click the Add Dialog menu option to show the Add Dialog dialog box (I did that on purpose).
3. In the dialog, find and select the Welcome screen and click OK.

1. Be sure the new screen is the active selection and take a look at the property window to notice the three properties available for this screen. Leave their values as the defaults.

The properties vary by screen, so be sure to take a look at the options available to you and customize them to suit your requirements.

Registry editor

Adding registry keys is a common scenario and our Registry Editor allows you to specify registry entries in a few quick steps:

1. Open the Registry Editor by clicking its icon in the Solution Explorer window.

2. Right-click the HKEY_CURRENT_USER node and click the Key option.
3. Name the new key MySampleApp.
4. Right click the newly created MySampleApp key and click String. Rename this string to URL.
5. In the Properties window, change URL’s Value property to https://mysampleapp.com.

This is just what you expect – a simple way to create registry entries for your application.

Custom actions

Click the Custom Actions Editor icon to open the editor.]

The Custom Action editor allows you to specify actions the installer should take during different stages of the installation.

As you see above, you can add actions to the Install, Commit, Rollback, and Uninstall stages. To add a custom action, you first need a custom action in the form an EXE, DLL, VBS, or JS file. Let’s add a custom action to the Install step.

1. First, we need a custom step. For our purposes, a DLL will do. Add a new Class Library project to your solution and name it MyInstallAction. Go ahead and build it.
2. Open the File System editor and add the MyInstallAction output to the Application Folder.

3. Open the Custom Actions editor (or return to it).
4. Right-click the Install node and click Add Custom Action.
5. In the Select Item in Project dialog, choose the Primary Output from MyInstallAction and click OK.

Build your WiX setup project, test, and revise until ready

With these configurations, you now have the base for a solid setup package. Now the real work begins as it is ready for you to compile and test (and revise and repeat). As you learned in the walkthrough, the WiX Designer fills the void left Visual Studio dropping support of setup projects. With our tool, there is very little learning curve and you can build WiX setup packages using a familiar method.

Available downloads:

Sample WiX setup project