From MSI to WiX, Part 10 - Shortcuts

Article
02/20/2008

The main page for the series is here.

Introduction

Microsoft Windows Installer supports four installation states for product features:

Installed locally
Installed to run from source
Absent
Advertised

When feature is advertised, it is not actually installed on the local system. However, appropriate shortcut to launch the feature is present. The first time a user attempts to use an advertised feature, feature is installed on user's computer.

Microsoft Windows Installer supports two type of shortcuts:

Advertised shortcut:
- Created on the target system when product/component is advertised.
- Supported on all operating systems with Internet Explorer 4.01 or greater installed.
- Provides the key features: Install-On-Demand and Self-Repair.
Non-advertised shortcut:
- Can launch any executable or file, whether it is being installed by the current installation or already exists on the target system.
- Does not support Self-Repair.
- Should be avoided due to the nature of user profiles, per-machine/per-user installs, and the relationships between Features, Components and their key paths.

What is involved in creating shortcuts in MSI

Two standard actions and one table are required to successfully install/uninstall shortcuts.

The RemoveShortcuts action manages the removal of a shortcut and the CreateShortcuts action manages the creation of shortcuts. These actions must be scheduled in the following order:

…

InstallInitialize

…

RemoveShortcuts

…

InstallFiles

…

CreateShortcuts

…

InstallFinalize

…

Information about shortcuts is stored in the Shortcut table. Here is the table with description for columns of Shortcut table and attributes of <Shortcut> element:

Shortcut table	<Shortcut> element	Description
Shortcut	Id	Primary key for the row.
Directory_	Directory	The external key to the Directory table (reference to <Directory> element) in which the shortcut file is created.
Name	Name/LongName	The localizable name for the shortcut.
Component_	Parent <Component>	The external key to the Component table.
Target	Target	For advertised shortcuts: The external key to the Feature table.For Non-advertised shortcuts: Formatted identifier pointing to a file or a folder.
Arguments	Arguments	The command-line arguments for the shortcut.
Description	Description	The localizable description for the shortcut.
Hotkey	Hotkey	The hotkey for the shortcut. General recommendation is to not set this value.
Icon_	Icon	External key to the Icon table.
IconIndex	IconIndex	The icon index for the shortcut.
ShowCmd	Show	The Show command for the application window.
WkDir	WorkingDirectory	The name of the property that has the path of the working directory for the shortcut. The value can use the Windows format to reference environment variables, for example %USERPROFILE%.

There are four additional columns (with matching names for attributes) which are used on Windows Vista or above in Multilingual User Interface:

DisplayResourceDLL
DisplayResourceId
DescriptionResourceDLL
DescriptionResourceId

I will not discuss them in this post.

Test project

For this blog I am using the following console application as an installable software:

using System;

using System.Collections.Generic;

using System.Text;

namespace ConsoleApp

