What is the WiX 'KeyPath' attribute?

Question

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>

Kettering

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!! – Farrah

@Farrah we (volunteers on the WiX toolset) appreciate bugs and recommended text to help us improve the documentation. Complaining in a comment on a question on StackOverflow isn't likely to be noticed. Although I did happen to find you this time. :) – Ulcerous

@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". – Farrah

Will do, @Cheeso! Please file bugs here: wixtoolset.org/bugs – Ulcerous

@Farrah 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. – Biweekly

A good tutorial for WIX is found here: wix.tramontana.co.hu/tutorial – Hep

@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. – Coopersmith

@Scott Stafford Plus, many users (like me) only use WiX for specific tasks and do not want to drown in Windows Installer too much, especially after they tasted some of its quirks. – Extramarital

@Brain2000 I know, right? You'd think after 10 years someone (anyone!) would take the information here and dig into the doc a little bit to contribute whatever words are missing. I mean the doc makes sense to me (but I wrote the compiler). I tend to spend my time on things that are much more challenging for new devs to contribute to, like implementing features and fixing bugs deep in the compiler, linker, or binder. – Ulcerous

Answer 1

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.

Sphenoid

So then what is the point in explicitly giving the only file in a component a keypath="no" attribute? – Artair

@Adkins: that would supress the default behavior of wix to take that file as the keypath. As a result, no keypath is written to the installer database for that component. During installation, windows installer will then use the destination folder of the component as the keypath. Another way to get this behavior is to set "keypath=yes" on the component element itself. In any case, it doesn't seem like a good idea to me. – Sphenoid