From MSI to WiX, Part 4 - Features and Components by Alex Shevchuk

Following content is directly reprinted from : http://blogs.technet.com/b/alexshev/archive/2008/08/23/from-msi-to-wix-part-4-features-and-components.aspx

Author: Alex Shevchuk

The main page for the series is here.

Introduction

When we install any msi what we are doing is we are installing a Product which is contained in a package (msi file).  Every product consists of one or more features and every feature contains zero or more components.  Components can be shared between features in the same application or between features in different applications.

Features

In MSI database features are represented by Feature table.  This table defines the logical tree structure of features.  There is a limit on maximum depth of the feature tree which is 16.

Next tables shows columns in the Feature table and how they are represented by <Feature> element in WiX.

Feature table		Feature element's attribute	Description
Column	Flag Value
Feature		Id	Unique primary key to identify the Feature.  Maximum length of this field is 38 characters.
Feature_Parent			In MSI database used to create a tree hierarchy.  In WiX it is represented by hierarchy of XML nodes.
Title		Title	The short name of the feature.
Description		Description	The long name of the feature.
Display		Display="collapse" Display="expand" Display="hidden" Display="integer value"	The number in this field specifies the order in which the feature is to be displayed in the user interface. Special cases: Zero - the record is not displayed The value is odd - the feature node is expanded initially The value is even - the feature node is collapsed initially
Level		Level	Initial installation level of the feature.  See explanation below for more details.
Directory_		ConfigurableDirectory	The Id of the directory that can be configured by a Selection Dialog.  This name must be a Public Property.
Attributes	FavorLocal	InstallDefault="local"	Components of this feature will be installed locally unless there is an override on component level.
	FavorSource	InstallDefault="source"	Components of this feature will be installed to run from the source unless there is an override on component level.
	FollowParent	InstallDefault="followParent"	Installation option of this feature is the same as an installation option of the parent feature unless there is an override on component level.
	FavorAdvertise	TypicalDefault="advertise"	See Advertising Options below for more details.
	DisallowAdvertise	AllowAdvertise="yes" AllowAdvertise="no"	See Advertising Options below for more details.
	UIDisallowAbsent	Absent="allow" Absent="disallow"	Enables or disables in the user interface an option to set the feature state to absent.
	NoUnsupportedAdvertise	AllowAdvertise="system"	See Advertising Options below for more details.

Components

In MSI database
components are represented by Component
table.

Component table		Component element's attribute	Description
Column	Flag Value
Component		Id	Unique primary key to identify the Component.
ComponentId		Guid	A string GUID unique to this component, version, and language.  This value can be NULL (empty string in WiX) if component does not need to be registered.
Directory_			External key to the record in the Directory table.  WiX will set this column for you.
Condition			This column contains a conditional statement that can control whether a component is installed.  In WiX this value is represented by child <Condition> element.
KeyPath		KeyPath="yes"	Sets the folder where Component is located to be the KeyPath of the component. If msidbComponentAttributesRegistryKeyPath attribute is set, this column contains a reference to a record in the Registry table.  The registry key it points to will be the KeyPath of the component.  In WiX it is handled by setting the KeyPath attribute of the <Registry> element.
Attributes	LocalOnly	Location="local"	Component must be installed locally.  Setting this attribute will prevent the feature from being run-from-network or run-from-source.
	SourceOnly	Location="source"	Component can only be run from source.  Setting this attribute will prevent the feature from being run-from-my-computer.
	Optional	Location="either"	Component can run locally or from source.
	RegistryKeyPath		In WiX this flag is represented by setting the KeyPath attribute of the <Registry> element.
	SharedDllRefCount	SharedDllRefCount="yes"	If this bit is set, the installer increments the reference count in the shared DLL registry of the component's key file. If this bit is not set, the installer increments the reference count only if the reference count already exists.
	Permanent	Permanent="yes"	Component will be never removed from the system.
	Transitive	Transitive="yes"	Component must have a condition which always will be reevaluated during maintenance install.
	NeverOverwrite	NeverOverwrite="yes"	If the KeyPath file or KeyPath registry key exists, component will not be installed or reinstalled.
	64bit	Win64="yes"	Marks 64-bit component.
	DisableRegistryReflection	DisableRegistryReflection="yes"	Disables Registry Reflection for registry keys in the component.

  

Sample 1

