Alex Shevchuk : From MSI to WiX, Part 10

From MSI to WiX, Part 10 - Shortcuts

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=http://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.

Published Wednesday, February 20, 2008 3:55 PM by Alex Shevchuk

Filed under: Microsoft Installer, MSI, WiX

Attachment(s): Shortcuts.zip

Comment Notification

If you would like to receive an email when updates are made to this post, please register here

Subscribe to this post's comments using RSS

Comments

Thursday, May 08, 2008 8:51 PM by Tonko

# re: From MSI to WiX, Part 10 - Shortcuts

Again Alex you did a great job and a favor to Wix installation developers like myself.

I was looking for a good reference on shortcuts but what I found is mostly incomplete or uses a fake Registry search component (for reasons I did't quite understand.)

The bit on removing the shortcut from roaming profile is very much appreciated.

Tuesday, June 10, 2008 10:54 AM by Rick R

# re: From MSI to WiX, Part 10 - Shortcuts

Good article, but I have a question/comment about localization.

When localizing the name of the shortcut, you change the name of a file (the .lnk file) in a component. According to MSI rules, you must therefore change the name of all other files/registry entries in the same component, including the .exe file.

If this rule isn't followed, you can get orphaned shortcuts if you install your product with Language A, overwrite it with Language B, and then uninstall.

Since advertised shortcuts must be in the same component as the file they advertise, I haven't ever been able to use advertised shortcuts.

Am I missing something, or are advertised shortcuts not practical in Windows XP if my product requires the language overwriting desribed above?

Monday, July 07, 2008 3:04 PM by Sachin

# re: From MSI to WiX, Part 10 - Shortcuts

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

If I change this to Id="myIcon.ico", the shortcut icons are not displayed on Vista, but they work on Server 2003 /XP

Monday, July 07, 2008 7:27 PM by Alex Shevchuk

# re: From MSI to WiX, Part 10 - Shortcuts

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.

Wednesday, July 30, 2008 9:19 AM by Ajay

# re: From MSI to WiX, Part 10 - Shortcuts

How can i pass a property value to the name of the shortcut?

Thursday, August 21, 2008 9:23 PM by Alex Shevchuk

# re: From MSI to WiX, Part 10 - Shortcuts

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

Thursday, October 30, 2008 11:15 PM by Tony

# re: From MSI to WiX, Part 10 - Shortcuts

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~!!!

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

Friday, October 31, 2008 3:09 PM by Arun

# re: From MSI to WiX, Part 10 - Shortcuts

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.

2. 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.

Sunday, November 02, 2008 2:29 PM by Alex Shevchuk

# re: From MSI to WiX, Part 10 - Shortcuts

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

Wednesday, January 14, 2009 7:42 AM by Fatih

# re: From MSI to WiX, Part 10 - Shortcuts

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

Monday, May 18, 2009 8:57 AM by sam

# re: From MSI to WiX, Part 10 - Shortcuts

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

Monday, May 18, 2009 11:52 AM by Alex Shevchuk

# re: From MSI to WiX, Part 10 - Shortcuts

Hi Sam,

You need to set Feature/@InstallDefault to "source". In addition you may want to set Feature/@Display to "hidden", so user won't be able to change installation state to "local". Also, you may want to set Component/@Location to "source".

Alex

Thursday, August 20, 2009 2:49 AM by SamDesilva

# msiexec.exe -Embedding <GUID> - this is the custom action server (indicated by the -Embedding switch)

i would like like to know

what guid stand in

msiexec.exe -Embedding <GUID> - this is the custom action server (indicated by the -Embedding switch)

since it is not the product guid and not component guid and it is changing every time when i install could you please help me in this regard

Wednesday, December 30, 2009 4:21 AM by vinodk

# re: From MSI to WiX, Part 10 - Shortcuts

Hello everyone,

Does any one know how to create a Shortcut on QuickLaunch and whats the sample wix script for that. Thanks in advance.

Sunday, January 17, 2010 11:20 PM by vinodk

# re: From MSI to WiX, Part 10 - Shortcuts

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

Title (required)
Name required
Your URL
Comments (required)

Enter Code Here: Required
Remember Me?

Alex Shevchuk

This Blog

Syndication

Search

From MSI to WiX

WiX Blogs

От MSI к WiX (русская версия)

Tags

Recent Posts

Archives

From MSI to WiX, Part 10 - Shortcuts

Comment Notification

Comments

# re: From MSI to WiX, Part 10 - Shortcuts

# re: From MSI to WiX, Part 10 - Shortcuts

# re: From MSI to WiX, Part 10 - Shortcuts

# re: From MSI to WiX, Part 10 - Shortcuts

# re: From MSI to WiX, Part 10 - Shortcuts

# re: From MSI to WiX, Part 10 - Shortcuts

# re: From MSI to WiX, Part 10 - Shortcuts

# re: From MSI to WiX, Part 10 - Shortcuts

# re: From MSI to WiX, Part 10 - Shortcuts

# re: From MSI to WiX, Part 10 - Shortcuts

# re: From MSI to WiX, Part 10 - Shortcuts

# re: From MSI to WiX, Part 10 - Shortcuts

# msiexec.exe -Embedding <GUID> - this is the custom action server (indicated by the -Embedding switch)

# re: From MSI to WiX, Part 10 - Shortcuts

# re: From MSI to WiX, Part 10 - Shortcuts

Leave a Comment