WiX Toolset

When installing applications it is a common requirement to place a shortcut on the user’s Start Menu to provide a launching point for the program. This how to walks through how to create a shortcut on the start menu. It assumes you have a WiX source file based on the concepts described in How To: Add a file to your installer.

Step 1: Define the directory structure

Start Menu shortcuts are installed in a different directory than regular application files, so modifications to the installer’s directory structure are required. The following WiX fragment should be placed inside a element with the TARGETDIR ID and adds directory structure information for the Start Menu:

The ProgramMenuFolder Id is a standard Windows Installer property that points to the Start Menu folder on the target machine. The second Directory element creates a subfolder on the Start Menu called My Application Name, and gives it an id for use later in the WiX project.

Step 2: Add the shortcut to your installer package

A shortcut is added to the installer using three elements: a element to specify an atomic unit of installation, a element to specify the shortcut that should be installed, and a element to ensure proper cleanup when your application is uninstalled.

The following sample uses the directory structure defined in Step 1 to create the Start Menu shortcut.

The element is used to refer to the directory structure created in step 1. By referencing the ApplicationProgramsFolder directory the shortcut will be installed into the user’s Start Menu inside the My Application Name folder.

Underneath the DirectoryRef is a single Component to group the elements used to install the Shortcut. The first element is Shortcut and it creates the actual shortcut in the Start Menu. The Id attribute is a unique id for the shortcut. The Name attribute is the text that will be displayed in the Start Menu. The description is an optional attribute for an additional application description. The Target attribute points to the executable to launch on disk. Notice how it references the full path using the [#FileId] syntax where myapplication.exe was previously defined. The WorkingDirectory attribute sets the working directory for the shortcut.

To set an optional icon for the shortcut you need to first include the icon in your installer using the element, then reference it using the Icon attribute on the Shortcut element.

In addition to creating the shortcut the component contains two other important pieces. The first is a RemoveFolder element, which ensures the ApplicationProgramsFolder is correctly removed from the Start Menu when the user uninstalls the application. The second creates a registry entry on install that indicates the application is installed. This is required as a Shortcut cannot serve as the KeyPath for a component when installing non-advertised shortcuts for the current users. For more information on creating registry entries see How To: Write a registry entry during installation.

Step 3: Tell Windows Installer to install the shortcut

After defining the directory structure and listing the shortcuts to package into the installer, the last step is to tell Windows Installer to actually install the shortcut. The element is used to do this. The following snippet adds a reference to the shortcut component, and should be inserted inside a parent Feature element.

The element is used to reference the component created in Step 2 via the Id attribute.

The Complete Sample

The following is a complete sample that uses the above concepts. This example can be inserted into a WiX project and compiled, or compiled and linked from the command line, to generate an installer.

Property Reference

This section lists the properties defined by Windows Installer:

Additional properties can be specified by authored data or custom actions. Properties with names containing no lowercase letters are public properties and can be specified on the command line.

For information about values of the Uninstall registry key that are provided by installer properties, see Uninstall Registry Key.

Component Location Properties

The following list provides links to more information about the component location properties.

Property	Description
OriginalDatabase	The installer sets this property to the launched-from database, the database on the source, or the cached database.
ParentOriginalDatabase	The installer sets this property for installations run by a Concurrent Installation action.
SourceDir	Root directory that contains the source files.
TARGETDIR	Specifies the root destination directory for the installation. During an administrative installation this property is the location to copy the installation package.

Configuration Properties

The following list provides links to more information about other configurable properties.

Property	Description
ACTION	Initial action called after the installer is initialized.
ALLUSERS	Determines where configuration information is stored.
ARPAUTHORIZEDCDFPREFIX	URL of the update channel for an application.
ARPCOMMENTS	Provides Comments for the Add or Remove Programs in Control Panel.
ARPCONTACT	Provides Contact for the Add or Remove Programs in Control Panel.
ARPINSTALLLOCATION	Fully qualified path to the primary folder of an application.
ARPNOMODIFY	Disables functionality that modifies a product.
ARPNOREMOVE	Disables functionality that removes a product.
ARPNOREPAIR	Disables the Repair button in the Programs wizard.
ARPPRODUCTICON	Specifies the primary icon for the installation package.
ARPREADME	Provides a ReadMe for the Add or Remove Programs in Control Panel.
ARPSIZE	Estimated size of an application in kilobytes.
ARPSYSTEMCOMPONENT	Prevents display of an application in the Add or Remove Programs list.
ARPURLINFOABOUT	URL for the home page of an application.
ARPURLUPDATEINFO	URL for application update information.
AVAILABLEFREEREG	Registry space (in kilobytes) that an application requires. Used by AllocateRegistrySpace action.
CCP_DRIVE	The root path for qualifying products for CCP.
DefaultUIFont	Default font style used for controls.
DISABLEADVTSHORTCUTS	Set to disable the generation the specific shortcuts that support installation-on-demand.
DISABLEMEDIA	Prevents the installer from registering media sources, such as a CD-ROMs, as valid sources for the product.
DISABLEROLLBACK	Disables rollback for the current configuration.
EXECUTEACTION	Top-level action that ExecuteAction initiates.
EXECUTEMODE	Mode of execution that the installer performs.
FASTOEM	Improves installation performance under specific OEM scenarios.
INSTALLLEVEL	Initial level where features are installed.
LIMITUI	UI level capped as Basic.
LOGACTION	List of action names to be logged.
MEDIAPACKAGEPATH	This property must be set to the relative path if the installation package is not located at the root of the CD-ROM.
MSIARPSETTINGSIDENTIFIER	This optional property contains a semi-colon delimited list of the registry locations where the application stores a user’s settings and preferences. Available with Windows Installer 4.0.
MSIDISABLEEEUI	Disable the embedded user interface for the installation. Windows Installer 4.0 and earlier: Not supported.
MSIFASTINSTALL	Reduce the time required to install a large Windows Installer package. Windows Installer 4.5 and earlier: Not supported.
MSIINSTALLPERUSER	Requests that the Windows Installer install the package only for the current user. Windows Installer 4.5 and earlier: Not supported.
MSINODISABLEMEDIA	Set this property to prevent the installer from setting the DISABLEMEDIA property.
MSIENFORCEUPGRADECOMPONENTRULES	Set this property to 1 (one) on the command line or in the Property Table to apply the upgrade component rules during small updates and minor upgrades of a specific product. Available beginning with Windows Installer 3.0.
MSIUNINSTALLSUPERSEDEDCOMPONENTS	When this property has been set to 1, the installer can unregister and uninstall redundant components to prevent leaving behind orphan components on the computer. Windows Installer 4.0 and earlier: Not supported.
PRIMARYFOLDER	Allows the author to designate a primary folder for an installation. Used to determine the values for the PrimaryVolumePath, PrimaryVolumeSpaceAvailable, PrimaryVolumeSpaceRequired, and PrimaryVolumeSpaceRemaining properties.
Privileged	Runs an installation with elevated privileges.
PROMPTROLLBACKCOST	Action if there is insufficient disk space for the installation.
REBOOT	Forces or suppresses a restart.
REBOOTPROMPT	Suppresses the display of prompts for restarts to the user. Any restarts that are needed happen automatically.
ROOTDRIVE	Default drive for an installation.
SEQUENCE	A table that has the sequence table schema.
SHORTFILENAMES	Causes short file names to be used.
TRANSFORMS	List of transforms to be applied to a database.
TRANSFORMSATSOURCE	Informs the installer that the transforms for a product reside at the source.
TRANSFORMSSECURE	Setting the TRANSFORMSECURE property to 1 (one) informs the installer that transforms are to be cached locally on the user computer in a location where the user does not have write access.
MsiLogFileLocation	The installer sets the value of this property to the full path of the log file, when logging has been enabled. This property is available starting with Windows Installer 4.0.
MsiLogging	Sets the default logging mode for the Windows Installer package. This property is available starting with Windows Installer 4.0.
MSIUSEREALADMINDETECTION	Set this property to 1 to request that the installer use actual user information when setting the AdminUser property. This property is available starting with Windows Installer 4.0.

Date, Time Properties

The Date and Time properties are live properties that the installer sets when data is extracted.

Property	Description
Date	The current date.
Time	The current time.

Feature Installation Options Properties

The following list provides links to more information about the feature installation options properties.

Property	Description
ADDDEFAULT	List of features to be installed in the default configuration.
ADDLOCAL	List of features to be installed locally.
ADDSOURCE	List of features to be run from source.
ADVERTISE	List of features to be advertised.
COMPADDDEFAULT	List of components to be installed in the default configuration.
COMPADDLOCAL	List of component IDs to be installed locally.
COMPADDSOURCE	List of component IDs to run from source media.
FILEADDDEFAULT	List of file keys for files to be installed in the default configuration.
FILEADDLOCAL	List of file keys for files to be run locally.
FILEADDSOURCE	List of file keys to be run from the source media.
MSIDISABLELUAPATCHING	Setting this property prevents Least Privileged User (LUA) patching of an application.
MsiPatchRemovalList	List of patches to be removed during the installation.
MSIRESTARTMANAGERCONTROL	Specifies whether the package uses the Restart Manager or FilesInUse functionality.
MSIDISABLERMRESTART	Specifies how applications or services that are currently using files affected by an update should be shutdown and restarted to enable the installation of the update.
MSIRMSHUTDOWN	Specifies how applications or services that are currently using files affected by an update should be shutdown to enable the installation of the update.
MSIPATCHREMOVE	Setting this property removes patches.
PATCH	Setting this property applies a patch.
REINSTALL	List of features to be reinstalled.
REINSTALLMODE	A string that contains letters that specify the type of reinstall to perform.
REMOVE	List of features to be removed.

Hardware Properties

The following list identifies the hardware properties that the Windows Installer sets at startup.

Property	Description
Alpha	The numeric processor level when running on an Alpha processor. [!Note] This property is obsolete, the Alpha platform is not supported by Windows Installer.
BorderSide	The width of the window borders, in pixels.
BorderTop	The height of the window borders, in pixels.
CaptionHeight	The height of normal caption area, in pixels.
ColorBits	The number of adjacent color bits for each pixel.
Intel	The numeric processor level when running on an Intel processor.
Intel64	The numeric processor level when running on an Itanium processor.
Msix64	The numeric processor level when running on an x64 processor.
PhysicalMemory	The size of the installed RAM, in megabytes.
ScreenX	The width of the screen, in pixels.
ScreenY	The height of the screen, in pixels.
TextHeight	The height of characters, in logical units.
VirtualMemory	The amount of available page file space, in megabytes.

Installation Status Properties

The following list provides links to more information about status properties that are updated by the installer during installation.

Property	Description
AFTERREBOOT	Indicates current installation follows a reboot that the ForceReboot action invokes.
CostingComplete	Indicates whether disk space costing is complete.
Installed	Indicates that a product is already installed.
MSICHECKCRCS	The Installer does a CRC on files only if the MSICHECKCRCS property is set.
MsiRestartManagerSessionKey	The Installer sets this property to the session key for the Restart Manager session.
MsiRunningElevated	The Installer sets the value of this property to 1 when the installer is running with elevated privileges.
MsiSystemRebootPending	The Installer sets this property to 1 if a restart of the operating system is currently pending.
MsiUIHideCancel	The Installer sets MsiUIHideCancel to 1 when the internal install level includes INSTALLUILEVEL_HIDECANCEL.
MsiUIProgressOnly	The Installer sets MsiUIProgressOnly to 1 when the internal install level includes INSTALLUILEVEL_PROGRESSONLY.
MsiUISourceResOnly	MsiUISourceResOnly to 1 (one) when the internal install level includes INSTALLUILEVEL_SOURCERESONLY.
NOCOMPANYNAME	Suppresses the automatic setting of the COMPANYNAME property.
NOUSERNAME	Suppresses the automatic setting of the USERNAME property.
OutOfDiskSpace	Insufficient disk space to accommodate the installation.
OutOfNoRbDiskSpace	Insufficient disk space with rollback turned off.
Preselected	Features are already selected.
PrimaryVolumePath	The Installer sets the value of this property to the path of the volume that the PRIMARYFOLDER property designates.
PrimaryVolumeSpaceAvailable	The Installer sets the value of this property to a string that represents the total number of bytes available on the volume that the PrimaryVolumePath property references.
PrimaryVolumeSpaceRemaining	The Installer sets the value of this property to a string that represents the total number of bytes remaining on the volume that the PrimaryVolumePath property references if all the currently selected features are installed.
PrimaryVolumeSpaceRequired	The Installer sets the value of this property to a string that represents the total number of bytes required by all currently selected features on the volume that the PrimaryVolumePath property references.
ProductLanguage	Numeric language identifier (LANGID) for the database. (REQUIRED)
ReplacedInUseFiles	Set if the installer installs over a file that is being held in use.
RESUME	Resumed installation.
RollbackDisabled	The installer sets this property when rollback is disabled.
UILevel	Indicates the user interface level.
UpdateStarted	Set when changes to the system have begun for this installation.
UPGRADINGPRODUCTCODE	Set by the installer when an upgrade removes an application.
VersionMsi	The installer sets this property to the version of Windows Installer that is run during the installation.

Operating System Properties

The following list provides links to more information about operating system properties that the Installer sets at startup.

Property Name	Brief Description
AdminUser	Set on WindowsВ 2000 if the user has administrator privileges.
ComputerName	Computer name of the current system.
MsiNetAssemblySupport	On systems that support common language runtime assemblies, the Installer sets the value of this property to the file version of fusion.dll. The Installer does not set this property if the operating system does not support common language runtime assemblies.
MsiNTProductType	Indicates the Windows product type.
MsiNTSuiteBackOffice	On WindowsВ 2000 and later operating systems, the Installer sets this property to 1 (one) only if Microsoft BackOffice components are installed.
MsiNTSuiteDataCenter	On WindowsВ 2000 and later operating systems, the Installer sets this property to 1 (one) only if WindowsВ 2000 Datacenter Server is installed.
MsiNTSuiteEnterprise	On WindowsВ 2000 and later operating systems, the Installer sets this property to 1 (one) only if WindowsВ 2000 Advanced Server is installed.
MsiNTSuitePersonal	On WindowsВ XP and later operating systems, the Installer sets this property to 1 (one) only if the operating system is Home (not Professional).
MsiNTSuiteSmallBusiness	On WindowsВ 2000 and later operating systems, the Installer sets this property to 1 (one) only if Microsoft Small Business Server is installed.
MsiNTSuiteSmallBusinessRestricted	On WindowsВ 2000 and later operating systems, the Installer sets this property to 1 (one) only if Microsoft Small Business Server is installed with the restrictive client license.
MsiNTSuiteWebServer	On WindowsВ 2000 and later operating systems, the Installer sets the MsiNTSuiteWebServer property to 1 (one) if the web edition of the Windows ServerВ 2003 is installed. Only available with the Windows ServerВ 2003 release of the Windows Installer.
MsiTabletPC	The installer sets this property to a nonzero value if the current operating system is WindowsВ XP Tablet PC Edition.
MsiWin32AssemblySupport	On systems that support Win32 assemblies, the Installer sets the value of this property to the file version of sxs.dll. The Installer does not set this property if the operating system does not support Win32 assemblies.
OLEAdvtSupport	Set if OLE supports the Windows Installer.
RedirectedDllSupport	The Installer sets the RedirectedDllSupport property if the system performing the installation supports Isolated Components.
RemoteAdminTS	The Installer sets the RemoteAdminTS property when the system is a remote administration server running the Terminal Server role service.
ServicePackLevel	The version number of the operating system service pack.
ServicePackLevelMinor	The minor version number of the operating system service pack.
SharedWindows	Set when the system is operating as Shared Windows.
ShellAdvtSupport	Set if the shell supports feature advertising.
SystemLanguageID	Default language identifier for the system.
TerminalServer	Set when the system is a server running the Terminal Server role service.
TTCSupport	Indicates if the operating system supports using .ttc (true type font collections) files.
Version9X	Version number for the Windows operating system.
VersionDatabase	Numeric database version of the current installation.
VersionNT	Version number for the operating system.
VersionNT64	Version number for the operating system if the system is running on a 64-bit computer.
Windows build	Build number of the operating system.

Product Information Properties

The following list provides links to more information about product-specific properties specified in the Property Table.

Property Name	Brief Description
ARPHELPLINK	Internet address or URL for technical support.
ARPHELPTELEPHONE	Technical support phone numbers.
DiskPrompt	String displayed by a message box that prompts for a disk.
IsAdminPackage	Set to 1 (one) if the current installation is running from a package created through an administrative installation.
LeftUnit	Places units to the left of the number.
Manufacturer	Name of the application manufacturer. (Required)
MediaSourceDir	The installer sets this property to 1 (one) when the installation uses a media source, such as a CD-ROM.
MSIINSTANCEGUID	The presence of this property indicates that a product code changing transform is registered to the product.
MSINEWINSTANCE	This property indicates the installation of a new instance of a product with instance transforms.
ParentProductCode	The installer sets this property for installations that a Concurrent Installation action runs.
PIDTemplate	String used as a template for the PIDKEY property.
ProductCode	A unique identifier for a specific product release. (Required)
ProductName	Human readable name of an application. (Required)
ProductState	Set to the installed state of a product.
ProductVersion	String format of the product version as a numeric value. (Required)
UpgradeCode	A GUID that represents a related set of products.

Summary Information Update Properties

The following properties are only set by transforms in .msp files that are used to update the summary information stream of an administrative image.

Property	Description
PATCHNEWPACKAGECODE	The value of this property is written to the Revision Number Summary Property.
PATCHNEWSUMMARYCOMMENTS	The value of this property is written to the Comments Summary Property.
PATCHNEWSUMMARYSUBJECT	The value of this property is written to the Subject Summary Property.

System Folder Properties

The following list provides links to more information about system folders that the installer sets at setup.

Property	Description
AdminToolsFolder	The full path to the directory that contains administrative tools.
AppDataFolder	The full path to the Roaming folder for the current user.
CommonAppDataFolder	The full path to application data for all users.
CommonFiles64Folder	The full path to the predefined 64-bit Common Files folder.
CommonFilesFolder	The full path to the Common Files folder for the current user.
DesktopFolder	The full path to the Desktop folder.
FavoritesFolder	The full path to the Favorites folder for the current user.
FontsFolder	The full path to the Fonts folder.
LocalAppDataFolder	The full path to the folder that contains local (nonroaming) applications.
MyPicturesFolder	The full path to the Pictures folder.
NetHoodFolder	The full path to the NetHood folder.
PersonalFolder	The full path to the Documents folder for the current user.
PrintHoodFolder	The full path to the PrintHood folder.
ProgramFiles64Folder	The full path to the predefined 64-bit Program Files folder.
ProgramFilesFolder	The full path to the predefined 32-bit Program Files folder.
ProgramMenuFolder	The full path to the Program Menu folder.
RecentFolder	The full path to the Recent folder.
SendToFolder	The full path to the SendTo folder for the current user.
StartMenuFolder	The full path to the Start menu folder.
StartupFolder	The full path to the Startup folder.
System16Folder	The full path to folder for 16-bit system DLLs.
System64Folder	The full path to the predefined System64 folder.
SystemFolder	The full path to the System folder for the current user.
TempFolder	The full path to the Temp folder.
TemplateFolder	The full path to the Template folder for the current user.
WindowsFolder	The full path to the Windows folder.
WindowsVolume	The volume of the Windows folder.

User Information Properties

The following list provides links to more information about user-supplied information.