Let's start with simple installation package where we will have 3 features with one component in each of them.  The goal of this sample is to understand how the value of Level attribute of the <Feature> element affects the User Interface and which components will be installed.  The value of the Level attribute is called Install Level.

The range of possible values for Install Level is from 0 to 32,767.  Install Level zero disables the feature and prevents it from being displayed in the user interface.

Install Level for the installation (not Install Level for the feature) is determined by the value of the INSTALLLEVEL property.  By default its value is set to 1, but can be overridden by setting this property in the Property table to some other value.  For example, if value of the INSTALLLEVEL property is set to 3 than all features with Level attribute set to 3, 2, or 1 will be installed on the system.

Standard WiX Mondo UI contains a dialog where users can select Typical, Complete, or Custom installation levels.  Mondo defines Typical to be level 3 and Complete - level 1000.

Let's see how it works (source is from the Part1 project):

<?xml version="1.0" encoding="UTF-8"?>
<Wix xmlns="http://schemas.microsoft.com/wix/2003/01/wi">
  <Product Id="{73116928-CD06-4E5C-A78F-7854AADE0E4B}"
           Name="My Product"
           Language="1033"
           Version="1.0.0.0"
           Manufacturer="Your Company">
    <Package Id="{A38753E1-46CA-49E5-B5A5-7B4740FFCC8A}"
             Description="Description of your product"
             Comments="This will appear in the file summary stream."
             InstallerVersion="200"
             Compressed="yes" />

    <Media Id="1" Cabinet="Product.cab" EmbedCab="yes" />

    <Directory Id="TARGETDIR" Name="SourceDir">
      <Directory Id="ProgramFilesFolder">
        <Directory Id="INSTALLLOCATION"
                   Name="MyAppDir"
                   LongName="My Application Directory">

          <Directory Id="MinimumFolder" Name="Minimum">
            <Component Id="Minimum" Guid="{4E26479B-81FF-43B8-ADC7-5A18BCCBC7A1}" DiskId="1">
              <File Id="Minimum.txt" Name="Minimum.txt" Vital="yes" Source="Minimum.txt" />
            </Component>
          </Directory>

          <Directory Id="TypicalFolder" Name="Typical">
            <Component Id="Typical" Guid="{AC75B8DB-47D1-4D63-848F-DA13845804F3}" DiskId="1">
              <File Id="Typical.txt" Name="Typical.txt" Vital="yes" Source="Typical.txt" />
            </Component>
          </Directory>

          <Directory Id="FullFolder" Name="Full">
            <Component Id="Full" Guid="{4CB8DB95-2CA2-4B93-8F08-994113FBD627}" DiskId="1">
              <File Id="Full.txt" Name="Full.txt" Vital="yes" Source="Full.txt" />
            </Component>
          </Directory>

        </Directory>
      </Directory>
    </Directory>

    <Feature Id="MainTree" Title="My Product" Level="1">
      <Feature Id="MinimumFeature"
               Title="Minimum" Absent="allow"
               Description="Installs Minimum.txt"
               Level="1">
        <ComponentRef Id="Minimum" />
      </Feature>
      <Feature Id="TypicalFeature"
               Title="Typical"
               Description="Installs Typical.txt"
               Level="3">
        <ComponentRef Id="Typical" />
      </Feature>
      <Feature Id="FullFeature"
               Title="Full"
               Description="Installs Full.txt"
               Level="1000">
        <ComponentRef Id="Full" />
      </Feature>
    </Feature>

    <UIRef Id="WixUI_Mondo" />

  </Product>
</Wix>

