From 992168a38121f6217b2b2bb223f355f1ba564616 Mon Sep 17 00:00:00 2001 From: Frank Rojas <45807133+frankroj@users.noreply.github.com> Date: Fri, 29 Dec 2023 14:37:56 -0500 Subject: [PATCH] USMT Refresh 7 --- .../usmt/usmt-determine-what-to-migrate.md | 12 +- .../usmt-identify-application-settings.md | 10 +- .../usmt/usmt-plan-your-migration.md | 18 +- .../usmt/usmt-test-your-migration.md | 2 +- .../deployment/usmt/usmt-troubleshooting.md | 19 +- windows/deployment/usmt/usmt-utilities.md | 31 +- .../usmt/usmt-what-does-usmt-migrate.md | 184 ++++------ .../usmt/usmt-xml-elements-library.md | 320 +++++++++--------- 8 files changed, 276 insertions(+), 320 deletions(-) diff --git a/windows/deployment/usmt/usmt-determine-what-to-migrate.md b/windows/deployment/usmt/usmt-determine-what-to-migrate.md index 7cc02c3d50..e69c418536 100644 --- a/windows/deployment/usmt/usmt-determine-what-to-migrate.md +++ b/windows/deployment/usmt/usmt-determine-what-to-migrate.md @@ -5,23 +5,23 @@ manager: aaroncz ms.author: frankroj ms.prod: windows-client author: frankroj -ms.date: 12/19/2023 +ms.date: 12/28/2023 ms.topic: article ms.technology: itpro-deploy --- # Determine what to migrate -By default, User State Migration Tool (USMT) migrates the items listed in [What does USMT migrate?](usmt-what-does-usmt-migrate.md), depending on the migration .xml files you specify. These default settings are often enough for a basic migration. +By default, User State Migration Tool (USMT) migrates the items listed in [What does USMT migrate?](usmt-what-does-usmt-migrate.md), depending on the migration **.xml** files that are specified. These default settings are often enough for a basic migration. -However, when considering what settings to migrate, you should also consider: +However, when considering what settings to migrate, also consider: - What settings the user can configure, if any. - What settings should be standardized. -Many organizations use their migration as an opportunity to create and begin enforcing a better-managed environment. Some of the settings that users can configure on unmanaged computers prior to the migration can be locked on the new, managed computers. For example, standard wallpaper, Internet Explorer security settings, and desktop configuration are some of the items you can choose to standardize. +Many organizations use their migration as an opportunity to create and begin enforcing a better-managed environment. Some of the settings that users can configure on unmanaged computers prior to the migration can be locked on the new, managed computers. For example, standard wallpaper and desktop configuration are some of the items that can be standardized. -To reduce complexity and increase standardization, your organization should consider creating a *standard operating environment (SOE)*. An SOE is a combination of hardware and software that you distribute to all users. Creating an SOE means selecting: +To reduce complexity and increase standardization, the organization should consider creating a *standard operating environment (SOE)*. An SOE is a combination of hardware and software that is distributed to all users. Creating an SOE means selecting: - A baseline for all computers, including standard hardware drivers. - Core operating system features. @@ -36,7 +36,7 @@ Using an SOE can vastly simplify the migration and reduce overall deployment cha | Link | Description | |--- |--- | |[Identify users](usmt-identify-users.md)|Use command-line options to specify which users to migrate and how they should be migrated.| -|[Identify applications settings](usmt-identify-application-settings.md)|Determine which applications you want to migrate and prepare a list of application settings to be migrated.| +|[Identify applications settings](usmt-identify-application-settings.md)|Determine which applications need to be migrated and prepare a list of application settings to be migrated.| |[Identify operating system settings](usmt-identify-operating-system-settings.md)|Use migration to create a new standard environment on each of the destination computers.| |[Identify file types, files, and folders](usmt-identify-file-types-files-and-folders.md)|For the following items that need to be migrated:
determine where these items might be located. For example:| diff --git a/windows/deployment/usmt/usmt-identify-application-settings.md b/windows/deployment/usmt/usmt-identify-application-settings.md index adf5cfd43e..bb30074a81 100644 --- a/windows/deployment/usmt/usmt-identify-application-settings.md +++ b/windows/deployment/usmt/usmt-identify-application-settings.md @@ -1,18 +1,18 @@ --- title: Identify Applications Settings -description: Identify which applications and settings you want to migrate before using the User State Migration Tool (USMT). +description: Identify which applications and settings need to be migrated before using the User State Migration Tool (USMT). manager: aaroncz ms.author: frankroj ms.prod: windows-client author: frankroj -ms.date: 12/21/2023 +ms.date: 12/28/2023 ms.topic: article ms.technology: itpro-deploy --- # Identify applications settings -When planning for your migration, you should identify which applications and settings you want to migrate. For more information about how to create a custom **.xml** file to migrate the settings of another application, see [Customize USMT XML files](usmt-customize-xml-files.md). +Which applications and settings need to be migrated should be identified when planning a migration. For more information about how to create a custom **.xml** file to migrate the settings of another application, see [Customize USMT XML files](usmt-customize-xml-files.md). ## Applications @@ -22,7 +22,7 @@ Next, identify an application owner to be in charge of each application. Applica ## Application settings -Next, determine and locate the application settings to be migrated. You can acquire much of the information that you need for this step when you're testing the new applications for compatibility with the new operating system. +Next, determine and locate the application settings to be migrated. Much of the information that is needed for this step can be acquired when testing the new applications for compatibility with the new operating system. After completing the list of applications to be migrated, review the list, and work with each application owner on a list of settings to be migrated. For each setting, determine whether it needs to be migrated or if the default settings are adequate. Then, determine where the setting is located, for example, in the registry or in an .ini file. Next, consider the following questions to determine what needs to be done to migrate the setting successfully: @@ -32,7 +32,7 @@ After completing the list of applications to be migrated, review the list, and w - Do the settings need to be moved or altered? -- Can the first-run process force the application to appear as if it had run already? If so, does this work correctly, or does it break the application? +- Can the first-run process force the application to appear as if it ran already? If so, does this work correctly, or does it break the application? After answering these questions, create a custom **.xml** file to migrate settings. Work with the application owner to develop test cases and to determine the file types that need to be migrated for the application. diff --git a/windows/deployment/usmt/usmt-plan-your-migration.md b/windows/deployment/usmt/usmt-plan-your-migration.md index c82edcb9dc..c84be6b27b 100644 --- a/windows/deployment/usmt/usmt-plan-your-migration.md +++ b/windows/deployment/usmt/usmt-plan-your-migration.md @@ -1,22 +1,22 @@ --- -title: Plan Your Migration -description: Learn how to your plan your migration carefully so your migration can proceed smoothly and so that you reduce the risk of migration failure. +title: Plan The Migration +description: Learn how to plan the migration carefully so the migration can proceed smoothly and so that the risk of migration failure is reduced. manager: aaroncz ms.author: frankroj ms.prod: windows-client author: frankroj -ms.date: 12/22/2023 +ms.date: 12/28/2023 ms.topic: article ms.technology: itpro-deploy --- -# Plan your migration +# Plan the migration -Before you use the User State Migration Tool (USMT) to perform your migration, we recommend that you plan your migration carefully. Planning can help your migration proceed smoothly and can reduce the risk of migration failure. +Before using the User State Migration Tool (USMT) to perform a migration, Microsoft recommends that to plan the migration carefully. Planning can help the migration proceed smoothly and can reduce the risk of migration failure. -In migration planning, both organizations and individuals must first identify what to migrate, including user settings, applications and application settings, and personal data files and folders. Identifying the applications to migrate is especially important so that you can avoid capturing data about applications that might be phased out. +In migration planning, both organizations and individuals must first identify what to migrate, including user settings, applications and application settings, and personal data files and folders. Identifying the applications to migrate is especially important to avoid capturing data about applications that might be phased out. -One of the most important requirements for migrating settings and data is restoring only the information that the destination computer requires. Although the data that you capture on the source computer might be more comprehensive than the restoration data for backup purposes, restoring data or settings for applications that aren't installed on the destination system is redundant. Restoring data or settings for applications that aren't installed can also introduce instability in a newly deployed computer. +One of the most important requirements for migrating settings and data is restoring only the information that the destination computer requires. Although the data that is captured on the source computer might be more comprehensive than the restoration data for backup purposes, restoring data or settings for applications that aren't installed on the destination system is redundant. Restoring data or settings for applications that aren't installed can also introduce instability in a newly deployed computer. ## In this section @@ -25,8 +25,8 @@ One of the most important requirements for migrating settings and data is restor |[Common migration scenarios](usmt-common-migration-scenarios.md)|Determine whether to perform a refresh migration or a replace migration.| |[What does USMT migrate?](usmt-what-does-usmt-migrate.md)|Learn which applications, user data, and operating system components USMT migrates.| |[Choose a migration store type](usmt-choose-migration-store-type.md)|Choose an uncompressed, compressed, or hard-link migration store.| -|[Determine what to migrate](usmt-determine-what-to-migrate.md)|Identify user accounts, application settings, operating system settings, and files that you want to migrate inside your organization.| -|[Test your migration](usmt-test-your-migration.md)|Test your migration before you deploy Windows to all users.| +|[Determine what to migrate](usmt-determine-what-to-migrate.md)|Identify user accounts, application settings, operating system settings, and files that need to be migrated inside the organization.| +|[Test the migration](usmt-test-your-migration.md)|Test the migration before deploying Windows to all users.| ## Related articles diff --git a/windows/deployment/usmt/usmt-test-your-migration.md b/windows/deployment/usmt/usmt-test-your-migration.md index 78541849eb..8b9eceee76 100644 --- a/windows/deployment/usmt/usmt-test-your-migration.md +++ b/windows/deployment/usmt/usmt-test-your-migration.md @@ -41,5 +41,5 @@ After the pilot migration is verified that it successfully migrated the specifie ## Related articles -- [Plan your migration](usmt-plan-your-migration.md). +- [Plan the migration](usmt-plan-your-migration.md). - [Log files](usmt-log-files.md). diff --git a/windows/deployment/usmt/usmt-troubleshooting.md b/windows/deployment/usmt/usmt-troubleshooting.md index 05971e5afd..a2fbbd858f 100644 --- a/windows/deployment/usmt/usmt-troubleshooting.md +++ b/windows/deployment/usmt/usmt-troubleshooting.md @@ -1,18 +1,18 @@ --- -title: User State Migration Tool (USMT) Troubleshooting (Windows 10) -description: Learn about topics that address common User State Migration Tool (USMT) 10.0 issues and questions to help troubleshooting. +title: User State Migration Tool (USMT) Troubleshooting +description: Learn about articles that address common User State Migration Tool (USMT) issues and questions to help troubleshooting. manager: aaroncz ms.author: frankroj ms.prod: windows-client author: frankroj -ms.date: 11/01/2022 +ms.date: 12/28/2023 ms.topic: article ms.technology: itpro-deploy --- # User State Migration Tool (USMT) troubleshooting -The following table describes articles that address common User State Migration Tool (USMT) 10.0 issues and questions. These articles describe tools that you can use to troubleshoot issues that arise during your migration. +The following table describes articles that address common User State Migration Tool (USMT) issues and questions. These articles describe tools that you can use to troubleshoot issues that arise during your migration. ## In this section @@ -26,10 +26,7 @@ The following table describes articles that address common User State Migration ## Related articles -[USMT best practices](usmt-best-practices.md) - -[User State Migration Tool (USMT) overview topics](usmt-topics.md) - -[User State Migration Tool (USMT) how-to topics](usmt-how-to.md) - -[User State Migration Toolkit (USMT) reference](usmt-reference.md) +- [USMT best practices](usmt-best-practices.md). +- [User State Migration Tool (USMT) overview articles](usmt-topics.md). +- [User State Migration Tool (USMT) how-to articles](usmt-how-to.md). +- [User State Migration Toolkit (USMT) reference](usmt-reference.md). diff --git a/windows/deployment/usmt/usmt-utilities.md b/windows/deployment/usmt/usmt-utilities.md index 2a174b6f13..01fe29dbaa 100644 --- a/windows/deployment/usmt/usmt-utilities.md +++ b/windows/deployment/usmt/usmt-utilities.md @@ -1,6 +1,6 @@ --- -title: UsmtUtils Syntax (Windows 10) -description: Learn about the syntax for the utilities available in User State Migration Tool (USMT) 10.0 through the command-line interface. +title: UsmtUtils Syntax +description: Learn about the syntax for the utilities available in User State Migration Tool (USMT) through the command-line interface. manager: aaroncz ms.author: frankroj ms.prod: windows-client @@ -12,15 +12,15 @@ ms.technology: itpro-deploy # UsmtUtils Syntax -This article describes the syntax for the utilities available in User State Migration Tool (USMT) 10.0 through the command-line interface. These utilities: +This article describes the syntax for the utilities available in User State Migration Tool (USMT) through the command-line interface. These utilities: -- Improve your ability to determine cryptographic options for your migration. +- Improve the ability to determine cryptographic options for the migration. - Help removing hard-link stores that can't otherwise be deleted due to a sharing lock. -- Verify whether the catalog file or any of the other files in the compressed migration store have become corrupted. +- Verify whether the catalog file or any of the other files in the compressed migration store are corrupted. -- Extract files from the compressed migration store when you migrate files and settings to the destination computer. +- Extract files from the compressed migration store created when files and settings are migrated to the destination computer. ## UsmtUtils.exe @@ -32,15 +32,15 @@ The syntax for `UsmtUtils.exe` is: |Command-line Option|Description| |--- |--- | -|**/ec**|Returns a list of supported cryptographic algorithms (AlgIDs) on the current system. You can use this option on a destination computer to determine which algorithm to use with the `/encrypt` command before you run the **ScanState** tool on the source computer.| -|**/rd** *<storeDir>* |Removes the directory path specified by the *<storeDir>* argument on the computer. You can use this command to delete hard-link migration stores that can't otherwise be deleted at a command prompt due to a sharing lock. If the migration store spans multiple volumes on a given drive, it will be deleted from all of these volumes.

