From MSI to WiX, Part 1 - Required properties

  • Article

The main page for the series is here.

Русская версия здесь.

 

Introduction 

Today I will start a series of posts about creating an MSI installation package using WiX.  The goal here is to show what is omitted from the WiX documentation and explain not just what needs to be done in WiX, but also - why.  In this series I will be using WiX 2.0, unless stated otherwise.

Because I will use tools from Windows Installer SDK, such as Orca, we need to install the Windows Installer SDK which is part of Microsoft Plafrom SDK.  You can install it from here.

You can disable everything except Core SDK and Windows Installer SDK.

Creating WiX source file

Every WiX source file must have the following root element:

<?

xml version='1.0' encoding='UTF-8'?>
<Wix xmlns='https://schemas.microsoft.com/wix/2003/01/wi'>
   . . .
</Wix>

The extension of the WiX source file is usually wxs.

Defining required properties

Windows Installer is using five properties from the Property table in order to distinguish installed applications from each other.

Here is the list of required properties:

It is highly recommended to add the UpgradeCode property to support future upgrades to the product.

Tip: Always remember that letters in GUIDs in the Windows Installer are always upper-case. If you are using Visual Studio to edit your WiX source code, here are instructions on how to create a Visual Studio macro to automate the process of creating a new GUID.

Here is how we add required properties to the WiX source file:

<?xml version="1.0" encoding="UTF-8"?>

<Wix xmlns="https://schemas.microsoft.com/wix/2003/01/wi">

  <Product Id="{1EFFDCD2-4B4B-439E-8296-651795EE02D9}"

           Name="Minimal Windows Installer Sample"

           Language="1033"

           Codepage="1252"

           Version="1.0.0"

           Manufacturer="Acme Corporation"

           UpgradeCode="{15F9543C-1C8D-45D6-B587-86E65F914F20}">

  </Product>

</Wix>

This is how properties correspond to attributes of the <Product> element:

Now, we need to add the last required property which is stored in the Revision Number Summary property of the Summary Information stream.  This property is the package code of the installer package.  Summary Information stream has a number of additional properties and represented in the WiX source file by <Package> element.

Summary Information stream properties and their counterparts in <Package> element

Property Attribute Description
Revision Number Id Package Code
Subject Description For installation package the value of this field is the product name and can have the same value as ProductName property:[ProductName]
Comments Comments Describes the general purpose of the installation package. Usually contains the following message:This installer database contains the logic and data required to install [ProductName].
Author Manufacturer Manufacturer of the installation package. Usually has this value:[Manufacturer]
Codepage SummaryCodepage Numeric value of the ANSI code page used for any strings that are stored in the summary information.
Keywords Keywords List of keywords. For installation packages should include "Installer" as well as other product-specific keywords.
Template PlatformsLanguages Indicates the platform and language versions that are compatible with this installation database. The valid syntax for the Template property is:platform;langId,langId,... Wix is using two separate properties for platform and the list of languages.Warning: Wix help for <Package> element falsely states that the value of Platforms attribute is a list of supported platforms. Only one platform is valid for the Template Summary property.
Page Count InstallerVersion Minimum installer version required.
Word CountBit 0 ShortNames Original source is using short/long file names.
Word CountBit 1 Compressed Default compression status for all files in the installation package.
Word CountBit 2 AdminImage Source is original media/administrative image created by an administrative installation.
Word CountBit 3 InstallPrivileges Elevated privileges can be/are not required to install this package.
Security ReadOnly Conveys whether the package should be opened as read-only.
Title   Type of the installer package. For installation package the value of this field usually:Installation Database
Character Count   Used in Transforms only.
Creating Application   Application created the installer database.
Last Saved By   In an installation package, the installer sets this property to the value of the LogonUser property during an administrative installation. This property should be set to Null in a final shipping database.
Last Save Time/Date   The last time when this installation package was modified.
Create Time/Date   The time and date when an author created the installation package.
Last Printed   In an installation package, the Last Printed Summary property can be set to the date and time during an administrative installtion to record when the administrative image was created. For non-administrative installations, this property is the same as the Create Time/Date Summary property.

