myexamples

WiX Toolset examples ⬆

Directory myexamples\ contains WiX Toolset examples written by ourself.

The WiX Toolset examples presented in the following sections share the same project organization, i.e.

• directory app\ contains the application files
• directory src\ contains the WiX source files and resource files
• batch file build.bat creates the Windows installer from the two input directories.
• output directory target\ contains the generated .msi, .msi.md5 ¹ and .msi.sha256 files.

MyApp Example

In this first example we aim to install a single file, concretely the Windows application MyApp.exe, accessible for all users and located in the MyApp directory inside the Program Files system folder.

For that purpose we declare one single component element in our WiX source file MyApp.wxs; the component element belongs to the MyApp directory and refers to the above executable.

> cd
Y:\myexamples\MyApp
 
> tree /f . | findstr /v /b [a-z]
│   build.bat          (calls candle/light)
├───app
│   └───HelloWorld
│       │   00download.txt
│       │   build.bat  (calls MSBuild)
│       │   README.md
│       └───cpp
│           │   HelloWorld.sln
│           │   HelloWorld.vcxproj
│           └───src
│                   main.cpp
└───src
        MyApp.wxs      (with PUT-GUID-HERE placeholders)

🔎 In order the have a self-contained example we include the HelloWorld subproject which contains a simple Visual Studio solution for generating MyApp.exe to be added to the MyApp Windows installer.

Our main batch file build.bat invokes the WiX tools candle.exe (compiler) and light.exe (linker) with the appropriate settings and inputs.

> build -verbose install
Generate executable "MyApp.exe"
Copy executable "MyApp.exe" to directory "Y:\myexamples\MyApp\app\"
Generate auxiliary WXS file
[...]
Compiling 1 WiX source file to directory "target"
Create Windows installer "target\MyApp-1.0.0.msi"
Execute Windows installer "target\MyApp-1.0.0.msi"

Figures 1.1 and 1.2 below illustrate the updated user environment after the successful execution of the MyApp Windows installer.

🔎 The user must navigate to the Apps & features window in the Windows Settings in order to uninstall the MyApp application (Figure 1.2).

Figure 1.1 - MyApp executable (Program Files folder).

Figure 1.2 - Uninstall MyApp (Settings window).

MyAppShortcuts Example ▴

This second example adds Start Menu shortcuts (see WiX manual) to the above MyApp example.

We declare 3 components in our WiX source file MyAppShortcuts.wxs :

• component 1 refers to the MyApp executable (as in previous example).
• component 2 refers to the HTML file documentation.html.
• component 3 defines the two shortcuts MyApp and Uninstall MyApp (Figure 2.2).

🔎 The user has now two possibilities to remove the MyApp application :

• from the Apps & features window in the Windows Settings
• through the Uninstall MyApp shortcut in the Start Menu folder.

Figures 2.1 to 2.4 below illustrate the updated user environment after the successful execution of the MyApp Windows installer.

Figure 2.1 - MyApp executable (Program Files folder).   Figure 2.2 - MyApp shortcuts (Start Menu folder).

Figure 2.3 - Uninstall MyApp (Settings window).

Figure 2.4 - Shortcut properties (Uninstall shortcut).

🔎 Figure 2.4 shows the window Properties of the Uninstall shortcut visible in Figure 2.2; in particular we can read in the field "Target" the GUID ² value corresponding to PRODUCT_CODE in the file build.properties.

PRODUCT_CODE=C04AE4CF22B4403D97EDF523D3A1BD30
PRODUCT_UPGRADE_CODE=...

MyAppLocalized Example

Project MyAppLocalized adds language localization to the WiX source files of the MyApp Windows installer.

This project contains the additional directory src\localizations\ with 3 WiX localization files:

> cd
Y:\myexamples\MyAppLocalized
 
> tree /f . | findstr /v /b [a-z]
│   build.bat
├───app
│   │   documentation.html
│   └───HelloWorld
│           ... (same as before)
└───src
    │   Includes.wxi
    │   MyAppLocalized.wxs
    └───localizations
            de-DE.wxl
            en-US.wxl
            fr-FR.wxl
            README.txt

Command build link generates a separate MSI file for each language localization, e.g. MyApp-1.0.0-fr-FR.msi is the french version of the MyApp Windows installer.

> build clean link && dir /a-d /b target
candle_opts.txt
candle_sources.txt
light_opts.txt
MyApp-1.0.0.msi
MyApp-1.0.0.msi.md5
MyApp-1.0.0.msi.sha256
MyApp-1.0.0.wixpdb
MyApp-1.0.0_de-DE.msi
MyApp-1.0.0_de-DE.msi.md5
MyApp-1.0.0_de-DE.msi.sha256
MyApp-1.0.0_de-DE.wixpdb
MyApp-1.0.0_fr-FR.msi
MyApp-1.0.0_fr-FR.msi.md5
MyApp-1.0.0_fr-FR.msi.sha256
MyApp-1.0.0_fr-FR.wixpdb
MyAppLocalized.wixobj

Figures 3.1 and 3.2 below illustrate the updated user environment after the successful execution of the MyApp Windows installer.

Figure 3.1 - MyApp application (Program Files folder).

Figure 3.2 - MyApp shortcuts (Start Menu folder).

MyAppFeatures Example

Project MyAppFeatures adds feature customization to the MyApp Windows installer.

tbd

Figure 4.1 - Welcome (MyApp installer).

Figure 4.2 - Custom Setup (MyApp installer).

Footnotes ▴

[1] File Checksums ↩

We rely on the PowerShell cmdlet Get-FileHash to generate .md5 and .sha256 checksum files. MD5 checksums can also be generated with command-line tools such as MD5 or MD5sums (see also document SECURITY.md).

 > powershell -C "(Get-FileHash 'target\MyApp-1.0.0.msi' -Algorithm md5).Hash"
38C2F1D6F7FF5D40A75DAEA0950CF949

[2] GUID ↩

A GUID is a 128-bit integer (16 bytes) that can be used across all computers and networks wherever a unique identifier is required. Such an identifier has a very low probability of being duplicated (see also the nice article series from Eric Lippert's "Guid guide", part 1, part 2 and part 3).

WiX examples developed in this project rely on the PowerShell cmdlet New-Guid to generate GUID values; for instance :

> powershell -C "(New-Guid).Guid"
2d30a843-3eb2-497a-99a1-49a368bba5f7

---

mics/December 2023 ▲