From MSI to WiX, Part 1 - Required properties, by Alex Shevchuk

Following content is directly reprinted from From MSI to WiX, Part 1 - Required properties

Author: Alex Shevchuk

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=‘http://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:

• ProductCode - Unique identifier for particular product release (GUID).
• ProductVersion - Version of the product.  The format of this string is: major.minor.build.
• ProductLanguage - Numeric language identifier (LANGID) installer will use for any strings in the user interface that are not authored in the database. This value must be one of the languages listed in the Template Summaryproperty in the Summary Information stream.
• ProductName - The name of the application.
• Manufacturer - The name of the manufacturer of the product.

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="http://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:

• ProductCode - Id.
• ProductVersion - Version.
• ProductLanguage - Language.
• ProductName - Name.
• Manufacturer - Manufacturer.
• UpgradeCode - UpgradeCode.

Now, we need to add the last required property which is stored in the Revision Number Summary property of theSummary 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

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

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

<Wix xmlns="http://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="http://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 theCreateFolder 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="http://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.