Skip to content

00_HelloWorldInstaller

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

00_HelloWorldInstaller

README.md

00_HelloWorldInstaller

Building installer

To build minimum installer run in PowerShell:

.\DownloadAndExtractWix.ps1
.\BuildInstaller.ps1

If execution of PowerShell scripts is not allowed, it can be enabled by calling (as Administrator):

Set-ExecutionPolicy RemoteSigned

Minimum installer elements

It has to contain at least these elements:

Below is a short explanation of each element and why it is needed.

Product

Describes the software the installer is installing.

  <Product Id="DD475EBC-D960-4AF4-BB8A-BE91FA942756"
           Language="1033"
           Manufacturer="Acme Corporation"
           Name="Hello World"
           Version="1.0.0.0">
  • Id
    • GUID of the product being installed
    • best practice is to set it to "*" so that it is autogenerated by WiX on each compile
    • installation of this MSI (which is by default 32-bit) will create the following windows registry entry (on 64-bit Windows)
      • \HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Microsoft\Windows\CurrentVersion\Uninstall\{DD475EBC-D960-4AF4-BB8A-BE91FA942756}
    • and on 32-bit Windows
      • \HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\{DD475EBC-D960-4AF4-BB8A-BE91FA942756}
  • Language
  • Manufacturer, Name, Version
    • visible in Windows in the list of installed applications

Package

Describes the installer itself.
The element itself is mandatory, but none of its attributes are mandatory - the example sets only two attributes - InstallScope and Compressed.
With only these two elements, the installer can be compiled, but trying to install it will result in nothing being installed.

    <Package InstallScope="perMachine" Compressed="yes" />
  • InstallScope
    • set to perUser if installer does not require elevated privileges to install (set to perMachine if it does)
  • Compressed
    • if not set, the default is "no"
    • if not set or set to "no", files installed by the MSI are distributed alongside the MSI
    • if set to "yes", files installed by the MSI are contained inside the MSI

MediaTemplate

Describes how files are packaged in the installer (are they in cabinets (CAB) and how they are compressed).
The element itself is mandatory, but none of its attributes are mandatory - the example sets only one attribute - EmbedCab.
Instead of this element, a Media element can be used instead.
Media element should be used when we want to split the installer into multiple files (e.g. for distribution on CDs / diskettes).

<MediaTemplate EmbedCab="yes" />
  • EmbedCab
    • when set to "no" and cabinet files are used, they are distributed alongside the MSI

Directory

Represents a directory that will be created by the installer, in which case Name and Id properties must be set.
Or it represents one of the predefined directories (e.g. ProgramFilesFolder), in which case only Id property must be set.

Directory structure must start with:

    <Directory Id="TARGETDIR" Name="SourceDir">

During an install, TARGETDIR will default to the largest drive on the machine.
SourceDir will be set to the location where the MSI is being executed.
Explanation from Rob Mensching why this is needed can be found here.

Directory structure used in the installer:

    <Directory Id="TARGETDIR" Name="SourceDir">
      <Directory Id="ProgramFilesFolder">
        <Directory Id="INSTALLFOLDER" Name="Hello World Installation Folder">
          <Component Id="ProductComponent">
            <File KeyPath="yes" Source="FileToInstall.txt"></File>
          </Component>
        </Directory>
      </Directory>
    </Directory>

Here we are saying that the default install folder is a folder called "Hello World Installation Folder" which is located in the 32-bit Program Files folder.

Component

An element that wraps other elements.
Windows track all installed components in Windows Registry (for uninstall and repair), and each component should have a unique Guid attribute.

  • Guid
    • does not have to be specified if the component contains just one file or if a versioned file is a keypath and the other files are unversioned
    • in all other cases specifying Guid of component is mandatory

According to this article:

  • you should restrict yourself to a single file per component
  • every component must have a unique GUID
  • failure to follow these two basic rules can lead to many problems

Some of the problems that can occur are described here.

File

Represents a file deployed by the installer.

<File KeyPath="yes" Source="FileToInstall.txt"></File>

  • KeyPath

    • only one element under a single component can have KeyPath="yes"
    • if the component contains multiple files, only the file with KeyPath="yes" will be checked in case of upgrade (this should be a version file - e.g. exe or dll)
    • if this file did not change from the previous version of the installer, the installer will not upgrade/reinstall/repair any of the other files under the same component
    • a general rule would be to have only one file under a component and to always set KeyPath="yes"

  • Source

    • represent the relative or absolute path to the file (path is relative to the location of wxs file)
    • if Id property is not explicitly set, it defaults to the file name portion of the Source attribute

  • Name

    • if this attribute is omitted then its default value is the file name portion of the Source attribute
    • if set, this name is used when the file is installed (instead of the Source name)

Feature

Used to break up installer into logical pieces that the user can install independently.
If an installer has a UI, individual features are usually displayed in a feature tree.
If an installer does not have a UI, individual features can be installed using the msiexec ADDLOCAL property.

The following command installs only the "HelloWorldFeature":

msiexec /i Product.msi ADDLOCAL=HelloWorldFeature

Following command installs only all the feature:

msiexec /i Product.msi ADDLOCAL=ALL

In this example, both calls have the same result, because the installer contains just one feature:

    <Feature Id="HelloWorldFeature">
      <ComponentRef Id="ProductComponent" />
    </Feature>

Note on upgradability

  • once installed, this installer is not upgradable
  • the next example contains the changes needed to make the installer upgradable
  • with the code as it is:
    • user can build an installer and install it (Version="1.0.0.0")
    • if the version is changed (e.g. to Version="2.0.0.0") and a new installer is built, trying to install that installer will result in an error saying that another version of the product is already installed