May 29, 2012

Installable Items - Registry keys and values

1 comment
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 can we 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's
attribute
Description
Name Value Name
+ 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's
attribute
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>
       <RemoveRegistryValues />
     </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">
         <RegistryValue>123</RegistryValue>
         <RegistryValue>456</RegistryValue>
         <RegistryValue>789</RegistryValue>
       </Registry>
     </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>

1 comment :