From e185f43bf363bee4dc1d390b50f16e06a26773d2 Mon Sep 17 00:00:00 2001 From: Frank Rojas <45807133+frankroj@users.noreply.github.com> Date: Fri, 29 Dec 2023 18:11:04 -0500 Subject: [PATCH] USMT Refresh 10 --- .../usmt/usmt-xml-elements-library.md | 512 +++++++++--------- 1 file changed, 256 insertions(+), 256 deletions(-) diff --git a/windows/deployment/usmt/usmt-xml-elements-library.md b/windows/deployment/usmt/usmt-xml-elements-library.md index 2ed6433654..0db8752f52 100644 --- a/windows/deployment/usmt/usmt-xml-elements-library.md +++ b/windows/deployment/usmt/usmt-xml-elements-library.md @@ -26,19 +26,19 @@ The following table describes the XML elements and helper functions you can use | Elements A-K | Elements L-Z | Helper functions | |-----|----|-----| -| [<addObjects>](#addobjects)
[<attributes>](#attributes)
[<bytes>](#bytes)
[<commandLine>](#commandline)
[<component>](#component)
[<condition>](#condition)
[<conditions>](#conditions)
[<content>](#content)
[<contentModify>](#contentmodify)
[<description>](#description)
[<destinationCleanup>](#destinationcleanup)
[<detect>](#detect)
[<detects>](#detects)
[<detection>](#detection)
[<displayName>](#displayname)
[<environment>](#environment)
[<exclude>](#exclude)
[<excludeAttributes>](#excludeattributes)
[<extensions>](#extensions)
[<extension>](#extension)
[<externalProcess>](#externalprocess)
[<icon>](#icon)
[<include>](#include)
[<includeAttribute>](#includeattributes) | [<library>](#library)
[<location>](#location)
[<locationModify>](#locationmodify)
[<_locDefinition>](#_locdefinition)
[<manufacturer>](#manufacturer)
[<merge>](#merge)
[<migration>](#migration)
[<namedElements>](#namedelements)
[<object>](#object)
[<objectSet>](#objectset)
[<path>](#path)
[<paths>](#paths)
[<pattern>](#pattern)
[<processing>](#processing)
[<plugin>](#plugin)
[<role>](#role)
[<rules>](#rules)
[<script>](#script)
[<text>](#text)
[<unconditionalExclude>](#unconditionalexclude)
[<variable>](#variable)
[<version>](#version)
[<windowsObjects>](#windowsobjects) | [<condition> functions](#condition-functions)
[<content> functions](#content-functions)
[<contentModify> functions](#contentmodify-functions)
[<include> and <exclude> filter functions](#include-and-exclude-filter-functions)
[<locationModify> functions](#locationmodify-functions)
[<merge> functions](#merge-functions)
[<script> functions](#script-functions)
[Internal USMT functions](#internal-usmt-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 **<addObjects>** element emulates the existence of one or more objects on the source computer. The child **<object>** elements provide the details of the emulated objects. If the content is a **<script>** element, the result of the invocation is an array of objects. +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>](#rules) +- **Parent elements:** [\](#rules) -- **Required child elements:** [<object>](#object) In addition, you must specify [<location>](#location) and [<attribute>](#attributes) as child elements of this **<object>** element. +- **Required child elements:** [\](#object) In addition, you must specify [\](#location) and [\](#attributes) as child elements of this **\** element. -- **Optional child elements:** [<conditions>](#conditions), [<condition>](#condition), [<script>](#script) +- **Optional child elements:** [\](#conditions), [\](#condition), [\](#script) Syntax: @@ -52,25 +52,25 @@ The following example is from the `MigApp.xml` file: ```xml - %HklmWowSoftware%\Microsoft\Office\12.0\Common\Migration\Office [UpgradeVersion] + %HklmWowSoftware%\Microsoft\Office\16.0\Common\Migration\Office [UpgradeVersion] DWORD 0B000000 - %HklmWowSoftware%\Microsoft\Office\12.0\Common\Migration\Office [Lang] + %HklmWowSoftware%\Microsoft\Office\16.0\Common\Migration\Office [Lang] DWORD 00000000 ``` -## <attributes> +## \ -The **<attributes>** element defines the attributes for a registry key or file. +The **\** element defines the attributes for a registry key or file. -- **Number of occurrences:** once for each [<object>](#object) +- **Number of occurrences:** once for each [\](#object) -- **Parent elements:** [<object>](#object) +- **Parent elements:** [\](#object) - **Child elements:** none @@ -94,13 +94,13 @@ The following example is from the `MigApp.xml` file: ``` -## <bytes> +## \ -You must specify the **<bytes>** element only for files because, if **<location>** corresponds to a registry key or a directory, then **<bytes>** is ignored. +You must specify the **\** element only for files because, if **\** corresponds to a registry key or a directory, then **\** is ignored. - **Number of occurrences:** zero or one -- **Parent elements:** [<object>](#object) +- **Parent elements:** [\](#object) - **Child elements:** none @@ -113,8 +113,8 @@ Syntax: |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 **<bytes>** 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 **<bytes>** element is interpreted as a string.
  • When the string is **No**: the content of the **<bytes>** 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`.
| +|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: @@ -126,13 +126,13 @@ The following example is from the `MigApp.xml` file: ``` -## <commandLine> +## \ -You might want to use the **<commandLine>** element if you want to start or stop a service or application before or after you run the **ScanState** and **LoadState** tools. +You might want to use the **\** element if you want to start or stop a service or application before or after you run the **ScanState** and **LoadState** tools. - **Number of occurrences:** unlimited -- **Parent elements:** [<externalProcess>](#externalprocess) +- **Parent elements:** [\](#externalprocess) - **Child elements:** none @@ -146,22 +146,22 @@ Syntax: |--- |--- |--- | |*CommandLineString*|Yes|A valid command line.| -## <component> +## \ -The **<component>** 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**. You can use the child elements to define the component. +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**. You can use the child elements to define the component. -A component can be nested inside another component; that is, the **<component>** element can be a child of the **<role>** element within the **<component>** element in two cases: +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 **<component>** element is a container -1. If the child **<component>** element has the same role as the parent **<component>** element. +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>](#migration), [<role>](#role) +- **Parent elements:** [\](#migration), [\](#role) -- **Required child elements:** [<role>](#role), [<displayName>](#displayname) +- **Required child elements:** [\](#role), [\](#displayname) -- **Optional child elements:** [<manufacturer>](#manufacturer), [<version>](#version), [<description>](#description), [<paths>](#paths), [<icon>](#icon), [<environment>](#environment), [<extensions>](#extensions) +- **Optional child elements:** [\](#manufacturer), [\](#version), [\](#description), [\](#paths), [\](#icon), [\](#environment), [\](#extensions) Syntax: @@ -174,25 +174,25 @@ hidden="Yes|No"> |Setting|Required?|Value| |--- |--- |--- | | type | Yes | You can use the following 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 you specify this file on the `ScanState.exe` command line, you must also specify the file 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 **<component>** element. For example, if a **<component>** element has a context of **User** and a **<rules>** element had a context of **UserAndSystem**, then the **<rules>** element would act as though it has a context of **User**. If a **<rules>** element has a context of **System**, it would act as though the **<rules>** 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.
| +| 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 you specify this file on the `ScanState.exe` command line, you must also specify the file 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. -## <condition> +## \ -Although the **<condition>** element under the **<detect>**, **<objectSet>**, and **<addObjects>** elements is still supported, Microsoft recommends to no longer use the **<condition>** element because it might be deprecated in future versions of USMT. If the **<condition>** element is deprecated, it would require a rewrite of any scripts that use the **<condition>** element. Instead, if you need to use a condition within the **<objectSet>** and **<addObjects>** elements, Microsoft recommends using the more powerful **[<conditions>](#conditions)** element. The **<conditions>** element allows for formulation of complex Boolean statements. +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 you need to use a condition within the **\** and **\** elements, Microsoft recommends using the more powerful **[\](#conditions)** element. The **\** element allows for formulation of complex Boolean statements. -The **<condition>** element has a Boolean result. You can use this element 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. +The **\** element has a Boolean result. You can use this element 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>](#conditions), [<detect>](#detect), [<objectSet>](#objectset), [<addObjects>](#addobjects) +- **Parent elements:** [\](#conditions), [\](#detect), [\](#objectset), [\](#addobjects) - **Child elements:** none -- **Helper functions:** You can use the following [<condition> functions](#condition-functions) with this element: `DoesOSMatch`, `IsNative64Bit()`, `IsOSLaterThan`, `IsOSEarlierThan`, `DoesObjectExist`, `DoesFileVersionMatch`, `IsFileVersionAbove`, `IsFileVersionBelow`, `IsSystemContext`, `DoesStringContentEqual`, `DoesStringContentContain`, `IsSameObject`, `IsSameContent`, and `IsSameStringContent`. +- **Helper functions:** You can use the following [\ functions](#condition-functions) with this element: `DoesOSMatch`, `IsNative64Bit()`, `IsOSLaterThan`, `IsOSEarlierThan`, `DoesObjectExist`, `DoesFileVersionMatch`, `IsFileVersionAbove`, `IsFileVersionBelow`, `IsSystemContext`, `DoesStringContentEqual`, `DoesStringContentContain`, `IsSameObject`, `IsSameContent`, and `IsSameStringContent`. Syntax: @@ -205,7 +205,7 @@ Syntax: |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 **<condition>** elements, **A** and **B**, are joined together by the **AND** operator because they are in separate **<conditions>** sections: +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 @@ -218,7 +218,7 @@ For example, in the following code sample, the **<condition>** elements, * ``` -However, in the following code sample, the **<condition>** elements, **A** and **B**, are joined together by the **OR** operator because they are in the same **<conditions>** section. +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 @@ -229,9 +229,9 @@ However, in the following code sample, the **<condition>** elements, **A** ``` -### <condition> functions +### \ functions -The **<condition>** functions return a Boolean value. You can use these elements in **<addObjects>** conditions. +The **\** functions return a Boolean value. You can use these elements in **\** conditions. - [Operating system version functions](#operating-system-version-functions) @@ -247,7 +247,7 @@ The **<condition>** functions return a Boolean value. You can use these el |Setting|Required?|Value| |--- |--- |--- | - |*OSType*|Yes|The only valid value for this setting is **NT**. Note, however, that you must set this setting for the **<condition>** functions to work correctly.| + |*OSType*|Yes|The only valid value for this setting is **NT**. Note, however, that you must set this setting 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`. You can also specify partial specification of the version with a pattern such as `5.0.*`.| For example: @@ -426,15 +426,15 @@ The **<condition>** functions return a Boolean value. You can use these el |*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. You can specify environment variables.| -## <conditions> +## \ -The **<conditions>** 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. +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 **<conditions>** element. Limited to one occurrence in [<detection>](#detection), [<rules>](#rules), [<addObjects>](#addobjects), and [<objectSet>](#objectset) +- **Number of occurrences:** Unlimited inside another **\** element. Limited to one occurrence in [\](#detection), [\](#rules), [\](#addobjects), and [\](#objectset) -- **Parent elements:** [<conditions>](#conditions), [<detection>](#detection), [<environment>](#environment), [<rules>](#rules), [<addObjects>](#addobjects), and [<objectSet>](#objectset) +- **Parent elements:** [\](#conditions), [\](#detection), [\](#environment), [\](#rules), [\](#addobjects), and [\](#objectset) -- **Child elements:** [<conditions>](#conditions), [<condition>](#condition) +- **Child elements:** [\](#conditions), [\](#condition) Syntax: @@ -460,17 +460,17 @@ The following example is from the `MigApp.xml` file: ``` -## <content> +## \ -You can use the **<content>** element to specify a list of object patterns to obtain an object set from the source computer. Each **<objectSet>** within a **<content>** 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 **<content>** element. The filter script returns an array of locations. The parent **<objectSet>** element can contain multiple child **<content>** elements. +You can use the **\** element 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>](#objectset) +- **Parent elements:** [\](#objectset) -- **Child elements:** [<objectSet>](#objectset) +- **Child elements:** [\](#objectset) -- **Helper functions:** You can use the following [<content> functions](#content-functions) with this element: `ExtractSingleFile`, `ExtractMultipleFiles`, and `ExtractDirectory`. +- **Helper functions:** You can use the following [\ functions](#content-functions) with this element: `ExtractSingleFile`, `ExtractMultipleFiles`, and `ExtractDirectory`. Syntax: @@ -481,11 +481,11 @@ Syntax: |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.| +|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.| -### <content> functions +### \ functions -The following functions generate patterns out of the content of an object. These functions are called for every object that the parent **<ObjectSet>** element is enumerating. +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** @@ -512,7 +512,7 @@ The following functions generate patterns out of the content of an object. These - **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 **<Separators>** argument must be **NULL**. + 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. @@ -547,17 +547,17 @@ The following functions generate patterns out of the content of an object. These ``` -## <contentModify> +## \ -The **<contentModify>** element modifies the content of an object before the object is written to the destination computer. For each **<contentModify>** element, there can be multiple **<objectSet>** elements. This element returns the new content of the object that is being processed. +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>](#rules) +- **Parent elements:** [\](#rules) -- **Required child elements:** [<objectSet>](#objectset) +- **Required child elements:** [\](#objectset) -- **Helper functions**: You can use the following [<contentModify> functions](#contentmodify-functions) with this element: **ConvertToDWORD**, **ConvertToString**, **ConvertToBinary**, **KeepExisting**, **OffsetValue**, **SetValueByTable**, **MergeMultiSzContent**, and **MergeDelimitedContent**. +- **Helper functions**: You can use the following [\ functions](#contentmodify-functions) with this element: **ConvertToDWORD**, **ConvertToString**, **ConvertToBinary**, **KeepExisting**, **OffsetValue**, **SetValueByTable**, **MergeMultiSzContent**, and **MergeDelimitedContent**. Syntax: @@ -570,13 +570,13 @@ Syntax: |--- |--- |--- | |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.| -### <contentModify> functions +### \ functions -The following functions change the content of objects as they're migrated. These functions are called for every object that the parent **<ObjectSet>** element is enumerating. +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 **<ObjectSet>** 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. + 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)` @@ -586,7 +586,7 @@ The following functions change the content of objects as they're migrated. These - **ConvertToString** - The **ConvertToString** function converts the content of registry values that match the parent **<ObjectSet>** 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. + 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)` @@ -606,7 +606,7 @@ The following functions change the content of objects as they're migrated. These - **ConvertToBinary** - The **ConvertToBinary** function converts the content of registry values that match the parent **<ObjectSet>** element to a binary type. + The **ConvertToBinary** function converts the content of registry values that match the parent **\** element to a binary type. Syntax: `ConvertToBinary ()` @@ -640,11 +640,11 @@ The following functions change the content of objects as they're migrated. These |Setting|Required?|Value| |--- |--- |--- | - | *OptionString* | Yes | *OptionString* can be **Security**, **TimeFields**, or **FileAttrib**:*Letter*. You can specify one of each type of *OptionStrings*. Don't specify multiple *OptionStrings* with the same value. If you do, 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:<Letter>**: 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:**. You can specify any combination of the following attributes:
    • **A** = Archive
    • **C** = Compressed
    • **E** = Encrypted
    • **H** = Hidden
    • **I** = Not Content Indexed
    • **O** = Offline
    • **R** = Read-Only
    • **S** = System
    • **T** = Temporary
| + | *OptionString* | Yes | *OptionString* can be **Security**, **TimeFields**, or **FileAttrib**:*Letter*. You can specify one of each type of *OptionStrings*. Don't specify multiple *OptionStrings* with the same value. If you do, 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:**. You can specify any combination of the following attributes:
    • **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 **<ObjectSet>** 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. + 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,…)` @@ -655,7 +655,7 @@ The following functions change the content of objects as they're migrated. These - **MergeDelimitedContent** - The **MergeDelimitedContent** function merges the content of the registry values that are enumerated by the parent **<ObjectSet>** 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. + 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,…)` @@ -665,13 +665,13 @@ The following functions change the content of objects as they're migrated. These | *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. | -## <description> +## \ -The **<description>** element defines a description for the component but doesn't affect the migration. +The **\** element defines a description for the component but doesn't affect the migration. - **Number of occurrences:** zero or one -- **Parent elements:** [<component>](#component) +- **Parent elements:** [\](#component) - **Child elements:** none @@ -685,26 +685,26 @@ Syntax: |--- |--- |--- | |*ComponentDescription*|Yes|The description of the component.| -The following code sample shows how the <description> element defines the "My custom component" description: +The following code sample shows how the \ element defines the "My custom component" description: ```xml My custom component ``` -## <destinationCleanup> +## \ -The **<destinationCleanup>** 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. +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 **<destinationCleanup>** element, there can be multiple **<objectSet>** elements. A common use for this element is if there's a missing registry key on the source computer and you want to ensure that a component is migrated. In this case, you can delete all of the component's registry keys 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. +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 and you want to ensure that a component is migrated. In this case, you can delete all of the component's registry keys 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>](#rules) +- **Parent elements:** [\](#rules) -- **Child elements:** [<objectSet>](#objectset) (The destination computer deletes all child elements.) +- **Child elements:** [\](#objectset) (The destination computer deletes all child elements.) Syntax: @@ -728,21 +728,21 @@ For example: ``` -## <detect> +## \ -Although the **<detect>** element is still supported, Microsoft recommends no longer using the **<detect>** element because it might be deprecated in future versions of USMT. If the **<detect>** element is deprecated, it would require a rewrite of any scripts that use the **<detect>** element. Instead, Microsoft recommends using the **[<detection>](#detection)** element. The **<detection>** element allows for more clearly formulated complex Boolean statements +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 **<detect>** element can be used to determine if the component is present on a system. If all child **<detect>** elements within a **<detect>** element resolve to **TRUE**, then the **<detect>** element resolves to **TRUE**. If any child **<detect>** elements resolve to **FALSE**, then their parent **<detect>** element resolves to **FALSE**. If there's no **<detect>** element section, then USMT assumes that the component is present. +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 **<detect>** element there can be multiple child **<condition>** or **<objectSet>** elements, which are logically joined by an **OR** operator. If at least one **<condition>** or **<objectSet>** element evaluates to **TRUE**, then the **<detect>** element evaluates to **TRUE**. +For each **\** element there can be multiple child **\** 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>](#detects), [<namedElements>](#namedelements) +- **Parent elements:** [\](#detects), [\](#namedelements) -- **Required child elements:** [<condition>](#condition) +- **Required child elements:** [\](#condition) -- **Optional child elements:** [<objectSet>](#objectset) +- **Optional child elements:** [\](#objectset) Syntax: @@ -753,16 +753,16 @@ Syntax: |Setting|Required?|Value| |--- |--- |--- | -| name | Yes, when **<detect>** is a child to **<namedElements>**
No, when **<detect>** is a child to <detects> | When *ID* is specified, any child elements aren't processed. Instead, any other **<detect>** elements with the same name that are declared within the **<namedElements>** 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 **<component>** element has a context of **User**, and a **<rules>** element had a context of **UserAndSystem**, then the **<rules>** element would act as though it had a context of **User**. If the **<rules>** element had a context of **System**, it would act as though the **<rules>** 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.
| +| 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>](#detection). +For examples, see the examples for [\](#detection). -## <detects> +## \ -Although the **<detects>** element is still supported, Microsoft recommends no longer using the **<detects>** element because it might be deprecated in future versions of USMT. If the **<detects>** element is deprecated, it would require a rewrite of any scripts that use the **<detects>** element. Instead, Microsoft recommends using the **[<detection>](#detection)** element if the parent element is **<role>** or **<namedElements>**, or use the **[<conditions>](#conditions)** element if the parent element is **<rules>**. The **<detection>** element allows for more clearly formulated complex Boolean statements and the **<conditions>** element allows for formulation of complex Boolean statements. +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 **<detects>** element is a container for one or more **<detect>** elements. If all of the child **<detect>** elements within a **<detects>** element resolve to **TRUE**, then **<detects>** resolves to **TRUE**. If any of the child **<detect>** elements resolve to **FALSE**, then **<detects>** resolves to **FALSE**. If you don't want to write the **<detects>** elements within a component, then you can create the **<detects>** element under the **<namedElements>** element, and then refer to it. If there's no **<detects>** element section, then USMT assumes that the component is present. The results from each **<detects>** element are joined together by the **OR** operator to form the rule used to detect the parent element. +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**. If you don't want to write the **\** elements within a component, then you can 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: @@ -773,14 +773,14 @@ Syntax: - **Number of occurrences:** Unlimited. -- **Parent elements:** [<role>](#role), [<rules>](#rules), [<namedElements>](#namedelements) +- **Parent elements:** [\](#role), [\](#rules), [\](#namedelements) -- **Required child elements:** [<detect>](#detect) +- **Required child elements:** [\](#detect) |Setting|Required?|Value| |--- |--- |--- | -| name | Yes, when <detects> is a child to **<namedElements>**
No, when <detects> is a child to **<role>** or **<rules>** | When *ID* is specified, no child **<detect>** elements are processed. Instead, any other **<detects>** elements with the same name that are declared within the **<namedElements>** 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 **<component element>**. For example, if a **<component>** element has a context of **User** and a **<rules>** element had a context of **UserAndSystem**, then the **<rules>** element would act as though it had a context of **User**. If the **<rules>** element had a context of **System**, it would act as though the **<rules>** 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 **<detects>** elements that are inside **<rules>** elements. | +| 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. @@ -795,19 +795,19 @@ The following example is from the `MigApp.xml` file. ``` -## <detection> +## \ -The **<detection>** element is a container for one **<conditions>** element. The result of the child **<condition>** elements, located underneath the **<conditions>** element, determines the result of this element. For example, if all of the child **<conditions>** elements within the **<detection>** element resolve to **TRUE**, then the **<detection>** element resolves to **TRUE**. If any of the child **<conditions>** elements resolve to **FALSE**, then the **<detection>** element resolves to **FALSE**. +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 **<detection>** section within the **<role>** element are joined together by the **OR** operator to form the detection rule of the parent element. That is, if one of the **<detection>** sections resolves to **TRUE**, then the **<role>** element is processed. Otherwise, the **<role>** element isn't processed. +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 resolves to **TRUE**, then the **\** element is processed. Otherwise, the **\** element isn't processed. -Use the **<detection>** element under the **<namedElements>** element if you don't want to write it within a component. Then include a matching **<detection>** section under the **<role>** element to control whether the component is migrated. If there isn't a **<detection>** section for a component, then USMT assumes that the component is present. +Use the **\** element under the **\** element if you don't want to write it 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>](#role), [<namedElements>](#namedelements) +- **Parent elements:** [\](#role), [\](#namedelements) -- **Child elements:** [<conditions>](#conditions) +- **Child elements:** [\](#conditions) Syntax: @@ -818,7 +818,7 @@ Syntax: |Setting|Required?|Value| |--- |--- |--- | -| name |
  • Yes, when **<detection>** is declared under **<namedElements>**
  • Optional, when declared under **<role>**
| If declared, the content of the **<detection>** element is ignored and the content of the **<detection>** element with the same name that is declared in the **<namedElements>** element is evaluated. | +| 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: @@ -844,13 +844,13 @@ and ``` -## <displayName> +## \ -The **<displayName>** element is a required field within each **<component>** element. +The **\** element is a required field within each **\** element. - **Number of occurrences:** once for each component -- **Parent elements:** [<component>](#component) +- **Parent elements:** [\](#component) - **Child elements:** none @@ -871,17 +871,17 @@ For example: Command Prompt settings ``` -## <environment> +## \ -The **<environment>** element is a container for **<variable>** elements in which you can define variables to use in your .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). +The **\** element is a container for **\** elements in which you can define variables to use in your .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>](#role), [<component>](#component), [<namedElements>](#namedelements) +- **Parent elements:** [\](#role), [\](#component), [\](#namedelements) -- **Required child elements:** [<variable>](#variable) +- **Required child elements:** [\](#variable) -- **Optional child elements:** [<conditions>](#conditions) +- **Optional child elements:** [\](#conditions) Syntax: @@ -892,8 +892,8 @@ Syntax: |Setting|Required?|Value| |--- |--- |--- | -| name | Yes, when **<environment>** is a child of **<namedElements>**
No, when **<environment>** is a child of **<role>** or **<component>** | When declared as a child of the **<role>** or **<component>** elements, if *ID* is declared, USMT ignores the content of the **<environment>** element and the content of the **<environment>** element with the same name declared in the **<namedElements>** 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 **<component>** element. For example, if a **<component>** element has a context of **User** and a **<rules>** element had a context of **UserAndSystem**, then the **<rules>** element would act as though it had a context of **User**. If the **<rules>** element had a context of **System**, it would act as though **<rules>** 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.
| +| 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 @@ -909,7 +909,7 @@ In this scenario, you want to generate the location of objects at run time depen ``` -Then you can use an include rule as follows. You can use any of the [<script> functions](#script-functions) to perform similar tasks. +Then you can use an include rule as follows. You can use any of the [\ functions](#script-functions) to perform similar tasks. ```xml @@ -937,7 +937,7 @@ Second, you can also filter registry values that contain data that you need. The ### Example scenario 2 -In this scenario, you want to migrate five files named `File1.txt`, `File2.txt`, and so on, from `%SYSTEMDRIVE%\data\userdata\dir1\dir2\`. To migrate these files, you must have the following **<include>** rule in an .xml file: +In this scenario, you want to migrate five files named `File1.txt`, `File2.txt`, and so on, from `%SYSTEMDRIVE%\data\userdata\dir1\dir2\`. To migrate these files, you must have the following **\** rule in an .xml file: ```xml @@ -961,7 +961,7 @@ Instead of typing the path five times, you can create a variable for the locatio ``` -Then, you can specify the variable in an **<include>** rule as follows: +Then, you can specify the variable in an **\** rule as follows: ```xml @@ -975,17 +975,17 @@ Then, you can specify the variable in an **<include>** rule as follows: ``` -## <exclude> +## \ -The **<exclude>** element determines what objects aren't migrated, unless there's a more specific **<include>** element that migrates an object. If there's an **<include>** and **<exclude>** element for the same object, the object is included. For each **<exclude>** element, there can be multiple child **<objectSet>** elements. +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>](#rules) +- **Parent elements:** [\](#rules) -- **Child elements:** [<objectSet>](#objectset) +- **Child elements:** [\](#objectset) -- **Helper functions:** You can use the following [<exclude> filter functions](#include-and-exclude-filter-functions) with this element: `CompareStringContent`, `IgnoreIrrelevantLinks`, `AnswerNo`, `NeverRestore`, and `SameRegContent`. +- **Helper functions:** You can use the following [\ filter functions](#include-and-exclude-filter-functions) with this element: `CompareStringContent`, `IgnoreIrrelevantLinks`, `AnswerNo`, `NeverRestore`, and `SameRegContent`. Syntax: @@ -1010,15 +1010,15 @@ For example, from the `MigUser.xml` file: ``` -## <excludeAttributes> +## \ -You can use the **<excludeAttributes>** element to determine which parameters associated with an object aren't migrated. If there are conflicts between the **<includeAttributes>** and **<excludeAttributes>** elements, the most specific pattern determines the patterns that aren't migrated. If an object doesn't have an **<includeAttributes>** or **<excludeAttributes>** element, then all of its parameters are migrated. +You can use the **\** element 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>](#rules) +- **Parent elements:** [\](#rules) -- **Child elements:** [<objectSet>](#objectset) +- **Child elements:** [\](#objectset) Syntax: @@ -1082,15 +1082,15 @@ Example: ``` -## <extensions> +## \ -The <extensions> element is a container for one or more <extension> elements. +The \ element is a container for one or more \ elements. - **Number of occurrences:** zero or one -- **Parent elements:** [<component>](#component) +- **Parent elements:** [\](#component) -- **Required child elements:** [<extension>](#extension) +- **Required child elements:** [\](#extension) Syntax: @@ -1099,13 +1099,13 @@ Syntax: ``` -## <extension> +## \ -You can use the <extension> element to specify documents of a specific extension. +You can use the \ element to specify documents of a specific extension. - **Number of occurrences:** unlimited -- **Parent elements:** [<extensions>](#extensions) +- **Parent elements:** [\](#extensions) - **Child elements:** none @@ -1119,7 +1119,7 @@ Syntax: |--- |--- |--- | |*FilenameExtension*|Yes|A file name extension.| -For example, if you want to migrate all \*.doc files from the source computer, specifying the following code under the **<component>** element: +For example, if you want to migrate all \*.doc files from the source computer, specifying the following code under the **\** element: ```xml @@ -1127,7 +1127,7 @@ For example, if you want to migrate all \*.doc files from the source computer, s ``` -is the same as specifying the following code below the **<rules>** element: +is the same as specifying the following code below the **\** element: ```xml @@ -1137,17 +1137,17 @@ is the same as specifying the following code below the **<rules>** element ``` -For another example of how to use the <extension> element, see the example for [<excludeAttributes>](#excludeattributes). +For another example of how to use the \ element, see the example for [\](#excludeattributes). -## <externalProcess> +## \ -You can use the <externalProcess> element to run a command line during the migration process. For example, you might want to run a command after the **LoadState** process completes. +You can use the \ element to run a command line during the migration process. For example, you might want to run a command after the **LoadState** process completes. - **Number of occurrences:** Unlimited -- **Parent elements:** [<rules>](#rules) +- **Parent elements:** [\](#rules) -- **Required child elements:** [<commandLine>](#commandline) +- **Required child elements:** [\](#commandline) Syntax: @@ -1160,23 +1160,23 @@ Syntax: |--- |--- |--- | | 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 <externalProcess> element, see the example for [<excludeAttributes>](#excludeattributes). +For an example of how to use the \ element, see the example for [\](#excludeattributes). -## <icon> +## \ This element is an internal USMT element. Don't use this element. -## <include> +## \ -The **<include>** element determines what to migrate, unless there's a more specific [<exclude>](#exclude) rule. You can specify a script to be more specific to extend the definition of what you want to collect. For each **<include>** element, there can be multiple **<objectSet>** elements. +The **\** element determines what to migrate, unless there's a more specific [\](#exclude) rule. You can specify a script to be more specific to extend the definition of what you want to collect. For each **\** element, there can be multiple **\** elements. - **Number of occurrences:** Unlimited -- **Parent elements:** [<rules>](#rules) +- **Parent elements:** [\](#rules) -- **Required child element:** [<objectSet>](#objectset) +- **Required child element:** [\](#objectset) -- **Helper functions:** You can use the following [<include> filter functions](#include-and-exclude-filter-functions) with this element: `CompareStringContent`, `IgnoreIrrelevantLinks`, `AnswerNo`, and `NeverRestore`. +- **Helper functions:** You can use the following [\ filter functions](#include-and-exclude-filter-functions) with this element: `CompareStringContent`, `IgnoreIrrelevantLinks`, `AnswerNo`, and `NeverRestore`. Syntax: @@ -1187,7 +1187,7 @@ Syntax: |Setting|Required?|Value| |--- |--- |--- | -| filter | No.
If this parameter isn't specified, then all patterns that are inside the child **<objectSet>** 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 **<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. | +| 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: @@ -1219,7 +1219,7 @@ The following example is from the MigUser.xml file:
``` -### <include> and **<exclude>** filter functions +### \ and **\** filter functions The following functions return a Boolean value. You can use them to migrate certain objects based on when certain conditions are met. @@ -1270,15 +1270,15 @@ The following functions return a Boolean value. You can use them to migrate cert ``` -## <includeAttributes> +## \ -You can use the **<includeAttributes>** element to determine whether certain parameters associated with an object are migrated along with the object itself. If there are conflicts between the **<includeAttributes>** and **<excludeAttributes>** elements, the most specific pattern determines which parameters are migrated. If an object doesn't have an **<includeAttributes>** or **<excludeAttributes>** element, then all of its parameters are migrated. +You can use the **\** element 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>](#rules) +- **Parent elements:** [\](#rules) -- **Child elements:** [<objectSet>](#objectset) +- **Child elements:** [\](#objectset) Syntax: @@ -1291,21 +1291,21 @@ Syntax: |--- |--- |--- | | attributes | Yes | Specifies the attributes to be included with a migrated object. You can specify one of the following, or both 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 **<includeAttributes>** element, see the example for [<excludeAttributes>](#excludeattributes). +For an example of how to use the **\** element, see the example for [\](#excludeattributes). -## <library> +## \ This element is an internal USMT element. Don't use this element. -## <location> +## \ -The **<location>** element defines the location of the **<object>** element. +The **\** element defines the location of the **\** element. -- **Number of occurrences:** once for each **<object>** +- **Number of occurrences:** once for each **\** -- **Parent elements:** [<object>](#object) +- **Parent elements:** [\](#object) -- **Child elements:** [<script>](#script) +- **Child elements:** [\](#script) Syntax: @@ -1335,17 +1335,17 @@ The following example is from the `MigApp.xml` file: ``` -## <locationModify> +## \ -You can use the **<locationModify>** element to change the location and name of an object before the object is migrated to the destination computer. The **<locationModify>** 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 **<locationModify>** element creates the appropriate folder on the destination computer if it doesn't already exist. +You can use the **\** element 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>](#rules) +- **Parent elements:** [\](#rules) -- **Required child element:** [<objectSet>](#objectset) +- **Required child element:** [\](#objectset) -- **Helper functions:** You can use the following [<locationModify> functions](#locationmodify-functions) with this element: `ExactMove`, `RelativeMove`, and `Move`. +- **Helper functions:** You can use the following [\ functions](#locationmodify-functions) with this element: `ExactMove`, `RelativeMove`, and `Move`. Syntax: @@ -1368,13 +1368,13 @@ The following example is from the `MigApp.xml` file: ``` -### <locationModify> functions +### \ functions -The following functions change the location of objects as they're migrated when using the **<locationModify>** element. These functions are called for every object that the parent **<objectSet>** element is enumerating. The **<locationModify>** element creates the appropriate folder on the destination computer if it doesn't already exist. +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 **<objectSet>** element into the given *ObjectEncodedLocation*. You can use this function when you want 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. + The ExactMove function moves all of the objects that are matched by the parent **\** element into the given *ObjectEncodedLocation*. You can use this function when you want 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)` @@ -1410,7 +1410,7 @@ The following functions change the location of objects as they're migrated when |Setting|Required?|Value| |--- |--- |--- | - |*SourceRoot*|Yes|The location where the objects are moved from. Any source objects that are enumerated by the parent **<objectSet>** element that aren't in this location aren't moved.| + |*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: @@ -1428,17 +1428,17 @@ For example: ``` -## <\_locDefinition> +## \<\_locDefinition\> This element is an internal USMT element. Don't use this element. -## <manufacturer> +## \ -The **<manufacturer>** element defines the manufacturer for the component, but doesn't affect the migration. +The **\** element defines the manufacturer for the component, but doesn't affect the migration. - **Number of occurrences:** zero or one -- **Parent elements:** [<component>](#component) +- **Parent elements:** [\](#component) - **Child elements:** none @@ -1452,19 +1452,19 @@ Syntax: |--- |--- |--- | |*Name*|Yes|The name of the manufacturer for the component.| -## <merge> +## \ -The **<merge>** 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 you don't specify this element, 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 your objects to migrate, you must specify **<include>** rules along with the **<merge>** 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 you have a **<merge>** rule `C:\* [*]` set to **<sourcePriority>** and a **<merge>** rule `C:\subfolder\* [*]` set to **<destinationPriority>**, then USMT would use the **<destinationPriority>** rule because it's the more specific. +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 you don't specify this element, 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 your objects to migrate, you must specify **\** rules 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 you have a **\** rule `C:\* [*]` set to **\** and a **\** rule `C:\subfolder\* [*]` 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>](#rules) +- **Parent elements:** [\](#rules) -- **Required child element:** [<objectSet>](#objectset) +- **Required child element:** [\](#objectset) -- **Helper functions:** You can use the following [<merge> functions](#merge-functions) with this element: `SourcePriority`, `DestinationPriority`, `FindFilePlaceByPattern`, `LeafPattern`, `NewestVersion`, `HigherValue()`, and `LowerValue()`. +- **Helper functions:** You can use the following [\ functions](#merge-functions) with this element: `SourcePriority`, `DestinationPriority`, `FindFilePlaceByPattern`, `LeafPattern`, `NewestVersion`, `HigherValue()`, and `LowerValue()`. Syntax: @@ -1475,7 +1475,7 @@ Syntax: |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.| +|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: @@ -1494,7 +1494,7 @@ The following example is from the MigUser.xml file: ``` -### <merge> functions +### \ functions These functions control how collisions are resolved. @@ -1516,13 +1516,13 @@ These functions control how collisions are resolved. - **FindFilePlaceByPattern** - The FindFilePlaceByPattern function saves files with an incrementing counter when a collision occurs. It's a string that contains one of each construct: **<F>**, **<E>**, **<N>** in any order. + 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 |
  • **<F>** is replaced by the original file name.
  • **<N>** is replaced by an incrementing counter until there's no collision with the objects on the destination computer.
  • **<E>** is replaced by the original file name extension.

For example, ` ().` changes the source file `MyDocument.doc` into `MyDocument (1).doc` on the destination computer. | + | *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** @@ -1558,17 +1558,17 @@ These functions control how collisions are resolved. ``` -## <migration> +## \ -The **<migration>** 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 you specify on the command line must be unique. The urlids must be unique because USMT uses the urlid to define the components within the file. +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 you specify 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>](#component) +- **Required child elements:** [\](#component) -- **Optional child elements:** [<library>](#library), [<namedElements>](#namedelements) +- **Optional child elements:** [\](#library), [\](#namedelements) Syntax: @@ -1615,9 +1615,9 @@ This filter helper function can be used to filter the migration of files based o ``` -## <namedElements> +## \ -You can use the **<namedElements>** element to define named elements. You can use these elements in any component throughout your .xml file. For an example of how to use this element, see the `MigApp.xml` file. +You can use the **\** element to define named elements. You can use these elements in any component throughout your .xml file. For an example of how to use this element, see the `MigApp.xml` file. Syntax: @@ -1628,23 +1628,23 @@ Syntax: - **Number of occurrences:** Unlimited -- **Parent elements:** [<migration>](#migration) +- **Parent elements:** [\](#migration) -- **Child elements:** [<environment>](#environment), [<rules>](#rules), [<conditions>](#conditions), [<detection>](#detection), [<detects>](#detects), [<detect>](#detect) +- **Child elements:** [\](#environment), [\](#rules), [\](#conditions), [\](#detection), [\](#detects), [\](#detect) For an example of this element, see the `MigApp.xml` file. -## <object> +## \ -The **<object>** element represents a file or registry key. +The **\** element represents a file or registry key. - **Number of occurrences:** Unlimited -- **Parent elements:** [<addObjects>](#addobjects) +- **Parent elements:** [\](#addobjects) -- **Required child elements:** [<location>](#location), [<attributes>](#attributes) +- **Required child elements:** [\](#location), [\](#attributes) -- **Optional child elements:** [<bytes>](#bytes) +- **Optional child elements:** [\](#bytes) Syntax: @@ -1670,17 +1670,17 @@ The following example is from the `MigApp.xml` file: ``` -## <objectSet> +## \ -The **<objectSet>** element contains a list of object patterns; for example, file paths, registry locations, and so on. Any child **<conditions>** elements are evaluated first. If all child **<conditions>** elements return **FALSE**, the **<objectSet>** element evaluates to an empty set. For each parent element, there can be only multiple **<objectSet>** elements. +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>](#variable), [<content>](#content), [<include>](#include), [<exclude>](#exclude), [<merge>](#merge), [<contentModify>](#contentmodify), [<locationModify>](#locationmodify), [<destinationCleanup>](#destinationcleanup), [<includeAttributes>](#includeattributes), [<excludeAttributes>](#excludeattributes), [<unconditionalExclude>](#unconditionalexclude), [<detect>](#detect) +- **Parent elements:** [\](#variable), [\](#content), [\](#include), [\](#exclude), [\](#merge), [\](#contentmodify), [\](#locationmodify), [\](#destinationcleanup), [\](#includeattributes), [\](#excludeattributes), [\](#unconditionalexclude), [\](#detect) -- **Required child elements:** either [<script>](#script) or [<pattern>](#pattern) +- **Required child elements:** either [\](#script) or [\](#pattern) -- **Optional child elements:** [<content>](#content), [<conditions>](#conditions), [<condition>](#condition) +- **Optional child elements:** [\](#content), [\](#conditions), [\](#condition) Syntax: @@ -1719,17 +1719,17 @@ The following example is from the MigUser.xml file: ``` -## <path> +## \ This element is an internal USMT element. Don't use this element. -## <paths> +## \ This element is an internal USMT element. Don't use this element. -## <pattern> +## \ -You can use this element to specify multiple objects. You can specify multiple **<pattern>** elements for each **<objectSet>** element and they're combined. If you're specifying files, you might want to use `GenerateDrivePatterns` with **<script>** instead. `GenerateDrivePatterns` is basically the same as a **<pattern>** rule, without the drive letter specification. For example, the following two lines of code are similar: +You can use this element to specify multiple objects. You can specify multiple **\** elements for each **\** element and they're combined. If you're specifying files, you might want to use `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] @@ -1738,7 +1738,7 @@ You can use this element to specify multiple objects. You can specify multiple * - **Number of occurrences:** Unlimited -- **Parent elements:** [<objectSet>](#objectset) +- **Parent elements:** [\](#objectset) - **Child elements:** none but *Path* \[*object*\] must be valid. @@ -1750,7 +1750,7 @@ Syntax: |Setting|Required?|Value| |--- |--- |--- | -| type | Yes | *typeID* can be Registry, File, or Ini. If *typeId* is Ini, then you can't have a space between *Path* and *object*. For example, the following format is correct when type="Ini":
**<pattern type="Ini">%WinAmp5InstPath%\Winamp.ini|WinAmp[keeponscreen]</pattern>** | +| type | Yes | *typeID* can be Registry, File, or Ini. If *typeId* is Ini, then you can't have a space between *Path* and *object*. 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). You can't use the question mark as a wildcard character. You can use `HKCU` and `HKLM` to refer to `HKEY_CURRENT_USER` and `HKEY_LOCAL_MACHINE` respectively.
  • *Object* can contain the asterisk (`*`) wildcard character. However, you can't use the question mark 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", you must specify `c:\documents\mydocs [file^].txt]` instead of `c:\documents\mydocs [file].txt]`.
| For example: @@ -1785,15 +1785,15 @@ For example: - 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). -## <processing> +## \ You can use this element to run a script during a specific point within the migration process. Return values aren't expected from the scripts that you specify, and if there are return values, they're ignored. - **Number of occurrences:** unlimited -- **Parent elements:** [<rules>](#rules) +- **Parent elements:** [\](#rules) -- **Required child element:** [<script>](#script) +- **Required child element:** [\](#script) Syntax: @@ -1806,21 +1806,21 @@ Syntax: |--- |--- |--- | | 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.
| -## <plugin> +## \ This element is an internal USMT element. Don't use this element. -## <role> +## \ -The **<role>** element is required in a custom .xml file. By specifying the **<role>** element, you can create a concrete component. The component is defined by the parameters specified at the **<component>** level, and with the role that you specify here. +The **\** element is required in a custom .xml file. By specifying the **\** element, you can create a concrete component. The component is defined by the parameters specified at the **\** level, and with the role that you specify here. -- **Number of occurrences:** Each **<component>** can have one, two or three child **<role>** elements. +- **Number of occurrences:** Each **\** can have one, two or three child **\** elements. -- **Parent elements:** [<component>](#component), [<role>](#role) +- **Parent elements:** [\](#component), [\](#role) -- **Required child elements:** [<rules>](#rules) +- **Required child elements:** [\](#rules) -- **Optional child elements:** [<environment>](#environment), [<detection>](#detection), [<component>](#component), [<role>](#role), [<detects>](#detects), [<plugin>](#plugin) +- **Optional child elements:** [\](#environment), [\](#detection), [\](#component), [\](#role), [\](#detects), [\](#plugin) Syntax: @@ -1831,7 +1831,7 @@ Syntax: |Setting|Required?|Value| |--- |--- |--- | -| role | Yes | Defines the role for the component. Role can be one of:
  • **Container**
  • **Binaries**
  • **Settings**
  • **Data**
You can either:
  1. Specify up to three **<role>** elements within a **<component>** - 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 you categorize the settings that you're migrating. You can nest these **<role>** elements, but each nested element must be of the same role parameter.
  2. Specify one "Container" **<role>** element within a **<component>** element. In this case, you can't specify any child **<rules>** elements, only other **<component>** elements. And each child **<component>** element must have the same type as that of parent **<component>** element. For example:
<component context="UserAndSystem" type="Application"> 
<displayName _locID="migapp.msoffice2003">Microsoft Office 2003</displayName>
<environment name="GlobalEnv" />
<role role="Container">
<detection name="AnyOffice2003Version" />
<detection name="FrontPage2003" />
<!--
Office 2003 Common Settings
-->
<component context="UserAndSystem" type="Application">
| +| role | Yes | Defines the role for the component. Role can be one of:
  • **Container**
  • **Binaries**
  • **Settings**
  • **Data**
You can either:
  1. Specify 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 you categorize the settings that you're migrating. You can nest these **\** elements, but each nested element must be of the same role parameter.
  2. Specify one "Container" **\** element within a **\** element. In this case, you can't specify any child **\** elements, only other **\** elements. And each child **\** element must have the same type as that of parent **\** element. For example:
\ 
\Microsoft Office 2003\
\
\
\
\
\