Creating an installer using WiX
For starters, what is WiX? WiX technology (Windows Installer XML) is a set of tools and specifications that simplify the process of creating distributions based on MSI (Microsoft Installer). Simply put, this is a wrapper around MSI with a human face.
In my opinion, the easiest way to learn is with simple examples. In this article I will give an example of a simple installer.
To begin with, we will set the task conditions - it is necessary to create an installation distribution package that will contain the following dialogs:
Welcome
License agreement
Directory selection
Installation start
To create the distribution package we need WiX itself, the latest version of which can always be downloaded from Source Forge . At the moment, the latest version is 3.5.0828.0.
You need to download and install:
1. ProjectAggregator2.msi - needed to install Votive (located inside distribution number 2). Which, in turn, is an addition to Visual Studio, facilitating the process of working with WiX (syntax highlighting, IntelliSense).
2. Wix35.msi orWix35_x64.msi (depending on the platform)
3. Russian language file
So, download, install, run Visual Studio. File menu -> New Project, if everything is installed correctly - a new Windows Installer XML section has appeared. Select the project template Setup Project, enter the name of the project (I left SetupProject1 as it is).
The project will consist of one Product.wxs file and we will work with it. In my case, the file looked like this:
To get started, set up the look and add support for the Russian language.
Let's start by adding the Russian language. To do this:
1. In the Product key, change 1033 to 1049
2. In the project properties ( right-click on the project name in Solution Explorer -> Properties ), the Build tab, insert ru-RU in the Cultures to build field
3. Add to the project ( right click on the project name in Solution Explorer -> Add -> Existing Item ) file WixUI_ru-ru.wxl (from the archive WixUI_ru-ru.v3.zip)
There is not a single dialog box in the generated project. There are two options for adding dialog boxes - create one yourself, or use a predefined set of dialog boxes.
We will go the second way, it is better to start acquaintance with the simple. To do this, add a link to WixUIExtension.dll ( right- click on the project name in Solution Explorer -> Add Reference - open the folder in which WiX was installed, the bin subdirectory ) we
added the link, indicate which set we will use, at the end of the Product section add
WixVariable Id = "WixUILicenseRtf " - indicates the path to the license file (there was no talk about it yet, it was added right away so as not to go twice).
WixUI_InstallDir - a ready-made set of dialog boxes. This set includes all the dialogs we need. In addition to it, there are also sets WixUI_Advanced, WixUI_Mondo, WixUI_FeatureTree, WixUI_InstallDir, WixUI_Minimal.
The preparations are finished, you can start editing the installation file. First, let's see what the studio generated for us:
Product Key - describes the properties of the product.
Id - product identifier, unique GUID.
Name - product name
Language - language of the installation package
Version - product version
Manufacturer - manufacturer
UpgradeCode - unique GUID
To simplify our lives, we define some variables. For what - the name of the product, for example, can be found more than once in a script, if we want to change it, we will have to search it throughout the script and change it to a new one. To avoid this, we define a variable that will contain the name of the product and, if necessary, we will only change it. Above the Product section, add:
Now replace the value of the parameters of the Product key with the variables:
We will now decide on where we will install our product.
Directory key - Defines the installation path.
Directory Id = "TARGETDIR" is the root element for all folders that will be used to install the project.
Directory Id = "ProgramFilesFolder" folder Program Files (as indicated by Id = "ProgramFilesFolder").
Directory Id = "INSTALLLOCATION" folder named SetupProject1 in the Program Files folder. We immediately replace Name = “SetupProject1” with Name = “$ (var.ProductName)”.
Add files to the installation package. To do this, first add the installed components. Following the advice “Remove the comments around this Component” we remove the comments with Component inside the target folder and add, for example, a calculator.
Installing a component is impossible without including it in one of the Feature ( if I’m honestly not sure how in this case you can translate this term into Russian ). This element can be used when we need to give the user the opportunity to choose what to install and what not. In the context of our task, nothing was said about the possibility of choice, but despite this we need to bind the described Component to one single Feature:
It remains to add a shortcut to the Start menu.
First, we indicate that we are going to work with the Start menu folder and want to create a folder with the name of our program there containing a shortcut to the calculator.
In the Directory Id = "TARGETDIR" section, somewhere at the end we add:
We begin to understand:
Directory Id = "ProgramMenuFolder" - indicates the directory that contains the Start menu shortcuts.
Directory Id = "ApplicationProgramsFolder" - the folder of our program in the Start menu
Component - the component containing the shortcut (do not forget to include it in Feature)
Shortcut - the shortcut to the calculator itself
The final version of the file should look like this:
We do Build, run, check the result.
Where else to read Alex Shevchuk's
project page
: From MSI to WiX (mostly in English, but a little in Russian)
WiX Tutorial
wixwiki
Continued Part 2 - fragments and inclusions
In my opinion, the easiest way to learn is with simple examples. In this article I will give an example of a simple installer.
To begin with, we will set the task conditions - it is necessary to create an installation distribution package that will contain the following dialogs:
Welcome
License agreement
Directory selection
Installation start
To create the distribution package we need WiX itself, the latest version of which can always be downloaded from Source Forge . At the moment, the latest version is 3.5.0828.0.
You need to download and install:
1. ProjectAggregator2.msi - needed to install Votive (located inside distribution number 2). Which, in turn, is an addition to Visual Studio, facilitating the process of working with WiX (syntax highlighting, IntelliSense).
2. Wix35.msi orWix35_x64.msi (depending on the platform)
3. Russian language file
So, download, install, run Visual Studio. File menu -> New Project, if everything is installed correctly - a new Windows Installer XML section has appeared. Select the project template Setup Project, enter the name of the project (I left SetupProject1 as it is).
The project will consist of one Product.wxs file and we will work with it. In my case, the file looked like this:
<?xml version="1.0" encoding="UTF-8"?>
<Wix xmlns="http://schemas.microsoft.com/wix/2006/wi">
<Product Id="b7bc7c6f-9a4e-4973-be84-eca8e3427c97" Name="SetupProject1" Language="1033" Version="1.0.0.0" Manufacturer="SetupProject1" UpgradeCode="06a81104-1e30-463d-87e1-e8a79b4c682a">
<Package InstallerVersion="200" Compressed="yes" />
<Media Id="1" Cabinet="media1.cab" EmbedCab="yes" />
<Directory Id="TARGETDIR" Name="SourceDir">
<Directory Id="ProgramFilesFolder">
<Directory Id="INSTALLLOCATION" Name="SetupProject1">
<!-- TODO: Remove the comments around this Component element and the ComponentRef below in order to add resources to this installer. -->
<!-- <Component Id="ProductComponent" Guid="b11556a2-e066-4393-af5c-9c9210187eb2"> -->
<!-- TODO: Insert files, registry keys, and other resources here. -->
<!-- </Component> -->
</Directory>
</Directory>
</Directory>
<Feature Id="ProductFeature" Title="SetupProject1" Level="1">
<!-- TODO: Remove the comments around this ComponentRef element and the Component above in order to add resources to this installer. -->
<!-- <ComponentRef Id="ProductComponent" /> -->
</Feature>
</Product>
</Wix>
* This source code was highlighted with Source Code Highlighter.To get started, set up the look and add support for the Russian language.
Let's start by adding the Russian language. To do this:
1. In the Product key, change 1033 to 1049
2. In the project properties ( right-click on the project name in Solution Explorer -> Properties ), the Build tab, insert ru-RU in the Cultures to build field
3. Add to the project ( right click on the project name in Solution Explorer -> Add -> Existing Item ) file WixUI_ru-ru.wxl (from the archive WixUI_ru-ru.v3.zip)
There is not a single dialog box in the generated project. There are two options for adding dialog boxes - create one yourself, or use a predefined set of dialog boxes.
We will go the second way, it is better to start acquaintance with the simple. To do this, add a link to WixUIExtension.dll ( right- click on the project name in Solution Explorer -> Add Reference - open the folder in which WiX was installed, the bin subdirectory ) we
added the link, indicate which set we will use, at the end of the Product section add
<Property Id="WIXUI_INSTALLDIR" Value="INSTALLLOCATION" ></Property>
<WixVariable Id="WixUILicenseRtf" Overridable="yes" Value="License.rtf"/>
<UIRef Id="WixUI_InstallDir"/>
* This source code was highlighted with Source Code Highlighter.WixVariable Id = "WixUILicenseRtf " - indicates the path to the license file (there was no talk about it yet, it was added right away so as not to go twice).
WixUI_InstallDir - a ready-made set of dialog boxes. This set includes all the dialogs we need. In addition to it, there are also sets WixUI_Advanced, WixUI_Mondo, WixUI_FeatureTree, WixUI_InstallDir, WixUI_Minimal.
The preparations are finished, you can start editing the installation file. First, let's see what the studio generated for us:
Product Key - describes the properties of the product.
Id - product identifier, unique GUID.
Name - product name
Language - language of the installation package
Version - product version
Manufacturer - manufacturer
UpgradeCode - unique GUID
To simplify our lives, we define some variables. For what - the name of the product, for example, can be found more than once in a script, if we want to change it, we will have to search it throughout the script and change it to a new one. To avoid this, we define a variable that will contain the name of the product and, if necessary, we will only change it. Above the Product section, add:
<?define ProductName="SetupProject1" ?>
<?define ProductVersion="1.0.0.0" ?>
<?define ProductCode="b7bc7c6f-9a4e-4973-be84-eca8e3427c97"?>
<?define UpgradeCode="06a81104-1e30-463d-87e1-e8a79b4c682a"?>
<?define Manufacturer="MyCompany"?>
* This source code was highlighted with Source Code Highlighter.Now replace the value of the parameters of the Product key with the variables:
<Product Id="$(var.ProductCode)" Name="$(var.ProductName)" Language="1049" Version="$(var.ProductVersion)" Manufacturer="$(var.Manufacturer)" UpgradeCode="$(var.UpgradeCode)">
* This source code was highlighted with Source Code Highlighter.We will now decide on where we will install our product.
Directory key - Defines the installation path.
Directory Id = "TARGETDIR" is the root element for all folders that will be used to install the project.
Directory Id = "ProgramFilesFolder" folder Program Files (as indicated by Id = "ProgramFilesFolder").
Directory Id = "INSTALLLOCATION" folder named SetupProject1 in the Program Files folder. We immediately replace Name = “SetupProject1” with Name = “$ (var.ProductName)”.
Add files to the installation package. To do this, first add the installed components. Following the advice “Remove the comments around this Component” we remove the comments with Component inside the target folder and add, for example, a calculator.
<Component Id="ProductComponent" Guid="b11556a2-e066-4393-af5c-9c9210187eb2">
<File Id='Calc' DiskId='1' Source='C:\WINDOWS\system32\calc.exe'/>
</Component>
* This source code was highlighted with Source Code Highlighter.Installing a component is impossible without including it in one of the Feature ( if I’m honestly not sure how in this case you can translate this term into Russian ). This element can be used when we need to give the user the opportunity to choose what to install and what not. In the context of our task, nothing was said about the possibility of choice, but despite this we need to bind the described Component to one single Feature:
<Feature Id="ProductFeature" Title="$(var.ProductName)" Level="1">
<ComponentRef Id="ProductComponent" />
</Feature>
* This source code was highlighted with Source Code Highlighter.It remains to add a shortcut to the Start menu.
First, we indicate that we are going to work with the Start menu folder and want to create a folder with the name of our program there containing a shortcut to the calculator.
In the Directory Id = "TARGETDIR" section, somewhere at the end we add:
<Directory Id="ProgramMenuFolder">
<Directory Id="ApplicationProgramsFolder" Name="$(var.ProductName)">
<Component Id="ApplicationShortcutCalc" Guid="4CEBD68F-E933-47f9-B02C-A4FC69FDB551">
<Shortcut Id="ShortcutCalc"
Name="Calc"
Description="$(var.ProductName)"
Target="[INSTALLLOCATION]Calc.exe"
WorkingDirectory="INSTALLLOCATION"/>
<RemoveFolder Id="ApplicationProgramsFolder" On="uninstall"/>
<RegistryValue Root="HKCU" Key="Software\$(var.Manufacturer)\$(var.ProductName)" Name="installed" Type="integer" Value="1" KeyPath="yes"/>
</Component>
</Directory>
</Directory>
* This source code was highlighted with Source Code Highlighter.We begin to understand:
Directory Id = "ProgramMenuFolder" - indicates the directory that contains the Start menu shortcuts.
Directory Id = "ApplicationProgramsFolder" - the folder of our program in the Start menu
Component - the component containing the shortcut (do not forget to include it in Feature)
Shortcut - the shortcut to the calculator itself
The final version of the file should look like this:
<?xml version="1.0" encoding="UTF-8"?>
<Wix xmlns="http://schemas.microsoft.com/wix/2006/wi">
<?define ProductName="SetupProject1" ?>
<?define ProductVersion="1.0.0.0" ?>
<?define ProductCode="b7bc7c6f-9a4e-4973-be84-eca8e3427c97"?>
<?define UpgradeCode="06a81104-1e30-463d-87e1-e8a79b4c682a"?>
<?define Manufacturer="MyCompany"?>
<Product Id="$(var.ProductCode)" Name="$(var.ProductName)" Language="1049" Version="$(var.ProductVersion)" Manufacturer="$(var.Manufacturer)" UpgradeCode="$(var.UpgradeCode)">
<Package InstallerVersion="200" Compressed="yes" />
<Media Id="1" Cabinet="media1.cab" EmbedCab="yes" />
<Directory Id="TARGETDIR" Name="SourceDir">
<Directory Id="ProgramFilesFolder">
<Directory Id="INSTALLLOCATION" Name="$(var.ProductName)">
<Component Id="ProductComponent" Guid="b11556a2-e066-4393-af5c-9c9210187eb2">
<File Id='Calc' DiskId='1' Source='C:\WINDOWS\system32\calc.exe'/>
</Component>
</Directory>
</Directory>
<Directory Id="ProgramMenuFolder">
<Directory Id="ApplicationProgramsFolder" Name="$(var.ProductName)">
<Component Id="ApplicationShortcutCalc" Guid="4CEBD68F-E933-47f9-B02C-A4FC69FDB551">
<Shortcut Id="ShortcutCalc"
Name="Calc"
Description="$(var.ProductName)"
Target="[INSTALLLOCATION]Calc.exe"
WorkingDirectory="INSTALLLOCATION"/>
<RemoveFolder Id="ApplicationProgramsFolder" On="uninstall"/>
<RegistryValue Root="HKCU" Key="Software\$(var.Manufacturer)\$(var.ProductName)" Name="installed" Type="integer" Value="1" KeyPath="yes"/>
</Component>
</Directory>
</Directory>
</Directory>
<Feature Id="ProductFeature" Title="SetupProject1" Level="1">
<ComponentRef Id="ProductComponent" />
<ComponentRef Id="ApplicationShortcutCalc" />
</Feature>
<Property Id="WIXUI_INSTALLDIR" Value="INSTALLLOCATION" ></Property>
<WixVariable Id="WixUILicenseRtf" Overridable="yes" Value="License.rtf"/>
<UIRef Id="WixUI_InstallDir"/>
</Product>
</Wix>
* This source code was highlighted with Source Code Highlighter.We do Build, run, check the result.
Where else to read Alex Shevchuk's
project page
: From MSI to WiX (mostly in English, but a little in Russian)
WiX Tutorial
wixwiki
Continued Part 2 - fragments and inclusions