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

时间:2022-11-15 14:05:50

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