deepblue/windows-itpro-docs
1
0
Fork 0
mirror of https://github.com/MicrosoftDocs/windows-itpro-docs.git synced 2025-06-15 10:23:37 +00:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity

USMT Refresh 9

Browse Source
This commit is contained in:
Frank Rojas
2023-12-29 17:54:31 -05:00
parent 72b2f91dce
commit e126b861dd
1 changed files with 20 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files

40
windows/deployment/usmt/usmt-xml-elements-library.md
View File

@ -28,7 +28,7 @@ The following table describes the XML elements and helper functions you can use
|-----|----|-----|
| [&lt;addObjects&gt;](#addobjects) <br/>[&lt;attributes&gt;](#attributes) <br/>[&lt;bytes&gt;](#bytes) <br/>[&lt;commandLine&gt;](#commandline) <br/>[&lt;component&gt;](#component) <br/>[&lt;condition&gt;](#condition) <br/>[&lt;conditions&gt;](#conditions) <br/>[&lt;content&gt;](#content) <br/>[&lt;contentModify&gt;](#contentmodify) <br/>[&lt;description&gt;](#description) <br/>[&lt;destinationCleanup&gt;](#destinationcleanup) <br/>[&lt;detect&gt;](#detect) <br/>[&lt;detects&gt;](#detects) <br/>[&lt;detection&gt;](#detection) <br/>[&lt;displayName&gt;](#displayname) <br/>[&lt;environment&gt;](#environment) <br/>[&lt;exclude&gt;](#exclude) <br/>[&lt;excludeAttributes&gt;](#excludeattributes) <br/>[&lt;extensions&gt;](#extensions) <br/>[&lt;extension&gt;](#extension) <br/>[&lt;externalProcess&gt;](#externalprocess) <br/>[&lt;icon&gt;](#icon) <br/>[&lt;include&gt;](#include) <br/>[&lt;includeAttribute&gt;](#includeattributes) | [&lt;library&gt;](#library) <br/>[&lt;location&gt;](#location) <br/>[&lt;locationModify&gt;](#locationmodify) <br/>[&lt;_locDefinition&gt;](#_locdefinition) <br/>[&lt;manufacturer&gt;](#manufacturer) <br/>[&lt;merge&gt;](#merge) <br/>[&lt;migration&gt;](#migration) <br/>[&lt;namedElements&gt;](#namedelements) <br/>[&lt;object&gt;](#object) <br/>[&lt;objectSet&gt;](#objectset) <br/>[&lt;path&gt;](#path) <br/>[&lt;paths&gt;](#paths) <br/>[&lt;pattern&gt;](#pattern) <br/>[&lt;processing&gt;](#processing) <br/>[&lt;plugin&gt;](#plugin) <br/>[&lt;role&gt;](#role) <br/>[&lt;rules&gt;](#rules) <br/>[&lt;script&gt;](#script) <br/>[&lt;text&gt;](#text) <br/>[&lt;unconditionalExclude&gt;](#unconditionalexclude) <br/>[&lt;variable&gt;](#variable) <br/>[&lt;version&gt;](#version) <br/>[&lt;windowsObjects&gt;](#windowsobjects) | [&lt;condition&gt; functions](#condition-functions) <br/>[&lt;content&gt; functions](#content-functions) <br/>[&lt;contentModify&gt; functions](#contentmodify-functions) <br/>[&lt;include&gt; and &lt;exclude&gt; filter functions](#include-and-exclude-filter-functions) <br/>[&lt;locationModify&gt; functions](#locationmodify-functions) <br/>[&lt;merge&gt; functions](#merge-functions) <br/>[&lt;script&gt; functions](#script-functions) <br/>[Internal USMT functions](#internal-usmt-functions) |
## &lt;addObjects&gt;
## \<addObjects\>
The **&lt;addObjects&gt;** element emulates the existence of one or more objects on the source computer. The child **&lt;object&gt;** elements provide the details of the emulated objects. If the content is a **&lt;script&gt;** element, the result of the invocation is an array of objects.
@ -173,9 +173,9 @@ hidden="Yes|No">
|Setting|Required?|Value|
|--- |--- |--- |
| type | Yes | You can use the following to group settings, and define the type of the component.<ul><li>**System:** Operating system settings. All Windows components are defined by this type. <br/>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=&quot;System&quot;** and **defaultSupported=&quot;FALSE&quot;**. 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.</li><li>**Application:** Settings for an application.</li><li>**Device:** Settings for a device.</li><li>**Documents:** Specifies files.</li></ul> |
| type | Yes | You can use the following to group settings, and define the type of the component.<ul><li>**System:** Operating system settings. All Windows components are defined by this type. <br/>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.</li><li>**Application:** Settings for an application.</li><li>**Device:** Settings for a device.</li><li>**Documents:** Specifies files.</li></ul> |
| context | No <br/>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. <br/>The largest possible scope is set by the **&lt;component&gt;** element. For example, if a **&lt;component&gt;** element has a context of **User** and a **&lt;rules&gt;** element had a context of **UserAndSystem**, then the **&lt;rules&gt;** element would act as though it has a context of **User**. If a **&lt;rules&gt;** element has a context of **System**, it would act as though the **&lt;rules&gt;** element isn't there. <ul><li>**User**: Evaluates the component for each user.</li><li>**System**: Evaluates the component only once for the system.</li><li>**UserAndSystem**: Evaluates the component for the entire operating system and each user.</li></ul> |
| defaultSupported | No <br/>(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. <br/>When **type=&quot;System&quot;** and **defaultSupported=&quot;FALSE&quot;**, 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=&quot;System&quot;** and **defaultSupported=&quot;FALSE&quot;**. 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. This is 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 is helpful because you can use the same store for destination computers that are the same version of Windows and a different version of Windows as the source computer. |
| defaultSupported | No <br/>(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. <br/>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.
@ -640,7 +640,7 @@ 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 **(&quot;FileAttrib:H&quot;, &quot;FileAttrib:R&quot;)** because only Read-only is evaluated. Instead specify **(&quot;FileAttrib:HR&quot;)** and both Hidden and Read-only attributes are kept on the destination computer. <ul><li>**Security**: Keeps the destination object's security descriptor if it exists.</li><li>**TimeFields**: Keeps the destination object's time stamps. This parameter is for files only.</li><li>**FileAttrib:&lt;Letter&gt;**: 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: <ul><li>**A** = Archive</li><li>**C** = Compressed</li><li>**E** = Encrypted</li><li>**H** = Hidden</li><li>**I** = Not Content Indexed</li><li>**O** = Offline</li><li>**R** = Read-Only</li><li>**S** = System</li><li>**T** = Temporary</li></ul></li></ul> |
| *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. <ul><li>**Security**: Keeps the destination object's security descriptor if it exists.</li><li>**TimeFields**: Keeps the destination object's time stamps. This parameter is for files only.</li><li>**FileAttrib:&lt;Letter&gt;**: 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: <ul><li>**A** = Archive</li><li>**C** = Compressed</li><li>**E** = Encrypted</li><li>**H** = Hidden</li><li>**I** = Not Content Indexed</li><li>**O** = Offline</li><li>**R** = Read-Only</li><li>**S** = System</li><li>**T** = Temporary</li></ul></li></ul> |
- **MergeMultiSzContent**
@ -1187,7 +1187,7 @@ Syntax:
|Setting|Required?|Value|
|--- |--- |--- |
| filter | No. <br/>If this parameter isn't specified, then all patterns that are inside the child **&lt;objectSet&gt;** 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 (&quot;Arg1&quot;,&quot;Arg2&quot;)`. <br/>The script is called for each object that is enumerated by the object sets in the **&lt;include&gt;** 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. <br/>If this parameter isn't specified, then all patterns that are inside the child **&lt;objectSet&gt;** 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")`. <br/>The script is called for each object that is enumerated by the object sets in the **&lt;include&gt;** 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:
@ -1256,7 +1256,7 @@ The following functions return a Boolean value. You can use them to migrate cert
- **NeverRestore**
You can use this function 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**. You might want to use this function when you want to check an object's value on the destination computer but don't intend to migrate the object to the destination.
You can use this function 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()`
@ -1410,7 +1410,7 @@ The following functions change the location of objects as they're migrated when
|Setting|Required?|Value|
|--- |--- |--- |
|*SourceRoot*|Yes|The location from where the objects are moved. Any source objects that are enumerated by the parent **&lt;objectSet&gt;** 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 **&lt;objectSet&gt;** 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:
@ -1454,7 +1454,7 @@ Syntax:
## &lt;merge&gt;
The **&lt;merge&gt;** 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 **&lt;include&gt;** rules along with the **&lt;merge&gt;** element. When an object is processed and a collision is detected, USMT selects the most specific merge rule and apply it to resolve the conflict. For example, if you have a **&lt;merge&gt;** rule `C:\* [*]` set to **&lt;sourcePriority&gt;** and a **&lt;merge&gt;** rule `C:\subfolder\* [*]` set to **&lt;destinationPriority&gt;**, then USMT would use the **&lt;destinationPriority&gt;** rule because it's the more specific.
The **&lt;merge&gt;** 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 **&lt;include&gt;** rules along with the **&lt;merge&gt;** 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 **&lt;merge&gt;** rule `C:\* [*]` set to **&lt;sourcePriority&gt;** and a **&lt;merge&gt;** rule `C:\subfolder\* [*]` set to **&lt;destinationPriority&gt;**, then USMT would use the **&lt;destinationPriority&gt;** rule because it's the more specific.
For an example of this element, see [Conflicts and precedence](usmt-conflicts-and-precedence.md).
@ -1536,11 +1536,11 @@ These functions control how collisions are resolved.
- **HigherValue()**
You can use this function for merging registry values. The registry values are evaluated as numeric values, and the one with the higher value determines which registry values is merged.
You can use this function 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()**
You can use this function for merging registry values. The registry values are evaluated as numeric values and the one with the lower value determines which registry values is merged.
You can use this function 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**
@ -1560,7 +1560,7 @@ These functions control how collisions are resolved.
## &lt;migration&gt;
The **&lt;migration&gt;** 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. For example, you must specify the following at the beginning of each file: &lt;CustomFileName&gt; is the name of the file; for example, "CustomApp".
The **&lt;migration&gt;** 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
@ -1750,8 +1750,8 @@ 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=&quot;Ini&quot;: <br/>**&lt;pattern type=&quot;Ini&quot;&gt;%WinAmp5InstPath%\Winamp.ini&#124;WinAmp[keeponscreen]&lt;/pattern&gt;** |
| *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. <ul><li>*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.</li><li>*Object* can contain the asterisk (`*`) wildcard character. However, you can't use the question mark as a wildcard character. For example: <br/> **`C:\Folder\ [*]`** enumerates all files in `C:\Folder` but no subfolders of `C:\Folder`. <br/> **`C:\Folder* [*]`** enumerates all files and subfolders of `C:\Folder`. <br/> **`C:\Folder\ [*.mp3]`** enumerates all `.mp3` files in `C:\Folder`. <br/> **`C:\Folder\ [Sample.doc]`** enumerates only the `Sample.doc` file located in C:\Folder. <div class="alert">**Note**<br/>If you're migrating a file that has a square bracket character ([ or ]) in the file name, you must insert the carrot (^) character directly before the bracket for it to be valid. For example, if there's a file named &quot;file].txt&quot;, you must specify `<pattern type="File">c:\documents\mydocs [file^].txt]</pattern>` instead of `<pattern type="File">c:\documents\mydocs [file].txt]</pattern>`.</div></li></ul> |
| 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": <br/>**&lt;pattern type="Ini"&gt;%WinAmp5InstPath%\Winamp.ini&#124;WinAmp[keeponscreen]&lt;/pattern&gt;** |
| *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. <ul><li>*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.</li><li>*Object* can contain the asterisk (`*`) wildcard character. However, you can't use the question mark as a wildcard character. For example: <br/> **`C:\Folder\ [*]`** enumerates all files in `C:\Folder` but no subfolders of `C:\Folder`. <br/> **`C:\Folder* [*]`** enumerates all files and subfolders of `C:\Folder`. <br/> **`C:\Folder\ [*.mp3]`** enumerates all `.mp3` files in `C:\Folder`. <br/> **`C:\Folder\ [Sample.doc]`** enumerates only the `Sample.doc` file located in C:\Folder. <div class="alert">**Note**<br/>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 `<pattern type="File">c:\documents\mydocs [file^].txt]</pattern>` instead of `<pattern type="File">c:\documents\mydocs [file].txt]</pattern>`.</div></li></ul> |
For example:
@ -1831,7 +1831,7 @@ Syntax:
|Setting|Required?|Value|
|--- |--- |--- |
| role | Yes | Defines the role for the component. Role can be one of: <ul><li>**Container**</li><li>**Binaries**</li><li>**Settings**</li><li>**Data**</li></ul> You can either: <ol><li>Specify up to three **&lt;role&gt;** elements within a **&lt;component&gt;** - 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 **&lt;role&gt;** elements, but each nested element must be of the same role parameter.</li><li>Specify one "Container" **&lt;role&gt;** element within a **&lt;component&gt;** element. In this case, you can't specify any child **&lt;rules&gt;** elements, only other **&lt;component&gt;** elements. And each child **&lt;component&gt;** element must have the same type as that of parent **&lt;component&gt;** element. For example:</li></ol> <pre class="syntax"><code>&lt;component context=&quot;UserAndSystem&quot; type=&quot;Application&quot;&gt; <br/> &lt;displayName _locID=&quot;migapp.msoffice2003&quot;&gt;Microsoft Office 2003&lt;/displayName&gt; <br/> &lt;environment name=&quot;GlobalEnv&quot; /&gt; <br/> &lt;role role=&quot;Container&quot;&gt;<br/> &lt;detection name=&quot;AnyOffice2003Version&quot; /&gt; <br/> &lt;detection name=&quot;FrontPage2003&quot; /&gt; <br/> &lt;!-- <br/> Office 2003 Common Settings <br/> --&gt; <br/> &lt;component context=&quot;UserAndSystem&quot; type=&quot;Application&quot;&gt;</code></pre> |
| role | Yes | Defines the role for the component. Role can be one of: <ul><li>**Container**</li><li>**Binaries**</li><li>**Settings**</li><li>**Data**</li></ul> You can either: <ol><li>Specify up to three **&lt;role&gt;** elements within a **&lt;component&gt;** - 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 **&lt;role&gt;** elements, but each nested element must be of the same role parameter.</li><li>Specify one "Container" **&lt;role&gt;** element within a **&lt;component&gt;** element. In this case, you can't specify any child **&lt;rules&gt;** elements, only other **&lt;component&gt;** elements. And each child **&lt;component&gt;** element must have the same type as that of parent **&lt;component&gt;** element. For example:</li></ol> <pre class="syntax"><code>&lt;component context="UserAndSystem" type="Application"&gt; <br/> &lt;displayName _locID="migapp.msoffice2003"&gt;Microsoft Office 2003&lt;/displayName&gt; <br/> &lt;environment name="GlobalEnv" /&gt; <br/> &lt;role role="Container"&gt;<br/> &lt;detection name="AnyOffice2003Version" /&gt; <br/> &lt;detection name="FrontPage2003" /&gt; <br/> &lt;!-- <br/> Office 2003 Common Settings <br/> --&gt; <br/> &lt;component context="UserAndSystem" type="Application"&gt;</code></pre> |
The following example is from the MigUser.xml file. For more examples, see the `MigApp.xml` file:
@ -1958,7 +1958,7 @@ The return value that is required by **&lt;script&gt;** depends on the parent el
|Setting|Required?|Value|
|--- |--- |--- |
| *ScriptWithArguments* | Yes | A script followed by any number of string arguments that are separated by a comma and enclosed in parenthesis. For example, `MyScripts.AScript (&quot;Arg1&quot;,&quot;Arg2&quot;)`. <br/>The script is called for each object that is enumerated by the object sets in the **&lt;include&gt;** 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. <br/>The return value that is required by **&lt;script&gt;** depends on the parent element. <ul><li>When used within **&lt;variable&gt;**, the return value must be a string.</li><li>When used within **&lt;objectSet&gt;**, the return value must be a two-dimensional array of strings.</li><li>When used within **&lt;location&gt;**, the return value must be a valid location that aligns with the type attribute of **&lt;location&gt;**. For example, if &lt;location type=&quot;File&quot;&gt;, the child script element, if specified, must be a valid file location. <div class="alert">**Note**<br/>If you're migrating a file that has a bracket character ([ or ]) in the file name, insert the carrot (^) character directly before the bracket for it to be valid. For example, if there's a file named &quot;file].txt&quot;, specify `<pattern type="File">c:\documents\mydocs [file^].txt]</pattern>` instead of `<pattern type="File">c:\documents\mydocs [file].txt]</pattern>`.</div></li></ul> |
| *ScriptWithArguments* | 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")`. <br/>The script is called for each object that is enumerated by the object sets in the **&lt;include&gt;** 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. <br/>The return value that is required by **&lt;script&gt;** depends on the parent element. <ul><li>When used within **&lt;variable&gt;**, the return value must be a string.</li><li>When used within **&lt;objectSet&gt;**, the return value must be a two-dimensional array of strings.</li><li>When used within **&lt;location&gt;**, the return value must be a valid location that aligns with the type attribute of **&lt;location&gt;**. For example, if &lt;location type="File"&gt;, the child script element, if specified, must be a valid file location. <div class="alert">**Note**<br/>If you're migrating a file that has a bracket character ([ or ]) in the file name, insert the carrot (^) character directly before the bracket for it to be valid. For example, if there's a file named "file].txt", specify `<pattern type="File">c:\documents\mydocs [file^].txt]</pattern>` instead of `<pattern type="File">c:\documents\mydocs [file].txt]</pattern>`.</div></li></ul> |
Examples:
@ -2004,13 +2004,13 @@ These functions return either a string or a pattern.
- **GenerateDrivePatterns**
The `GenerateDrivePatterns` function iterates all of the available drives and select the ones that match the requested drive type. It then concatenates the selected drives with the end part of *PatternSegment* to form a full encoded file pattern. For example, if *PatternSegment* is `Path [file.txt]` and *DriveType* is `Fixed`, then the function generates `C:\Path [file.txt]`, and other patterns if there are fixed drives other than C:. You can't specify environment variables with this function. You can use `GenerateDrivePatterns` with **&lt;script&gt;** elements that are within [&lt;objectSet&gt;](#objectset) that are within **&lt;include&gt;**/**&lt;exclude&gt;**.
The `GenerateDrivePatterns` function iterates all of the available drives and selects the ones that match the requested drive type. It then concatenates the selected drives with the end part of *PatternSegment* to form a full encoded file pattern. For example, if *PatternSegment* is `Path [file.txt]` and *DriveType* is `Fixed`, then the function generates `C:\Path [file.txt]`, and other patterns if there are fixed drives other than C:. You can't specify environment variables with this function. You can use `GenerateDrivePatterns` with **&lt;script&gt;** elements that are within [&lt;objectSet&gt;](#objectset) that are within **&lt;include&gt;**/**&lt;exclude&gt;**.
Syntax: `GenerateDrivePatterns("PatternSegment","DriveType")`
|Setting|Required?|Value|
|--- |--- |--- |
| *PatternSegment* | Yes | The suffix of an encoded pattern. It is concatenated with a drive specification, such as &quot;c:&quot;, to form a complete [encoded file pattern](#specifying-locations). For example, &quot;* [*.doc]&quot;. *PatternSegment* can't be an environment variable. |
| *PatternSegment* | Yes | The suffix of an encoded pattern. It's concatenated with a drive specification, such as "c:", to form a complete [encoded file pattern](#specifying-locations). For example, "* [*.doc]". *PatternSegment* can't be an environment variable. |
| *DriveType* | Yes | The drive type for which the patterns are to be generated. You can specify one of: <ul><li>Fixed</li><li>CDROM</li><li>Removable</li><li>Remote</li></ul> |
See the last component in the MigUser.xml file for an example of this element.
@ -2037,7 +2037,7 @@ These functions return either a string or a pattern.
If `GenerateUserPattens('File','%userprofile% [*.doc]','FALSE')` is called while USMT is processing user A, then this function only generates patterns for users B and C. You can use this helper function to build complex rules. For example, to migrate all `.doc` files from the source computer - but if user X isn't migrated, then don't migrate any of the `.doc` files from user X's profile.
The following example is example code for this scenario. The first **&lt;rules&gt;** element migrates all `.doc` files on the source computer except for those inside `C:\Documents and Settings`. The second **&lt;rules&gt;** elements migrate all `.doc` files from `C:\Documents and Settings` except for the `.doc` files in the profiles of the other users. Because the second **&lt;rules&gt;** element are processed in each migrated user context, the end result is the desired behavior. The end result is the one we expected.
The following example is example code for this scenario. The first **&lt;rules&gt;** element migrates all `.doc` files on the source computer except for those inside `C:\Documents and Settings`. The second **&lt;rules&gt;** elements migrate all `.doc` files from `C:\Documents and Settings` except for the `.doc` files in the profiles of the other users. Because the second **&lt;rules&gt;** element is processed in each migrated user context, the end result is the desired behavior. The end result is the one we expected.
```xml
<rules context="System">
@ -2141,7 +2141,7 @@ The following scripts have no return value. You can use the following errors wit
- **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 it's changed by the migration engine, and then synchronizes Service Control Manager (SCM) with the new value.
- **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.
## &lt;text&gt;
@ -2283,7 +2283,7 @@ The **&lt;windowsObjects&gt;** element is for USMT internal use only. Don't use
### 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. It's composed of the node part, optionally followed by the leaf enclosed in square brackets. This makes a clear distinction between nodes and leaves.
- **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.)