The overall concept of MSI is that there is a 1:1 mapping between
a component GUID (unique identifier) and an absolute path
(install location / key path). The full path, including file name if
any (a directory can be the key path for a component). See update below for a new Wix feature to deal auto-magically
with this.
Rob Mensching (WiX author):
- Windows Installer Component Rules 101
- Windows Installer Components Introduction
More on Component Rules:
- Organizing Applications into Components
- Best Practice for Creating Components.
I use some simple rules to deal with the overly complex and rather counterintuitive component rules (especially for developers as opposed to deployment specialists):
- Always use a separate component per file (even for non-binaries). This avoids all kinds of problems. There are a few exceptions:
- Multi-file .NET assemblies should all be in one component since they should always be installed / uninstalled as a single unit.
- A few other, general file types come in “matching pairs” – they belong together. Often these are content and index files. As an example consider Microsoft help files:
- .HLP and .CNT files belong together.
- .CHM and .CHI files belong together.
- There are likely several such file types that belong together and should hence be put in the same component so they install/uninstall together – I suspect certain certificate files to be candidates. It is hard to come up with a definite list. Simply ask yourself “do these files always belong together” – so they always show up in pairs whenever there is a new version? If yes, then install them via the same component. Set the versioned file, if any, as key file.
- I want to add driver files as an example of a bunch of files always belonging together:
SampleDriver.cat,SampleDriver.inf,SampleDriver.sys,SampleDriver.cer. They must all match as a “unit” for deployment.
- Remember that once you have allocated a GUID for a component, it’s set in stone for that component’s key path (absolute path). If you move the file to a new location or rename the file, give it a new component GUID (since the absolute path is different it’s effectively a new identity).
- In summary component GUIDs are tied to an absolute installation location, and not to a specific file. The GUID doesn’t follow the file around if it moves. The GUID reference counts an absolute location, not the file per se.
- Do not add or remove files from an existing component. All sorts of upgrade and patching problems result. This is why I like one file per component as a general rule.
- There is a lot more to component referencing, but I will leave it at that for an “overview”.
Some samples:
- You rename the file C:\Program Files\MyCompany\MyApp\MyFile.exe to C:\Program Files\MyCompany\MyApp\MyFile_NEW.exe. What does this mean for component creation? This is a new absolute installation path, so you generate a new GUID for the hosting component, OR you add a new component and delete the old one (which has the same effect).
- Your updated MSI delivers a new version of MyFile.exe. The location is the same as before, this means the component GUID should not change. It is the same file (identity), just in a different version.
UPDATE:
Auto Component-GUIDs: WIX now has a new
auto-generate component GUIDfeature thatcalculates a GUIDas long as the target path
stays the same. I have not tried this out to be honest, but many seem
to use it without problems, andRob Mensching (Wix author) states it is safe for normal use. As a concept I highly recommend this
since it features some auto-magic and shields you from some
complexity.Minimal WiX Markup: Also note that you can leave out a lot of source attributes from
your Wix xml file and rely on Wix defaults instead of hard
coding values.