--- title: XML Elements Library description: Learn about the XML elements and helper functions that can be employed to author migration .xml files to use with User State Migration Tool (USMT). ms.reviewer: kevinmi,warrenw manager: aaroncz ms.author: frankroj ms.service: windows-client author: frankroj ms.date: 01/09/2024 ms.topic: conceptual ms.subservice: itpro-deploy appliesto: - ✅ Windows 11 - ✅ Windows 10 --- # XML elements library This article describes the XML elements and helper functions that can be employed to author migration **.xml** files to use with User State Migration Tool (USMT). This article assumes a basic knowledge of XML. In addition to XML elements and helper functions, this article: - Describes how to specify encoded locations and locations patterns. - Functions that are for internal USMT use only. - The version tags that can be used with helper functions. ## Elements and helper functions The following table describes the XML elements and helper functions can be used with USMT. | Elements A-K | Elements L-Z | Helper functions | |-----|----|-----| | [\](#addobjects)
[\](#attributes)
[\](#bytes)
[\](#commandline)
[\](#component)
[\](#condition)
[\](#conditions)
[\](#content)
[\](#contentmodify)
[\](#description)
[\](#destinationcleanup)
[\](#detect)
[\](#detects)
[\](#detection)
[\](#displayname)
[\](#environment)
[\](#exclude)
[\](#excludeattributes)
[\](#extensions)
[\](#extension)
[\](#externalprocess)
[\](#icon)
[\](#include)
[\](#includeattributes) | [\](#library)
[\](#location)
[\](#locationmodify)
[\<_locDefinition\>](#_locdefinition)
[\](#manufacturer)
[\](#merge)
[\](#migration)
[\](#namedelements)
[\](#object)
[\](#objectset)
[\](#path)
[\](#paths)
[\](#pattern)
[\](#processing)
[\](#plugin)
[\](#role)
[\](#rules)
[\](#script)
[\](#text)
[\](#unconditionalexclude)
[\](#variable)
[\](#version)
[\](#windowsobjects) | [\ functions](#condition-functions)
[\ functions](#content-functions)
[\ functions](#contentmodify-functions)
[\ and \ filter functions](#include-and-exclude-filter-functions)
[\ functions](#locationmodify-functions)
[\ functions](#merge-functions)
[\ functions](#script-functions)
[Internal USMT functions](#internal-usmt-functions) | ## \ The **\** element emulates the existence of one or more objects on the source computer. The child **\** elements provide the details of the emulated objects. If the content is a **\** element, the result of the invocation is an array of objects. - **Number of occurrences:** unlimited - **Parent elements:** [\](#rules) - **Required child elements:** [\](#object) In addition, [\](#location) and [\](#attributes) must be specified as child elements of this **\** element. - **Optional child elements:** [\](#conditions), [\](#condition), [\](#script) Syntax: ```xml ``` The following example is from the `MigApp.xml` file: ```xml %HklmWowSoftware%\Microsoft\Office\16.0\Common\Migration\Office [UpgradeVersion] DWORD 0B000000 %HklmWowSoftware%\Microsoft\Office\16.0\Common\Migration\Office [Lang] DWORD 00000000 ``` ## \ The **\** element defines the attributes for a registry key or file. - **Number of occurrences:** once for each [\](#object) - **Parent elements:** [\](#object) - **Child elements:** none Syntax: ```xml Content ``` | Setting | Required? | Value | |------|-----|----| | *Content* | Yes | The content depends on the type of object specified.
  • For files, the content can be a string containing any of the following attributes separated by commas:
    • Archive
    • Read-only
    • System
    • Hidden
  • For registry keys, the content can be one of the following types:
    • None
    • String
    • ExpandString
    • Binary
    • Dword
    • REG_SZ
| The following example is from the `MigApp.xml` file: ```xml %HklmWowSoftware%\Microsoft\Office\16.0\Common\Migration\Office [Lang] DWORD 00000000 ``` ## \ The **\** element can only be specified for files because, if **\** corresponds to a registry key or a directory, then **\** is ignored. - **Number of occurrences:** zero or one - **Parent elements:** [\](#object) - **Child elements:** none Syntax: ```xml Content ``` |Setting|Required?|Value| |--- |--- |--- | |string|No, default is No|Determines whether *Content* should be interpreted as a string or as bytes.| |expand|No (default = Yes|When the expand parameter is **Yes**, the content of the **\** element is first expanded in the context of the source computer and then interpreted.| |*Content*|Yes|Depends on the value of the string.
  • When the string is **Yes**: the content of the **\** element is interpreted as a string.
  • When the string is **No**: the content of the **\** element is interpreted as bytes. Every two characters represent the hexadecimal value of a byte. For example, `616263` is the representation for the `abc` ANSI string. A complete representation of the UNICODE string `abc` including the string terminator would be: `6100620063000000`.
| The following example is from the `MigApp.xml` file: ```xml %HklmWowSoftware%\Microsoft\Office\16.0\Common\Migration\Office [Lang] DWORD 00000000 ``` ## \ The **\** element might be used to start or stop a service or application before or after running the **ScanState** and **LoadState** tools. - **Number of occurrences:** unlimited - **Parent elements:** [\](#externalprocess) - **Child elements:** none Syntax: ```xml CommandLineString ``` |Setting|Required?|Value| |--- |--- |--- | |*CommandLineString*|Yes|A valid command line.| ## \ The **\** element is required in a custom **.xml** file. This element defines the most basic construct of a migration **.xml** file. For example, in the `MigApp.xml` file, **Microsoft Office 2016** is a component that contains another component, **Microsoft Office Access 2016**. The child elements can be used to define the component. A component can be nested inside another component; that is, the **\** element can be a child of the **\** element within the **\** element in two cases: 1. When the parent **\** element is a container 1. If the child **\** element has the same role as the parent **\** element. - **Number of occurrences:** Unlimited - **Parent elements:** [\](#migration), [\](#role) - **Required child elements:** [\](#role), [\](#displayname) - **Optional child elements:** [\](#manufacturer), [\](#version), [\](#description), [\](#paths), [\](#icon), [\](#environment), [\](#extensions) Syntax: ```xml ``` |Setting|Required?|Value| |--- |--- |--- | | type | Yes | The following items can be used to group settings, and define the type of the component.
  • **System:** Operating system settings. All Windows components are defined by this type.
    When **type="System"** and **defaultSupported="FALSE"**, the settings don't migrate unless there's an equivalent component in the **.xml** files that is specified on the `LoadState.exe` command line. For example, the default `MigSys.xml` file contains components with **type="System"** and **defaultSupported="FALSE"**. If this file is specified on the `ScanState.exe` command line, the file must also be specified on the `LoadState.exe` command line for the settings to migrate. The file must be specified because the `LoadState.exe` tool must detect an equivalent component. That is, the component must have the same migration urlid of the **.xml** file and an identical display name. Otherwise, the **LoadState** tool doesn't migrate those settings from the store. This setting is helpful because a store can be used for destination computers that are the same or different version of Windows as the source computer.
  • **Application:** Settings for an application.
  • **Device:** Settings for a device.
  • **Documents:** Specifies files.
| | context | No
Default = UserAndSystem | Defines the scope of this parameter; that is, whether to process this component in the context of the specific user, across the entire operating system, or both.
The largest possible scope is set by the **\** element. For example, if a **\** element has a context of **User** and a **\** element had a context of **UserAndSystem**, then the **\** element would act as though it has a context of **User**. If a **\** element has a context of **System**, it would act as though the **\** element isn't there.
  • **User**: Evaluates the component for each user.
  • **System**: Evaluates the component only once for the system.
  • **UserAndSystem**: Evaluates the component for the entire operating system and each user.
| | defaultSupported | No
(default = TRUE) | Can be any of **TRUE**, **FALSE**, **YES**, or **NO**. If this parameter is **FALSE** (or **NO**), the component isn't migrated unless there's an equivalent component on the destination computer.
When **type="System"** and **defaultSupported="FALSE"**, the settings aren't migrated unless there's an equivalent component in the **.xml** files that are specified on the `LoadState.exe` command line. For example, the default `MigSys.xml` file contains components with **type="System"** and **defaultSupported="FALSE"**. If this file is specified on the `ScanState.exe` command line, the file must also be specified on the `LoadState.exe` command line for the settings to migrate. The file has to be specified in both command lines because the **LoadState** tool must detect an equivalent component. That is, the component must have the same migration urlid of the **.xml** file and an identical display name or the **LoadState** tool doesn't migrate those settings from the store. This setting is helpful because a store can be used for destination computers that are the same or different version of Windows as the source computer. | | hidden | | This parameter is for internal USMT use only. | For an example, see any of the default migration **.xml** files. ## \ Although the **\** element under the **\**, **\**, and **\** elements is still supported, Microsoft recommends to no longer use the **\** element because it might be deprecated in future versions of USMT. If the **\** element is deprecated, it would require a rewrite of any scripts that use the **\** element. Instead, if a condition needs to be used within the **\** and **\** elements, Microsoft recommends using the more powerful **[\](#conditions)** element. The **\** element allows for formulation of complex Boolean statements. The **\** element has a Boolean result. This element can be used to specify the conditions in which the parent element is evaluated. If any of the present conditions return **FALSE**, the parent element isn't be evaluated. - **Number of occurrences:** unlimited. - **Parent elements:** [\](#conditions), [\](#detect), [\](#objectset), [\](#addobjects) - **Child elements:** none - **Helper functions:** The following [\ functions](#condition-functions) can be used with this element: `DoesOSMatch`, `IsNative64Bit()`, `IsOSLaterThan`, `IsOSEarlierThan`, `DoesObjectExist`, `DoesFileVersionMatch`, `IsFileVersionAbove`, `IsFileVersionBelow`, `IsSystemContext`, `DoesStringContentEqual`, `DoesStringContentContain`, `IsSameObject`, `IsSameContent`, and `IsSameStringContent`. Syntax: ```xml ScriptName ``` |Setting|Required?|Value| |--- |--- |--- | |negation|No
Default = No|**"Yes"** reverses the True/False value of the condition.| |*ScriptName*|Yes|A script that is defined within this migration section.| For example, in the following code sample, the **\** elements, **A** and **B**, are joined together by the **AND** operator because they are in separate **\** sections: ```xml A B ``` However, in the following code sample, the **\** elements, **A** and **B**, are joined together by the **OR** operator because they are in the same **\** section. ```xml A B ``` ### \ functions The **\** functions return a Boolean value. These elements can be used in **\** conditions. - [Operating system version functions](#operating-system-version-functions) - [Object content functions](#object-content-functions) ### Operating system version functions - **DoesOSMatch** All matches are case insensitive. Syntax: `DoesOSMatch("OSType","OSVersion")` |Setting|Required?|Value| |--- |--- |--- | |*OSType*|Yes|The only valid value for this setting is **NT**. However, this setting must be set for the **\** functions to work correctly.| |*OSVersion*|Yes|The major version, minor version, build number and corrected service diskette version separated by periods. For example, `5.0.2600.Service Pack 1`. Partial specification of the version can also be specified with a pattern such as `5.0.*`.| For example: ```xml MigXmlHelper.DoesOSMatch("NT","\*") ``` - **IsNative64Bit** The **IsNative64Bit** function returns **TRUE** if the migration process is running as a native 64-bit process; that is, a process running on a 64-bit system without Windows on Windows (WOW). Otherwise, it returns **FALSE**. - **IsOSLaterThan** All comparisons are case insensitive. Syntax: `IsOSLaterThan("OSType","OSVersion")` |Setting|Required?|Value| |--- |--- |--- | |*OSType*|Yes|Can be **9x** or **NT**. If *OSType* doesn't match the type of the current operating system, then it returns **FALSE**. For example, if the current operating system is Windows NT-based and *OSType* is **"9x"**, the result is **FALSE**.| |*OSVersion*|Yes|The major version, minor version, build number, and corrected service diskette version separated by periods. For example, `5.0.2600.Service Pack 1`. Partial specification of the version can also be specified but no pattern is allowed such as `5.0`.

The **IsOSLaterThan** function returns **TRUE** if the current operating system is later than or equal to *OSVersion*.| For example: ```xml MigXmlHelper.IsOSLaterThan("NT","6.0") ``` - **IsOSEarlierThan** All comparisons are case insensitive. Syntax: `IsOSEarlierThan("OSType","OSVersion")` |Setting|Required?|Value| |--- |--- |--- | |*OSType*|Yes|Can be **9x** or **NT**. If *OSType* doesn't match the type of the current operating system, then it returns **FALSE**. For example, if the current operating system is Windows NT-based and *OSType* is **"9x"** the result is **FALSE**.| |*OSVersion*|Yes|The major version, minor version, build number, and corrected service diskette version separated by periods. For example, `5.0.2600.Service Pack 1`. Partial specification of the version can also be specified but no pattern is allowed such as `5.0`.

The **IsOSEarlierThan** function returns **TRUE** if the current operating system is earlier than *OSVersion*.| ### Object content functions - **DoesObjectExist** The DoesObjectExist function returns **TRUE** if any object exists that matches the location pattern. Otherwise, it returns **FALSE**. The location pattern is expanded before attempting the enumeration. Syntax: `DoesObjectExist("ObjectType","EncodedLocationPattern")` |Setting|Required?|Value| |--- |--- |--- | |*ObjectType*|Yes|Defines the object type. Can be File or Registry.| |*EncodedLocationPattern*|Yes|The **[location pattern](#specifying-locations)**. Environment variables are allowed.| For an example of this element, see the `MigApp.xml` file. - **DoesFileVersionMatch** The pattern check is case insensitive. Syntax: `DoesFileVersionMatch("EncodedFileLocation","VersionTag","VersionValue")` |Setting|Required?|Value| |--- |--- |--- | |*EncodedFileLocation*|Yes|The **[location pattern](#specifying-locations)** for the file that is checked. Environment variables are allowed.| |*VersionTag*|Yes|The **[version tag](#valid-version-tags)** value that is checked.| |*VersionValue*|Yes|A string pattern. For example, "Microsoft*".| For example: ```xml MigXmlHelper.DoesFileVersionMatch("%MSNMessengerInstPath%\\msnmsgr.exe","ProductVersion","6.\*") MigXmlHelper.DoesFileVersionMatch("%MSNMessengerInstPath%\\msnmsgr.exe","ProductVersion","7.\*") ``` - **IsFileVersionAbove** The **IsFileVersionAbove** function returns **TRUE** if the version of the file is higher than *VersionValue*. Syntax: `IsFileVersionAbove("EncodedFileLocation","VersionTag","VersionValue")` |Setting|Required?|Value| |--- |--- |--- | |*EncodedFileLocation*|Yes|The **[location pattern](#specifying-locations)** for the file that is checked. Environment variables are allowed.| |*VersionTag*|Yes|The **[version tag](#valid-version-tags)** value that is checked.| |*VersionValue*|Yes|The value to compare to. A pattern can't be specified.| - **IsFileVersionBelow** Syntax: `IsFileVersionBelow("EncodedFileLocation","VersionTag","VersionValue")` |Setting|Required?|Value| |--- |--- |--- | |*EncodedFileLocation*|Yes|The **[location pattern](#specifying-locations)** for the file that is checked. Environment variables are allowed.| |*VersionTag*|Yes|The **[version tag](#valid-version-tags)** value that is checked.| |*VersionValue*|Yes|The value to compare to. A pattern can't be specified.| - **IsSystemContext** The **IsSystemContext** function returns **TRUE** if the current context is **"System"**. Otherwise, it returns **FALSE**. Syntax: `IsSystemContext()` - **DoesStringContentEqual** The **DoesStringContentEqual** function returns **TRUE** if the string representation of the given object is identical to `StringContent`. Syntax: `DoesStringContentEqual("ObjectType","EncodedLocation","StringContent")` |Setting|Required?|Value| |--- |--- |--- | |*ObjectType*|Yes|Defines the type of object. Can be File or Registry.| |*EncodedLocationPattern*|Yes|The **[encoded location](#specifying-locations)** for the object that is examined. Environment variables can be specified.| |StringContent|Yes|The string that is checked against.| For example: ```xml MigXmlHelper.DoesStringContentEqual("File","%USERNAME%","") ``` - **DoesStringContentContain** The **DoesStringContentContain** function returns **TRUE** if there is at least one occurrence of *StrToFind* in the string representation of the object. Syntax: `DoesStringContentContain("ObjectType","EncodedLocation","StrToFind")` |Setting|Required?|Value| |--- |--- |--- | |*ObjectType*|Yes|Defines the type of object. Can be File or Registry.| |*EncodedLocationPattern*|Yes|The **[encoded location](#specifying-locations)** for the object that is examined. Environment variables can be specified.| |*StrToFind*|Yes|A string that is searched inside the content of the given object.| - **IsSameObject** The **IsSameObject** function returns **TRUE** if the given encoded locations resolve to the same physical object. Otherwise, it returns **FALSE**. Syntax: `IsSameObject("ObjectType","EncodedLocation1","EncodedLocation2")` |Setting|Required?|Value| |--- |--- |--- | |*ObjectType*|Yes|Defines the type of object. Can be File or Registry.| |*EncodedLocation1*|Yes|The **[encoded location](#specifying-locations)** for the first object. Environment variables can be specified.| |*EncodedLocation2*|Yes|The **[encoded location](#specifying-locations)** for the second object. Environment variables can be specified.| For example: ```xml MigXmlHelper.IsSameObject("File","%CSIDL_FAVORITES%","%CSIDL_COMMON_FAVORITES%") %CSIDL_FAVORITES%\* [*] ``` - **IsSameContent** The **IsSameContent** function returns **TRUE** if the given objects have the same content. Otherwise, it returns **FALSE**. The content is compared byte by byte. Syntax: `IsSameContent("ObjectType1","EncodedLocation1","ObjectType2","EncodedLocation2")` |Setting|Required?|Value| |--- |--- |--- | |*ObjectType1*|Yes|Defines the type of the first object. Can be File or Registry.| |*EncodedLocation1*|Yes|The **[encoded location](#specifying-locations)** for the first object. Environment variables can be specified.| |*ObjectType2*|Yes|Defines the type of the second object. Can be File or Registry.| |*EncodedLocation2*|Yes|The **[encoded location](#specifying-locations)** for the second object. Environment variables can be specified.| - **IsSameStringContent** The **IsSameStringContent** function returns **TRUE** if the given objects have the same content. Otherwise, it returns **FALSE**. The content is interpreted as a string. Syntax: `IsSameStringContent("ObjectType1","EncodedLocation1","ObjectType2","EncodedLocation2")` |Setting|Required?|Value| |--- |--- |--- | |*ObjectType1*|Yes|Defines the type of the first object. Can be File or Registry.| |*EncodedLocation1*|Yes|The **[encoded location](#specifying-locations)** for the first object. Environment variables can be specified.| |*ObjectType2*|Yes|Defines the type of the second object. Can be File or Registry.| |*EncodedLocation2*|Yes|The **[encoded location](#specifying-locations)** for the second object. Environment variables can be specified.| ## \ The **\** element returns a Boolean result that is used to specify the conditions in which the parent element is evaluated. USMT evaluates the child elements, and then joins their results using the operators **AND** or **OR** according to the operation parameter. - **Number of occurrences:** Unlimited inside another **\** element. Limited to one occurrence in [\](#detection), [\](#rules), [\](#addobjects), and [\](#objectset) - **Parent elements:** [\](#conditions), [\](#detection), [\](#environment), [\](#rules), [\](#addobjects), and [\](#objectset) - **Child elements:** [\](#conditions), [\](#condition) Syntax: ```xml ``` |Setting|Required?|Value| |--- |--- |--- | |operation|No, default = AND|Defines the Boolean operation that is performed on the results that are obtained from the child elements.| The following example is from the `MigApp.xml` file: ```xml MigXmlHelper.IsNative64Bit() HKLM\Software ``` ## \ The **\** element can be used to specify a list of object patterns to obtain an object set from the source computer. Each **\** within a **\** element is evaluated. For each resulting object pattern list, the objects that match it are enumerated and their content is filtered by the filter parameter. The resulting string array is the output for the **\** element. The filter script returns an array of locations. The parent **\** element can contain multiple child **\** elements. - **Number of occurrences:** unlimited - **Parent elements:** [\](#objectset) - **Child elements:** [\](#objectset) - **Helper functions:** The following [\ functions](#content-functions) can be used with this element: `ExtractSingleFile`, `ExtractMultipleFiles`, and `ExtractDirectory`. Syntax: ```xml ``` |Setting|Required?|Value| |--- |--- |--- | |filter|Yes|A script followed by any number of string arguments that are separated by a comma and enclosed in parenthesis. For example, `MyScripts.AScript ("Arg1","Arg2")`.
The script is called for each object that is enumerated by the object sets in the **\** rule. The filter script returns a Boolean value. If the return value is **TRUE**, the object is migrated. If it's **FALSE**, it isn't migrated.| ### \ functions The following functions generate patterns out of the content of an object. These functions are called for every object that the parent **\** element is enumerating. - **ExtractSingleFile** If the registry value is a **MULTI-SZ**, only the first segment is processed. The returned pattern is the encoded location for a file that must exist on the system. If the specification is correct in the registry value, but the file doesn't exist, this function returns **NULL**. Syntax: `ExtractSingleFile(Separators,PathHints)` |Setting|Required?|Value| |--- |--- |--- | |*Separators*|Yes|A list of possible separators that might follow the file specification in this registry value name. For example, if the content is **"C:\Windows\Notepad.exe,-2"**, the separator is a comma. **NULL** can be specified.| |*PathHints*|Yes|A list of extra paths, separated by colons (`;`), where the function looks for a file matching the current content. For example, if the content is **"Notepad.exe"** and the path is the **%Path%** environment variable, the function finds **Notepad.exe** in `%windir%` and returns **"c:\Windows [Notepad.exe]"**. **NULL** can be specified.| For example: ```xml ``` and ```xml ``` - **ExtractMultipleFiles** The **ExtractMultipleFiles** function returns multiple patterns, one for each file that is found in the content of the given registry value. If the registry value is a **MULTI-SZ**, the **MULTI-SZ** separator is considered a separator by default. therefore, for **MULTI-SZ**, the **\** argument must be **NULL**. The returned patterns are the encoded locations for files that must exist on the source computer. If the specification is correct in the registry value but the file doesn't exist, it isn't included in the resulting list. Syntax: `ExtractMultipleFiles(Separators,PathHints)` |Setting|Required?|Value| |--- |--- |--- | |*Separators*|Yes|A list of possible separators that might follow the file specification in this registry value name. For example, if the content is **"C:\Windows\Notepad.exe,-2"**, the separator is a comma. This parameter must be NULL when processing **MULTI-SZ** registry values.| |*PathHints*|Yes|A list of extra paths, separated by colons (`;`), where the function looks for a file matching the current content. For example, if the content is **"Notepad.exe"** and the path is the **%Path%** environment variable, the function finds **Notepad.exe** in `%windir%` and returns **"c:\Windows [Notepad.exe]"**. **NULL** can be specified.| - **ExtractDirectory** The **ExtractDirectory** function returns a pattern that is the encoded location for a directory that must exist on the source computer. If the specification is correct in the registry value, but the directory doesn't exist, this function returns **NULL**. If it's processing a registry value that is a **MULTI-SZ**, only the first segment is processed. Syntax: `ExtractDirectory(Separators,LevelsToTrim,PatternSuffix)` |Setting|Required?|Value| |--- |--- |--- | |*Separators*|No|A list of possible separators that might follow the file specification in this registry value name. For example, if the content is **"C:\Windows\Notepad.exe,-2"**, the separator is a comma. **NULL** must be specified when processing **MULTI-SZ** registry values.| |*LevelsToTrim*|Yes|The number of levels to delete from the end of the directory specification. Use this function to extract a root directory when there's a registry value that points inside that root directory in a known location.| |*PatternSuffix*|Yes|The pattern to add to the directory specification. For example, `* [*]`.| For example: ```xml %HklmWowSoftware%\Classes\Software\RealNetworks\Preferences\DT_Common [] ``` ## \ The **\** element modifies the content of an object before the object is written to the destination computer. For each **\** element, there can be multiple **\** elements. This element returns the new content of the object that is being processed. - **Number of occurrences:** Unlimited - **Parent elements:** [\](#rules) - **Required child elements:** [\](#objectset) - **Helper functions**: The following [\ functions](#contentmodify-functions) can be used with this element: **ConvertToDWORD**, **ConvertToString**, **ConvertToBinary**, **KeepExisting**, **OffsetValue**, **SetValueByTable**, **MergeMultiSzContent**, and **MergeDelimitedContent**. Syntax: ```xml ``` |Setting|Required?|Value| |--- |--- |--- | |script|Yes|A script followed by any number of string arguments that are separated by a comma and enclosed in parenthesis. For example, `MyScripts.AScript ("Arg1","Arg2").`

The script is called for each object that is enumerated by the object sets in the include rule. The filter script returns a Boolean value. If the return value is **TRUE**, the object is migrated. If it's **FALSE**, it isn't migrated.| ### \ functions The following functions change the content of objects as they're migrated. These functions are called for every object that the parent **\** element is enumerating. - **ConvertToDWORD** The **ConvertToDWORD** function converts the content of registry values that are enumerated by the parent **\** element to a DWORD. For example, **ConvertToDWORD** converts the string `"1"` to the DWORD `0x00000001`. If the conversion fails, then the value of **DefaultValueOnError** is applied. Syntax: `ConvertToDWORD(DefaultValueOnError)` |Setting|Required?|Value| |--- |--- |--- | |*DefaultValueOnError*|No|The value that is written into the value name if the conversion fails. **NULL** can be specified, and `0` is written if the conversion fails.| - **ConvertToString** The **ConvertToString** function converts the content of registry values that match the parent **\** element to a string. For example, it converts the DWORD `0x00000001` to the string **"1"**. If the conversion fails, then the value of **DefaultValueOnError** is applied. Syntax: `ConvertToString(DefaultValueOnError)` |Setting|Required?|Value| |--- |--- |--- | |*DefaultValueOnError*|No|The value that is written into the value name if the conversion fails. **NULL** can be specified, and `0` is written if the conversion fails.| For example: ```xml HKCU\Control Panel\Desktop [ScreenSaveUsePassword] ``` - **ConvertToBinary** The **ConvertToBinary** function converts the content of registry values that match the parent **\** element to a binary type. Syntax: `ConvertToBinary ()` - **OffsetValue** The **OffsetValue** function adds or subtracts *Value* from the value of the migrated object, and then writes the result back into the registry value on the destination computer. For example, if the migrated object is a DWORD with a value of `14`, and the *Value* is **"-2"**, the registry value will be `12` on the destination computer. Syntax: `OffsetValue(Value)` |Setting|Required?|Value| |--- |--- |--- | |*Value*|Yes|The string representation of a numeric value. It can be positive or negative. For example, `OffsetValue(2)`.| - **SetValueByTable** The **SetValueByTable** function matches the value from the source computer to the source table. If the value is there, the equivalent value in the destination table is applied. If the value isn't there, or if the destination table has no equivalent value, the *DefaultValueOnError* is applied. Syntax: `SetValueByTable(SourceTable,DestinationTable,DefaultValueOnError)` |Setting|Required?|Value| |--- |--- |--- | |*SourceTable*|Yes|A list of values separated by commas that are possible for the source registry values.| |*DestinationTable*|No|A list of translated values separated by commas.| |*DefaultValueOnError*|No|The value that is applied to the destination computer if either
  1. The value for the source computer doesn't match *SourceTable*
  2. *DestinationTable* has no equivalent value.

If **DefaultValueOnError** is **NULL**, the value isn't changed on the destination computer.| - **KeepExisting** The **KeepExisting** function can be used when there are conflicts on the destination computer. This function keeps (not overwrites) the specified attributes for the object that is on the destination computer. Syntax: `KeepExisting("OptionString","OptionString","OptionString",…)` |Setting|Required?|Value| |--- |--- |--- | | *OptionString* | Yes | *OptionString* can be **Security**, **TimeFields**, or **FileAttrib**:*Letter*. One of each type of *OptionStrings* can be specified. Don't specify multiple *OptionStrings* with the same value. If multiple *OptionStrings* with the same value are specified, the right-most option of that type is kept. For example, don't specify **("FileAttrib:H", "FileAttrib:R")** because only Read-only is evaluated. Instead specify **("FileAttrib:HR")** and both Hidden and Read-only attributes are kept on the destination computer.
  • **Security**: Keeps the destination object's security descriptor if it exists.
  • **TimeFields**: Keeps the destination object's time stamps. This parameter is for files only.
  • **FileAttrib:\**: Keeps the destination object's attribute value, either **ON** or **OFF**, for the specified set of file attributes. This parameter is for files only. The following are case-insensitive, but USMT will ignore any values that are invalid, repeated, or if there's a space after **FileAttrib:**. Any combination of the following attributes can be specified:
    • **A** = Archive
    • **C** = Compressed
    • **E** = Encrypted
    • **H** = Hidden
    • **I** = Not Content Indexed
    • **O** = Offline
    • **R** = Read-Only
    • **S** = System
    • **T** = Temporary
| - **MergeMultiSzContent** The **MergeMultiSzContent** function merges the **MULTI-SZ** content of the registry values that are enumerated by the parent **\** element with the content of the equivalent registry values that already exist on the destination computer. `Instruction` and `String` either remove or add content to the resulting **MULTI-SZ**. Duplicate elements are removed. Syntax: `MergeMultiSzContent (Instruction,String,Instruction,String,…)` |Setting|Required?|Value| |--- |--- |--- | | *Instruction* | Yes | Can be one of the following values:
  • **Add**. Adds the corresponding String to the resulting MULTI-SZ if it isn't already there.
  • **Remove**. Removes the corresponding String from the resulting MULTI-SZ.
| | *String* | Yes | The string to be added or removed. | - **MergeDelimitedContent** The **MergeDelimitedContent** function merges the content of the registry values that are enumerated by the parent **\** element with the content of the equivalent registry values that already exist on the destination computer. The content is considered a list of elements separated by one of the characters in the Delimiters parameter. Duplicate elements are removed. Syntax: `MergeDelimitedContent(Delimiters,Instruction,String,…)` |Setting|Required?|Value| |--- |--- |--- | | *Delimiters* | Yes | A single character that is used to separate the content of the object that is being processed. The content is considered as a list of elements that is separated by the *Delimiters*.
For example, `"."` separates the string based on a period. | | *Instruction* | Yes | Can be one of the following values:
  • **Add**: Adds *String* to the resulting MULTI-SZ if it isn't already there.
  • **Remove**: Removes *String* from the resulting MULTI-SZ.
| | *String* | Yes | The string to be added or removed. | ## \ The **\** element defines a description for the component but doesn't affect the migration. - **Number of occurrences:** zero or one - **Parent elements:** [\](#component) - **Child elements:** none Syntax: ```xml ComponentDescription ``` |Setting|Required?|Value| |--- |--- |--- | |*ComponentDescription*|Yes|The description of the component.| The following code sample shows how the \ element defines the "My custom component" description: ```xml My custom component ``` ## \ The **\** element deletes objects, such as files and registry keys, from the destination computer before applying the objects from the source computer. This element is evaluated only when the **LoadState** tool is run on the destination computer. That is, this element is ignored by the **ScanState** tool. > [!IMPORTANT] > Use this option with extreme caution because it will delete objects from the destination computer. For each **\** element, there can be multiple **\** elements. A common use for this element is if there's a missing registry key on the source computer but the component still needs to be migrated. In this case, all of the component's registry keys can be deleted before migrating the source registry keys. Deleting all of the component's registry keys ensures that if there's a missing key on the source computer, it will also be missing on the destination computer. - **Number of occurrences:** Unlimited - **Parent elements:** [\](#rules) - **Child elements:** [\](#objectset) (The destination computer deletes all child elements.) Syntax: ```xml ``` |Setting|Required?|Value| |--- |--- |--- | |filter|Yes|A script followed by any number of string arguments that are separated by a comma and enclosed in parenthesis. For example, `MyScripts.AScript ("Arg1","Arg2")`.

The script is called for each object that is enumerated by the object sets in the include rule. The filter script returns a Boolean value. If the return value is **TRUE**, the object is migrated. If it's **FALSE**, it isn't migrated.| For example: ```xml HKCU\Software\Lotus\123\99.0\DDE Preferences\* [*] HKCU\Software\Lotus\123\99.0\Find Preferences\* [*] ``` ## \ Although the **\** element is still supported, Microsoft recommends no longer using the **\** element because it might be deprecated in future versions of USMT. If the **\** element is deprecated, it would require a rewrite of any scripts that use the **\** element. Instead, Microsoft recommends using the **[\](#detection)** element. The **\** element allows for more clearly formulated complex Boolean statements The **\** element can be used to determine if the component is present on a system. If all child **\** elements within a **\** element resolve to **TRUE**, then the **\** element resolves to **TRUE**. If any child **\** elements resolve to **FALSE**, then their parent **\** element resolves to **FALSE**. If there's no **\** element section, then USMT assumes that the component is present. For each **\** element there can be multiple children **\** or **\** elements, which are logically joined by an **OR** operator. If at least one **\** or **\** element evaluates to **TRUE**, then the **\** element evaluates to **TRUE**. - **Number of occurrences:** unlimited - **Parent elements:** [\](#detects), [\](#namedelements) - **Required child elements:** [\](#condition) - **Optional child elements:** [\](#objectset) Syntax: ```xml ``` |Setting|Required?|Value| |--- |--- |--- | | name | Yes, when **\** is a child to **\**
No, when **\** is a child to \ | When *ID* is specified, any child elements aren't processed. Instead, any other **\** elements with the same name that are declared within the **\** element are processed. | | context | No
(default = UserAndSystem) | Defines the scope of this parameter, which is whether to process this component in the context of the specific user, across the entire operating system, or both.
The largest possible scope is set by the component element. For example, if a **\** element has a context of **User**, and a **\** element had a context of **UserAndSystem**, then the **\** element would act as though it had a context of **User**. If the **\** element had a context of **System**, it would act as though the **\** element weren't there.
  • **User**: Evaluates the variables for each user.
  • **System**: Evaluates the variables only once for the system.
  • **UserAndSystem**: Evaluates the variables for the entire operating system and each user.
| For examples, see the examples for [\](#detection). ## \ Although the **\** element is still supported, Microsoft recommends no longer using the **\** element because it might be deprecated in future versions of USMT. If the **\** element is deprecated, it would require a rewrite of any scripts that use the **\** element. Instead, Microsoft recommends using the **[\](#detection)** element if the parent element is **\** or **\**, or use the **[\](#conditions)** element if the parent element is **\**. The **\** element allows for more clearly formulated complex Boolean statements and the **\** element allows for formulation of complex Boolean statements. The **\** element is a container for one or more **\** elements. If all of the child **\** elements within a **\** element resolve to **TRUE**, then **\** resolves to **TRUE**. If any of the child **\** elements resolve to **FALSE**, then **\** resolves to **FALSE**. To prevent the **\** element to be written within a component, create the **\** element under the **\** element, and then refer to it. If there's no **\** element section, then USMT assumes that the component is present. The results from each **\** element are joined together by the **OR** operator to form the rule used to detect the parent element. Syntax: ```xml ``` - **Number of occurrences:** Unlimited. - **Parent elements:** [\](#role), [\](#rules), [\](#namedelements) - **Required child elements:** [\](#detect) |Setting|Required?|Value| |--- |--- |--- | | name | Yes, when \ is a child to **\**
No, when \ is a child to **\** or **\** | When *ID* is specified, no child **\** elements are processed. Instead, any other **\** elements with the same name that are declared within the **\** element are processed. | | context | No
(default = UserAndSystem) | Defines the scope of this parameter: whether to process this component in the context of the specific user, across the entire operating system, or both.
The largest possible scope is set by the **\**. For example, if a **\** element has a context of **User** and a **\** element had a context of **UserAndSystem**, then the **\** element would act as though it had a context of **User**. If the **\** element had a context of **System**, it would act as though the **\** element weren't there.
  • **User**: Evaluates the variables for each user.
  • **System**: Evaluates the variables only once for the system.
  • **UserAndSystem**: Evaluates the variables for the entire operating system and each user.

The context parameter is ignored for **\** elements that are inside **\** elements. | The following example is from the `MigApp.xml` file. ```xml MigXmlHelper.DoesFileVersionMatch("%Lotus123InstPath%\123w.exe","ProductVersion","9.*") MigXmlHelper.DoesFileVersionMatch("%SmartSuiteInstPath%\smartctr.exe","ProductVersion","99.*") ``` ## \ The **\** element is a container for one **\** element. The result of the child **\** elements, located underneath the **\** element, determines the result of this element. For example, if all of the child **\** elements within the **\** element resolve to **TRUE**, then the **\** element resolves to **TRUE**. If any of the child **\** elements resolve to **FALSE**, then the **\** element resolves to **FALSE**. In addition, the results from each **\** section within the **\** element are joined together by the **OR** operator to form the detection rule of the parent element. That is, if one of the **\** sections resolve to **TRUE**, then the **\** element is processed. Otherwise, the **\** element isn't processed. Use the **\** element under the **\** element to not write within a component. Then include a matching **\** section under the **\** element to control whether the component is migrated. If there isn't a **\** section for a component, then USMT assumes that the component is present. - **Number of occurrences:** Unlimited. - **Parent elements:** [\](#role), [\](#namedelements) - **Child elements:** [\](#conditions) Syntax: ```xml ``` |Setting|Required?|Value| |--- |--- |--- | | name |
  • Yes, when **\** is declared under **\**
  • Optional, when declared under **\**
| If declared, the content of the **\** element is ignored and the content of the **\** element with the same name that is declared in the **\** element is evaluated. | | context | No, default = UserAndSystem | Defines the scope of this parameter: whether to process this component in the context of the specific user, across the entire operating system, or both.
  • **User**: Evaluates the component for each user.
  • **System**: Evaluates the component only once for the system.
  • **UserAndSystem**: Evaluates the component for the entire operating system and each user.
| For example: ```xml MigXmlHelper.DoesObjectExist("Registry","HKCU\Software\Adobe\Photoshop\8.0") MigXmlHelper.DoesFileVersionMatch("%PhotoshopSuite8Path%\Photoshop.exe","FileVersion","8.*") ``` and ```xml MigXmlHelper.DoesFileVersionMatch("%QuickTime5Exe%","ProductVersion","QuickTime 5.*") MigXmlHelper.DoesFileVersionMatch("%QuickTime5Exe%","ProductVersion","QuickTime 6.*") ``` ## \ The **\** element is a required field within each **\** element. - **Number of occurrences:** once for each component - **Parent elements:** [\](#component) - **Child elements:** none Syntax: ```xml ComponentName ``` |Setting|Required?|Value| |--- |--- |--- | |locID|No|This parameter is for internal USMT use. Don't use this parameter.| |*ComponentName*|Yes|The name for the component.| For example: ```xml Command Prompt settings ``` ## \ The **\** element is a container for **\** elements in which variables can be defined for use in an **.xml** file. All environment variables defined this way are private. That is, they're available only for their child components and the component in which they were defined. For two example scenarios, see [Examples](#examples). - **Number of occurrences:** unlimited - **Parent elements:** [\](#role), [\](#component), [\](#namedelements) - **Required child elements:** [\](#variable) - **Optional child elements:** [\](#conditions) Syntax: ```xml ``` |Setting|Required?|Value| |--- |--- |--- | | name | Yes, when **\** is a child of **\**
No, when **\** is a child of **\** or **\** | When declared as a child of the **\** or **\** elements, if *ID* is declared, USMT ignores the content of the **\** element and the content of the **\** element with the same name declared in the **\** element is processed. | | context | No
(default = UserAndSystem) | Defines the scope of this parameter: whether to process this component in the context of the specific user, across the entire operating system, or both.
The largest possible scope is set by the **\** element. For example, if a **\** element has a context of **User** and a **\** element had a context of **UserAndSystem**, then the **\** element would act as though it had a context of **User**. If the **\** element had a context of **System**, it would act as though **\** weren't there.
  • **User**: Evaluates the variables for each user.
  • **System**: Evaluates the variables only once for the system.
  • **UserAndSystem**: Evaluates the variables for the entire operating system and each user.
| ## Examples ### Example scenario 1 In this scenario, generate the location of objects at run time depending on the configuration of the destination computer. For example, if an application writes data in the directory where the application is installed, and users can install the application anywhere on the computer. If the application writes a registry value `hklm\software\companyname\install [path\]` and then updates this value with the location where the application is installed, then the only way to migrate the required data correctly is to define an environment variable. For example: ```xml ``` Then an include rule can be used as follows. Any of the [\ functions](#script-functions) can be used to perform similar tasks. ```xml %INSTALLPATH%\ [*.xyz] ``` Second, registry values can be filtered to contain the data that is needed. The following example extracts the first string (before the separator "`,`") in the value of the registry `Hklm\software\companyname\application\ [Path\]`. ```xml Hklm\software\companyname\application\ [Path] ``` ### Example scenario 2 In this scenario, five files named `File1.txt`, `File2.txt`, and so on, need to be migrated from `%SYSTEMDRIVE%\data\userdata\dir1\dir2\`. To migrate these files, the following **\** rule must be in an **.xml** file: ```xml %SYSTEMDRIVE%\data\userdata\dir1\dir2 [File1.txt] %SYSTEMDRIVE%\data\userdata\dir1\dir2 [File2.txt] %SYSTEMDRIVE%\data\userdata\dir1\dir2 [File3.txt] %SYSTEMDRIVE%\data\userdata\dir1\dir2 [File4.txt] %SYSTEMDRIVE%\data\userdata\dir1\dir2 [File5.txt] ``` Instead of typing the path five times, create a variable for the location as follows: ```xml %SYSTEMDRIVE%\data\userdata\dir1\dir2 ``` Then, specify the variable in an **\** rule as follows: ```xml %DATAPATH% [File1.txt] %DATAPATH% [File2.txt] %DATAPATH% [File3.txt] %DATAPATH% [File4.txt] %DATAPATH% [File5.txt] ``` ## \ The **\** element determines what objects aren't migrated, unless there's a more specific **\** element that migrates an object. If there's an **\** and **\** element for the same object, the object is included. For each **\** element, there can be multiple child **\** elements. - **Number of occurrences:** Unlimited - **Parent elements:** [\](#rules) - **Child elements:** [\](#objectset) - **Helper functions:** The following [\ filter functions](#include-and-exclude-filter-functions) can be used with this element: `CompareStringContent`, `IgnoreIrrelevantLinks`, `AnswerNo`, `NeverRestore`, and `SameRegContent`. Syntax: ```xml ``` |Setting|Required?|Value| |--- |--- |--- | |filter|No
(default = No)|A script followed by any number of string arguments that are separated by a comma and enclosed in parenthesis. For example, `MyScripts.AScript ("Arg1","Arg2")`.

The script is called for each object that is enumerated by the object sets in the include rule. The filter script returns a Boolean value. If the return value is **TRUE**, the object is migrated. If it's **FALSE**, it isn't migrated.| For example, from the `MigUser.xml` file: ```xml %CSIDL_MYMUSIC%\* [*] %CSIDL_MYPICTURES%\* [*] %CSIDL_MYVIDEO%\* [*] ``` ## \ The **\** element can be used to determine which parameters associated with an object aren't migrated. If there are conflicts between the **\** and **\** elements, the most specific pattern determines the patterns that aren't migrated. If an object doesn't have an **\** or **\** element, then all of its parameters are migrated. - **Number of occurrences:** Unlimited - **Parent elements:** [\](#rules) - **Child elements:** [\](#objectset) Syntax: ```xml ``` |Setting|Required?|Value| |--- |--- |--- | | attributes | Yes | Specifies the attributes to be excluded. Either one of the following or both can be specified. If specifying both, they need to be separated by quotes. For example, `"Security","TimeFields"`:
  • Security can be one of Owner, Group, DACL, or SACL.
  • TimeFields can be one of CreationTime, LastAccessTime and LastWrittenTime
| Example: ```xml System Data %SYSTEMDRIVE%\ [*.txt] %SYSTEMDRIVE%\ [a*.txt] %SYSTEMDRIVE%\ [aa.txt] logoff DOC PPT VXD PST CPP ``` ## \ The \ element is a container for one or more \ elements. - **Number of occurrences:** zero or one - **Parent elements:** [\](#component) - **Required child elements:** [\](#extension) Syntax: ```xml ``` ## \ The \ element can be used to specify documents of a specific extension. - **Number of occurrences:** unlimited - **Parent elements:** [\](#extensions) - **Child elements:** none Syntax: ```xml FilenameExtension ``` |Setting|Required?|Value| |--- |--- |--- | |*FilenameExtension*|Yes|A file name extension.| For example, to migrate all \*.doc files from the source computer, specifying the following code under the **\** element: ```xml doc ``` is the same as specifying the following code below the **\** element: ```xml ``` For another example of how to use the \ element, see the example for [\](#excludeattributes). ## \ The \ element can be used to run a command line during the migration process. For example, a run a command might need to run after the **LoadState** process completes. - **Number of occurrences:** Unlimited - **Parent elements:** [\](#rules) - **Required child elements:** [\](#commandline) Syntax: ```xml ``` |Setting|Required?|Value| |--- |--- |--- | | when | Yes | Indicates when the command line should be run. This value can be one of the following values:
  • **pre-scan** before the scanning process begins.
  • **scan-success** after the scanning process finishes successfully.
  • **post-scan** after the scanning process finished, whether it was successful or not.
  • **pre-apply** before the apply process begins.
  • **apply-success** after the apply process finishes successfully.
  • **post-apply** after the apply process finished, whether it was successful or not.
| For an example of how to use the \ element, see the example for [\](#excludeattributes). ## \ This element is an internal USMT element. Don't use this element. ## \ The **\** element determines what to migrate, unless there's a more specific [\](#exclude) rule. A script can be specified to be more specific to extend the definition of what want needs to be collected. For each **\** element, there can be multiple **\** elements. - **Number of occurrences:** Unlimited - **Parent elements:** [\](#rules) - **Required child element:** [\](#objectset) - **Helper functions:** The following [\ filter functions](#include-and-exclude-filter-functions) can be used with this element: `CompareStringContent`, `IgnoreIrrelevantLinks`, `AnswerNo`, and `NeverRestore`. Syntax: ```xml ``` |Setting|Required?|Value| |--- |--- |--- | | filter | No.
If this parameter isn't specified, then all patterns that are inside the child **\** element are processed. | A script followed by any number of string arguments that are separated by a comma and enclosed in parenthesis. For example, `MyScripts.AScript ("Arg1","Arg2")`.
The script is called for each object that is enumerated by the object sets in the **\** rule. The filter script returns a Boolean value. If the return value is **TRUE**, the object is migrated. If it's **FALSE**, it isn't migrated. | The following example is from the `MigUser.xml` file: ```xml My Video %CSIDL_MYVIDEO% MigXmlHelper.DoesObjectExist("File","%CSIDL_MYVIDEO%") %CSIDL_MYVIDEO%\* [*] %CSIDL_MYVIDEO% [desktop.ini] ``` ### \ and **\** filter functions The following functions return a Boolean value. They can be used to migrate certain objects based on when certain conditions are met. - **AnswerNo** This filter always returns **FALSE**. Syntax: `AnswerNo ()` - **CompareStringContent** Syntax: `CompareStringContent("StringContent","CompareType")` |Setting|Required?|Value| |--- |--- |--- | | *StringContent* | Yes | The string to check against. | | *CompareType* | Yes | A string. Use one of the following values:
  • **Equal** (case insensitive). The function returns **TRUE** if the string representation of the current object that is processed by the migration engine is identical to `StringContent`.
  • **NULL** **or any other value**. The function returns **TRUE** if the string representation of the current object that is processed by the migration engine doesn't match `StringContent`.
| - **IgnoreIrrelevantLinks** This filter screens out the **.lnk** files that point to an object that isn't valid on the destination computer. The screening takes place on the destination computer, so all **.lnk** files are saved to the store during **ScanState**. Then they're screened out when the **LoadState** tool runs. Syntax: `IgnoreIrrelevantLinks ()` For example: ```xml %CSIDL_COMMON_VIDEO%\* [*] ``` - **NeverRestore** This function can be used to collect the specified objects from the source computer but then not migrate the objects to the destination computer. When run with the **ScanState** tool, this function evaluates to **TRUE**. When run with the **LoadState** tool, this function evaluates to **FALSE**. This function might be used to check an object's value on the destination computer but there's no intention to migrate the object to the destination. Syntax: `NeverRestore()` In the following example, HKCU\\Control Panel\\International \[Locale\] is included in the store, but it isn't migrated to the destination computer: ```xml HKCU\Control Panel\International [Locale] ``` ## \ The **\** element can be used to determine whether certain parameters associated with an object are migrated along with the object itself. If there are conflicts between the **\** and **\** elements, the most specific pattern determines which parameters are migrated. If an object doesn't have an **\** or **\** element, then all of its parameters are migrated. - **Number of occurrences:** unlimited - **Parent elements:** [\](#rules) - **Child elements:** [\](#objectset) Syntax: ```xml ``` |Setting|Required?|Value| |--- |--- |--- | | attributes | Yes | Specifies the attributes to be included with a migrated object. Either one of the following or both can be specified. If specifying both, they need to be separated by quotes. For example, `"Security","TimeFields"`:
  • Security can be one of the following values:
    • **Owner**: The owner of the object (SID).
    • **Group**: The primary group for the object (SID).
    • **DACL** (discretionary access control list): An access control list that is controlled by the owner of an object and that specifies the access particular users or groups can have to the object.
    • **SACL** (system access control list): An ACL that controls the generation of audit messages for attempts to access a securable object. The ability to get or set an object's SACL is controlled by a privilege typically held only by system administrators.
  • TimeFields can be one of the following values:
    • **CreationTime**: Specifies when the file or directory was created.
    • **LastAccessTime**: Specifies when the file is last read from, written to, or for executable files, run.
    • **LastWrittenTime**: Specifies when the file is last written to, truncated, or overwritten.
| For an example of how to use the **\** element, see the example for [\](#excludeattributes). ## \ This element is an internal USMT element. Don't use this element. ## \ The **\** element defines the location of the **\** element. - **Number of occurrences:** once for each **\** - **Parent elements:** [\](#object) - **Child elements:** [\](#script) Syntax: ```xml ObjectLocation ``` |Setting|Required?|Value| |--- |--- |--- | |type|Yes|*typeID* can be Registry or File.| |*ObjectLocation*|Yes|The location of the object.| The following example is from the `MigApp.xml` file: ```xml %HklmWowSoftware%\Microsoft\Office\16.0\Common\Migration\Office [UpgradeVersion] DWORD 0B000000 %HklmWowSoftware%\Microsoft\Office\16.0\Common\Migration\Office [Lang] DWORD 00000000 ``` ## \ The **\** element can be used to change the location and name of an object before the object is migrated to the destination computer. The **\** element is processed only when the **LoadState** tool is run on the destination computer. In other words, this element is ignored by the **ScanState** tool. The **\** element creates the appropriate folder on the destination computer if it doesn't already exist. **Number of occurrences:** Unlimited - **Parent elements:** [\](#rules) - **Required child element:** [\](#objectset) - **Helper functions:** The following [\ functions](#locationmodify-functions) can be used with this element: `ExactMove`, `RelativeMove`, and `Move`. Syntax: ```xml ``` |Setting|Required?|Value| |--- |--- |--- | |script|Yes|A script followed by any number of string arguments that are separated by a comma and enclosed in parenthesis. For example, `MyScripts.AScript ("Arg1","Arg2")`.

The script is called for each object that is enumerated by the object sets in the include rule. The filter script returns a Boolean value. If the return value is **TRUE**, the object is migrated. If it's **FALSE**, it isn't migrated.| The following example is from the `MigApp.xml` file: ```xml %CSIDL_APPDATA%\Microsoft\Office\ [Access10.pip] ``` ### \ functions The following functions change the location of objects as they're migrated when using the **\** element. These functions are called for every object that the parent **\** element is enumerating. The **\** element creates the appropriate folder on the destination computer if it doesn't already exist. - **ExactMove** The ExactMove function moves all of the objects that are matched by the parent **\** element into the given *ObjectEncodedLocation*. This function can be used to move a single file to a different location on the destination computer. If the destination location is a node, all of the matching source objects are written to the node without any subdirectories. If the destination location is a leaf, the migration engine migrates all of the matching source objects to the same location. If a collision occurs, the normal collision algorithms apply. Syntax: `ExactMove(ObjectEncodedLocation)` |Setting|Required?|Value| |--- |--- |--- | |*ObjectEncodedLocation*|Yes|The destination [location](#specifying-locations) for all of the source objects.| For example: ```xml HKCU\Keyboard Layout\Toggle [] ``` - **Move** The Move function moves objects to a different location on the destination computer. In addition, this function creates subdirectories that were above the longest CSIDL in the source object name. Syntax: `Move(DestinationRoot)` |Setting|Required?|Value| |--- |--- |--- | |*DestinationRoot*|Yes|The location where the source objects are moved. If needed, this function creates any subdirectories that were above the longest CSIDL in the source object name.| - **RelativeMove** The RelativeMove function can be used to collect and move data. Environment variables can be used in source and destination roots, but they might be defined differently on the source and destination computers. Syntax: `RelativeMove(SourceRoot,DestinationRoot)` |Setting|Required?|Value| |--- |--- |--- | |*SourceRoot*|Yes|The location where the objects are moved from. Any source objects that are enumerated by the parent **\** element that aren't in this location aren't moved.| |*DestinationRoot*|Yes|The location where the source objects are moved to on the destination computer. If needed, this function creates any subdirectories that were above *SourceRoot*.| For example: ```xml %CSIDL_COMMON_FAVORITES%\* [*] %CSIDL_COMMON_FAVORITES%\* [*] ``` ## \<\_locDefinition\> This element is an internal USMT element. Don't use this element. ## \ The **\** element defines the manufacturer for the component, but doesn't affect the migration. - **Number of occurrences:** zero or one - **Parent elements:** [\](#component) - **Child elements:** none Syntax: ```xml Name ``` |Setting|Required?|Value| |--- |--- |--- | |*Name*|Yes|The name of the manufacturer for the component.| ## \ The **\** element determines what happens when a collision occurs. A collision is when an object that is migrated is already present on the destination computer. If this element isn't specified, the default behavior for the registry is for the source object to overwrite the destination object. The default behavior for files is for the source file to be renamed to `OriginalFileName(1).OriginalExtension`. This element specifies only what should be done when a collision occurs. It doesn't include objects. Therefore, for the objects to migrate, **\** rules must be specified along with the **\** element. When an object is processed and a collision is detected, USMT selects the most specific merge rule. It then applies the rule to resolve the conflict. For example, if a **\** rule `C:\* [*]` is set to **\** and a **\** rule `C:\subfolder\* [*]` is set to **\**, then USMT would use the **\** rule because it's the more specific. For an example of this element, see [Conflicts and precedence](usmt-conflicts-and-precedence.md). - **Number of occurrences:** Unlimited - **Parent elements:** [\](#rules) - **Required child element:** [\](#objectset) - **Helper functions:** The following [\ functions](#merge-functions) can be used with this element: `SourcePriority`, `DestinationPriority`, `FindFilePlaceByPattern`, `LeafPattern`, `NewestVersion`, `HigherValue()`, and `LowerValue()`. Syntax: ```xml ``` |Setting|Required?|Value| |--- |--- |--- | |script|Yes|A script followed by any number of string arguments that are separated by a comma and enclosed in parenthesis. For example, `MyScripts.AScript ("Arg1","Arg2")`.

The script is called for each object that is enumerated by the object sets in the **\** rule. The filter script returns a Boolean value. If the return value is **TRUE**, the object is migrated. If it's **FALSE**, it isn't migrated.| The following example is from the `MigUser.xml` file: ```xml %CSIDL_MYVIDEO%\* [*] %CSIDL_MYVIDEO% [desktop.ini] ``` ### \ functions These functions control how collisions are resolved. - **DestinationPriority** Specifies to keep the object that is on the destination computer and not migrate the object from the source computer. For example: ```xml HKCU\Software\Microsoft\Office\16.0\PhotoDraw\ [MyPictures] HKCU\Software\Microsoft\Office\16.0\PhotoDraw\Settings\ [PicturesPath] HKCU\Software\Microsoft\Office\16.0\PhotoDraw\Settings\ [AdditionalPlugInPath] ``` - **FindFilePlaceByPattern** The FindFilePlaceByPattern function saves files with an incrementing counter when a collision occurs. It's a string that contains one of each construct: **\**, **\**, **\** in any order. Syntax: `FindFilePlaceByPattern(FilePattern)` |Setting|Required?|Value| |--- |--- |--- | | *FilePattern* | Yes |
  • **\** is replaced by the original file name.
  • **\** is replaced by an incrementing counter until there's no collision with the objects on the destination computer.
  • **\** is replaced by the original file name extension.

For example, ` ().` changes the source file `MyDocument.doc` into `MyDocument (1).doc` on the destination computer. | - **NewestVersion** The NewestVersion function resolves conflicts on the destination computer based on the version of the file. Syntax: `NewestVersion(VersionTag)` |Setting|Required?|Value| |--- |--- |--- | |*VersionTag*|Yes|The version field that is checked. This field can be `FileVersion` or `ProductVersion`. The file with the highest *VersionTag* version determines which conflicts are resolved based on the file's version. For example, if `Myfile.txt` contains FileVersion 1 and the same file on the destination computer contains FileVersion 2, the file on destination remains.| - **HigherValue()** This function can be used for merging registry values. The registry values are evaluated as numeric values, and the one with the higher value determines which registry values are merged. - **LowerValue()** This function can be used for merging registry values. The registry values are evaluated as numeric values and the one with the lower value determines which registry values are merged. - **SourcePriority** Specifies to migrate the object from the source computer, and to delete the object that is on the destination computer. For example: ```xml %HklmWowSoftware%\Microsoft\Office\14.0\Common\Migration\Publisher [UpgradeVersion] %HklmWowSoftware%\Microsoft\Office\15.0\Common\Migration\Publisher [UpgradeVersion] %HklmWowSoftware%\Microsoft\Office\16.0\Common\Migration\Publisher [UpgradeVersion] ``` ## \ The **\** element is the single root element of a migration **.xml** file and is required. Each **.xml** file must have a unique migration urlid. The urlid of each file that is specified on the command line must be unique. The urlids must be unique because USMT uses the urlid to define the components within the file. - **Number of occurrences:** one - **Parent elements:** none - **Required child elements:** [\](#component) - **Optional child elements:** [\](#library), [\](#namedelements) Syntax: ```xml ``` |Setting|Required?|Value| |--- |--- |--- | |urlid|Yes|*UrlID* is a string identifier that uniquely identifies this **.xml** file. This parameter must be a no-colon-name as defined by the XML Namespaces specification. Each migration **.xml** file must have a unique urlid. If two migration **.xml** files have the same urlid, the second **.xml** file that is specified on the command line isn't processed. For more information about XML Namespaces, see [Use XML Namespaces](/previous-versions/windows/desktop/ms754539(v=vs.85)).| |Name|No|Although not required, it's good practice to use the name of the **.xml** file.| The following example is from the `MigApp.xml` file: ```xml ``` ## MigXMLHelper.FileProperties This filter helper function can be used to filter the migration of files based on file size and date attributes. |Helper Function|MigXMLHelper.FileProperties (property, operator, valueToCompare)| |--- |--- | |Property|filesize, dateCreated, dateModified, dateAccessed| |Operator|range, neq, lte, lt, eq, gte, gt| |valueToCompare|The value that is being compared. For example:
Date: "2023/05/15-2020/05/17", "2023/05/15"
Size: A numeral with B, KB, MB, or GB at the end. "5GB", "1KB-1MB"| ```xml File_size %SYSTEMDRIVE%\DOCS\* [*] ``` ## \ The **\** element can be used to define named elements. These elements can be used in any component throughout the **.xml** file. For an example of how to use this element, see the `MigApp.xml` file. Syntax: ```xml ``` - **Number of occurrences:** Unlimited - **Parent elements:** [\](#migration) - **Child elements:** [\](#environment), [\](#rules), [\](#conditions), [\](#detection), [\](#detects), [\](#detect) For an example of this element, see the `MigApp.xml` file. ## \ The **\** element represents a file or registry key. - **Number of occurrences:** Unlimited - **Parent elements:** [\](#addobjects) - **Required child elements:** [\](#location), [\](#attributes) - **Optional child elements:** [\](#bytes) Syntax: ```xml ``` The following example is from the `MigApp.xml` file: ```xml %HklmWowSoftware%\Microsoft\Office\16.0\Common\Migration\Office [UpgradeVersion] DWORD 0B000000 %HklmWowSoftware%\Microsoft\Office\16.0\Common\Migration\Office [Lang] DWORD 00000000 ``` ## \ The **\** element contains a list of object patterns; for example, file paths, registry locations, and so on. Any child **\** elements are evaluated first. If all child **\** elements return **FALSE**, the **\** element evaluates to an empty set. For each parent element, there can be only multiple **\** elements. - **Number of occurrences:** Unlimited - **Parent elements:** [\](#variable), [\](#content), [\](#include), [\](#exclude), [\](#merge), [\](#contentmodify), [\](#locationmodify), [\](#destinationcleanup), [\](#includeattributes), [\](#excludeattributes), [\](#unconditionalexclude), [\](#detect) - **Required child elements:** either [\](#script) or [\](#pattern) - **Optional child elements:** [\](#content), [\](#conditions), [\](#condition) Syntax: ```xml ``` The following example is from the `MigUser.xml` file: ```xml My Music %CSIDL_MYMUSIC% MigXmlHelper.DoesObjectExist("File","%CSIDL_MYMUSIC%") %CSIDL_MYMUSIC%\* [*] %CSIDL_MYMUSIC%\ [desktop.ini] ``` ## \ This element is an internal USMT element. Don't use this element. ## \ This element is an internal USMT element. Don't use this element. ## \ This element can be used to specify multiple objects. Multiple **\** elements can be used for each **\** element and they're combined. If specifying files, Microsoft recommends using `GenerateDrivePatterns` with **\** instead. `GenerateDrivePatterns` is basically the same as a **\** rule, without the drive letter specification. For example, the following two lines of code are similar: ```xml C:\Folder\* [Sample.doc] ``` - **Number of occurrences:** Unlimited - **Parent elements:** [\](#objectset) - **Child elements:** none but *Path* \[*object*\] must be valid. Syntax: ```xml Path [object] ``` |Setting|Required?|Value| |--- |--- |--- | | type | Yes | *typeID* can be Registry, File, or Ini. If *typeId* is Ini, then a space between *Path* and *object* isn't allowed. For example, the following format is correct when type="Ini":
**\%WinAmp5InstPath%\Winamp.ini|WinAmp[keeponscreen]\** | | *Path* [*object*] | Yes | A valid registry or file path pattern, followed by at least one space, followed by brackets [] that contain the object to be migrated.
  • *Path* can contain the asterisk (`*`) wildcard character or can be an [Recognized environment variables](usmt-recognized-environment-variables.md). The question mark can't be used as a wildcard character. `HKCU` and `HKLM` can be used to refer to `HKEY_CURRENT_USER` and `HKEY_LOCAL_MACHINE` respectively.
  • *Object* can contain the asterisk (`*`) wildcard character. However, the question mark can't be used as a wildcard character. For example:
    **`C:\Folder\ [*]`** enumerates all files in `C:\Folder` but no subfolders of `C:\Folder`.
    **`C:\Folder* [*]`** enumerates all files and subfolders of `C:\Folder`.
    **`C:\Folder\ [*.mp3]`** enumerates all `.mp3` files in `C:\Folder`.
    **`C:\Folder\ [Sample.doc]`** enumerates only the `Sample.doc` file located in C:\Folder.
    **Note**
    If migrating a file that has a square bracket character ([ or ]) in the file name, a carrot (^) character must be inserted directly before the bracket for it to be valid. For example, if there's a file named "file].txt", `c:\documents\mydocs [file^].txt]` must be specified instead of `c:\documents\mydocs [file].txt]`.
| For example: - To migrate a single registry key: ```xml HKLM\Software\Microsoft\Windows\CurrentVersion\Internet Settings\Cache [Persistent] ``` - To migrate the `C:\EngineeringDrafts` folder and any subfolders from the C: drive: ```xml C:\EngineeringDrafts\* [*] ``` - To migrate only the `C:\EngineeringDrafts` folder, excluding any subfolders, from the C: drive: [Reroute files and settings](usmt-reroute-files-and-settings.md) - To migrate the `Sample.doc` file from `C:\EngineeringDrafts`: ```xml C:\EngineeringDrafts\ [Sample.doc] ``` - To migrate the `Sample.doc` file from where ever it exists on the C: drive use pattern in the following way. If multiple files exist with the same name on the C: drive, then all of these files are migrated. ```xml C:\* [Sample.doc] ``` - For more examples of how to use this element, see [Exclude files and settings](usmt-exclude-files-and-settings.md), [Reroute files and settings](usmt-reroute-files-and-settings.md), [Include files and settings](usmt-include-files-and-settings.md), and [Custom XML examples](usmt-custom-xml-examples.md). ## \ This element can be used to run a script during a specific point within the migration process. Return values aren't expected from the scripts that are specified. If there are return values, they're ignored. - **Number of occurrences:** unlimited - **Parent elements:** [\](#rules) - **Required child element:** [\](#script) Syntax: ```xml ``` |Setting|Required?|Value| |--- |--- |--- | | when | Yes | Indicates when the script should be run. This value can be one of the following values:
  • **pre-scan** means before the scanning process begins.
  • **scan-success** means after the scanning process finishes successfully.
  • **post-scan** means after the scanning process finished, whether it was successful or not.
  • **pre-apply** means before the apply process begins.
  • **apply-success** means after the apply process finishes successfully.
  • **post-apply** means after the apply process finished, whether it was successful or not.
| ## \ This element is an internal USMT element. Don't use this element. ## \ The **\** element is required in a custom **.xml** file. When the **\** element is specified, a concrete component can be created. The component is defined by the parameters specified at the **\** level, and with the role that is specified here. - **Number of occurrences:** Each **\** can have one, two or three child **\** elements. - **Parent elements:** [\](#component), [\](#role) - **Required child elements:** [\](#rules) - **Optional child elements:** [\](#environment), [\](#detection), [\](#component), [\](#role), [\](#detects), [\](#plugin) Syntax: ```xml ``` |Setting|Required?|Value| |--- |--- |--- | | role | Yes | Defines the role for the component. Role can be one of:
  • **Container**
  • **Binaries**
  • **Settings**
  • **Data**
One of the following items can be specified:
  1. Up to three **\** elements within a **\** - one "Binaries" role element, one "Settings" role element and one "Data" role element. These parameters don't change the migration behavior - their only purpose is to help categorize the settings that are migrating. These **\** elements can be nested, but each nested element must be of the same role parameter.
  2. One "Container" **\** element within a **\** element. In this case, any child **\** elements can't be specified, only other **\** elements. And each child **\** element must have the same type as that of parent **\** element. For example:
\
  \Microsoft Office 2016\
  \
  \
    \
    \
    \
  
    MigDocUser
    
      
        
          
            
          
        
        
          
           
          
        
      
    
  
```

### Simple executing scripts

The following scripts have no return value. The following errors can be used with **\** elements that are within **\** elements

- **AskForLogoff()**. Prompts the user to sign out at the end of the migration. For example:

  ```xml
  
    
  
  ```

- **ConvertToShortFileName(RegistryEncodedLocation)**. If *RegistryEncodedLocation* is the full path of an existing file, this function converts the file to its short file name and then it updates the registry value.

- **KillExplorer()**. Stops Explorer.exe for the current user context. Stopping Explorer.exe allows access to certain keys and files that are kept open when Explorer.exe is running. For example:

  ```xml
  
    
  
  ```

- **RegisterFonts(FileEncodedLocation)**. Registers the given font or all of the fonts in the given directory. For example:

 ```xml
  
    
  
  ```

- **RemoveEmptyDirectories (DirectoryEncodedPattern).** Deletes any empty directories that match *DirectoryEncodedPattern* on the destination computer.

- **RestartExplorer().** Restarts Explorer.exe at the end of the migration. For example:

  ```xml
  
    
  
  ```

- **StartService (ServiceName, OptionalParam1, OptionalParam2,…).** Starts the service identified by *ServiceName. ServiceName* is the subkey in `HKLM\System\CurrentControlSet\Services` that holds the data for the given service. The optional parameters, if any, is passed to the StartService API. For more information, see the [StartServiceA function (winsvc.h)](/windows/win32/api/winsvc/nf-winsvc-startservicea) article.

- **StopService (ServiceName)**. Stops the service that is identified by *ServiceName. ServiceName* is the subkey in `HKLM\System\CurrentControlSet\Services` that holds the data for the given service.

- **SyncSCM(ServiceShortName).** Reads the Start type value from the registry `(HKLM\System\CurrentControlSet\Services\ServiceShortName [Start])` after the value is changed by the migration engine, and then synchronizes Service Control Manager (SCM) with the new value.

## \

The **\** element can be used to set a value for any environment variables that are inside one of the migration **.xml** files.

- **Number of occurrences:** Once in each [\](#variable) element.

- **Parent elements:** [\](#variable)

- **Child elements:** None.

Syntax:

```xml
NormalText
```

|Setting|Value|
|--- |--- |
|*NormalText*|This text is interpreted as normal text.|

For example:

```xml

  %CSIDL_COMMON_APPDATA%\QuickTime 

```

## \

The **\** element excludes the specified files and registry values from the migration, regardless of the other include rules in any of the migration **.xml** files or in the `Config.xml` file. The objects declared here aren't migrated because this element takes precedence over all other rules. For example, even if there are explicit **\** rules to include `.mp3` files, if they're excluded with this option, then they aren't migrated.

Use this element to exclude all `.mp3` files from the source computer. Or, if backing up `C:\UserData` using another method, the entire folder can be excluded from the migration. Use this element with caution. If an application needs a file that is excluded, the application might not function properly on the destination computer.

- **Number of occurrences:** Unlimited.

- **Parent elements:** [\](#rules)

- **Child elements:** [\](#objectset)

Syntax:

```xml

```

The following **.xml** file excludes all `.mp3` files from migration. For additional examples of how to use this element, see the [Exclude Files and Settings](usmt-exclude-files-and-settings.md).

```xml

  
        Test
        
            
             
                        
    
                         
             
            
        
    

```

## \

The **\** element is required in an **\** element. For each **\** element there must be one **\**, **\**, or **\** element. The content of the **\** element assigns a text value to the environment variable. This element has the following three options:

1. If the **\** element contains a **\** element, then the value of the variable element is the value of the **\** element.

2. If the **\** element contains a **\** element and the invocation of the script produces a non-null string, then the value of the **\** element is the result of the script invocation.

3. If the **\** element contains an **\** element and the evaluation of the **\** element produces at least one object pattern, then the value of the first object to match the resulting object pattern is the value of the variable element.

- **Number of occurrences:** Unlimited

- **Parent elements:** [\](#environment)

- **Required child elements:** either [\](#text), or [\](#script), or [\](#objectset)

Syntax:

```xml


```

|Setting|Required?|Value|
|--- |--- |--- |
|name|Yes|*ID* is a string value that is the name used to reference the environment variable. Microsoft recommends that *ID* start with the component's name to avoid namespace collisions. For example, if the component's name is MyComponent, and a variable is desired that is the component's install path, `MyComponent.InstallPath`could be specified.|
|remap|No, default = FALSE|Specifies whether to evaluate this environment variable as a remapping environment variable. Objects that are located in a path that is underneath this environment variable's value are automatically moved to where the environment variable points on the destination computer.|

The following example is from the `MigApp.xml` file:

```xml

   
      HKLM\Software
   
   
      
   

```

## \

The **\** element defines the version for the component, but doesn't affect the migration.

- **Number of occurrences:** zero or one

- **Parent elements:** [\](#component)

- **Child elements:** none

Syntax:

```xml
ComponentVersion
```

|Setting|Required?|Value|
|--- |--- |--- |
|*ComponentVersion*|Yes|The version of the component, which can contain patterns.|

For example:

```xml
4.*
```

## \

The **\** element is for USMT internal use only. Don't use this element.

## Appendix

### Specifying locations

- **Specifying encoded locations**. The encoded location used in all of the helper functions is an unambiguous string representation for the name of an object. The encoded location is composed of the node part, optionally followed by the leaf enclosed in square brackets. This format makes a clear distinction between nodes and leaves.

    For example, specify the file `C:\Windows\Notepad.exe` like this: `c:\Windows[Notepad.exe]`. Similarly, specify the directory `C:\Windows\System32` like this: `c:\Windows\System32`. (Notice the absence of the `[]` construct.)

    Representing the registry is similar. The default value of a registry key is represented as an empty `[]` construct. For example, the default value for the `HKLM\SOFTWARE\MyKey` registry key is `HKLM\SOFTWARE\MyKey[]`.

- **Specifying location patterns**. Specifying a location pattern is similar to specifying an actual location. The exception is that both the node and leaf part accept patterns. However, a pattern from the node doesn't extend to the leaf.

    For example, the pattern `c:\Windows\*` matches the Windows directory and all subdirectories, but it doesn't match any of the files in those directories. To match the files as well, `c:\Windows\*[*]` must be specified.

### Internal USMT functions

The following functions are for internal USMT use only. Don't use them in an **.xml** file.

- *AntiAlias*

- *ConvertScreenSaver*

- *ConvertShowIEOnDesktop*

- *ConvertToOfficeLangID*

- *MigrateActiveDesktop*

- *MigrateAppearanceUPM*

- *MigrateDisplayCS*

- *MigrateDisplaySS*

- *MigrateIEAutoSearch*

- *MigrateMouseUPM*

- *MigrateSoundSysTray*

- *MigrateTaskBarSS*

- *SetPstPathInMapiStruc*

### Valid version tags

The following version tags can be used with various helper functions:

- "CompanyName"

- "FileDescription"

- "FileVersion"

- "InternalName"

- "LegalCopyright"

- "OriginalFilename"

- "ProductName"

- "ProductVersion"

The following version tags contain values that can be compared:

- "FileVersion"

- "ProductVersion"

## Related articles

- [USMT XML reference](usmt-xml-reference.md).