For example:
`UsmtUtils.exe /rd D:\MyHardLinkStore`| -|**/y**|Overrides the accept deletions prompt when used with the `/rd` option. When you use the `/y` option with the `/rd` option, you won't be prompted to accept the deletions before USMT deletes the directories.| +|**/ec**|Returns a list of supported cryptographic algorithms (AlgIDs) on the current system. This option can be used on a destination computer to determine which algorithm to use with the `/encrypt` command before running the **ScanState** tool on the source computer.| +|**/rd** *<storeDir>* |Removes the directory path specified by the *<storeDir>* argument on the computer. This command can be used to delete hard-link migration stores that can't otherwise be deleted at a command prompt due to a sharing lock. If the migration store spans multiple volumes on a given drive, the migration store is deleted from all of these volumes.

For example:
`UsmtUtils.exe /rd D:\MyHardLinkStore`| +|**/y**|Overrides the prompt to accept deletions when used with the `/rd` option. When the `/y` option is used with the `/rd` option, a prompt isn't displayed to accept the deletions before USMT deletes the directories.| |**/verify**|Returns information on whether the compressed migration store is intact or whether it contains corrupted files or a corrupted catalog.

See [Verify options](#verify-options) for syntax and options to use with `/verify`.| |**/extract**|Recovers files from a compressed USMT migration store.

See [Extract options](#extract-options) for syntax and options to use with `/extract`.| ## Verify options -Use the `/verify` option when you want to determine whether a compressed migration store is intact or whether it contains corrupted files or a corrupted catalog. For more information on how to use the `/verify` option, see [Verify the condition of a compressed migration store](verify-the-condition-of-a-compressed-migration-store.md). +Use the `/verify` option to determine whether a compressed migration store is intact or whether it contains corrupted files or a corrupted catalog. For more information on how to use the `/verify` option, see [Verify the condition of a compressed migration store](verify-the-condition-of-a-compressed-migration-store.md). The syntax for `/verify` is: @@ -50,8 +50,8 @@ The syntax for `/verify` is: |-----|--------| | *<reportType>* | Specifies whether to report on all files, corrupted files only, or the status of the catalog. | | **/l:**
*<logfilePath>* | Specifies the location and name of the log file. | -| **/v:** *<VerbosityLevel>* | **(Verbosity)**

Enables verbose output in the **UsmtUtils** log file. The default value is 0.

You can set the *VerbosityLevel* to one of the following levels:
| -| **/decrypt** *<AlgID>* **/**:*<KeyString>*
or
**/decrypt** *<AlgID>* **/**:*<"Key String">*
or
**/decrypt:** *<AlgID>* **/keyfile**:*<FileName>* | Specifies that the `/encrypt` option was used to create the migration store with the **ScanState** tool. To decrypt the migration store, specify a `/key` or `/keyfile` option as follows:

For more information about supported encryption algorithms, see [Migration Store Encryption](usmt-migration-store-encryption.md) | +| **/v:** *<VerbosityLevel>* | **(Verbosity)**

Enables verbose output in the **UsmtUtils** log file. The default value is 0.

The *VerbosityLevel* can be set to one of the following levels:
| +| **/decrypt** *<AlgID>* **/**:*<KeyString>*
or
**/decrypt** *<AlgID>* **/**:*<"Key String">*
or
**/decrypt:** *<AlgID>* **/keyfile**:*<FileName>* | Specifies that the `/encrypt` option was used to create the migration store with the **ScanState** tool. To decrypt the migration store, specify a `/key` or `/keyfile` option as follows:

For more information about supported encryption algorithms, see [Migration Store Encryption](usmt-migration-store-encryption.md). | Some examples of `/verify` commands: @@ -65,7 +65,7 @@ Some examples of `/verify` commands: ## Extract options -Use the `/extract` option to recover files from a compressed USMT migration store if it will not restore normally with **LoadState**. For more information on how to use the `/extract` option, see [Extract files from a compressed USMT migration store](usmt-extract-files-from-a-compressed-migration-store.md). +Use the `/extract` option to recover files from a compressed USMT migration store if it doesn't restore normally with **LoadState**. For more information on how to use the `/extract` option, see [Extract files from a compressed USMT migration store](usmt-extract-files-from-a-compressed-migration-store.md). The syntax for `/extract` is: @@ -94,6 +94,5 @@ Some examples of `/extract` commands: ## Related articles -[User State Migration Tool (USMT) command-line syntax](usmt-command-line-syntax.md) - -[Return codes](/troubleshoot/windows-client/deployment/usmt-return-codes) +- [User State Migration Tool (USMT) command-line syntax](usmt-command-line-syntax.md). +- [Return codes](/troubleshoot/windows-client/deployment/usmt-return-codes). diff --git a/windows/deployment/usmt/usmt-what-does-usmt-migrate.md b/windows/deployment/usmt/usmt-what-does-usmt-migrate.md index e32b8c614c..82d5932b1e 100644 --- a/windows/deployment/usmt/usmt-what-does-usmt-migrate.md +++ b/windows/deployment/usmt/usmt-what-does-usmt-migrate.md @@ -1,11 +1,11 @@ --- -title: What does USMT migrate (Windows 10) -description: Learn how User State Migration Tool (USMT) 10.0 is designed so that an IT engineer can precisely define migrations using the USMT .xml scripting language. +title: What does USMT migrate +description: Learn how User State Migration Tool (USMT) is designed so that an IT engineer can precisely define migrations using the USMT .xml scripting language. manager: aaroncz ms.author: frankroj ms.prod: windows-client author: frankroj -ms.date: 11/23/2022 +ms.date: 12/28/2023 ms.topic: article ms.technology: itpro-deploy --- @@ -14,7 +14,7 @@ ms.technology: itpro-deploy ## Default migration scripts -The User State Migration Tool (USMT) 10.0 is designed so that an IT engineer can precisely define migrations using the USMT .xml scripting language. USMT provides the following sample scripts: +The User State Migration Tool (USMT) is designed so that an IT engineer can precisely define migrations using the USMT .xml scripting language. USMT provides the following sample scripts: - **MigApp.XML** - Rules to migrate application settings. @@ -22,7 +22,7 @@ The User State Migration Tool (USMT) 10.0 is designed so that an IT engineer can - **MigUser.XML** - Rules to migrate user profiles and user data. - `MigUser.xml` gathers everything in a user's profile and then does a file extension- based search of most of the system for other user data. If data doesn't match either of these criteria, the data won't be migrated. Usually, this file describes a core migration. + `MigUser.xml` gathers everything in a user's profile and then does a file extension- based search of most of the system for other user data. If data doesn't match either of these criteria, the data isn't migrated. Usually, this file describes a core migration. The following data doesn't migrate with `MigUser.xml`: @@ -33,28 +33,29 @@ The User State Migration Tool (USMT) 10.0 is designed so that an IT engineer can This section describes the user data that USMT migrates by default, using the `MigUser.xml` file. It also defines how to migrate access control lists (ACLs). -- **Folders from each user profile.** When you specify the `MigUser.xml` file, USMT migrates everything in a user's profiles including the following items: +- **Folders from each user profile.** When the `MigUser.xml` file is specified, USMT migrates everything in a user's profiles including the following items: - - My Documents + - My Documents. - - My Video + - My Video. - - My Music + - My Music. - - My Pictures + - My Pictures. - - Desktop files + - Desktop files. - - Start menu + - Start menu. - - Quick Launch settings + - Quick Launch settings. - - Favorites + - Favorites. > [!IMPORTANT] - > Starting in Windows 10, version 1607 the USMT does not migrate the Start menu layout. To migrate a user's Start menu, you must export and then import settings using the Windows PowerShell cmdlets **Export-StartLayout** and **Import-StartLayout**. For more information, see [USMT common issues](/troubleshoot/windows-client/deployment/usmt-common-issues#usmt-doesnt-migrate-the-start-layout). + > + > USMT doesn't migrate the Start menu layout. To migrate a user's Start menu, settings must be exported and then imported using the Windows PowerShell cmdlets **Export-StartLayout** and **Import-StartLayout**. For more information, see [USMT common issues](/troubleshoot/windows-client/deployment/usmt-common-issues#usmt-doesnt-migrate-the-start-layout). -- **Folders from the All Users and Public profiles.** When you specify the `MigUser.xml` file, USMT also migrates the following from the **Public** profile in Windows Vista, Windows 7, Windows 8, or Windows 10: +- **Folders from the All Users and Public profiles.** When the `MigUser.xml` file is specified, USMT also migrates the following from the **Public** profile in Windows: - Shared Documents @@ -70,20 +71,23 @@ This section describes the user data that USMT migrates by default, using the `M - Shared Favorites -- **File types.** When you specify the `MigUser.xml` file, the **ScanState** tool searches the fixed drives, collects, and then migrates files with any of the following file extensions: +- **File types.** When the `MigUser.xml` file is specified, the **ScanState** tool searches the fixed drives, collects, and then migrates files with any of the following file extensions: `.accdb`, `.ch3`, `.csv`, `.dif`, `.doc*`, `.dot*`, `.dqy`, `.iqy`, `.mcw`, `.mdb*`, `.mpp`, `.one*`, `.oqy`, `.or6`, `.pot*`, `.ppa`, `.pps*`, `.ppt*`, `.pre`, `.pst`, `.pub`, `.qdf`, `.qel`, `.qph`, `.qsd`, `.rqy`, `.rtf`, `.scd`, `.sh3`, `.slk`, `.txt`, `.vl*`, `.vsd`, `.wk*`, `.wpd`, `.wps`, `.wq1`, `.wri`, `.xl*`, `.xla`, `.xlb`, `.xls*` > [!NOTE] + > > The asterisk (`*`) stands for zero or more characters. > [!NOTE] + > > The OpenDocument extensions (`*.odt`, `*.odp`, `*.ods`) that Microsoft Office applications can use aren't migrated by default. -- **Access control lists.** USMT migrates access control lists (ACLs) for specified files and folders from computers running both Windows® XP and Windows Vista. For example, if you migrate a file named `File1.txt` that is **read-only** for **User1** and **read/write** for **User2**, these settings will still apply on the destination computer after the migration. +- **Access control lists.** USMT migrates access control lists (ACLs) for specified files and folders from computers running Windows. For example, if a file named `File1.txt` that is **read-only** for **User1** and **read/write** for **User2** is migrated, these settings will still apply on the destination computer after the migration. > [!IMPORTANT] - > To migrate ACLs, you must specify the directory to migrate in the MigUser.xml file. Using file patterns like \*.doc will not migrate a directory. The source ACL information is migrated only when you explicitly specify the directory. For example, `c:\test docs`. + > + > To migrate ACLs, the directory to migrate must be specified in the `MigUser.xml` file. Using file patterns like \*.doc won't migrate a directory. The source ACL information is migrated only when the directory is explicitly specified. For example, `c:\test docs`. ## Operating-system components @@ -91,140 +95,94 @@ USMT migrates operating-system components to a destination computer from compute The following components are migrated by default using the manifest files: -- Accessibility settings +- Accessibility settings. -- Address book +- Address book. -- Command-prompt settings +- Command-prompt settings. -- Desktop wallpaper **¹** +- Desktop wallpaper. **¹** -- EFS files +- EFS files. -- Favorites +- Favorites. -- Folder options +- Folder options. -- Fonts +- Fonts. -- Group membership. USMT migrates users' group settings. The groups to which a user belongs can be found by right-clicking **My Computer** on the Start menu and then selecting **Manage**. When running an offline migration, the use of a **<ProfileControl>** section in the `Config.xml` file is required. +- Group membership. USMT migrates users' group settings. The groups to which a user belongs can be found by right-clicking **My Computer** on the Start menu and then selecting **Manage**. The use of a **<ProfileControl>** section in the `Config.xml` file is required when running an offline migration. -- Windows Internet Explorer® settings **¹** +- Windows Internet Explorer® settings. **¹** -- Microsoft® Open Database Connectivity (ODBC) settings +- Microsoft® Open Database Connectivity (ODBC) settings. -- Mouse and keyboard settings +- Mouse and keyboard settings. -- Network drive mapping +- Network drive mapping. -- Network printer mapping **¹** +- Network printer mapping. **¹** -- Offline files **¹** +- Offline files. **¹** -- Phone and modem options **¹** +- Phone and modem options. **¹** -- RAS connection and phone book (.pbk) files +- RAS connection and phone book (.pbk) files. -- Regional settings **¹** +- Regional settings. **¹** -- Remote Access +- Remote Access. -- Taskbar settings **¹** +- Taskbar settings. **¹** -- User personal certificates (all) +- User personal certificates (all). -- Windows Mail +- Windows Mail. -- Windows Media Player **¹** +- Windows Media Player. **¹** -- Windows Rights Management +- Windows Rights Management. **¹** These settings aren't available for an offline migration. For more information, see [Offline migration reference](offline-migration-reference.md). > [!IMPORTANT] -> This list may not be complete. There may be additional components that are migrated. +> +> This list might not be complete. There might be additional components that are migrated. > [!NOTE] -> Some settings, such as fonts, aren't applied by the **LoadState** tool until after the destination computer has been restarted. For this reason, restart the destination computer after you run the **LoadState** tool. +> +> Some settings, such as fonts, aren't applied by the **LoadState** tool until after the destination computer is restarted. For this reason, restart the destination computer after running the **LoadState** tool. ## Supported applications -Even though it's not required for all applications, it's good practice to install all applications on the destination computer before restoring the user state. Installing applications before migrating settings helps to ensure that migrated settings aren't overwritten by the application installers. +Even though it isn't required for all applications, it's good practice to install all applications on the destination computer before restoring the user state. Installing applications before migrating settings helps to ensure application installers don't overwrite settings that were migrated. > [!NOTE] -> The versions of installed applications must match on the source and destination computers. USMT does not support migrating the settings of an earlier version of an application to a later version, except for Microsoft Office. +> +> The versions of installed applications must match on the source and destination computers. USMT doesn't support migrating the settings of an earlier version of an application to a later version, except for Microsoft Office. > [!NOTE] -> USMT migrates only the settings that have been used or modified by the user. If there is an application setting on the source computer that was not touched by the user, the setting may not migrate. +> +> USMT only migrates settings that are modified on the source computer. If an application setting isn't modified from the default on the source computer, the setting might not migrate. -When you specify the `MigApp.xml` file, USMT migrates the settings for the following applications: - -|Product|Version| -|--- |--- | -|Adobe Acrobat Reader|9| -|AOL Instant Messenger|6.8| -|Adobe Creative Suite|2| -|Adobe Photoshop CS|8, 9| -|Adobe ImageReady CS|| -|Apple iTunes|6, 7, 8| -|Apple QuickTime Player|5, 6, 7| -|Apple Safari|3.1.2| -|Google Chrome|beta| -|Google Picasa|3| -|Google Talk|beta| -|IBM Lotus 1-2-3|9| -|IBM Lotus Notes|6, 7, 8| -|IBM Lotus Organizer|5| -|IBM Lotus WordPro|9.9| -|Intuit Quicken Deluxe|2009| -|Money Plus Business|2008| -|Money Plus Home|2008| -|Mozilla Firefox|3| -|Microsoft Office|2003, 2007, 2010| -|Microsoft Office Access®|2003, 2007, 2010| -|Microsoft Office Excel®|2003, 2007, 2010| -|Microsoft Office FrontPage®|2003, 2007, 2010| -|Microsoft Office OneNote®|2003, 2007, 2010| -|Microsoft Office Outlook®|2003, 2007, 2010| -|Microsoft Office PowerPoint®|2003, 2007, 2010| -|Microsoft Office Publisher|2003, 2007, 2010| -|Microsoft Office Word|2003, 2007, 2010| -|Opera Software Opera|9.5| -|Microsoft Outlook Express|(only mailbox file)| -|Microsoft Project|2003, 2007| -|Microsoft Office Visio®|2003, 2007| -|RealPlayer Basic|11| -|Sage Peachtree|2009| -|Skype|3.8| -|Windows Live Mail|12, 14| -|Windows Live Messenger|8.5, 14| -|Windows Live MovieMaker|14| -|Windows Live Photo Gallery|12, 14| -|Windows Live Writer|12, 14| -|Windows Mail|(Windows 7 and 8)| -|Microsoft Works|9| -|Yahoo Messenger|9| -|Microsoft Zune™ Software|3| +When the `MigApp.xml` file is specified, USMT migrates the settings for specific applications defined in the `MigApp.xml` file. Consult the `MigApp.xml` file for applications are supported. ## What USMT doesn't migrate -The following items are settings that USMT doesn't migrate. If you're having a problem that isn't listed here, see [Common issues](/troubleshoot/windows-client/deployment/usmt-common-issues). +The following items are settings that USMT doesn't migrate. If having a problem that isn't listed here, see [Common issues](/troubleshoot/windows-client/deployment/usmt-common-issues). ### Application settings USMT doesn't migrate the following application settings: +- Settings for Microsoft Store applications. + - Settings from earlier versions of an application. The versions of each application must match on the source and destination computers. USMT doesn't support migrating the settings of an earlier version of an application to a later version, except for Microsoft Office. USMT can migrate from an earlier version of Microsoft Office to a later version. -- Application settings and some operating-system settings when a local account is created. For example, if you run `/lac` to create a local account on the destination computer, USMT will migrate the user data, but only some of the operating-system settings, such as wallpaper and screensaver settings, and no application settings will migrate. +- Application settings and some operating-system settings when a local account is created. For example, if `/lac` is specified to create a local account on the destination computer, USMT migrates the user data, but doesn't migrate: -- Microsoft Project settings, when migrating from Office 2003 to Office 2007 system. - -- ICQ Pro settings, if ICQ Pro is installed in a different location on the destination computer. To successfully migrate the settings of ICQ Pro, you must install ICQ Pro in the same location on the destination computer as it was on the source computer. Otherwise, after you run the **LoadState** tool, the application won't start. You may encounter problems when: - - - You change the default installation location on 32-bit destination computers. - - - You attempt to migrate from a 32-bit computer to a 64-bit computer. Attempting to migrate settings between different architectures doesn't work because the ICQ Pro default installation directory is different on the two types of computers. When you install ICQ Pro on a 32-bit computer, the default location is `C:\Program Files\...`. The ICQ Pro default installation directory on an x64-based computer, however, is `C:\Program Files (x86)\...`. + - Some operating system settings - Only some operating-system settings, such as wallpaper and screensaver settings, are migrated. + - Application settings. ### Operating-System settings @@ -232,23 +190,21 @@ USMT doesn't migrate the following operating-system settings. - Local printers, hardware-related settings, drivers, passwords, application binary files, synchronization files, DLL files, or other executable files. -- Permissions for shared folders. After migration, you must manually re-share any folders that were shared on the source computer. +- Permissions for shared folders. After migration, any folders that were shared on the source computer must be manually re-shared. - Files and settings migrating between operating systems with different languages. The operating system of the source computer must match the language of the operating system on the destination computer. -- Customized icons for shortcuts may not migrate. +- Customized icons for shortcuts might not migrate. -You should also note the following items: +Also note the following items: -- You should run USMT from an account with administrative credentials. Otherwise, some data won't migrate. When running the **ScanState** and **LoadState** tools, you must run the tools in Administrator mode from an account with administrative credentials. If you don't run USMT in Administrator mode, only the user profile that is logged on will be included in the migration. +- Run USMT from an account with administrative credentials. Otherwise, some data doesn't migrate. When running the **ScanState** and **LoadState** tools, the tools must be run in Administrator mode from an account with administrative credentials. If USMT isn't run in Administrator mode, only the user profile that is logged on is included in the migration. -- You can use the `/localonly` option to exclude the data from removable drives and network drives mapped on the source computer. For more information about what is excluded when you specify `/localonly`, see [ScanState syntax](usmt-scanstate-syntax.md). +- Use the `/localonly` option to exclude the data from removable drives and network drives mapped on the source computer. For more information about what is excluded when `/localonly` is specified, see [ScanState syntax](usmt-scanstate-syntax.md). ### Start menu layout -Starting in Windows 10, version 1607 the USMT doesn't migrate the Start menu layout. To migrate a user's Start menu, you must export and then import settings using the Windows PowerShell cmdlets **Export-StartLayout** and **Import-StartLayout**. For more information, see [USMT common issues](/troubleshoot/windows-client/deployment/usmt-common-issues#usmt-doesnt-migrate-the-start-layout). - - +USMT doesn't migrate the Start menu layout. To migrate a user's Start menu, settings must be exported and then imported using the Windows PowerShell cmdlets **Export-StartLayout** and **Import-StartLayout**. For more information, see [USMT common issues](/troubleshoot/windows-client/deployment/usmt-common-issues#usmt-doesnt-migrate-the-start-layout). ### User profiles from Active Directory to Microsoft Entra ID @@ -256,4 +212,4 @@ USMT doesn't support migrating user profiles from Active Directory to Microsoft ## Related articles -[Plan your migration](usmt-plan-your-migration.md) +- [Plan the migration](usmt-plan-your-migration.md). diff --git a/windows/deployment/usmt/usmt-xml-elements-library.md b/windows/deployment/usmt/usmt-xml-elements-library.md index e669804e3e..b5a1ca1d97 100644 --- a/windows/deployment/usmt/usmt-xml-elements-library.md +++ b/windows/deployment/usmt/usmt-xml-elements-library.md @@ -1,20 +1,24 @@ --- -title: XML Elements Library (Windows 10) +title: XML Elements Library description: Learn about the XML elements and helper functions that you can employ to author migration .xml files to use with User State Migration Tool (USMT). manager: aaroncz ms.author: frankroj ms.prod: windows-client author: frankroj -ms.date: 11/01/2022 +ms.date: 12/29/2023 ms.topic: article ms.technology: itpro-deploy --- # XML elements library -This topic describes the XML elements and helper functions that you can employ to author migration .xml files to use with User State Migration Tool (USMT). It is assumed that you understand the basics of XML. +This article describes the XML elements and helper functions that you can employ to author migration .xml files to use with User State Migration Tool (USMT). This article assumes a basic knowledge of XML. -In addition to XML elements and helper functions, this article describes how to specify encoded locations and locations patterns, functions that are for internal USMT use only, and the version tags that you can use with helper functions. +In addition to XML elements and helper functions, this article: + +- Describes how to specify encoded locations and locations patterns. +- Functions that are for internal USMT use only. +- The version tags that you can use with helper functions. ## Elements and helper functions @@ -26,7 +30,7 @@ The following table describes the XML elements and helper functions you can use ## <addObjects> -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 will be an array of objects. +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. - **Number of occurrences:** unlimited @@ -92,7 +96,7 @@ 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>** will be ignored. +You must specify the **<bytes>** element only for files because, if **<location>** corresponds to a registry key or a directory, then **<bytes>** is ignored. - **Number of occurrences:** zero or one @@ -110,7 +114,7 @@ Syntax: |--- |--- |--- | |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.| +|*Content*|Yes|Depends on the value of the string.| The following example is from the `MigApp.xml` file: @@ -144,12 +148,12 @@ Syntax: ## <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 2003" is a component that contains another component, "Microsoft Office Access 2003". You can use the child elements to define the 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. 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: 1. When the parent **<component>** element is a container -2. If the child **<component>** element has the same role as the parent **<component>** element. +1. If the child **<component>** element has the same role as the parent **<component>** element. - **Number of occurrences:** Unlimited @@ -169,18 +173,18 @@ hidden="Yes|No"> |Setting|Required?|Value| |--- |--- |--- | -| type | Yes | You can use the following to group settings, and define the type of the component. | -| 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 is not there. | -| defaultSupported | No
(default = TRUE) | Can be any of **TRUE**, **FALSE**, **YES**, or **NO**. If this parameter is **FALSE** (or **NO**), the component will not be migrated unless there is an equivalent component on the destination computer.
When **type="System"** and **defaultSupported="FALSE"** the settings will not migrate unless there is 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. 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 will not 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. | +| type | Yes | You can use the following to group settings, and define the type of the component. | +| 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. | +| 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. 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. | | 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, it is recommend to no longer use the **<condition>** element because it may be deprecated in future versions of USMT. If the **<condition>** element were depecated, 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, it is recommended to use the more powerful **[<conditions>](#conditions)** element. The **<conditions>** element allows for formulation of complex Boolean statements. +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. -The **<condition>** element has a Boolean result. You can use this element to specify the conditions in which the parent element will be evaluated. If any of the present conditions return **FALSE**, the parent element will not be evaluated. +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. - **Number of occurrences:** unlimited. @@ -199,9 +203,9 @@ Syntax: |Setting|Required?|Value| |--- |--- |--- | |negation|No
Default = No|**"Yes"** reverses the True/False value of the condition.| -|*ScriptName*|Yes|A script that has been defined within this migration section.| +|*ScriptName*|Yes|A script that is defined within this migration section.| -For example, in the code sample below, 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 **<condition>** elements, **A** and **B**, are joined together by the **AND** operator because they are in separate **<conditions>** sections: ```xml @@ -214,7 +218,7 @@ For example, in the code sample below, the **<condition>** elements, **A** ``` -However, in the code sample below, 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 **<condition>** elements, **A** and **B**, are joined together by the **OR** operator because they are in the same **<conditions>** section. ```xml @@ -264,7 +268,7 @@ The **<condition>** functions return a Boolean value. You can use these el |Setting|Required?|Value| |--- |--- |--- | - |*OSType*|Yes|Can be **9x** or **NT**. If *OSType* does not match the type of the current operating system, then it returns **FALSE**. For example, if the current operating system is Windows NT-based and *OSType* is **"9x"**, the result will be **FALSE**.| + |*OSType*|Yes|Can be **9x** or **NT**. If *OSType* doesn't match the type of the current operating system, then it returns **FALSE**. For example, if the current operating system is Windows NT-based and *OSType* is **"9x"**, the result is **FALSE**.| |*OSVersion*|Yes|The major version, minor version, build number, and corrected service diskette version separated by periods. For example, `5.0.2600.Service Pack 1`. You can also specify partial specification of the version but no pattern is allowed such as `5.0`.

The **IsOSLaterThan** function returns **TRUE** if the current operating system is later than or equal to *OSVersion*.| For example: @@ -281,7 +285,7 @@ The **<condition>** functions return a Boolean value. You can use these el |Setting|Required?|Value| |--- |--- |--- | - |*OSType*|Yes|Can be **9x** or **NT**. If *OSType* does not match the type of the current operating system, then it returns **FALSE**. For example, if the current operating system is Windows NT-based and *OSType* is **"9x"** the result will be **FALSE**.| + |*OSType*|Yes|Can be **9x** or **NT**. If *OSType* doesn't match the type of the current operating system, then it returns **FALSE**. For example, if the current operating system is Windows NT-based and *OSType* is **"9x"** the result is **FALSE**.| |*OSVersion*|Yes|The major version, minor version, build number, and corrected service diskette version separated by periods. For example, `5.0.2600.Service Pack 1`. You can also specify partial specification of the version but no pattern is allowed such as `5.0`.

The **IsOSEarlierThan** function returns **TRUE** if the current operating system is earlier than *OSVersion*.| ### Object content functions @@ -307,8 +311,8 @@ The **<condition>** functions return a Boolean value. You can use these el |Setting|Required?|Value| |--- |--- |--- | - |*EncodedFileLocation*|Yes|The **[location pattern](#specifying-locations)** for the file that will be checked. Environment variables are allowed.| - |*VersionTag*|Yes|The **[version tag](#valid-version-tags)** value that will be checked.| + |*EncodedFileLocation*|Yes|The **[location pattern](#specifying-locations)** for the file that is checked. Environment variables are allowed.| + |*VersionTag*|Yes|The **[version tag](#valid-version-tags)** value that is checked.| |*VersionValue*|Yes|A string pattern. For example, "Microsoft*".| For example: @@ -325,9 +329,9 @@ The **<condition>** functions return a Boolean value. You can use these el |Setting|Required?|Value| |--- |--- |--- | - |*EncodedFileLocation*|Yes|The **[location pattern](#specifying-locations)** for the file that will be checked. Environment variables are allowed.| - |*VersionTag*|Yes|The **[version tag](#valid-version-tags)** value that will be checked.| - |*VersionValue*|Yes|The value to compare to. You cannot specify a pattern.| + |*EncodedFileLocation*|Yes|The **[location pattern](#specifying-locations)** for the file that is checked. Environment variables are allowed.| + |*VersionTag*|Yes|The **[version tag](#valid-version-tags)** value that is checked.| + |*VersionValue*|Yes|The value to compare to. You can't specify a pattern.| - **IsFileVersionBelow** @@ -335,9 +339,9 @@ The **<condition>** functions return a Boolean value. You can use these el |Setting|Required?|Value| |--- |--- |--- | - |*EncodedFileLocation*|Yes|The **[location pattern](#specifying-locations)** for the file that will be checked. Environment variables are allowed.| - |*VersionTag*|Yes|The **[version tag](#valid-version-tags)** value that will be checked.| - |*VersionValue*|Yes|The value to compare to. You cannot specify a pattern.| + |*EncodedFileLocation*|Yes|The **[location pattern](#specifying-locations)** for the file that is checked. Environment variables are allowed.| + |*VersionTag*|Yes|The **[version tag](#valid-version-tags)** value that is checked.| + |*VersionValue*|Yes|The value to compare to. You can't specify a pattern.| - **IsSystemContext** @@ -354,8 +358,8 @@ The **<condition>** functions return a Boolean value. You can use these el |Setting|Required?|Value| |--- |--- |--- | |*ObjectType*|Yes|Defines the type of object. Can be File or Registry.| - |*EncodedLocationPattern*|Yes|The **[encoded location](#specifying-locations)** for the object that will be examined. You can specify environment variables.| - |StringContent|Yes|The string that will be checked against.| + |*EncodedLocationPattern*|Yes|The **[encoded location](#specifying-locations)** for the object that is examined. You can specify environment variables.| + |StringContent|Yes|The string that is checked against.| For example: @@ -372,8 +376,8 @@ The **<condition>** functions return a Boolean value. You can use these el |Setting|Required?|Value| |--- |--- |--- | |*ObjectType*|Yes|Defines the type of object. Can be File or Registry.| - |*EncodedLocationPattern*|Yes|The **[encoded location](#specifying-locations)** for the object that will be examined. You can specify environment variables.| - |*StrToFind*|Yes|A string that will be searched inside the content of the given object.| + |*EncodedLocationPattern*|Yes|The **[encoded location](#specifying-locations)** for the object that is examined. You can specify environment variables.| + |*StrToFind*|Yes|A string that is searched inside the content of the given object.| - **IsSameObject** @@ -398,7 +402,7 @@ The **<condition>** functions return a Boolean value. You can use these el - **IsSameContent** - The **IsSameContent** function returns **TRUE** if the given objects have the same content. Otherwise, it returns **FALSE**. The content will be compared byte by byte. + The **IsSameContent** function returns **TRUE** if the given objects have the same content. Otherwise, it returns **FALSE**. The content is compared byte by byte. Syntax: `IsSameContent("ObjectType1","EncodedLocation1","ObjectType2","EncodedLocation2")` @@ -411,7 +415,7 @@ The **<condition>** functions return a Boolean value. You can use these el - **IsSameStringContent** - The **IsSameStringContent** function returns **TRUE** if the given objects have the same content. Otherwise, it returns **FALSE**. The content will be interpreted as a string. + The **IsSameStringContent** function returns **TRUE** if the given objects have the same content. Otherwise, it returns **FALSE**. The content is interpreted as a string. Syntax: `IsSameStringContent("ObjectType1","EncodedLocation1","ObjectType2","EncodedLocation2")` @@ -477,7 +481,7 @@ 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 will be migrated. If it is **FALSE**, it will not be 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 **<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.| ### <content> functions @@ -485,14 +489,14 @@ The following functions generate patterns out of the content of an object. These - **ExtractSingleFile** - If the registry value is a **MULTI-SZ**, only the first segment is processed. The returned pattern is the encoded location for a file that must exist on the system. If the specification is correct in the registry value, but the file does not exist, this function returns **NULL**. + If the registry value is a **MULTI-SZ**, only the first segment is processed. The returned pattern is the encoded location for a file that must exist on the system. If the specification is correct in the registry value, but the file doesn't exist, this function returns **NULL**. Syntax: `ExtractSingleFile(Separators,PathHints)` |Setting|Required?|Value| |--- |--- |--- | |*Separators*|Yes|A list of possible separators that might follow the file specification in this registry value name. For example, if the content is **"C:\Windows\Notepad.exe,-2"**, the separator is a comma. You can specify **NULL**.| - |*PathHints*|Yes|A list of extra paths, separated by colons (`;`), where the function will look for a file matching the current content. For example, if the content is **"Notepad.exe"** and the path is the **%Path%** environment variable, the function will find **Notepad.exe** in `%windir%` and returns **"c:\Windows [Notepad.exe]"**. You can specify **NULL**.| + |*PathHints*|Yes|A list of extra paths, separated by colons (`;`), where the function looks for a file matching the current content. For example, if the content is **"Notepad.exe"** and the path is the **%Path%** environment variable, the function finds **Notepad.exe** in `%windir%` and returns **"c:\Windows [Notepad.exe]"**. You can specify **NULL**.| For example: @@ -510,18 +514,18 @@ The following functions generate patterns out of the content of an object. These 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 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 does not exist, it will not be included in the resulting list. + The returned patterns are the encoded locations for files that must exist on the source computer. If the specification is correct in the registry value but the file doesn't exist, it isn't included in the resulting list. Syntax: `ExtractMultipleFiles(Separators,PathHints)` |Setting|Required?|Value| |--- |--- |--- | |*Separators*|Yes|A list of possible separators that might follow the file specification in this registry value name. For example, if the content is **"C:\Windows\Notepad.exe,-2"**, the separator is a comma. This parameter must be NULL when processing **MULTI-SZ** registry values.| - |*PathHints*|Yes|A list of extra paths, separated by colons (`;`), where the function will look for a file matching the current content. For example, if the content is **"Notepad.exe"** and the path is the **%Path%** environment variable, the function will find **Notepad.exe** in `%windir%` and returns **"c:\Windows [Notepad.exe]"**. You can specify **NULL**.| + |*PathHints*|Yes|A list of extra paths, separated by colons (`;`), where the function looks for a file matching the current content. For example, if the content is **"Notepad.exe"** and the path is the **%Path%** environment variable, the function finds **Notepad.exe** in `%windir%` and returns **"c:\Windows [Notepad.exe]"**. You can specify **NULL**.| - **ExtractDirectory** - The **ExtractDirectory** function returns a pattern that is the encoded location for a directory that must exist on the source computer. If the specification is correct in the registry value, but the directory does not exist, this function returns **NULL**. If it is processing a registry value that is a **MULTI-SZ**, only the first segment will be processed. + The **ExtractDirectory** function returns a pattern that is the encoded location for a directory that must exist on the source computer. If the specification is correct in the registry value, but the directory doesn't exist, this function returns **NULL**. If it's processing a registry value that is a **MULTI-SZ**, only the first segment is processed. Syntax: `ExtractDirectory(Separators,LevelsToTrim,PatternSuffix)` @@ -545,7 +549,7 @@ The following functions generate patterns out of the content of an object. These ## <contentModify> -The **<contentModify>** element modifies the content of an object before it 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 **<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. - **Number of occurrences:** Unlimited @@ -564,31 +568,31 @@ 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 will be 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 will be migrated. If it is **FALSE**, it will not be 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 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 -The following functions change the content of objects as they are 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 **<ObjectSet>** 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** will convert the string `"1"` to the DWORD `0x00000001`. If the conversion fails, then the value of **DefaultValueOnError** will be applied. + 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. Syntax: `ConvertToDWORD(DefaultValueOnError)` |Setting|Required?|Value| |--- |--- |--- | - |*DefaultValueOnError*|No|The value that will be written into the value name if the conversion fails. You can specify **NULL**, and `0` will be written if the conversion fails.| + |*DefaultValueOnError*|No|The value that is written into the value name if the conversion fails. You can specify **NULL**, and `0` is written if the conversion fails.| - **ConvertToString** - The **ConvertToString** function converts the content of registry values that match the parent **<ObjectSet>** element to a string. For example, it will convert the DWORD `0x00000001` to the string **"1"**. If the conversion fails, then the value of **DefaultValueOnError** will be applied. + 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. Syntax: `ConvertToString(DefaultValueOnError)` |Setting|Required?|Value| |--- |--- |--- | - |*DefaultValueOnError*|No|The value that will be written into the value name if the conversion fails. You can specify **NULL**, and `0` will be written if the conversion fails.| + |*DefaultValueOnError*|No|The value that is written into the value name if the conversion fails. You can specify **NULL**, and `0` is written if the conversion fails.| For example: @@ -618,7 +622,7 @@ The following functions change the content of objects as they are migrated. Thes - **SetValueByTable** - The **SetValueByTable** function matches the value from the source computer to the source table. If the value is there, the equivalent value in the destination table will be applied. If the value is not there, or if the destination table has no equivalent value, the *DefaultValueOnError* will be applied. + The **SetValueByTable** function matches the value from the source computer to the source table. If the value is there, the equivalent value in the destination table is applied. If the value isn't there, or if the destination table has no equivalent value, the *DefaultValueOnError* is applied. Syntax: `SetValueByTable(SourceTable,DestinationTable,DefaultValueOnError)` @@ -626,44 +630,44 @@ The following functions change the content of objects as they are migrated. Thes |--- |--- |--- | |*SourceTable*|Yes|A list of values separated by commas that are possible for the source registry values.| |*DestinationTable*|No|A list of translated values separated by commas.| - |*DefaultValueOnError*|No|The value that will be applied to the destination computer if either
  1. The value for the source computer does not match *SourceTable*
  2. *DestinationTable* has no equivalent value.

If **DefaultValueOnError** is **NULL**, the value will not be changed on the destination computer.| + |*DefaultValueOnError*|No|The value that is applied to the destination computer if either
  1. The value for the source computer doesn't match *SourceTable*
  2. *DestinationTable* has no equivalent value.

If **DefaultValueOnError** is **NULL**, the value isn't changed on the destination computer.| - **KeepExisting** - You can use the **KeepExisting** function when there are conflicts on the destination computer. This function will keep (not overwrite) the specified attributes for the object that is on the destination computer. + You can use the **KeepExisting** function when there are conflicts on the destination computer. This function keeps (not overwrites) the specified attributes for the object that is on the destination computer. Syntax: `KeepExisting("OptionString","OptionString","OptionString",…)` |Setting|Required?|Value| |--- |--- |--- | - | *OptionString* | Yes | *OptionString* can be **Security**, **TimeFields**, or **FileAttrib**:*Letter*. You can specify one of each type of *OptionStrings*. Do not specify multiple *OptionStrings* with the same value. If you do, the right-most option of that type will be kept. For example, do not specify **("FileAttrib:H", "FileAttrib:R")** because only Read-only will be evaluated. Instead specify **("FileAttrib:HR")** and both Hidden and Read-only attributes will be kept on the destination computer. | + | *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. | - **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 will be removed. + 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. Syntax: `MergeMultiSzContent (Instruction,String,Instruction,String,…)` |Setting|Required?|Value| |--- |--- |--- | - | *Instruction* | Yes | Can be one of the following: | + | *Instruction* | Yes | Can be one of the following values: | | *String* | Yes | The string to be added or removed. | - **MergeDelimitedContent** - The **MergeDelimitedContent** function merges the content of the registry values that are enumerated by the parent **<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 will be removed. + 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. Syntax: `MergeDelimitedContent(Delimiters,Instruction,String,…)` |Setting|Required?|Value| |--- |--- |--- | - | *Delimiters* | Yes | A single character that will be used to separate the content of the object that is being processed. The content will be considered as a list of elements that is separated by the *Delimiters*.
For example, `"."` will separate the string based on a period. | - | *Instruction* | Yes | Can be one of the following: | + | *Delimiters* | Yes | A single character that is used to separate the content of the object that is being processed. The content is considered as a list of elements that is separated by the *Delimiters*.
For example, `"."` separates the string based on a period. | + | *Instruction* | Yes | Can be one of the following values: | | *String* | Yes | The string to be added or removed. | ## <description> -The **<description>** element defines a description for the component but does not affect the migration. +The **<description>** element defines a description for the component but doesn't affect the migration. - **Number of occurrences:** zero or one @@ -681,7 +685,7 @@ 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 <description> element defines the "My custom component" description: ```xml My custom component @@ -694,13 +698,13 @@ The **<destinationCleanup>** element deletes objects, such as files and re > [!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 is 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. This will ensure that if there is a missing key on the source computer, it will also be missing on 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. - **Number of occurrences:** Unlimited - **Parent elements:** [<rules>](#rules) -- **Child elements:** [<objectSet>](#objectset) (Note that the destination computer will delete all child elements.) +- **Child elements:** [<objectSet>](#objectset) (The destination computer deletes all child elements.) Syntax: @@ -711,7 +715,7 @@ 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 will be 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 will be migrated. If it is **FALSE**, it will not be 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 include rule. The filter script returns a Boolean value. If the return value is **TRUE**, the object is migrated. If it's **FALSE**, it isn't migrated.| For example: @@ -726,11 +730,11 @@ For example: ## <detect> -Although the **<detect>** element is still supported, it is recommend to no longer use the **<detect>** element because it may be deprecated in future versions of USMT. If the **<detect>** element were depecated, it would require a rewrite of any scripts that use the **<detect>** element. Instead, it is recommend to use the **[<detection>](#detection)** element. The **<detection>** element allows for more clearly formulated complex Boolean statements +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 -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 is no **<detect>** element section, then USMT will assume that the component is present. +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. -For each **<detect>** element there can be multiple child **<condition>** or **<objectSet>** elements, which will be 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 **<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**. - **Number of occurrences:** unlimited @@ -749,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 are not 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 are 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 were not 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 **<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.
| For examples, see the examples for [<detection>](#detection). ## <detects> -Although the **<detects>** element is still supported, it is recommend to no longer use the **<detects>** element because it may be deprecated in future versions of USMT. If the **<detects>** element were deprecated, it would require a rewrite of any scripts that use the **<detects>** element. Instead, it is recommend to use 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 **<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. -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 do not 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 is no **<detects>** element section, then USMT will assume 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 **<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. Syntax: @@ -776,7 +780,7 @@ Syntax: |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 were not 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. | +| 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. | The following example is from the `MigApp.xml` file. @@ -795,9 +799,9 @@ The following example is from the `MigApp.xml` file. 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**. -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 will be processed. Otherwise, the **<role>** element will not be processed. +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. -Use the **<detection>** element under the **<namedElements>** element if you do not 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 is not a **<detection>** section for a component, then USMT will assume that the component is present. +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. - **Number of occurrences:** Unlimited. @@ -814,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 will be evaluated. | +| 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. | | 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: @@ -858,7 +862,7 @@ Syntax: |Setting|Required?|Value| |--- |--- |--- | -|locID|No|This parameter is for internal USMT use. Do not use this parameter.| +|locID|No|This parameter is for internal USMT use. Don't use this parameter.| |*ComponentName*|Yes|The name for the component.| For example: @@ -869,7 +873,7 @@ For example: ## <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 will be private. That is, they will be available only for their child components and the component in which they were defined. For two example scenarios, see [Examples](#examples). +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). - **Number of occurrences:** unlimited @@ -889,13 +893,13 @@ 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>** were not 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.
| +| 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.
| ## Examples ### Example scenario 1 -In this scenario, you want to generate the location of objects at run time depending on the configuration of the destination computer. For example, you must do this if an application writes data in the directory where it is installed, and users can install the application anywhere on the computer. If the application writes a registry value `hklm\software\companyname\install [path\]` and then updates this value with the location where the application is installed, then the only way for you to migrate the required data correctly is to define an environment variable. For example: +In this scenario, you want to generate the location of objects at run time depending on the configuration of the destination computer. For example, if an application writes data in the directory where the application is installed, and users can install the application anywhere on the computer. If the application writes a registry value `hklm\software\companyname\install [path\]` and then updates this value with the location where the application is installed, then the only way for you to migrate the required data correctly is to define an environment variable. For example: ```xml @@ -933,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 do this 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 **<include>** rule in an .xml file: ```xml @@ -973,7 +977,7 @@ Then, you can specify the variable in an **<include>** rule as follows: ## <exclude> -The **<exclude>** element determines what objects will not be migrated, unless there is a more specific **<include>** element that migrates an object. If there is an **<include>** and **<exclude>** element for the same object, the object will be included. For each **<exclude>** element there can be multiple child **<objectSet>** elements. +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. - **Number of occurrences:** Unlimited @@ -992,7 +996,7 @@ Syntax: |Setting|Required?|Value| |--- |--- |--- | -|filter|No
(default = No)|A script followed by any number of string arguments that are separated by a comma and enclosed in parenthesis. For example, `MyScripts.AScript ("Arg1","Arg2")`.

The script will be 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 will be migrated. If it is **FALSE**, it will not be migrated.| +|filter|No
(default = No)|A script followed by any number of string arguments that are separated by a comma and enclosed in parenthesis. For example, `MyScripts.AScript ("Arg1","Arg2")`.

The script is called for each object that is enumerated by the object sets in the include rule. The filter script returns a Boolean value. If the return value is **TRUE**, the object is migrated. If it's **FALSE**, it isn't migrated.| For example, from the `MigUser.xml` file: @@ -1008,7 +1012,7 @@ For example, from the `MigUser.xml` file: ## <excludeAttributes> -You can use the **<excludeAttributes>** element to determine which parameters associated with an object will not be migrated. If there are conflicts between the **<includeAttributes>** and **<excludeAttributes>** elements, the most specific pattern determines the patterns that will not be migrated. If an object does not have an **<includeAttributes>** or **<excludeAttributes>** element, then all of its parameters will be migrated. +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. - **Number of occurrences:** Unlimited @@ -1137,7 +1141,7 @@ For another example of how to use the <extension> element, see the example ## <externalProcess> -You can use the <externalProcess> element to run a command line during the migration process. For example, you may want to run a command after the **LoadState** process completes. +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. - **Number of occurrences:** Unlimited @@ -1154,17 +1158,17 @@ Syntax: |Setting|Required?|Value| |--- |--- |--- | -| when | Yes | Indicates when the command line should be run. This value can be one of the following:
  • **pre-scan** before the scanning process begins.
  • **scan-success** after the scanning process has finished successfully.
  • **post-scan** after the scanning process has finished, whether it was successful or not.
  • **pre-apply** before the apply process begins.
  • **apply-success** after the apply process has finished successfully.
  • **post-apply** after the apply process has finished, whether it was successful or not.
| +| 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). ## <icon> -This is an internal USMT element. Do not use this element. +This element is an internal USMT element. Don't use this element. ## <include> -The **<include>** element determines what to migrate, unless there is 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 **<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. - **Number of occurrences:** Unlimited @@ -1183,7 +1187,7 @@ Syntax: |Setting|Required?|Value| |--- |--- |--- | -| filter | No.
If this parameter is not specified, then all patterns that are inside the child **<objectSet>** element will be 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 will be 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 will be migrated. If it is **FALSE**, it will not be migrated. | +| 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. | The following example is from the MigUser.xml file: @@ -1232,11 +1236,11 @@ The following functions return a Boolean value. You can use them to migrate cert |Setting|Required?|Value| |--- |--- |--- | | *StringContent* | Yes | The string to check against. | - | *CompareType* | Yes | A string. Use one of the following values:
  • **Equal** (case insensitive). The function returns **TRUE** if the string representation of the current object that is processed by the migration engine is identical to `StringContent`.
  • **NULL** **or any other value**. The function returns **TRUE** if the string representation of the current object that is processed by the migration engine does not match `StringContent`.
| + | *CompareType* | Yes | A string. Use one of the following values:
  • **Equal** (case insensitive). The function returns **TRUE** if the string representation of the current object that is processed by the migration engine is identical to `StringContent`.
  • **NULL** **or any other value**. The function returns **TRUE** if the string representation of the current object that is processed by the migration engine doesn't match `StringContent`.
| - **IgnoreIrrelevantLinks** - This filter screens out the .lnk files that point to an object that is not valid on the destination computer. Note that the screening takes place on the destination computer, so all .lnk files will be saved to the store during **ScanState**. Then they will be screened out when you run the **LoadState** tool. + This filter screens out the .lnk files that point to an object that isn't valid on the destination computer. The screening takes place on the destination computer, so all .lnk files are saved to the store during **ScanState**. Then they're screened out when you run the **LoadState** tool. Syntax: `IgnoreIrrelevantLinks ()` @@ -1252,11 +1256,11 @@ 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 may want to use this function when you want to check an object's value on the destination computer but do not 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**. 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. Syntax: `NeverRestore()` - In the following example, HKCU\\Control Panel\\International \[Locale\] will be included in the store, but it will not be migrated to the destination computer: + In the following example, HKCU\\Control Panel\\International \[Locale\] is included in the store, but it isn't migrated to the destination computer: ```xml @@ -1268,7 +1272,7 @@ 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 will be migrated along with the object itself. If there are conflicts between the **<includeAttributes>** and **<excludeAttributes>** elements, the most specific pattern will determine which parameters will be migrated. If an object does not have an **<includeAttributes>** or **<excludeAttributes>** element, then all of its parameters will be migrated. +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. - **Number of occurrences:** unlimited @@ -1285,13 +1289,13 @@ Syntax: |Setting|Required?|Value| |--- |--- |--- | -| 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:
    • **CreationTime**: Specifies when the file or directory was created.
    • **LastAccessTime**: Specifies when the file is last read from, written to, or, in the case of executable files, run.
    • **LastWrittenTime**: Specifies when the file is last written to, truncated, or overwritten.
| +| 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). ## <library> -This is an internal USMT element. Do not use this element. +This element is an internal USMT element. Don't use this element. ## <location> @@ -1333,7 +1337,7 @@ 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 it 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 will create the appropriate folder on the destination computer if it does not already exist. +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. **Number of occurrences:** Unlimited @@ -1352,7 +1356,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 will be 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 will be migrated. If it is **FALSE**, it will not be 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 include rule. The filter script returns a Boolean value. If the return value is **TRUE**, the object is migrated. If it's **FALSE**, it isn't migrated.| The following example is from the `MigApp.xml` file: @@ -1366,11 +1370,11 @@ The following example is from the `MigApp.xml` file: ### <locationModify> functions -The following functions change the location of objects as they are migrated when using the **<locationModify>** element. These functions are called for every object that the parent **<objectSet>** element is enumerating. The **<locationModify>** element will create the appropriate folder on the destination computer if it does not already exist. +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. - **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 will be written to the node without any subdirectories. If the destination location is a leaf, the migration engine will migrate all of the matching source objects to the same location. If a collision occurs, the normal collision algorithms will apply. + 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. Syntax: `ExactMove(ObjectEncodedLocation)` @@ -1396,18 +1400,18 @@ The following functions change the location of objects as they are migrated when |Setting|Required?|Value| |--- |--- |--- | - |*DestinationRoot*|Yes|The location where the source objects will be moved. If needed, this function will create any subdirectories that were above the longest CSIDL in the source object name.| + |*DestinationRoot*|Yes|The location where the source objects are moved. If needed, this function creates any subdirectories that were above the longest CSIDL in the source object name.| - **RelativeMove** - You can use the RelativeMove function to collect and move data. Note that you can use environment variables in source and destination roots, but they may be defined differently on the source and destination computers. + You can use the RelativeMove function to collect and move data. Environment variables can be used in source and destination roots, but they might be defined differently on the source and destination computers. Syntax: `RelativeMove(SourceRoot,DestinationRoot)` |Setting|Required?|Value| |--- |--- |--- | - |*SourceRoot*|Yes|The location from where the objects will be moved. Any source objects that are enumerated by the parent **<objectSet>** element that are not in this location will not be moved.| - |*DestinationRoot*|Yes|The location where the source objects will be moved to on the destination computer. If needed, this function will create any subdirectories that were above *SourceRoot*.| + |*SourceRoot*|Yes|The location from where the objects are moved. Any source objects that are enumerated by the parent **<objectSet>** 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: @@ -1426,11 +1430,11 @@ For example: ## <\_locDefinition> -This is an internal USMT element. Do not use this element. +This element is an internal USMT element. Don't use this element. ## <manufacturer> -The **<manufacturer>** element defines the manufacturer for the component, but does not affect the migration. +The **<manufacturer>** element defines the manufacturer for the component, but doesn't affect the migration. - **Number of occurrences:** zero or one @@ -1450,7 +1454,7 @@ Syntax: ## <merge> -The **<merge>** element determines what will happen when a collision occurs. A collision is when an object that is migrated is already present on the destination computer. If you do not 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 does not 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 will select the most specific merge rule and apply it 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 is the more specific. +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 and apply it 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. For an example of this element, see [Conflicts and precedence](usmt-conflicts-and-precedence.md). @@ -1471,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 will be 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 will be migrated. If it is **FALSE**, it will not be 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 **<include>** rule. The filter script returns a Boolean value. If the return value is **TRUE**, the object is migrated. If it's **FALSE**, it isn't migrated.| The following example is from the MigUser.xml file: @@ -1512,31 +1516,31 @@ These functions control how collisions are resolved. - **FindFilePlaceByPattern** - The FindFilePlaceByPattern function saves files with an incrementing counter when a collision occurs. It is a string that contains one of each constructs: **<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: **<F>**, **<E>**, **<N>** in any order. Syntax: `FindFilePlaceByPattern(FilePattern)` |Setting|Required?|Value| |--- |--- |--- | - | *FilePattern* | Yes |
  • **<F>** will be replaced by the original file name.
  • **<N>** will be replaced by an incrementing counter until there is no collision with the objects on the destination computer.
  • **<E>** will be replaced by the original file name extension.

For example, ` ().` will change the source file `MyDocument.doc` into `MyDocument (1).doc` on the destination computer. | + | *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. | - **NewestVersion** - The NewestVersion function will resolve conflicts on the destination computer based on the version of the file. + The NewestVersion function resolves conflicts on the destination computer based on the version of the file. Syntax: `NewestVersion(VersionTag)` |Setting|Required?|Value| |--- |--- |--- | - |*VersionTag*|Yes|The version field that will be checked. This can be `FileVersion` or `ProductVersion`. The file with the highest *VersionTag* version determines which conflicts will be resolved based on the file's version. For example, if `Myfile.txt` contains FileVersion 1 and the same file on the destination computer contains FileVersion 2, the file on destination will remain.| + |*VersionTag*|Yes|The version field that is checked. This field can be `FileVersion` or `ProductVersion`. The file with the highest *VersionTag* version determines which conflicts are resolved based on the file's version. For example, if `Myfile.txt` contains FileVersion 1 and the same file on the destination computer contains FileVersion 2, the file on destination remains.| - **HigherValue()** - You can use this function for merging registry values. The registry values will be evaluated as numeric values, and the one with the higher value will determine which registry values will be 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 is merged. - **LowerValue()** - You can use this function for merging registry values. The registry values will be evaluated as numeric values and the one with the lower value will determine which registry values will be 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 is merged. - **SourcePriority** @@ -1556,7 +1560,7 @@ 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. This is 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: <CustomFileName> is the name of the file; for example, "CustomApp". +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. For example, you must specify the following at the beginning of each file: <CustomFileName> is the name of the file; for example, "CustomApp". - **Number of occurrences:** one @@ -1575,8 +1579,8 @@ Syntax: |Setting|Required?|Value| |--- |--- |--- | -|urlid|Yes|*UrlID* is a string identifier that uniquely identifies this .xml file. This parameter must be a no-colon-name as defined by the XML Namespaces specification. Each migration .xml file must have a unique urlid. If two migration .xml files have the same urlid, the second .xml file that is specified on the command line will not be processed. For more information about XML Namespaces, see [Use XML Namespaces](/previous-versions/windows/desktop/ms754539(v=vs.85)).| -|Name|No|Although not required, it is good practice to use the name of the .xml file.| +|urlid|Yes|*UrlID* is a string identifier that uniquely identifies this .xml file. This parameter must be a no-colon-name as defined by the XML Namespaces specification. Each migration .xml file must have a unique urlid. If two migration .xml files have the same urlid, the second .xml file that is specified on the command line isn't processed. For more information about XML Namespaces, see [Use XML Namespaces](/previous-versions/windows/desktop/ms754539(v=vs.85)).| +|Name|No|Although not required, it's good practice to use the name of the .xml file.| The following example is from the `MigApp.xml` file: @@ -1593,7 +1597,7 @@ This filter helper function can be used to filter the migration of files based o |--- |--- | |Property|filesize, dateCreated, dateModified, dateAccessed| |Operator|range, neq, lte, lt, eq, gte, gt| -|valueToCompare|The value we are comparing. For example:
Date: "2008/05/15-2005/05/17", "2008/05/15"
Size: A numeral with B, KB, MB, or GB at the end. "5GB", "1KB-1MB"| +|valueToCompare|The value that is being compared. For example:
Date: "2008/05/15-2005/05/17", "2008/05/15"
Size: A numeral with B, KB, MB, or GB at the end. "5GB", "1KB-1MB"| ```xml @@ -1668,7 +1672,7 @@ 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 will be evaluated first. If all child **<conditions>** elements return **FALSE**, the **<objectSet>** element will evaluate to an empty set. For each parent element, there can be only multiple **<objectSet>** elements. +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. - **Number of occurrences:** Unlimited @@ -1717,15 +1721,15 @@ The following example is from the MigUser.xml file: ## <path> -This is an internal USMT element. Do not use this element. +This element is an internal USMT element. Don't use this element. ## <paths> -This is an internal USMT element. Do not use this element. +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 will be combined. If you are specifying files, you may 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 **<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: ```xml C:\Folder\* [Sample.doc] @@ -1746,8 +1750,8 @@ Syntax: |Setting|Required?|Value| |--- |--- |--- | -| type | Yes | *typeID* can be Registry, File, or Ini. If *typeId* is Ini, then you cannot have a space between *Path* and *object*. For example, the following is correct when type="Ini":
**<pattern type="Ini">%WinAmp5InstPath%\Winamp.ini|WinAmp[keeponscreen]</pattern>** | -| *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 cannot 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 cannot 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 you are 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 is a file named "file].txt", you must specify `c:\documents\mydocs [file^].txt]` instead of `c:\documents\mydocs [file].txt]`.
| +| 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>** | +| *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 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 "file].txt", you must specify `c:\documents\mydocs [file^].txt]` instead of `c:\documents\mydocs [file].txt]`.
| For example: @@ -1773,7 +1777,7 @@ For example: C:\EngineeringDrafts\ [Sample.doc] ``` -- To migrate the `Sample.doc` file from where ever it exists on the C: drive use pattern in the following way. If multiple files exist with the same name on the C: drive, then all of these files will be migrated. +- To migrate the `Sample.doc` file from where ever it exists on the C: drive use pattern in the following way. If multiple files exist with the same name on the C: drive, then all of these files are migrated. ```xml C:\* [Sample.doc] @@ -1783,7 +1787,7 @@ For example: ## <processing> -You can use this element to run a script during a specific point within the migration process. Return values are not expected from the scripts that you specify, and if there are return values, they will be ignored. +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 @@ -1800,15 +1804,15 @@ Syntax: |Setting|Required?|Value| |--- |--- |--- | -| when | Yes | Indicates when the script should be run. This value can be one of the following:
  • **pre-scan** means before the scanning process begins.
  • **scan-success** means after the scanning process has finished successfully.
  • **post-scan** means after the scanning process has finished, whether it was successful or not.
  • **pre-apply** means before the apply process begins.
  • **apply-success** means after the apply process has finished successfully.
  • **post-apply** means after the apply process has finished, whether it was successful or not.
| +| 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 is an internal USMT element. Do not use this element. +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 will be defined by the parameters specified at the **<component>** level, and with the role that you specify here. +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. - **Number of occurrences:** Each **<component>** can have one, two or three child **<role>** elements. @@ -1827,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 do not change the migration behavior — their only purpose is to help you categorize the settings that you are 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 cannot 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 **<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">
| The following example is from the MigUser.xml file. For more examples, see the `MigApp.xml` file: @@ -1862,7 +1866,7 @@ The following example is from the MigUser.xml file. For more examples, see the ` ## <rules> -The **<rules>** element is required in a custom .xml file. This element contains rules that will run during the migration if the parent **<component>** element is selected, unless the child **<conditions>** element, if present, evaluates to **FALSE**. For each **<rules>** element there can be multiple child **<rules>** elements. +The **<rules>** element is required in a custom .xml file. This element contains rules that run during the migration if the parent **<component>** element is selected, unless the child **<conditions>** element, if present, evaluates to **FALSE**. For each **<rules>** element, there can be multiple child **<rules>** elements. - **Number of occurrences:** unlimited @@ -1881,8 +1885,8 @@ Syntax: |Setting|Required?|Value| |--- |--- |--- | -| name | Yes, when **<rules>** is a child to **<namedElements>**
No, when **<rules>** is a child to any other element | When *ID* is specified, any child elements are not processed. Instead, any other **<rules>** elements with the same name that are declared within **<namedElements>** 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 has a context of **User**. If **<rules>** had a context of **System**, it would act as though **<rules>** was not 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 **<rules>** is a child to **<namedElements>**
No, when **<rules>** is a child to any other element | When *ID* is specified, any child elements aren't processed. Instead, any other **<rules>** elements with the same name that are declared within **<namedElements>** 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 has a context of **User**. If **<rules>** had a context of **System**, it would act as though **<rules>** wasn'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 following example is from the MigUser.xml file: @@ -1954,11 +1958,11 @@ The return value that is required by **<script>** 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 ("Arg1","Arg2")`.
The script will be 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 will be migrated. If it is **FALSE**, it will not be migrated.
The return value that is required by **<script>** depends on the parent element.
  • When used within **<variable>**, the return value must be a string.
  • When used within **<objectSet>**, the return value must be a two-dimensional array of strings.
  • When used within **<location>**, the return value must be a valid location that aligns with the type attribute of **<location>**. For example, if <location type="File">, the child script element, if specified, must be a valid file location.
    **Note**
    If you are 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 is a file named "file].txt", specify `c:\documents\mydocs [file^].txt]` instead of `c:\documents\mydocs [file].txt]`.
| +| *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")`.
The script is called for each object that is enumerated by the object sets in the **<include>** rule. The filter script returns a Boolean value. If the return value is **TRUE**, the object is migrated. If it's **FALSE**, it isn't migrated.
The return value that is required by **<script>** depends on the parent element.
  • When used within **<variable>**, the return value must be a string.
  • When used within **<objectSet>**, the return value must be a two-dimensional array of strings.
  • When used within **<location>**, the return value must be a valid location that aligns with the type attribute of **<location>**. For example, if <location type="File">, the child script element, if specified, must be a valid file location.
    **Note**
    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 `c:\documents\mydocs [file^].txt]` instead of `c:\documents\mydocs [file].txt]`.
| Examples: -To migrate the Sample.doc file from any drive on the source computer, use **<script>** as follows. If multiple files exist with the same name, all such files will get migrated. +To migrate the Sample.doc file from any drive on the source computer, use **<script>** as follows. If multiple files exist with the same name, all such files get migrated. ```xml @@ -1980,7 +1984,7 @@ These functions return either a string or a pattern. - **GetStringContent** - You can use GetStringContent with **<script>** elements that are within **<variable>** elements. If possible, this function returns the string representation of the given object. Otherwise, it returns **NULL**. For file objects this function always returns **NULL**. + You can use GetStringContent with **<script>** elements that are within **<variable>** elements. If possible, this function returns the string representation of the given object. Otherwise, it returns **NULL**. For file objects this function, always returns **NULL**. Syntax: `GetStringContent("ObjectType","EncodedLocationPattern", "ExpandContent")` @@ -1988,7 +1992,7 @@ These functions return either a string or a pattern. |--- |--- |--- | | *ObjectType* | Yes | The type of object. Can be Registry or Ini (for an .ini file). | | *EncodedLocationPattern* | Yes |
  • If type of object is Registry, EncodedLocationPattern must be a valid registry path. For example, `HKLM\SOFTWARE\MyKey[]`.
  • If the type of object is Ini, then EncodedLocationPattern must be in the following format:
    **IniFilePath|SectionName[SettingName]**
| - | *ExpandContent* | No (default=TRUE) | Can be **TRUE** or **FALSE**. If **FALSE**, then the given location will not be expanded before it is returned. | + | *ExpandContent* | No (default=TRUE) | Can be **TRUE** or **FALSE**. If **FALSE**, then the given location isn't expanded before returned. | For example: @@ -2000,20 +2004,20 @@ These functions return either a string or a pattern. - **GenerateDrivePatterns** - The `GenerateDrivePatterns` function will iterate all of the available drives and select the ones that match the requested drive type. It will then concatenate 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 will generate `C:\Path [file.txt]`, and other patterns if there are fixed drives other than C:. You cannot specify environment variables with this function. You can use `GenerateDrivePatterns` with **<script>** elements that are within [<objectSet>](#objectset) that are within **<include>**/**<exclude>**. + 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 **<script>** elements that are within [<objectSet>](#objectset) that are within **<include>**/**<exclude>**. Syntax: `GenerateDrivePatterns("PatternSegment","DriveType")` |Setting|Required?|Value| |--- |--- |--- | - | *PatternSegment* | Yes | The suffix of an encoded pattern. It will be concatenated with a drive specification, such as "c:", to form a complete [encoded file pattern](#specifying-locations). For example, "* [*.doc]". *PatternSegment* cannot be an environment variable. | + | *PatternSegment* | Yes | The suffix of an encoded pattern. It is 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:
  • Fixed
  • CDROM
  • Removable
  • Remote
| See the last component in the MigUser.xml file for an example of this element. - **GenerateUserPatterns** - The `GenerateUserPatterns` function will iterate through all users that are being migrated, excluding the currently processed user if **<ProcessCurrentUser>** is **FALSE**, and will expand the specified pattern in the context of each user. For example, if users A, B, and C have profiles in `C:\Documents and Settings`, by calling `GenerateUserPattens('File','%userprofile% [*.doc]','TRUE')`, the helper function will generate the following three patterns: + The `GenerateUserPatterns` function iterates through all users that are being migrated, excluding the currently processed user if **<ProcessCurrentUser>** is **FALSE**, and expands the specified pattern in the context of each user. For example, if users A, B, and C have profiles in `C:\Documents and Settings`, by calling `GenerateUserPattens('File','%userprofile% [*.doc]','TRUE')`, the helper function generates the following three patterns: - "C:\\Documents and Settings\\A\\\* \[\*.doc\]" @@ -2031,9 +2035,9 @@ These functions return either a string or a pattern. **Example:** -If `GenerateUserPattens('File','%userprofile% [*.doc]','FALSE')` is called while USMT is processing user A, then this function will only generate 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 is not migrated, then do not migrate any of the `.doc` files from user X's profile. +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 is example code for this scenario. The first **<rules>** element migrates all `.doc` files on the source computer with the exception of those inside `C:\Documents and Settings`. The second **<rules>** elements will migrate all `.doc` files from `C:\Documents and Settings` with the exception of the `.doc` files in the profiles of the other users. Because the second **<rules>** element will be processed in each migrated user context, the end result will be the desired behavior. The end result is the one we expected. +The following example is example code for this scenario. The first **<rules>** element migrates all `.doc` files on the source computer except for those inside `C:\Documents and Settings`. The second **<rules>** 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 **<rules>** element are processed in each migrated user context, the end result is the desired behavior. The end result is the one we expected. ```xml @@ -2068,8 +2072,8 @@ The `MigXmlHelper.GenerateDocPatterns` helper function invokes the document find |Setting|Required?|Value| |--- |--- |--- | -|*ScanProgramFiles*|No (default = FALSE)|Can be **TRUE** or **FALSE**. The *ScanProgramFiles* parameter determines whether or not the document finder scans the **Program Files** directory to gather registered file extensions for known applications. For example, when set to **TRUE** it will discover and migrate .jpg files under the Photoshop directory, if `.jpg` is a file extension registered to Photoshop.| -|*IncludePatterns*|No (default = TRUE)|Can be **TRUE** or **FALSE**. **TRUE** will generate include patterns and can be added under the **<include>** element. **FALSE** will generate exclude patterns and can be added under the **<exclude>** element.| +|*ScanProgramFiles*|No (default = FALSE)|Can be **TRUE** or **FALSE**. The *ScanProgramFiles* parameter determines whether or not the document finder scans the **Program Files** directory to gather registered file extensions for known applications. For example, when set to **TRUE** it discovers and migrates .jpg files under the Photoshop directory, if `.jpg` is a file extension registered to Photoshop.| +|*IncludePatterns*|No (default = TRUE)|Can be **TRUE** or **FALSE**. **TRUE** generates include patterns and can be added under the **<include>** element. **FALSE** generates exclude patterns and can be added under the **<exclude>** element.| |*SystemDrive*|No (default = FALSE)|Can be **TRUE** or **FALSE**. If **TRUE**, restricts all patterns to the system drive.| ```xml @@ -2097,7 +2101,7 @@ The `MigXmlHelper.GenerateDocPatterns` helper function invokes the document find The following scripts have no return value. You can use the following errors with **<script>** elements that are within **<processing>** elements -- **AskForLogoff()**. Prompts the user to log off at the end of the migration. For example: +- **AskForLogoff()**. Prompts the user to sign out at the end of the migration. For example: ```xml @@ -2105,9 +2109,9 @@ The following scripts have no return value. You can use the following errors wit ``` -- **ConvertToShortFileName(RegistryEncodedLocation)**. If *RegistryEncodedLocation* is the full path of an existing file, this function will convert the file to its short file name and then it will update the registry value. +- **ConvertToShortFileName(RegistryEncodedLocation)**. If *RegistryEncodedLocation* is the full path of an existing file, this function converts the file to its short file name and then it updates the registry value. -- **KillExplorer()**. Stops Explorer.exe for the current user context. This allows access to certain keys and files that are kept open when Explorer.exe is running. For example: +- **KillExplorer()**. Stops Explorer.exe for the current user context. Stopping Explorer.exe allows access to certain keys and files that are kept open when Explorer.exe is running. For example: ```xml @@ -2133,11 +2137,11 @@ The following scripts have no return value. You can use the following errors wit ``` -- **StartService (ServiceName, OptionalParam1, OptionalParam2,…).** Starts the service identified by *ServiceName. ServiceName* is the subkey in `HKLM\System\CurrentControlSet\Services` that holds the data for the given service. The optional parameters, if any, will be passed to the StartService API. For more information, see the [StartServiceA function (winsvc.h)](/windows/win32/api/winsvc/nf-winsvc-startservicea) article. +- **StartService (ServiceName, OptionalParam1, OptionalParam2,…).** Starts the service identified by *ServiceName. ServiceName* is the subkey in `HKLM\System\CurrentControlSet\Services` that holds the data for the given service. The optional parameters, if any, is passed to the StartService API. For more information, see the [StartServiceA function (winsvc.h)](/windows/win32/api/winsvc/nf-winsvc-startservicea) article. - **StopService (ServiceName)**. Stops the service that is identified by *ServiceName. ServiceName* is the subkey in `HKLM\System\CurrentControlSet\Services` that holds the data for the given service. -- **SyncSCM(ServiceShortName).** Reads the Start type value from the registry `(HKLM\System\CurrentControlSet\Services\ServiceShortName [Start])` after it is 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 it's changed by the migration engine, and then synchronizes Service Control Manager (SCM) with the new value. ## <text> @@ -2157,7 +2161,7 @@ Syntax: |Setting|Value| |--- |--- | -|*NormalText*|This is interpreted as normal text.| +|*NormalText*|This text is interpreted as normal text.| For example: @@ -2169,9 +2173,9 @@ For example: ## <unconditionalExclude> -The **<unconditionalExclude>** element excludes the specified files and registry values from the migration, regardless of the other include rules in any of the migration .xml files or in the `Config.xml` file. The objects declared here will not be migrated because this element takes precedence over all other rules. For example, even if there are explicit **<include>** rules to include `.mp3` files, if you specify to exclude them with this option, then they will not be migrated. +The **<unconditionalExclude>** element excludes the specified files and registry values from the migration, regardless of the other include rules in any of the migration .xml files or in the `Config.xml` file. The objects declared here aren't migrated because this element takes precedence over all other rules. For example, even if there are explicit **<include>** rules to include `.mp3` files, if you specify to exclude them with this option, then they aren't migrated. -Use this element if you want to exclude all `.mp3` files from the source computer. Or, if you are backing up `C:\UserData` using another method, you can exclude the entire folder from the migration. Use this element with caution, however, because if an application needs a file that you exclude, the application may not function properly on the destination computer. +Use this element if you want to exclude all `.mp3` files from the source computer. Or, if you're backing up `C:\UserData` using another method, you can exclude the entire folder from the migration. Use this element with caution, however, because if an application needs a file that you exclude, the application might not function properly on the destination computer. - **Number of occurrences:** Unlimited. @@ -2208,11 +2212,11 @@ The following .xml file excludes all `.mp3` files from migration. For additional The **<variable>** element is required in an **<environment>** element. For each **<variable>** element there must be one **<objectSet>**, **<script>**, or **<text>** element. The content of the **<variable>** element assigns a text value to the environment variable. This element has the following three options: -1. If the **<variable>** element contains a **<text>** element, then the value of the variable element will be the value of the **<text>** element. +1. If the **<variable>** element contains a **<text>** element, then the value of the variable element is the value of the **<text>** element. -2. If the **<variable>** element contains a **<script>** element and the invocation of the script produces a non-null string, then the value of the **<variable>** element will be the result of the script invocation. +2. If the **<variable>** element contains a **<script>** element and the invocation of the script produces a non-null string, then the value of the **<variable>** element is the result of the script invocation. -3. If the **<variable>** element contains an **<objectSet>** element and the evaluation of the **<objectSet>** element produces at least one object pattern, then the value of the first object to match the resulting object pattern will be the value of the variable element. +3. If the **<variable>** element contains an **<objectSet>** element and the evaluation of the **<objectSet>** element produces at least one object pattern, then the value of the first object to match the resulting object pattern is the value of the variable element. - **Number of occurrences:** Unlimited @@ -2247,7 +2251,7 @@ The following example is from the `MigApp.xml` file: ## <version> -The **<version>** element defines the version for the component, but does not affect the migration. +The **<version>** element defines the version for the component, but doesn't affect the migration. - **Number of occurrences:** zero or one @@ -2273,25 +2277,25 @@ For example: ## <windowsObjects> -The **<windowsObjects>** element is for USMT internal use only. Do not use this element. +The **<windowsObjects>** element is for USMT internal use only. Don't use this element. ## Appendix ### Specifying locations -- **Specifying encoded locations**. The encoded location used in all of the helper functions is an unambiguous string representation for the name of an object. It is 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. 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. For example, specify the file `C:\Windows\Notepad.exe` like this: `c:\Windows[Notepad.exe]`. Similarly, specify the directory `C:\Windows\System32` like this: `c:\Windows\System32`. (Notice the absence of the `[]` construct.) - Representing the registry is very similar. The default value of a registry key is represented as an empty `[]` construct. For example, the default value for the `HKLM\SOFTWARE\MyKey` registry key will be `HKLM\SOFTWARE\MyKey[]`. + Representing the registry is similar. The default value of a registry key is represented as an empty `[]` construct. For example, the default value for the `HKLM\SOFTWARE\MyKey` registry key is `HKLM\SOFTWARE\MyKey[]`. -- **Specifying location patterns**. You specify a location pattern in a way that is similar to how you specify an actual location. The exception is that both the node and leaf part accept patterns. However, a pattern from the node does not extend to the leaf. +- **Specifying location patterns**. You specify a location pattern in a way that is similar to how you specify an actual location. The exception is that both the node and leaf part accept patterns. However, a pattern from the node doesn't extend to the leaf. - For example, the pattern `c:\Windows\*` will match the Windows directory and all subdirectories, but it will not match any of the files in those directories. To match the files as well, you must specify `c:\Windows\*[*]`. + For example, the pattern `c:\Windows\*` matches the Windows directory and all subdirectories, but it doesn't match any of the files in those directories. To match the files as well, you must specify `c:\Windows\*[*]`. ### Internal USMT functions -The following functions are for internal USMT use only. Do not use them in an .xml file. +The following functions are for internal USMT use only. Don't use them in an .xml file. - *AntiAlias* @@ -2347,4 +2351,4 @@ The following version tags contain values that can be compared: ## Related articles -[USMT XML reference](usmt-xml-reference.md) +- [USMT XML reference](usmt-xml-reference.md).