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

Comments

Anonymous
May 08, 2008
The comment has been removed
Anonymous
June 10, 2008
The comment has been removed
Anonymous
July 07, 2008
Very informative and good article. In my product I had to create shortcut icons from external icon file and I discovered that the icon id name should end with .exe to work on Vista <Icon Id="myIcon.exe" SourceFile="..myIcon.ico" /> If I change this to Id="myIcon.ico", the shortcut icons are not displayed on Vista, but they work on Server 2003 /XP
Anonymous
July 07, 2008
Hi Sachin, Description of Icon table (http://msdn.microsoft.com/en-us/library/aa369210(VS.85).aspx) on MSDN has the following: "... Icon files that are associated strictly with file extensions or CLSIDs can have any extension, such as .ico. However, Icon files that are associated with shortcuts must be in the EXE binary format and must be named such that their extension matches the extension of the target. The shortcut will not work if this rule is not followed. For example, if a shortcut is to point to a resource having the key file Red.bar, then the icon file must also have the extension .bar. ..." So, if you are installing an executable, your icon file must have .exe extension.
Anonymous
July 30, 2008
How can i pass a property value to the name of the shortcut?
Anonymous
August 21, 2008
Ajay, Sorry for the delay. You can't pass property's value to the Name/LongName attribute of the Shortcut element. The reason for this is that the type of the Name field in the Shortcut table (http://msdn.microsoft.com/en-us/library/aa371847(VS.85).aspx) is Filename. The only datatype which accepts values of other properties/environment variables is Formatted. Alex
Anonymous
October 30, 2008
Hi guys, For localisation and changes to shortcuts name on upgrade, you can remove orphan shortcut using the following and also if you use variables for your shortcut (e.g Product 5.0, Prodcut 6.0 and so on... where in each product version or upgrade, your version changes.) as pointed in my post http://n2.nabble.com/Variable-Shorcut-Name-and-Upgrading...-td1392525.html#a1401696 :- It is to remove the files explicitly on install and uninstall~!!! <RemoveFile Id="RemoveDesktopShortcut" On="both" Name="shortc_1" LongName="Product*" Directory="DesktopFolder"/> <RemoveFile Id="RemoveProgramShortcut" On="both" Name="shortc_1" LongName="Product*" Directory="ProgramMenu"/> In addition, I specify the wildcard * so that the product will be removed~!!! With reference to RemoveFiles Action, you will also need to schedule the following due to Sequence Restrictions:- The InstallValidate action must be called before calling RemoveFiles. If an InstallFiles action is used, it must appear after RemoveFiles. Thanks Michael...for you are the only one to reply...haha.... Good luck guys who have similar problems =) -Tony
Anonymous
October 31, 2008
I am installing a product in per machine mode. my requirement is to provide shortcuts to my applications in Program Menu folder, along with a Uninstall product shortcut for all users. 1 .I having trouble placing the Uninstall shortcut, [which is a target to msisexec with product code argument]. Since its non-advertised target, it wouldn't let me have it a file, but needs a HKCU registry entry as keypath :ICE43.

It is my understanding that only Advertised shortcuts are removed during an uninstall. Even though i remove my shortcuts folder, only the Uninstall link stays back in the folder. This happens only when more than one version of the product is installed. The article was very informative, thought you could shed some light on my issues. thanks for the help.

Anonymous
November 02, 2008
Arun, For uninstall shortcut and ICE43 issue read Rob's blog: http://robmensching.com/blog/archive/2007/04/27/How-to-create-an-uninstall-shortcut-and-pass-all-the.aspx
Anonymous
January 14, 2009
Hi Alex again, I am trying to do conditional programmenu and desktop shortcuts. I put checkboxes on verifyready dialog. And trying to make my msi create them if they are choosed. I searched for it but couldn't get a useful document. What should I do? Do you have an example for this? Thanks
Anonymous
May 18, 2009
how i can make feature to run-from-source.. meaning.. i am having cd drive where i have msi when i install all the feature except one feaure should run-from-source ,after successful installation the application should run only when the source msi cd is inserted into machine because the feature is run-from-source....and without feature applicaion can run...how can i do this
Anonymous
May 18, 2009
The comment has been removed
Anonymous
August 20, 2009
The comment has been removed
Anonymous
December 30, 2009
Hello everyone, Does any one know how to create a Shortcut on QuickLaunch and whats the sample wix script for that. Thanks in advance.
Anonymous
January 17, 2010
Hello everyone, Does any one know how to create a Shortcut on QuickLaunch and what's the sample Wix script for that. Thanks in advance, vinodk
Anonymous
September 29, 2010
To create non-advertised shortcuts and avoid a bunch of ICE errors start with creating advertised shortcuts and set DISABLEADVTSHORTCUTS to 1. WindowsInstaller will convert the shortcuts to non-advertised, but as far as ICE is concerned you're creating advertised shortcuts

Share via

From MSI to WiX, Part 10 - Shortcuts

Comments

Additional resources