Ty Anderson

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

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.

Adding a WiX Setup Project to your solution

  1. 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:

Before After
<MediaTemplate /> <MediaTemplate EmbedCab=”yes”/>

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.

In the context menu, select View WiX Editors and then click File System Editor.

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

Delete the Program Files Folder.

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

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:

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.

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…

Click the User Interface editor icon.

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

The screen flow for two types of installations: standard and administrative

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.

Adding a Welcome screen to the Start task

  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.

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

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

In the Properties window, change URL's Value property to http://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.]

Click the icon to open the Custom Actions Editor.

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

The Custom Actions Editor

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.

Open the File System editor and add the MyInstallAction output to the Application Folder.

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

In the Select Item in Project dialog, choose the Primary Output from MyInstallAction.

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

19 Comments

  • https://secure.gravatar.com/avatar/1009ae929075f340cc9ee56d7ef8bb15?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G Robert Campbell says:

    Build error on the sample project: (the VDWExtension.dll is in the expected location on my system). I wondered if that double backslash is an issue?

    ‘…bin\\VDWExtension.dll’

    The extension ‘C:\Program Files (x86)\WiX Toolset v3.8\bin\\VDWExtension.dll’ could not be loaded because of the following reason: Could not load file or assembly ‘file:///C:\Program Files (x86)\WiX Toolset v3.8\bin\VDWExtension.dll’ or one of its dependencies. The module was expected to contain an assembly manifest.

  • https://secure.gravatar.com/avatar/ab4ec2858cfdf1e44dadf8c50fae314d?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G Dmitry Kostochko (Add-in Express Team) says:

    Hi Robert,

    Please add the VDWExtension.dll extension to the References section of your setup project. You can find the extension in the following folder:

    if you have WiX 3.x installed:
    “WiX_Designer_Installation_Folder”\Bin\WiX Extensions\v3.x

    if you have WiX 4.x installed:
    “WiX_Designer_Installation_Folder”\Bin\WiX Extensions\v4.x

  • https://secure.gravatar.com/avatar/110c21b358b357cd10986982defcadd5?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G Noufal says:

    Is it possible to create a Patch file using Wix Toolset designer?

  • https://secure.gravatar.com/avatar/ab4ec2858cfdf1e44dadf8c50fae314d?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G Dmitry Kostochko (Add-in Express Team) says:

    Hi Noufal,

    The current version of WiX Designer supports Setup Project (.msi) and Merge Module Project (.msm) only.

  • https://secure.gravatar.com/avatar/5c23196274a9bfafbabdd7b1b708e705?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G Jose L Castellanos says:

    Hey, Just purchased Wix designer. Works almost perfect like in the video.
    I’am a little lost. Whats next after we finish with this tutorial?
    How to actually compile the exe?

    2. I get an error saying : “Could not find Schema information for the attribute ‘http://schemas.add-in-express.com/wixdesigner:VSName”

    How to solve it?!

    Thanks in advance

  • https://secure.gravatar.com/avatar/29957f26ad2d8ba527fd9cc8cfa7b2e0?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G Andrei Smolin (Add-in Express Team) says:

    Hello Jose,

    To create a bootstrapper, start the editor of the Prerequisites property of your setup project.

    #2. You need to add a reference to {WiX Designer installation folder}\Bin\WiX Extension\{v3.xx or v4.xx}\VDWExtension.dll.

    You can ask your questions on the forum at https://www.add-in-express.com/forum/list.php?FID=11 or send them to the support email address, see {WiX Designer installation folder}\readme.txt.

  • https://secure.gravatar.com/avatar/83ce31b09e6c3b38ae5ad886f87bbced?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G Costanzo Ferraro says:

    I just purchased Wix designer, it works perfectly.
    Now, I would like to create an uninstall shortcut for my application, but I don’t know how to do it? Any suggestion? Are there some articles?

    Thanks in advance

  • https://secure.gravatar.com/avatar/29957f26ad2d8ba527fd9cc8cfa7b2e0?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G Andrei Smolin (Add-in Express Team) says:

    Hello Costanzo,

    Thank you for choosing the WiX Designer!

    This product mimics the UI and behavior of the Visual Studio Installer. This let’s you seek for a numerous posts about that product and use them with the WiX Designer. I’ve googled out this page: http://stackoverflow.com/questions/3303962/visual-studio-deployment-project-create-shortcut-to-deployed-executable. I’ve tested the suggestions posted in the first answer (by roman m): installing and uninstalling my test application creates the shortcut on the Desktop and removes it as expected.

  • https://secure.gravatar.com/avatar/83ce31b09e6c3b38ae5ad886f87bbced?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G Costanzo Ferraro says:

    Thanks a lot, Andrei,
    Wix Designer looks like stronger and stronger!
    Now I have a new problem:
    I want to install multiple instances of the same application on my machine.
    Also in this case, I need some articles (the Designer’s PDF Manual is very limited). Can someone help me?

    Thanks a lot

  • https://secure.gravatar.com/avatar/29957f26ad2d8ba527fd9cc8cfa7b2e0?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G Andrei Smolin (Add-in Express Team) says:

    Hello Costanzo,

    The manual is about creating setup projects using the WiX Designer. It doesn’t describe the options that MSI provides. I don’t understand your goal. Could you please provide more details? Why would you need this at all? How would you uninstall and upgrade these applications? If I install an application, I’ll have a folder where it is located, a shortcut on the desktop; why would I need another application? What occurs if the end-user installs the application to the same folder multiple times?

  • https://secure.gravatar.com/avatar/83ce31b09e6c3b38ae5ad886f87bbced?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G Costanzo Ferraro says:

    Hello Andrei,
    I simply need to install multiple instances of my application saving them in different folders, with no shortcut on desktop.
    In other words, when the App is already installed in a Folder, if I double-click the .msi file once again, the installer shouldn’t ask me if I want repair or remove my App, but it simply should permit to install it in a new folder.
    How can I solve this problem?

    Thanks in advance

  • https://secure.gravatar.com/avatar/29957f26ad2d8ba527fd9cc8cfa7b2e0?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G Andrei Smolin (Add-in Express Team) says:

    Hello Constanzo,

    I don’t know if it is possible to achieve this. I would try to set DetectNewerInstalledVersion=False and RemovePreviousVersion=False. If this doesn’t help I would recommend asking the same question in a WiX discussion group and apply their suggestions to the Product.wxs file.

  • https://secure.gravatar.com/avatar/83ce31b09e6c3b38ae5ad886f87bbced?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G Costanzo Ferraro says:

    Hello Andrei,
    I tried but it doesn’t work, unfortunately.

  • https://secure.gravatar.com/avatar/29957f26ad2d8ba527fd9cc8cfa7b2e0?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G Andrei Smolin (Add-in Express Team) says:

    I recommend that you ask the same question on a WiX discussion forum as suggested. Alternatively, you could google for a solution.

  • https://secure.gravatar.com/avatar/29957f26ad2d8ba527fd9cc8cfa7b2e0?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G Andrei Smolin (Add-in Express Team) says:

    See https://msdn.microsoft.com/en-us/library/aa369523%28VS.85%29.aspx: “If a product code remains unchanged, only one instance can be installed in the machine context and only one instance can be installed in each user context.”

  • https://secure.gravatar.com/avatar/83ce31b09e6c3b38ae5ad886f87bbced?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G Costanzo Ferraro says:

    I am creating a new installer, and in User Interface I have added a RadioButton with 3 Buttons. Is it possible to add in UI another one with the number of Buttons?

    Thanks in advance,

  • https://secure.gravatar.com/avatar/29957f26ad2d8ba527fd9cc8cfa7b2e0?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G Andrei Smolin (Add-in Express Team) says:

    Hello Costanzo,

    No, creating two instances of any of the RadioButons dialogs isn’t supported.

  • https://secure.gravatar.com/avatar/593b2576ab6f85b206c56d0409794a96?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G Dave Spicer says:

    After many wasted hours, I just can’t custom actions to work at all.
    Your example of creating a custom action is less than useful: it has no methods in the example, makes no mention of the new Wix custom action project, neglects to talk about the Custom Action properties like EntryPoint and Installer class, plus I’m confused aas to whether the .CA.Dll created by Wix comes in play ? Can you provide a working example of a “real” custom action, and not just an empty class definition?

  • https://secure.gravatar.com/avatar/29957f26ad2d8ba527fd9cc8cfa7b2e0?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D32&r=G Andrei Smolin (Add-in Express Team) says:

    Hello Dave,

    This article does *not* describe creating a *WiX* custom action project. On how to deal with such a project see e.g. https://www.add-in-express.com/creating-addins-blog/2014/01/29/create-wix-custom-actions/. This article *does* describe creating a regular custom action DLL that uses the InstallerClass component, see e.g. https://msdn.microsoft.com/en-us/library/d9k65z2d(v=vs.100).aspx.

Post a comment

Have any questions? Ask us right now!