{

class Program

{

static void Main(string[] args)

{

Console.WriteLine("Hello world!");

Console.ReadLine();

}

Advertised shortcut sample

Here is the source for the advertised shortcut sample:

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

<?define APPPATH = "..\Project\ConsoleApp\bin\Debug"?>

<Product Id="{0B97B94B-5387-45B0-A34C-EFFAD7F6E509}"

Name="Advertised Shortcut Sample"

Language="1033"

Codepage="1252"

Version="1.0.0"

Manufacturer="Acme Corporation"

UpgradeCode="{FC888F32-A21B-4AFB-81E9-EDBFB91E507B}">

<Package Id="{86EC5FC3-F006-4BFB-9EDA-8E8E72AC7325}"

Description="Advertised Shortcut Sample"

Comments="This installer database contains the logic and data required to install Advertised Shortcut Sample."

InstallerVersion="200"

Languages="1033"

SummaryCodepage="1252"

Platforms="Intel"

ReadOnly="no"

Compressed="yes"

AdminImage="no"

Keywords="Installer"

ShortNames ="no"

Manufacturer="Acme Corporation" />

<Component Id="Component1"

Guid="{7A274A33-CEFE-4A0E-9E47-EFC8169EA480}"

DiskId="1">

<File Id="ConsoleApp.exe"

Name="ConsApp.exe"

LongName="ConsoleApp.exe"

Vital="yes"

KeyPath="yes"

Source="$(var.APPPATH)\ConsoleApp.exe">

<Shortcut Id="startmenuAdv"

Directory="ProgramMenuDir"

Advertise="yes"

Name="Advertis"

LongName="Advertised Shortcut Sample"

WorkingDirectory="INSTALLDIR"

Icon="Icon.exe">

</Shortcut>

</File>

</Component>

</Directory>

</Directory>

<Feature Id="Feature1"

Title="Feature1 title"

Description="Feature1 description"

Level="1"

AllowAdvertise="yes"

TypicalDefault="advertise"

ConfigurableDirectory="INSTALLDIR" >

</Feature>

</Product>

</Wix>

Initial installation state for the feature Feature1 is Advertise (TypicalDefault="advertise"

). In this sample, advertised shortcut will be installed in the Start/All Programs menu. Create an installer database by using these two commands:

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

Install the application, make sure that folder "Advertised Shortcut" is not present in the Program Files folder. Click on Start/All Programs/Advertised Shortcut/Advertised Shortcut Sample. You will notice that application is being installed and after installation is completed, console window will pop up with the message "Hello World!". Press Enter to close the window.

Open "Program Files/Advertised Shortcut" folder. Delete the ConsoleApp.exe file. Start the application again clicking on the shortcut in the Start/All Programs/Advertised Shortcut/Advertised Shortcut Sample. You will notice that application is being installed again and console window will pop up after installation is done. That was the Self-Repair feature of advertised shortcuts.

Fixing ICE error

If you will run validation on the Advertised.msi you will get error ICE64 with the error message "The directory ProgramMenuDir is in the user profile but not listed in the RemoveFile table". ICE64 is telling you that in the roaming scenario folder for a shortcut won't be removed from the user profile. To fix this error we need to add RemoveFolder element to a component which installs the shortcut:

<Component Id="Component1"

Guid="{7A274A33-CEFE-4A0E-9E47-EFC8169EA480}"

DiskId="1">

<File Id="ConsoleApp.exe"

Name="ConsApp.exe"

LongName="ConsoleApp.exe"

Vital="yes"

KeyPath="yes"

Source="$(var.APPPATH)\ConsoleApp.exe">

<Shortcut Id="startmenuAdv"

Directory="ProgramMenuDir"

Advertise="yes"

Name="Advertis"

LongName="Advertised Shortcut Sample"

WorkingDirectory="INSTALLDIR"

Icon="Icon.exe">

</Shortcut>

</File>

<RemoveFolder Id="DeleteShortcutFolder"

Directory="ProgramMenuDir"

On="uninstall" />

</Component>

Non-advertised shortcut sample

Here is the source for non-advertised shortcut sample:

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

<?define APPPATH = "..\Project\ConsoleApp\bin\Debug"?>

<Product Id="{1F39DCE0-2260-4864-9BA0-485E6A71DF53}"

Name="Nonadvertised Shortcut Sample"

Language="1033"

Codepage="1252"

Version="1.0.0"

Manufacturer="Acme Corporation"

UpgradeCode="{6E802644-B952-4F69-AC5C-6F7F85F5B2D8}">

<Package Id="{EC78A9CE-C9AD-4C83-8ADB-AABDB21133A8}"

Description="Nonadvertised Shortcut Sample"

Comments="This installer database contains the logic and data required to install Nonadvertised Shortcut Sample."

InstallerVersion="200"

Languages="1033"

SummaryCodepage="1252"

Platforms="Intel"

ReadOnly="no"

Compressed="yes"

AdminImage="no"

Keywords="Installer"

ShortNames ="no"

Manufacturer="Acme Corporation" />

<Component Id="Component1"

Guid="{213F41E8-8AD5-4BEA-AFC5-652A02F6596F}"

DiskId="1">

<File Id="ConsoleApp.exe"

Name="ConsApp.exe"

LongName="ConsoleApp.exe"

Vital="yes"

KeyPath="yes"

Source="$(var.APPPATH)\ConsoleApp.exe" />

<Shortcut Id="startmenuNonadv"

Directory="ProgramMenuDir"

Advertise="no"

Name="Nonadver"

LongName="Nonadvertised Shortcut Sample"

WorkingDirectory="INSTALLDIR"

Icon="Icon.exe"

Target="[!ConsoleApp.exe]">

</Shortcut>

<RemoveFolder Id="DeleteShortcutFolder"

Directory="ProgramMenuDir"

On="uninstall" />

</Component>

</Directory>

</Directory>

<Feature Id="Feature1"

Title="Feature1 title"

Description="Feature1 description"

Level="1"

ConfigurableDirectory="INSTALLDIR" >

</Feature>

</Product>

</Wix>

Special case - Internet shortcut

Even though it is not supported directly by MSI and WiX, you still can create an Internet shortcut.

Create a file Microsoft.txt:

[InternetShortcut]

URL=https://www.microsoft.com

Here is the source for installing advertised Internet shortcut:

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

<?define APPPATH = "D:\MyLearning\WiX\Shortcuts\Project\ConsoleApp\bin\Debug"?>

<Product Id="{D0A6D167-690D-465C-806D-0FE6C17EB9B7}"

Name="Internet Shortcut Sample"

Language="1033"

Codepage="1252"

Version="1.0.0"

Manufacturer="Acme Corporation"

UpgradeCode="{2E8AA511-1970-4085-942B-42293A21B827}">

<Package Id="{1A7EA7DE-2B0C-4DC6-ACF1-5F2808B806B3}"

Description="Internet Shortcut Sample"

Comments="This installer database contains the logic and data required to install Internet Shortcut Sample."

InstallerVersion="200"

Languages="1033"

SummaryCodepage="1252"

Platforms="Intel"

ReadOnly="no"

Compressed="yes"

AdminImage="no"

Keywords="Installer"

ShortNames ="no"

Manufacturer="Acme Corporation" />

<Component Id="Component1"

Guid="{7A274A33-CEFE-4A0E-9E47-EFC8169EA480}"

DiskId="1">

<File Id="Microsoft.txt"

Name="MS.url"

LongName="Microsoft.url"

Vital="yes"

KeyPath="yes"

Source="Microsoft.txt">

<Shortcut Id="startmenuInternet"

Directory="ProgramMenuDir"

Advertise="yes"

Name="Intern"

LongName="Internet Shortcut Sample"

WorkingDirectory="INSTALLDIR"

Icon="Icon.exe">

</Shortcut>

</File>

<RemoveFolder Id="DeleteShortcutFolder"

Directory="ProgramMenuDir"

On="uninstall" />

</Component>

</Directory>

</Directory>

<Feature Id="Feature1"

Title="Feature1 title"

Description="Feature1 description"

Level="1"

AllowAdvertise="yes"

TypicalDefault="advertise"

ConfigurableDirectory="INSTALLDIR" >

</Feature>

</Product>

</Wix>

Special case - Starting application in the command window

We want to start our application in the command window. Command window must stay after our application will exit.

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

<?define APPPATH = "D:\MyLearning\WiX\Shortcuts\Project\ConsoleApp\bin\Debug"?>

<Product Id="{7DDD5785-FDDC-43A9-857F-75A3499B44B8}"

Name="Comspec Shortcut Sample"

Language="1033"

Codepage="1252"

Version="1.0.0"

Manufacturer="Acme Corporation"

UpgradeCode="{69CCD9BE-D753-4300-B3CA-2D645C795C2D}">

<Package Id="{58D0EF68-8DED-4F08-A6CD-C9487E5B4B5E}"

Description="Comspec Shortcut Sample"

Comments="This installer database contains the logic and data required to install Comspec Shortcut Sample."

InstallerVersion="200"

Languages="1033"

SummaryCodepage="1252"

Platforms="Intel"

ReadOnly="no"

Compressed="yes"

AdminImage="no"

Keywords="Installer"

ShortNames ="no"

Manufacturer="Acme Corporation" />

<Component Id="Component1"

Guid="{FC5A459A-74E6-4DF1-8A9A-EE9897414CFA}"

DiskId="1">

<File Id="ConsoleApp.exe"

Name="ConsApp.exe"

LongName="ConsoleApp.exe"

Vital="yes"

KeyPath="yes"

Source="$(var.APPPATH)\ConsoleApp.exe" />

<Shortcut Id="startmenuComspec"

Directory="ProgramMenuDir"

Advertise="no"

Name="Comspec"

LongName="Comspec Shortcut Sample"

WorkingDirectory="INSTALLDIR"

Icon="Icon.exe"

Target="[%ComSpec]"

Arguments='/k "[!ConsoleApp.exe]"'

Show="normal">

</Shortcut>

</Component>

</Directory>

</Directory>

<Feature Id="Feature1"

Title="Feature1 title"

Description="Feature1 description"

Level="1"

ConfigurableDirectory="INSTALLDIR" >

</Feature>

</Product>

</Wix>

Uninstall shortcut

For more details on why we need HKCU registry key as a keypath for uninstall shortcut component, read Rob Mensching's blog post How to create an uninstall shortcut (and pass all the ICE validation).

Here is the V3 code for uninstall shortcut sample which is almost identical to Rob's sample.

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

<?define APPPATH = "..\..\Project\ConsoleApp\bin\Debug"?>

<Product Id="{2E8A39F5-0699-4812-8863-8EB8C8D0DA39}"

Name="UninstallShortcut"

Language="1033"

Version="1.0.0.0"

Manufacturer="UninstallShortcut"

UpgradeCode="{A87BD175-7754-454A-B71E-13094FCB40C1}">

<Package InstallerVersion="200"

Compressed="yes"

InstallScope="perMachine" />

<Component Id="Component1"

Guid="{1ED0183B-198D-4612-ABEE-1BDE42F3CF54}"

DiskId="1">

<RegistryKey Root="HKCU"

Key="Software\Uninstall Shortcut Sample\Uninstall">

<RegistryValue Value="KeyPathValue"

Type="string"

KeyPath="yes" />

</RegistryKey>

<Shortcut Id="startmenuNonadv"

Directory="ProgramMenuDir"

Advertise="no"

Name="Uninstall Shortcut Sample"

WorkingDirectory="INSTALLDIR"

Icon="Icon.exe"

Target="[SystemFolder]msiexec.exe"

Arguments="/x [ProductCode]">

</Shortcut>

<RemoveFolder Id="DeleteShortcutFolder"

Directory="ProgramMenuDir"

On="uninstall" />

</Component>

<Component Id="Component2"

Guid="{5178004E-6F08-4A77-8178-80CB0DF55E15}"

DiskId="1">

<File Id="ConsoleApp.exe"

Name="ConsoleApp.exe"

Vital="yes"

KeyPath="yes"

Source="$(var.APPPATH)\ConsoleApp.exe" />

</Component>

</Directory>

</Directory>

</Feature>

</Product>

</Wix>

Attached is zip file containing all samples.

Shortcuts.zip

From MSI to WiX, Part 10 - Shortcuts

Additional resources