Here is how our updated source file looks like after adding <Package> element:

 <?xml version="1.0" encoding="UTF-8"?>

<Wix xmlns="https://schemas.microsoft.com/wix/2003/01/wi">

  <Product Id="{1EFFDCD2-4B4B-439E-8296-651795EE02D9}"

           Name="Minimal Windows Installer Sample"

           Language="1033"

           Codepage="1252"

           Version="1.0.0"

           Manufacturer="Acme Corporation"

           UpgradeCode="{15F9543C-1C8D-45D6-B587-86E65F914F20}">

    <Package Id="{909A6CE7-2739-4522-92C2-03AD7D7EE4CD}"

             Description="Minimal Windows Installer Sample"

             Comments="This installer database contains the logic and data required to install Minimal Windows Installer Sample."

             InstallerVersion="200"

             Languages="1033"

             SummaryCodepage="1252"

             Platforms="Intel"

             ReadOnly="no"

             Compressed="yes"

             AdminImage="no"

             Keywords="Installer"

             ShortNames ="no"

             Manufacturer="Acme Corporation" />

  </Product>

</Wix>

Package code is represented by the Id attribute and must be unique for every package.

Important:  Languages attribute must contain in its list the language ID from the Language attribute of the <Product> element.

More about properties

Windows Installer properties are the variables that you can use to define the behavior and actions taken by Windows Installer:

  • The names of the properties are case-sensitive.
  • A public property name must be all in uppercase, whereas a name of private property must have at least one lower case letter in its name. Only public properties can be specified in the command line.
  • Public properties can be restricted by using SecureCustomProperties property.  This property contains the semicolon delimited list of restricted properties.

Specifying directory layout for the product

In MSI database the Directory table specifies the directory layout for the product.  Directory layout starts with the mandatory root directory represented by the TARGETDIR property.  Default value for the TARGETDIR property is the value of the SourceDir property.

The directory layout is represented in WiX by the hierarchy of <Directory> elements.

Here is the directory layout for our installation project.

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

  <Directory Id="ProgramFilesFolder">

    <Directory Id="INSTALLDIR" Name="Minimal" LongName="MinimalInstallation">

    </Directory>

  </Directory>

</Directory>

I am using standard Program Files folder as an installation folder for our sample application.  Inside that folder I am creating a subfolder with the short name (the one which is using MS-DOS 8.3 name pattern) "Minimal" and the long name for that folder "MinimalInstallation".  Windows Installer has a set of predefined names for Windows System folders which you can use in your installation projects.

Now we add the feature we will install with our sample product and component which is a part of that feature.

The definition of the logical tree structure of features is defined in the Feature table of MSI database.  In WiX we are using <Feature> elements.

Tip:   Level column in the Feature table (Level attribute of the <Feature> element) holds the initial installation level of the feature.  An install level of zero disables the feature and prevents it from being displayed.  Users can use the INSTALLLEVEL public property to control features to be installed from the command line.

Components are listed in the Component table of MSI database and in WiX represented by <Component> elements.  For this sample our component won't install anything.  Here is how our WiX source file looks like:

<?xml version="1.0" encoding="UTF-8"?>

<Wix xmlns="https://schemas.microsoft.com/wix/2003/01/wi">

  <Product Id="{1EFFDCD2-4B4B-439E-8296-651795EE02D9}"

           Name="Minimal Windows Installer Sample"

           Language="1033"

           Codepage="1252"

           Version="1.0.0"

           Manufacturer="Acme Corporation"

       UpgradeCode="{15F9543C-1C8D-45D6-B587-86E65F914F20}">

    <Package Id="{909A6CE7-2739-4522-92C2-03AD7D7EE4CD}"

             Description="Minimal Windows Installer Sample"

             Comments="This installer database contains the logic and data required to install Minimal Windows Installer Sample."

             InstallerVersion="200"

             Languages="1033"

             SummaryCodepage="1252"

             Platforms="Intel"

             ReadOnly="no"

             Compressed="yes"

             AdminImage="no"

             Keywords="Installer"

             ShortNames ="no"

             Manufacturer="Acme Corporation" />

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

      <Directory Id="ProgramFilesFolder">

        <Directory Id="INSTALLDIR" Name="Minimal" LongName="MinimalInstallation">

          <Component Id="Component1"

                     Guid="{78E22868-B750-47EB-9E4C-C19CCA939394}">

            <CreateFolder />

          </Component>

        </Directory>

      </Directory>

    </Directory>

    <Feature Id="Feature1"

             Title="Feature1 title"

             Description="Feature1 description"

             Level="1"

             ConfigurableDirectory="INSTALLDIR" >

      <ComponentRef Id="Component1" />

    </Feature>

  </Product>

