Home / C# / Create an MSI/Setup Package for C# with WiX Toolset

Create an MSI/Setup Package for C# with WiX Toolset

WiX Toolset is a free installer. It is xml-based, which means that instead of a UI you can use a single xml file to create your installation package.
There is a wide choice of installers on the market, but I prefer WiX, especially when I need to distribute large applications and I’m very satisfied with it.
This installer has been used to create package for MS Office, Visual Studio, SQL Server, etc… you can find more info on Wikipedia.
Because you often see “Steep learning curve” associated with WiX toolset, here is a tutorial with the most common steps that are needed to create a basic installer package with some features.

Download sample application

You can download the sample application on GitHub.

Watch the video on youtube

Download WiX

To download Wix you can just go to WiX website (http://wixtoolset.org/releases/) and pick the last release.
When you execute the program, click on the install button in the middle to start the installation.
wix installer

Download WaX

To manage the files of the application I use a Visual Studio Extension, WaX. Files management is usually the most difficult part of WiX Toolset, but WaX makes it easy.
Just go to Tools -> Extensions and updates, then click Online and in the search bot type “wax” (https://github.com/tom-englert/Wax)
wax

Create a WiX setup project

For this tutorial let’s start from an empty Wpf application, and once we got the installer ready, we will add more features.
So the first thing is to open up Visual Studio and create a new Wpf Application (File -> New -> Project, Select Visual C# -> Windows Desktop -> Wpf application).
Now after creating the application, let’s add the Wix setup project: click on File -> Add -> Project, search for “Windows installer XML” -> Setup project.
windows installer xml

After adding the two project you should have a similar situation in your solution explorer:
solution explorer 1

Add the required files to the setup project

To manage the files in the setup project, we use Wax, which is a very simple User Interface that checks, adds and removes the files needed to be installed with the application.
Compile the Wpf application, then select Tools -> WiX Setup Editor to open WaX.
Wax2
As you can see you have 5 regions:
1) The setup project (in case you have more than 1 setup project it can handle more)
2) Root directory: select INSTALLFOLDER
3) Projects to install: here you have to select the project that you want to install in the installer. I selected the Wpf Application.
4) Directory mappings
5) File mappings: in this case, the red files are required and need to be added to the application. So we click the “+” button on the left to add the file to the setup package.

In the end we should obtaing an “all green” WaX window.wax1

Build and install the setup project

If we try to build the project, we receive a compilation error:
The Product/@Manufacturer attribute’s value cannot be an empty string. If a value is not required, simply remove the entire attribute.
To solve this, we have to locate for the Manufacturer attribute in the Product.wxs file, and fill it.

<Product Id="*" Name="SetupProject1" Language="1033" Version="1.0.0.0" Manufacturer="Mesta-Automation.com" ... />
  <Package InstallerVersion="200" Compressed="yes" InstallScope="perMachine" />

Now we can build and install the application. To find the package click with the right button of the mouse on the setup project -> “Open folder in File Explorer”, open “bin” ->”debug”, and there you have your installer file.
Double click on it to install, it will prompt for nothing and finish silently. If you check on Control panel -> Add/Remove programs, you should have the “SetupProject1” installed, and if you check on your program files folder, there you will find a SetupProject1 folder with your application inside.
Now you can uninstall it.
Also if you observe the Product.wxs file, you should be able to unterstand how it is composed and where all the informations are.

Name of the product

This is the first and most important thing that we have to change.
Locate the following line and replace the Name=”SetupProject1″ with something else, in the example I will use “MyWpfApplication”.

<Product Id="*" Name="SetupProject1" Language="1033" >

Do the same for this lime for the field Title:

<Feature Id="ProductFeature" Title="SetupProject1" Level="1">

replace the title.

Name of default folder

Locate the following line and replace Name=”SetupProject1″ with Name=”MyWpfApplication” (or the name of your application).

<Directory Id="INSTALLFOLDER" Name="SetupProject1" />

Now you can build and install, same as before, to find the package click with the right button of the mouse on the setup project -> “Open folder in File Explorer”, open “bin” ->”debug”.
If you check Control panel -> Add / Remove programs, you will see that there is MyWpfApplication instead of SetupProject1, and the same in the folder inside Program Files, you will find “MyWpfApplication”.

Shortcuts

To add the shortcuts we need to add two components, one for the shortcut in the desktop and one for the start menu.
We can follow the WiX toolset manual to do thess tasks: http://wixtoolset.org/documentation/manual/v3/howtos/files_and_registry/create_start_menu_shortcut.html
This can be a quite obscure part at this point of the tutorial, so just copy and paste the xml. At the end you can probably figure out how WiX works and what this code does.
Locate the line:

<Feature Id="ProductFeature" Title="MyWpfApplication" Level="1">
  <ComponentGroupRef Id="ProductComponents" />

and add the definitions of the two new componenents (one for the start menu shortcut, one for the desktop)

<ComponentRef Id="ApplicationShortcut" />
<ComponentRef Id="ApplicationShortcutDesktop" />

Then locate the directory definition lines:

<Directory Id="TARGETDIR" Name="SourceDir">
  <Directory Id="ProgramFilesFolder">
    <Directory Id="INSTALLFOLDER" Name="MyWpfApplication" />
  </Directory>

And add two more paths, one for the program files shortcut and the second one for the desktop:

<Directory Id="ProgramMenuFolder">
  <Directory Id="ApplicationProgramsFolder" Name="MyWpfApplication"/>
</Directory>
<Directory Id="DesktopFolder" Name="Desktop"/>

Then copy all this fragment and replace the GUID and the path of the program (check the original example).

<Fragment>
  <DirectoryRef Id="ApplicationProgramsFolder">
    <Component Id="ApplicationShortcut" Guid="9bd13330-6540-406f-a3a8-d7f7c69ae7f9">
      <Shortcut Id="ApplicationStartMenuShortcut" Name="MyWpfApplication" Description="MyWpfApplication" Target="[INSTALLFOLDER]MyWpfApplication.exe" WorkingDirectory="INSTALLFOLDER" />
      <RemoveFolder Id="RemoveApplicationProgramsFolder" Directory="ApplicationProgramsFolder" On="uninstall" />
      <RegistryValue Root="HKCU" Key="Software\MyWpfApplication" Name="installed" Type="integer" Value="1" KeyPath="yes" />
    </Component>
  </DirectoryRef>
  <DirectoryRef Id="DesktopFolder">
   <Component Id="ApplicationShortcutDesktop" Guid="cde1e030-eb64-49a5-b7b8-400b379c2d1a">
     <Shortcut Id="ApplicationDesktopShortcut" Name="MyWpfApplication" Description="MyWpfApplication" Target="[INSTALLFOLDER]MyWpfApplication.exe" WorkingDirectory="INSTALLFOLDER" />
      <RemoveFolder Id="RemoveDesktopFolder" Directory="DesktopFolder" On="uninstall" />
      <RegistryValue Root="HKCU" Key="Software\MyWpfApplication" Name="installed" Type="integer" Value="1" KeyPath="yes" />
    </Component>
  </DirectoryRef>
</Fragment>

Create basic dialogs

To add the dialogs you need to add a reference on your Setup project to WixUIExtension.
Right click on SetupProject1 -> Add -> Reference -> select WixUIExtension.
wix_reference

Then locate the line

<Package InstallerVersion="200" Compressed="yes" InstallScope="perMachine" />

and add this line:

<UIRef Id="WixUI_Minimal" />

License, icons and images

To add a Control panel icon you need to include the .ico file to the SetupProject, then set “Build Action: Content”.
Then locate the line

<Product Id="*" Name="MyWpfApplication" Language="1033" Version="1.0.0.0" Manufacturer="Mesta-Automation.com" UpgradeCode="c3d73c9d-4fa4-4033-93b9-59808a52472c">

and add this line:

<Icon Id="icon.ico" SourceFile="$(var.ProjectDir)Icon.ico" />
<Property Id="ARPPRODUCTICON" Value="icon.ico" />

To add top banner and background, add the images to the project (*.bmp only, jpeg and png are not accepted) add these lines under the ProductId section:

<WixVariable Id="WixUIBannerBmp" Value="Images\installer_top-banner.bmp" />
<WixVariable Id="WixUIDialogBmp" Value="Images\installer_background.bmp" />

Adding the license is similar to adding the images, just create your license.rtf file, add it to the project and add this line:

<WixVariable Id="WixUILicenseRtf" Value="$(var.ProjectDir)\license.rtf" />

Change the name of the installer

To change the file-name of the installer, right-click on SetupProject->Properties, and modify Output Name.setup proj properties
To change the name of the installed program (the name that appears in the Control Panel) you need to modify the property “Name” in the “Product” section:

<Product Id="*" Name="My Wpf Application" .../>

Output only one file, instead of multiple .cab

Depending on the size of the installer, you may want to create only one msi file that embeds everything.
This is possible by replacing the

<MediaTemplate />

with

<MediaTemplate EmbedCab="yes"/>

Fixed Product Id and manage application updates

This operation is needed to avoid multiple installations of the same application.
Go on the website http://www.guidgen.com/ and copy the guid. Replace the * in the following line

<Product Id="*" .../>

with the generated guid.
If you have to deliver an update to your application, just change the “Id” field with a new GUID and leave the UpgradeCode unchanged.

Dialogs customization and more features

If you need to customize the dialogs, for example by adding a dialog that permits to select the installation folder and so on, there are various themes on the folder C:\Program Files (x86)\WiX Toolset v3.10\SDK\wixui
This is the official reference for the dialogs of Wix: http://wixtoolset.org/documentation/manual/v3/wixui/wixui_dialog_library.html
You can also grab the sources and place them into the code.

Download sample application

You can download the sample application on GitHub.

Share Button

4 comments

  1. Very useful, thanks a lot!

  2. Much thanks for tutorial. Minor error in tutorial: we don’t learn the name of the WPF application until after we have created it.

  3. very useful

  4. Sir Please write article about making MSI installer for web application using WIX toolset. I will be very thankful to you.

Leave a Reply