What is the wix 'KeyPath' attribute?

131
votes

What is the Wix 'KeyPath' attribute? In particular, how does it apply to the following:

<Component Id="ProgramMenuDir" Guid="*">
  <RemoveFolder Id="ProgramMenuDir" On="uninstall" />
  <RegistryValue Root="HKCU" Key="Software\CompName\AppName" 
                 Type="string" Value="" KeyPath="yes" />
</Component>
1
installationwixwindows-installer
OMG the Wix documentation is utterly useless. The wix doc says, for the KeyPath attribute, that if you set it to "Yes" then the file is treated as the key path for the component. Soooo helpful!! – Cheeso
@RobMensching - appreciate your spirit and willingness to contribute to the community. Telling me how to NOT complain is not as good as telling me (and others) how TO complain. If I knew the place to raise a bug, 2 years ago, I'd have done it. Also, as you can see by the upvotes, apparently other people feel similarly. Maybe it's time for this kind of message: "Help improve WiX! Please raise appropriate bugs by clicking HERE". – Cheeso
Will do, @Cheeso! Please file bugs here: wixtoolset.org/bugs – Rob Mensching
@Cheeso The key concept to understand is that a WiX Setup project builds a Windows Installer package. The WiX docs don't (and mostly shouldn't) duplicate the Windows Installer docs. Though you can often use a WiX construct without understanding the Windows Installer tables it supports, if there is any question, you should check the docs on MSDN. For components, start here. – Tom Blodget
@TomBlodget: I'd argue WiX SHOULD duplicate Windows Installer docs. For most users, the WiX/Windows Installer split merely causes confusion, and the more that can be hidden to the end user the easier the overall tool is to use. – Scott Stafford

1 Answers

130
votes

As explained by Rob Mensching:

The KeyPath for a Component is a single resource that the Windows Installer uses to determine if a Component "exists" on a machine.

This means that when Windows Installer decides whether to install your component, it will first look whether the keypath resource is already present. If it is, none of the resources in the component are installed.

The presence of the keypath resource also determines whether a component has been damaged or has gone missing when you "repair" an MSI.

When the keypath resource is a versioned file, Windows Installer will consider it to exist only if it finds a file with an equal or higher version.

In your specific example, you have a component which removes a folder on uninstallation. This component will only be installed if the given registry key does not yet exists. Adding a registry key to use as the key path is a common trick when you need a keypath for a component that installs resources that cannot be used as a keypath themselves, like a shortcut.