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 |
Description |
|
Column |
Flag |
||
Feature |
Id |
Unique primary key to identify the |
|
Feature_Parent |
In MSI database used to create a |
||
Title |
Title |
The short name of the feature. |
|
Description |
Description |
The long name of the feature. |
|
Display |
Display="collapse" |
The number in this field specifies
|
|
Level |
Level |
Initial installation level of the |
|
Directory_ |
ConfigurableDirectory |
The Id of the directory that can |
|
Attributes |
FavorLocal |
InstallDefault="local" |
Components of this feature will be |
FavorSource |
InstallDefault="source" |
Components of this feature will be |
|
FollowParent |
InstallDefault="followParent" |
Installation option of this |
|
FavorAdvertise |
TypicalDefault="advertise" |
See Advertising Options below for |
|
DisallowAdvertise |
AllowAdvertise="yes" AllowAdvertise="no" |
See Advertising Options below for |
|
UIDisallowAbsent |
Absent="allow" Absent="disallow" |
Enables or disables in the user |
|
NoUnsupportedAdvertise |
AllowAdvertise="system" |
See Advertising Options below for |
Components
In MSI database
components are represented by Component
table.
Component table |
Component element's |
Description |
|
Column |
Flag |
||
Component |
Id |
Unique primary key to identify the |
|
ComponentId |
Guid |
A string GUID unique to this |
|
Directory_ |
External key to the record in the Directory |
||
Condition |
This column contains a conditional |
||
KeyPath |
KeyPath="yes" |
Sets the folder where Component is |
|
Attributes |
LocalOnly |
Location="local" |
Component must be installed |
SourceOnly |
Location="source" |
Component can only be run from |
|
Optional |
Location="either" |
Component can run locally or from |
|
RegistryKeyPath |
In WiX this flag is represented by |
||
SharedDllRefCount |
SharedDllRefCount="yes" |
If this bit is set, the installer |
|
Permanent |
Permanent="yes" |
Component will be never removed |
|
Transitive |
Transitive="yes" |
Component must have a condition |
|
NeverOverwrite |
NeverOverwrite="yes" |
If the KeyPath file or KeyPath |
|
64bit |
Win64="yes" |
Marks 64-bit component. |
|
DisableRegistryReflection |
DisableRegistryReflection="yes" |
Disables Registry |
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>