To create the msi file I am using the following MSBuild project (Part1.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>Part1</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>
    <WixLibrary Include="$(ToolPath)wixui.wixlib"></WixLibrary>
    <LocalizationFile Include="$(ToolPath)WixUI_en-us.wxl"></LocalizationFile>
  </ItemGroup>

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

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

As you can see, MinimumFeature has Level 1, TypicalFeature - 3, and FullFeature - 1000.  Let's test it first by installing our application using command line with default Install Level and no user interface options:

msiexec /i Part1.msi /qb

Make sure that we have one subfolder Minimum in the installation folder which contains the Minimum.txt file.

Uninstall the application and try these two commands one at a time:

msiexec /i Part1.msi /qb INSTALLLEVEL=3

msiexec /i Part1.msi /qb INSTALLLEVEL=1000

See how results are different.

Now, let's test the same Part1.msi by installing it with the user interface.  Right-click on it and select "Install".

First screen is a welcome screen.  Click the Next button.  Select "I accept the terms of License Agreement" check box in the second screen.  Click the Next button.

From this point test separatly Typical and Complete buttons and compare results with running commands with INSTALLLEVEL set to 3 and 1000.

Now, let's do more interesting testing.  Click the Custom button.

You'll see collapsed root node for our feature tree.  If you want it to be expanded - add  Display attribute to the root <Feature> element and set its value to "expand":

<Feature Id="MainTree" Title="My Product" Level="1" Display="expand">
  ...
</Feature>

Notice that Minimum feature is set to be installed locally and Typical and Full features are set to be unavailable (or not to be installed at all).  That does make sense because remember that default value of INSTALLLEVEL property is 1.  The Level attribute of Typical and Full features is set to a value greater than 1 and therefore they won't be installed by default.

Let's play a little bit with that.  Add INSTALLLEVEL property to your Property table by adding this line after <Media> element:

<Property Id="INSTALLLEVEL" Value="3" />

Recompile the project and start installation again.  Now you should see Minimum and Typical set to install-locally.  Try to change the value of INSTALLLEVEL property to 1000 and check if all three features are set to be installed locally.

Now, let's explore other options for features.  Click on the image on the left from Minimum feature.  You should see the following choices in the drop-down menu:

• Will be installed on local hard drive
• Entire feature will be installed on local hard drive
• Feature will be installed when required
• Entire feature will be unavailable

What if we want feature Minimum to be installed always and we don't want users to be able to disable it?  Use the Absent attribute to remove this option from the menu.  Set it to "disallow":

<Feature Id="MinimumFeature"
         Title="Minimum"
         Description="Installs Minimum.txt"
         Absent="disallow"
         Level="1">
  <ComponentRef Id="Minimum" />
</Feature>

You can even hide it from the Selection Dialog and this feature still will be installed:

<Feature Id="MinimumFeature"
         Title="Minimum"
         Description="Installs Minimum.txt"
         Display="hidden"
         Level="1">
  <ComponentRef Id="Minimum" />
</Feature>

Advertising Options

If you don't want "Feature will be installed when required" option set AllowAdvertise attribute to "no":

<Feature Id="MinimumFeature"
         Title="Minimum"
         Description="Installs Minimum.txt"
         AllowAdvertise="no"
         Level="1">
  <ComponentRef Id="Minimum" />
</Feature>

Not all Windows OS support advertising.  If you want to allow advertising, but have no control over on which Windows OS your product will be installed, set AllowAdvertise to "system":

<Feature Id="MinimumFeature"
         Title="Minimum"
         Description="Installs Minimum.txt"
         AllowAdvertise="system"
         Level="1">
  <ComponentRef Id="Minimum" />
</Feature>

To set initial installation state for the feature to "Feature will be installed when required" set TypicalDefault attribute:

<Feature Id="MinimumFeature"
         Title="Minimum"
         Description="Installs Minimum.txt"
         TypicalDefault="advertise"
         Level="1">
  <ComponentRef Id="Minimum" />
</Feature>

Configurable Directory

As you can see, Browse button is disabled and therefore you can not change the installation directory.  To be able to choose different installation directory we need to add ConfigurableDirectory attribute to the parent feature:

<Feature Id="MainTree" Title="My Product" Level="1"
         ConfigurableDirectory="INSTALLLOCATION">
   ...
</Feature>

Now, Browse button is enabled and we can select different installation directory.

Remember that the Id of the <Directory> element you want to able to configure must be all in upper-case letters.  That makes it to be a Public Property.

Fixing the Root node's menu

If you will click on the image next to root node "My Product" you will notice that it has two more options:

• Will be installed to run from network
• Entire feature will be installed to run from network

Windows Installer always adds these two items to features which don't have any components.  The workaround here is to add an empty component to the root feature:

<Directory Id="TARGETDIR" Name="SourceDir">
  <Directory Id="ProgramFilesFolder">
    <Directory Id="INSTALLLOCATION"
               Name="MyAppDir"
               LongName="My Application Directory">
      ...
      <Component Id="Empty" Guid="" />

    </Directory>
  </Directory>
</Directory>

<Feature Id="MainTree" Title="My Product" Level="1"
         ConfigurableDirectory="INSTALLLOCATION">
  ...
  <ComponentRef Id="Empty" />
</Feature>

Part1.zip