MSI Factory

Windows Installer installs and removes everything in pieces referred to as components. Each component is always installed or removed as a single unit.

All of the resources that are installed by your setup must be organized into components, from files and registry keys to shortcuts and custom actions.

MSI Factory automatically organizes these resources for you, placing each of them into their own unique component. However, if you wish to combine resources into a single component, you may do so using the Component Manager. (For example, it is a good idea to put any registry action that points to a file in the same component as the file. This ensures that the registry entry will only be created if the file it refers to was installed.)

A component can contain a single file, or a group of related files, registry keys, shortcuts, custom actions, COM objects, etc.

Although components can contain multiple items, it is very important that their contents are all related, and that they are all intended to be installed, uninstalled, or repaired together as a single "item."

When a component contains files, they must all be installed to the same destination folder. Only one destination per component is allowed.

Components are reference counted on the target system. This means that Windows Installer keeps track of each component as it is installed and uninstalled, adding or subtracting from a number which it stores in the Registry for each component. This reference counting is done based on the component's identifying GUID, which must be unique for each component.

Windows Installer uses this reference count to determine whether a component is already installed, and whether it is safe to uninstall the component when an application that uses it is uninstalled.

Note: It is important that component GUIDs remain stable between product versions. In order to avoid having to edit all the GUIDs in your project, you should always work with the same MSI Factory project when building setups that upgrade a previous version. Note also that MSI Factory automatically generates a unique component GUID for every file that is added. Once you remove a file (or action) from your project, if you add it back to the project again, you will need to edit its component properties if you want its component GUID to remain the same. You should always check that your component GUIDs are correct before distributing a setup that upgrades a previous version.

There are many rules for defining components. These rules are very important and must be followed to ensure proper functioning setups. It is highly recommended that you read all of the articles linked in the More Information section below, including Organizing Applications into Components, Defining Installer Components, and What happens if the component rules are broken?

Some additional guidelines for defining components:

- Components must be unique across applications, products, product versions, and companies.

- Once a component is defined, all future versions of that component -- which means any component that has the same GUID -- must be 100% compatible with all earlier versions, across applications, products, product versions, and companies.

- If you need to distribute a new component that is not compatible with all previous versions, you must create a new component for that version.

- Don't mix per-user and per-machine items in a single component.

- Ensure that only one .exe (or .dll, .ocx, .chm, .hlp) exists in each component.

- Use merge modules whenever possible for any resources that are shared across applications. Never put someone else's resources in one of your components.

- Ensure that components are unique -- for example don't have a .dll that exists in more than one component.

- If you must include the same resource in two components, give it a unique name or destination folder in each component.

- You cannot add a file to a component once it has been distributed. To avoid complications, add any new files in separate components.

- Do not assign the same key path file in multiple components.

- Although grouping several files into a single component can improve installation performance, in order to avoid complicated long-term component and key path conflicts it is recommended that you keep files in separate components as much as possible.

More Information

MSDN Online: Windows Installer Components

MSDN Online: Organizing Applications into Components

MSDN Online: Defining Installer Components

MSDN Online: What happens if the component rules are broken?

MSDN Online: Changing the Component Code

MSDN Blogs: Windows Installer Components Introduction

MSDN Blogs: Component Rules 101

WiX Help File: Component Element

Learn More: Indigo Rose Software - MSI Factory - Buy Now - Contact Us