</Wix>

Notice that <Component> element has a child node <CreateFolder>.  We need that because Windows Installer will not create an empty folder by default.  In order to create an empty folder, the name of the folder must be presented in the CreateFolder table in MSI database.

Tip:   If your installation creates an empty subfolder and it is not present after installation is done, that's because you forgot to add <CreateFolder> element.

You can build our Minimal sample application by using these commands:

candle.exe Minimal.wxs
light.exe -out Minimal.msi Minimal.wixobj

or, if you prefer MSBuild (Minimal.proj):

<

Project DefaultTargets="Build" xmlns="https://schemas.microsoft.com/developer/msbuild/2003">
<PropertyGroup>
<!-- Required by WiX -->
<!-- Path and name of the output without extension -->
<OutputName>Minimal</OutputName>
<!-- What need to be built -->
<OutputType Condition="$(OutputType)==''">package</OutputType>

<!--

The path to the WiX installation -->
<ToolPath>d:\WIX\</ToolPath>

<!--

Input path to source files.
If not passed, assumes the same folder where project file is located. -->
<BaseInputPath Condition="$(BaseInputPath)==''">$(MSBuildProjectDirectory)\</BaseInputPath>

<!--

Create a compiled output in the folder where project is located -->
<OutputPath Condition="$(OutputPath)==''">$(MSBuildProjectDirectory)\</OutputPath>

<!--

Add missing trailing slash in paths -->
<ToolPath Condition="!HasTrailingSlash('$(ToolPath)') ">$(ToolPath)\</ToolPath>
<BaseInputPath Condition="!HasTrailingSlash('$(BaseInputPath)') ">$(BaseInputPath)\</BaseInputPath>
<OutputPath Condition="!HasTrailingSlash('$(OutputPath)') ">$(OutputPath)\</OutputPath>
</PropertyGroup>

<!--

Candle.exe command-line options -->
<ItemGroup>
</ItemGroup>

<!--

Light.exe command-line options -->
<ItemGroup>
</ItemGroup>

<

Import Project="$(ToolPath)wix.targets"/>

<!--

List of files to compile -->
<ItemGroup>
<Compile Include="$(BaseInputPath)Minimal.wxs"/>
</ItemGroup>
</Project>

here is the command to use this file for compilation:

msbuild Minimal.proj

Now, if you've installed the Installer SDK, you can right-click on Minimal.msi file and select "Edit with Orca" menu item.  This will bring the Orca application with Minimal.msi database loaded.  Select "Tools" menu and then "Validate..." submenu.  Uncheck the "Show "INFO" Messages" check box and click the "Go" button.  This will start the package validation.  In our case validation will trigger the ICE71 warning: "The Media table has no entries."  Basically, it means that every package must have a record in the Media table with DiskId equal 1.  We can fix it by addind <Media> element to our WiX file right before first <Directory> element:

<Media Id="1" />
<Directory Id="TARGETDIR" Name="SourceDir">

Tip:   Always run ICE validation on your installation packages.

Now you can install the Minimal.msi and see that it does create the Minimal subfolder in the Program Files folder and delete it on uninstall.

The reason why we were using public property INSTALLDIR in the line:

 <Directory Id="INSTALLDIR" Name="Minimal" LongName="MinimalInstallation">

is because we want to give our users ability to change the installation directory in the command line during installation of our product.  Try to install Minimal.msi using the following command:

msiexec /i Minimal.msi INSTALLDIR=c:\MinimalTest

As you can see, now our msi creates a MinimalTest folder in the C driver root instead of in the Program Files.

What's next

Next time we will add an Add/Remove Program support to our package.