From MSI to WiX, Part 14 - Installable Items - Registry keys and values

Article
04/02/2008

The main page for the series is here.

Introduction

Today's topic is how to create registry keys and values.

MSI story

Information about registry keys and/or values to be installed is authored in the Registry table. This table is processed by WriteRegistryValues and RemoveRegistryValues standard actions which must be scheduled in the Execute sequence tables.

To remove registry keys and/or values during install users must use RemoveRegistry table. This table is processed by RemoveRegistryValues standard action which must be scheduled in the Execute sequence tables.

Here is the list of columns of the Registry table:

Column name	Description
Registry	Primary key of the record.
Root	The predefined root key for the registry value: default (-1) - Depends on the type of installation: HKCU - for per-user installation. HKLM - for per-machine installation. msidbRegistryRootClassesRoot (0) - HKCR msidbRegistryRootCurrentUser (1) - HKCU msidbRegistryRootLocalMachine (2) - HKLM msidbRegistryRootUsers (3) - HKU
Key	The localizable key for the registry value.
Name	Localizable registry value name. Use Null value to write to the default registry key.
Value	Localized registry value. This field is formatted field.
Component_	External key into the Component table.

To remove registry key on install we need to add record to the RemoveRegistry table:

Column name	Description
RemoveRegistry	Primary key of the record.
Root	The predefined root key for the registry value: default (-1) - Depends on the type of installation: HKCU - for per-user installation. HKLM - for per-machine installation. msidbRegistryRootClassesRoot (0) - HKCR msidbRegistryRootCurrentUser (1) - HKCU msidbRegistryRootLocalMachine (2) - HKLM msidbRegistryRootUsers (3) - HKU
Key	The localizable key for the registry value.
Name	The localizable registry value name. If registry key is to be deleted, this column must contain minus sign (-).
Component_	External key into the Component table.

What we can do with the registry

These are the options we have when we install/delete registry key or value:

For registry keys:
- Create the key on install.
- Delete the key on uninstall.
- Create the key on install and delete it on uninstall.
- Delete the key on install.
For registry values:
- Create a binary (REG_BINARY) value.
- Create an integer (REG_DWORD) value.
- Create a string (REG_SZ) value.
- Create an expandable string (REG_EXPAND_SZ) value.
- Create a Null terminated list of strings (REG_MULTI_SZ) value:
  - New string can override existing string.
  - New string can be appended to existing string.
  - New string can be prepended to existing string.

In MSI, prefixes to the Name column and prefixes and suffixes to the Value column are used to indicate the action to be performed. In Wix, elements <Registry> and <RegistryValue> are used for that purpose.

How it translates to WiX?

To create/delete registry keys:

Registry table		RemoveRegistry table	Registry element'sattribute	Description
Name	Value	Name	Registry element'sattribute	Description
+	Null		Action="createKey"	On install, the key will be created if it is absent.
-	Null		Action="removeKeyOnUninstall"	On uninstall, the key will be deleted, including all its values and subkeys.
*	Null		Action="createKeyAndRemoveKeyOnUninstall"	The key will be created on install and deleted on uninstall.
		-	Action="removeKeyOnInstall"	On install, the key will be deleted if present.

Prefixes and suffixes of the value in the Value column of the Registry table determine type of data stored in the registry:

Value column	Registry element'sattribute	Description
#x	Type="binary"	Hexadecimal value stored as binary data (REG_BINARY).
#%	Type="expandable"	Expandable string (REG_EXPAND_SZ).
#	Type="integer"	Integer value (REG_DWORD).
Contains [~] anywhere	Type="multiString"	List of strings (REG_MULTI_SZ).
Starts with two or more # or does not contain [~]	Type="string"	String (REG_SZ).

Examples

Create a registry key on install and remove it on uninstall:

<Registry Id="TestKey"

Root="HKLM"

Key="SOFTWARE\ACME Corp"

Action="createKeyAndRemoveKeyOnUninstall" />

Remove a registry key on install:

<Registry Id="TestKey"

Root="HKLM"

Key="SOFTWARE\ACME Corp"

Action="removeKeyOnInstall" />

If you only remove registry key and do not create new ones, make sure you schedule RemoveRegistryValues standard action in the Execute sequence table. For example:

</InstallExecuteSequence>

Create a registry key with default value:

<Registry Id="TestKey"

Root="HKLM"

Key="SOFTWARE\ACME Corp"

Action="createKeyAndRemoveKeyOnUninstall">

<Registry Id="DefaultValue"

Action="write"

Type="integer"

Value="123" />

</Registry>

Create a registry key with the string value:

<Registry Id="TestKey"

Root="HKLM"

Key="SOFTWARE\ACME Corp"

Action="createKeyAndRemoveKeyOnUninstall">

<Registry Id="TestValue"

Name="TestValue"

Action="write"

Value="123"

Type="string" />

</Registry>

On install, remove existing value of the registry key:

<Registry Id="TestKey"

Root="HKLM"

Key="SOFTWARE\ACME Corp"

Action="createKey">

<Registry Id="TestValue"

Name="TestValue"

Action="remove" />

</Registry>

Create a multi-string value:

<Registry Id="TestKey"

Root="HKLM"

Key="SOFTWARE\ACME Corp"

Action="createKeyAndRemoveKeyOnUninstall">

<Registry Id="TestValue"

Name="TestValue"

Type="multiString"

Action="append">

</Registry>

Create a key with sub-key:

<Registry Id="TestKey"

Root="HKLM"

Key="SOFTWARE\ACME Corp"

Action="createKeyAndRemoveKeyOnUninstall">

<Registry Id="SubKey"

Key="SubKey"

Action="createKeyAndRemoveKeyOnUninstall" />

</Registry>

From MSI to WiX, Part 14 - Installable Items - Registry keys and values

Additional resources