Setting

The <Setting/> element describes a setting that is migrated by this package.

Mapping

All strings are mapped from source to destination. If the Program Files directory changes between machines, the engine notices and corrects the paths that point to it. Similarly, if the user’s Documents folder moves, the paths are updated before being applied.

Registry Path Aliases

Many of the settings are stored in the registry and referenced by their registry path. The following aliases are recognized by the engine and make the settings package easier to read. All the examples use them.

Settings Within Settings

It can be useful to group settings together so that the settings package is easier to read:

        <Setting Name="Security">

            <Setting Name="EnablePGP">

                <Location Type="registry" SubType="value">

                    HCKU\Software\Crunch\EnablePGP

                </Location>

            </Setting>

            <Setting Name="RequirePassword">

                <Location Type="registry" SubType="value">

                    HCKU\Software\Crunch\PasswordRequired

                </Location>

            </Setting>

        </Setting>

Note that this is just a logical group within the settings package. It does not have to correspond to how those settings are stored. Any number of settings can be grouped at any depth.

The names of these settings are also slightly different. The nested settings have qualified names which are their parent’s qualified name, a forward slash, and then their own name. That would make these settings qualified names Security/EnablePGP and Security/RequirePassword.

Migrating a Key Tree with registry/subkey

Most of the time, you just want to move an entire registry key, all its values, all its subkeys, and all their values. You can do that with Type="registry" SubType="subkey".

        <Setting Name="CrunchSettings">

            <Location Type="registry" SubType="subkey">

                HKCU\Software\Crunch

            </Location>

        </Setting>

All strings are automatically mapped for you, and all data types are determined automatically. In certain cases, if the registry contains paths to files that you wish to migrate, those must be handled separately using filepath. Try the registry/subkey method first. Resort to other registry SubTypes only if needed.

Migrating a Registry Value with registry/value

A registry value can be migrated by giving its path:

        <Setting Name="ReticulateSplines">

            <Location Type="registry" SubType="value">

                HKCU\Software\Crunch\ReticulateSplines

            </Location>

        </Setting>

Migrating Whether Or Not A Registry Value Exists with registry/valueexistence

Sometimes an application doesn't store any information in a registry value, but checks for its existence. This can be migrated as follows:

        <Setting Name="IsRegistered">

            <Location Type="registry" SubType="valueexistence">

                HKCU\Software\Crunch\Registered

            </Location>

        </Setting>

Migrating a File with file

Migrating a file with a fixed position is simple:

        <Setting Name="DataFile">

            <Location Type="file" File="C:\Path\To\File.dat" />

        </Setting>

Whenever possible, use variables:

        <Setting Name="DataFile">

            <Location Type="file" File="%ProgramFiles%\Crunch\File.dat" />

        </Setting>

Migrating a File Whose Path Is In the Registry with filepath

When a setting is actually a path to a file, you often want to store not only the path, but the file as well. In this case, add a Type="filepath" attribute to the <Setting/>, and the engine will move the file for you. The registry value is mapped and migrated, and the file is migrated and applied into the appropriately-mapped location.

        <Setting Name="DataFile" Type="filepath">

            <Location Type="registry" SubType="value">

                HKCU\Software\Crunch\DataFilePath

            </Location>

        </Setting>