registry
Supports patching/merging within, and explicit editing of, the Windows registry. Also supports patching, merging, and editing of Windows Registry Editor files (.reg), which are basically INI files with a custom header that use full registry key names for sections. Any attempt to access a Windows registry on a non-Windows system will lead to a runtime error, but this task can be used to modify Windows Registry Editor files on any platform.
The processing engine for the Windows registry and for Registry Editor files is an integrated version of the ini4j framework. The options for attributes and nested elements reflect the functionality of this framework. The <registry> configuration type can be used to patch or update a single registry key (and its subkeys), or to patch a fileset of Registry Editor files against a target directory containing Registry Editor files. Manual definition of key/value/data entries is supported by using the <entry> element.
Parameters
Attributes marked ini4j expose features of the underlying ini4j framework. See the ini4j documentation for fuller details. A single <registry> task can work with either directly in the Windows registry, or with Registry Editor files.
Registry Editor (.reg) files
Specify a <registry> task to work with .reg files (instead of directly in the registry) in exactly the same way as the <inifile> task. Note that you should still use the format for the <entry> element as documented below, but that <fileset> and <mapper> nested elements can be used as documented for INI files.
Windows registry
Use these parameters with the <registry> task in order to work directly with the Windows registry. Registry keys must be specified as a full, absolute path. Abbreviations like HKLM are not permitted.
| Attribute | Description | Required |
|---|---|---|
| fromkey | The source registry key containing the original configuration. | No. Patching destinations can also be updated by manual definition using nested |
| tokey | The registry key to patch to. | Yes. Cannot be used with fromfile/tofile/targetfile. |
| create | Allow destination registry keys to be created when they don't already exist. | No; defaults to true. |
| failonerror | If false, the listener will try to continue processing remaining actions even when errors in reading, processing, or writing files occur. Instead of immediately failing, a warning message is written to the log. Setting to true will ignore errors on non-Windows systems, but this is not recommended. Cross-platform installers should use an OS condition to completely skip execution of the task on non-Windows systems. | No; defaults to true. |
| condition | Specifies the name of an IzPack installer condition that must be fulfilled before the configuration is executed. | No. |
| keepOldKeys (ini4j) | Whether to generally preserve registry values with the same name (but not necessarily the same data) from the source key, if they can be found. Note that the IzPack Configuration Listener deals with a property key and its value, which in Windows registry terms translates to a registry 'value' and its 'data'. Windows registry values occur inside a registry key. Hence, fromkey is about Windows registry keys, but keepOldKeys is about Windows registry values.If keepOldKeys="true" and a registry value occurs in the source key and also in the destination key, the value in the destination key is unmodified, and the data is set according to keepOldValues. Otherwise, if the value found in the source key is not found in the destination key, the old value/data pair is merged to the destination key. Manual <entry> definitions will override the original of a preserved registry key value. | No; defaults to true. |
| keepOldValues (ini4j) | Whether to preserve the value data of values that appear inside both the source key and the destination key. Note that the IzPack Configuration Listener deals with a property key and its value, which in Windows registry terms translates to a registry 'value' and its 'data'. Windows registry values occur inside a registry key. Hence, keepOldValues is about Windows registry value data. Set false to overwrite the data of source values by default with the destination ones, regardless whether they were already set in the source key. Data from a value in the source key can only be preserved, if the same value exists in the equivalent destination key. Manual <entry> definitions will override the data of a destination value even when keepOldValues is true. | No; defaults to true. |
| resolveExpressions (ini4j) | Whether ini4j expressions should be resolved when a registry key is being patched. This is not the same as substituting IzPack variables, but resolves references to subkeys and value in the same registry key. See [ini4j] - Expression handling. | No; defaults to false. |
Nested Elements
entry
The nested <entry> is used to override the definition of a certain registry value against the default behavior defined with action-global attributes or their ini4j defaults. An entry can even be used without the fromkey attribute to add values to, or modify existing values, in the destination registry key. Further, a new registry key, with values and subkeys, can be defined entirely using <entry> elements where tokey did not previously exist.
The <entry> element can be used when directly modifying the Windows registry, or when patching or modifying a single Registry Editor (.reg) file.
| Attribute | Description | Required |
|---|---|---|
| key | The registry subkey to modify or create. Interpreted relative to the registry key defined by tokey in the enclosing <registry> task. | No. If omitted, this <entry> will apply to the key defined in tokey. |
| value | The registry value to set. | Yes, unless operation is "keep" or "remove" (these operations may be applied to a whole subkey). |
| data | The new data to apply to the specified registry value. | Yes, if Defaults to |
| default | A fallback value to set the registry value data to if no other definition can be found, i.e. if parameter data is not specified, or if the value is not already defined in the registry key. | Yes, if Where no previous value is defined, defaults to |
| dataType | Instructs that value data be treated as a certain data type during processing. Support currently exists for treating value data as a date or an integer, instead of as a plain string. Can be used with the pattern parameter to define string parsing and output formatting, and/or with the operation parameter to perform basic calculations. | No; defaults to "string". Can also be set to "int" or "date". |
| operation | Overrides global patching behavior for specific entries, or allows basic calculations for numeric data types (i.e. Values can be removed from the registry key by specifying Specifying | No; defaults to "=". Valid values for all data types are "=" (set), "+" (increment/append), "remove", "keep". For numeric data types, the value "-" (decrement) is also valid. |
| unit | Defines the date component to modify when dataType="date" and operation is "+" or "-". | No; defaults to |
| pattern | For numeric data types, a string formatting pattern can be specified using conventional Java formatting placeholders. This defines both the input parsing and output formatting pattern for this entry. See javadoc for DecimalFormat (applies to int) and SimpleDateFormat (applies to date). | No. The default pattern for |
fileset
Can be used when patching multiple Registry Editor files. See the inifile documentation for usage.
mapper
Can be used when patching multiple Registry Editor files. See the inifile documentation for usage.
Examples
Merge the values from an existing registry key into a new registry key. Copy all values and data from the original key. Explicitly delete the subkey legacyOps (with all its values) from the new key. Execute the task only if the IzPack condition isUpgrade is fulfilled. Note the use of IzPack variable APP_VER and user-defined variable oldAppVer.
Create a new uninstall key in the registry, or update the values in an existing uninstall key.
Labels