diff --git a/windows/deployment/do/waas-delivery-optimization-reference.md b/windows/deployment/do/waas-delivery-optimization-reference.md index 856311df11..d770f57022 100644 --- a/windows/deployment/do/waas-delivery-optimization-reference.md +++ b/windows/deployment/do/waas-delivery-optimization-reference.md @@ -204,7 +204,7 @@ This setting specifies the minimum content file size in MB enabled to use Peer C ### Maximum Download Bandwidth -MDM Setting: **DOMaxUploadBandwidth** +MDM Setting: **DOMaxDownloadBandwidth** Deprecated in Windows 10, version 2004. This setting specifies the maximum download bandwidth that can be used across all concurrent Delivery Optimization downloads in kilobytes per second (KB/s). **A default value of "0"** means that Delivery Optimization dynamically adjusts and optimize the maximum bandwidth used. @@ -259,7 +259,7 @@ Starting in Windows 10, version 1803, set this policy to restrict peer selection If Group mode is set, Delivery Optimization connects to locally discovered peers that are also part of the same Group (have the same Group ID). -The Local Peer Discovery (DNS-SD) option can only be set via MDM delivered policies on Windows 11 builds. This feature can be enabled in supported Windows 10 builds by setting the `HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\Windows\DeliveryOptimization\DORestrictPeerSelectionBy` value to **2**. +In Windows 11, the Local Peer Discovery (DNS-SD) option can be set via MDM or Group Policy. However, in Windows 10, this feature can be enabled by setting the `HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\Windows\DeliveryOptimization\DORestrictPeerSelectionBy` value to **2**. ### Delay background download from HTTP (in secs) diff --git a/windows/deployment/update/waas-branchcache.md b/windows/deployment/update/waas-branchcache.md index 05c5f63d80..7856c98348 100644 --- a/windows/deployment/update/waas-branchcache.md +++ b/windows/deployment/update/waas-branchcache.md @@ -35,7 +35,7 @@ Whether you use BranchCache with Configuration Manager or WSUS, each client that In Windows 10, version 1607, the Windows Update Agent uses Delivery Optimization by default, even when the updates are retrieved from WSUS. When using BranchCache with Windows client, set the Delivery Optimization **Download mode** to '100' (Bypass) to allow clients to use the Background Intelligent Transfer Service (BITS) protocol with BranchCache instead. For instructions on how to use BranchCache in Distributed Cache mode with WSUS, see the section WSUS and Configuration Manager with BranchCache in Distributed Cache mode. > [!Note] -> Setting [Download mode](../do/waas-delivery-optimization-reference.md#download-mode) to '100' (Bypass) is only available in Windows 10, version 1607 and later, not in Windows 11. BranchCache isn't supported for Windows 11. +> [Bypass Download mode (100)](../do/waas-delivery-optimization-reference.md#download-mode) is only available in Windows 10 (starting in version 1607) and deprecated in Windows 11. BranchCache isn't supported for content downloaded using Delivery Optimization in Windows 11. ## Configure servers for BranchCache diff --git a/windows/deployment/usmt/getting-started-with-the-user-state-migration-tool.md b/windows/deployment/usmt/getting-started-with-the-user-state-migration-tool.md index 9eebdd0921..b007b891a8 100644 --- a/windows/deployment/usmt/getting-started-with-the-user-state-migration-tool.md +++ b/windows/deployment/usmt/getting-started-with-the-user-state-migration-tool.md @@ -1,83 +1,98 @@ --- -title: User State Migration Tool (USMT) - Getting Started (Windows 10) -description: Plan, collect, and prepare your source computer for migration using the User State Migration Tool (USMT). +title: User State Migration Tool (USMT) - Getting Started +description: Plan, collect, and prepare the source computer for migration using the User State Migration Tool (USMT). manager: aaroncz ms.author: frankroj ms.prod: windows-client author: frankroj ms.topic: article ms.technology: itpro-deploy -ms.date: 11/01/2022 +ms.date: 01/03/2024 +appliesto: + - ✅ Windows 11 + - ✅ Windows 10 --- # Getting started with the User State Migration Tool (USMT) -This article outlines the general process that you should follow to migrate files and settings. +This article outlines the general process to follow to migrate files and settings. -## Step 1: Plan your migration +## Step 1: Plan the migration -1. [Plan Your Migration](usmt-plan-your-migration.md). Depending on whether your migration scenario is refreshing or replacing computers, you can choose an online migration or an offline migration using Windows Preinstallation Environment (WinPE) or the files in the Windows.old directory. For more information, see [Common Migration Scenarios](usmt-common-migration-scenarios.md). +1. [Plan The Migration](usmt-plan-your-migration.md). Depending on whether the migration scenario is refreshing or replacing computers, an online migration or an offline migration can be chosen. Offline migrations can use either Windows Preinstallation Environment (WinPE) or the files in the **Windows.old** directory. For more information, see [Common Migration Scenarios](usmt-common-migration-scenarios.md). -1. [Determine What to Migrate](usmt-determine-what-to-migrate.md). Data you might consider migrating includes end-user information, applications settings, operating-system settings, files, folders, and registry keys. +1. [Determine What to Migrate](usmt-determine-what-to-migrate.md). Data to consider migrating includes end-user information, applications settings, operating-system settings, files, folders, and registry keys. -1. Determine where to store data. Depending on the size of your migration store, you can store the data remotely, locally in a hard-link migration store or on a local external storage device, or directly on the destination computer. For more information, see [Choose a Migration Store Type](usmt-choose-migration-store-type.md). +1. Determine where to store data. Depending on the size of the migration store, data can be stored in one of the following locations: -1. Use the `/GenMigXML` command-line option to determine which files will be included in your migration, and to determine whether any modifications are necessary. For more information, see [ScanState Syntax](usmt-scanstate-syntax.md) + - Remotely. + - Locally in a hard-link migration store or on a local external storage device. + - Directly on the destination computer. -1. Modify copies of the `Migration.xml` and `MigDocs.xml` files and create custom .xml files, if it's required. To modify the migration behavior, such as migrating the **Documents** folder but not the **Music** folder, you can create a custom .xml file or modify the rules in the existing migration .xml files. The document finder, or `MigXmlHelper.GenerateDocPatterns` helper function, can be used to automatically find user documents on a computer without creating extensive custom migration .xml files. + For more information, see [Choose a Migration Store Type](usmt-choose-migration-store-type.md). + +1. Use the `/GenMigXML` command-line option to determine which files are included in the migration, and to determine whether any modifications are necessary. For more information, see [ScanState Syntax](usmt-scanstate-syntax.md) + +1. If necessary, modify copies of the `Migration.xml` and `MigDocs.xml` files and create custom **.xml** files. To modify the migration behavior, such as migrating the **Documents** folder but not the **Music** folder, custom **.xml** file can be created or modify the rules in the existing migration **.xml** files. The document finder, or `MigXmlHelper.GenerateDocPatterns` helper function, can be used to automatically find user documents on a computer without creating extensive custom migration **.xml** files. > [!IMPORTANT] - > We recommend that you always make and modify copies of the .xml files included in User State Migration Tool (USMT) 10.0. Never modify the original .xml files. + > + > Microsoft recommends to always make copies of the **.xml** files included in User State Migration Tool (USMT) and then modify the copies. Never modify the original **.xml** files. - You can use the `MigXML.xsd` file to help you write and validate the .xml files. For more information about how to modify these files, see [USMT XML Reference](usmt-xml-reference.md). + The `MigXML.xsd` file can be used to help write and validate the **.xml** files. For more information about how to modify these files, see [USMT XML Reference](usmt-xml-reference.md). + +1. Create a [Config.xml File](usmt-configxml-file.md) if to exclude any components from the migration. To create this file, run the `ScanState.exe` command with the following options: -1. Create a [Config.xml File](usmt-configxml-file.md) if you want to exclude any components from the migration. To create this file, run the `ScanState.exe` command with the following options: - [/genconfig](usmt-scanstate-syntax.md#migration-rule-options). - - [/i](usmt-scanstate-syntax.md#migration-rule-options) - as arguments specify the .xml files that you plan to use with `ScanState.exe`. - + - [/i](usmt-scanstate-syntax.md#migration-rule-options) - as arguments specify the **.xml** files that are being used with `ScanState.exe`. + For example, the following command creates a `Config.xml` file by using the `MigDocs.xml` and `MigApp.xml` files: ```cmd ScanState.exe /genconfig:Config.xml /i:MigDocs.xml /i:MigApp.xml /v:13 /l:ScanState.log ``` -1. Open the `Config.xml` that was generated in the previous step. Review the migration state of each of the components listed in the `Config.xml` file. If necessary, edit the `Config.xml` file and specify `migrate=no` for any components that you don't want to migrate. +1. Open the `Config.xml` that was generated in the previous step. Review the migration state of each of the components listed in the `Config.xml` file. If necessary, edit the `Config.xml` file and specify `migrate=no` for any components that don't need to be migrated. ## Step 2: Collect files and settings from the source computer 1. Back up the source computer. -1. Close all applications. If some applications are running when you run the `ScanState.exe` command, USMT might not migrate all of the specified data. For example, if Microsoft Office Outlook is open, USMT might not migrate PST files. +1. Close all applications. If some applications are running when the `ScanState.exe` command is run, USMT might not migrate all of the specified data. For example, if Microsoft Office Outlook is open, USMT might not migrate PST files. > [!NOTE] - > USMT will fail if it cannot migrate a file or setting unless you specify the `/C` option. When you specify the `/C` option, USMT will ignore the errors, and log an error every time that it encounters a file that is being used that USMT did not migrate. You can use the `` section in the `Config.xml` file to specify which errors should be ignored, and which should cause the migration to fail. + > + > USMT fails if it can't migrate a file or setting unless the `/c` option is specified. When the `/c` option is specified, USMT ignores the errors, and logs an error every time that it encounters a file that is being used that USMT didn't migrate. The `` section in the `Config.xml` file can be used to specify which errors should be ignored, and which should cause the migration to fail. -1. Run the `ScanState.exe` command on the source computer to collect files and settings. You should specify all of the .xml files that you want the `ScanState.exe` command to use. For example, +1. Run the `ScanState.exe` command on the source computer to collect files and settings. All of the **.xml** files that the `ScanState.exe` command needs to use should be specified. For example, ```cmd ScanState.exe \\server\migration\mystore /config:Config.xml /i:MigDocs.xml /i:MigApp.xml /v:13 /l:ScanState.log ``` > [!NOTE] - > If the source computer is running Windows 7, or Windows 8, you must run the `ScanState.exe` command in **Administrator** mode. To run in **Administrator** mode, right-click **Command Prompt**, and then select **Run As Administrator**. For more information about the how the `ScanState.exe` command processes and stores the data, see [How USMT Works](usmt-how-it-works.md). + > + > The `ScanState.exe` command must be run in **Administrator** mode on the source computer. To run in **Administrator** mode, right-click **Command Prompt**, and then select **Run As Administrator**. For more information about how the `ScanState.exe` command processes and stores the data, see [How USMT Works](usmt-how-it-works.md). -1. Run the `UsmtUtils.exe` command with the `/Verify` option to ensure that the store you created isn't corrupted. +1. Run the `UsmtUtils.exe` command with the `/Verify` option to ensure that the created store isn't corrupted. ## Step 3: Prepare the destination computer and restore files and settings 1. Install the operating system on the destination computer. -1. Install all applications that were on the source computer. Although it isn't always required, we recommend installing all applications on the destination computer before you restore the user state. This makes sure that migrated settings are preserved. +1. Install all applications that were on the source computer. Although it isn't always required, Microsoft recommends installing all applications on the destination computer before restoring the user state. Installing all applications before restoring user state makes sure that migrated settings are preserved. > [!NOTE] - > The application version that is installed on the destination computer should be the same version as the one on the source computer. USMT does not support migrating the settings for an older version of an application to a newer version. The exception to this is Microsoft Office, which USMT can migrate from an older version to a newer version. + > + > The application version that is installed on the destination computer should be the same version as the one on the source computer. USMT doesn't support migrating the settings for an older version of an application to a newer version. The exception for this rule is Microsoft Office. USMT can migrate from an older version of Microsoft Office to a newer version of Microsoft Office. -1. Close all applications. If some applications are running when you run the `LoadState.exe ` command, USMT might not migrate all of the specified data. For example, if Microsoft Office Outlook is open, USMT might not migrate PST files. +1. Close all applications. If some applications are running when the `LoadState.exe` command runs, USMT might not migrate all of the specified data. For example, if Microsoft Office Outlook is open, USMT might not migrate PST files. > [!NOTE] - > Use `/C` to continue your migration if errors are encountered, and use the `` section in the `Config.xml` file to specify which errors should be ignored, and which errors should cause the migration to fail. + > + > Use `/c` to continue the migration if errors are encountered. Use the `` section in the `Config.xml` file to specify which errors should be ignored, and which errors should cause the migration to fail. -1. Run the `LoadState.exe ` command on the destination computer. Specify the same set of .xml files that you specified when you used the `ScanState.exe` command. However, you don't have to specify the `Config.xml` file, unless you want to exclude some of the files and settings that you migrated to the store. For example, you might want to migrate the My Documents folder to the store, but not to the destination computer. To do this, modify the `Config.xml` file and specify the updated file by using the `LoadState.exe ` command. Then, the `LoadState.exe ` command will migrate only the files and settings that you want to migrate. For more information about how the `LoadState.exe ` command processes and migrates data, see [How USMT Works](usmt-how-it-works.md). +1. Run the `LoadState.exe` command on the destination computer. Specify the same set of **.xml** files that were specified when the `ScanState.exe` command was used. However, the `Config.xml` file doesn't always need to be specified. The `Config.xml` file only needs to be specified to exclude some of the files and settings that were migrated to the store. For example, the **Documents** folder was migrated to the store, but doesn't need to be migrated to the destination computer. For example, modify the `Config.xml` file and specify the updated file by using the `LoadState.exe` command. Then, the `LoadState.exe` command migrates only the files and settings that need to be migrated. For more information about how the `LoadState.exe` command processes and migrates data, see [How USMT Works](usmt-how-it-works.md). For example, the following command migrates the files and settings: @@ -86,6 +101,7 @@ This article outlines the general process that you should follow to migrate file ``` > [!NOTE] - > Run the `LoadState.exe ` command in administrator mode. To do this, right-click **Command Prompt**, and then click **Run As Administrator**. + > + > Run the `LoadState.exe` command in administrator mode. To do this, right-click **Command Prompt**, and then select **Run As Administrator**. -5. Sign out after you run the `LoadState.exe ` command. Some settings, such as fonts, wallpaper, and screen saver settings, won't take effect until the next time that the user logs on. +1. Sign out after running the `LoadState.exe` command. Some settings, such as fonts, wallpaper, and screen saver settings, won't take effect until the next time that the user logs on. diff --git a/windows/deployment/usmt/migrate-application-settings.md b/windows/deployment/usmt/migrate-application-settings.md index f8c2dded9b..7c2dc34d50 100644 --- a/windows/deployment/usmt/migrate-application-settings.md +++ b/windows/deployment/usmt/migrate-application-settings.md @@ -1,36 +1,39 @@ --- -title: Migrate Application Settings (Windows 10) +title: Migrate Application Settings description: Learn how to author a custom migration .xml file that migrates the settings of an application that isn't migrated by default using MigApp.xml. manager: aaroncz ms.author: frankroj ms.prod: windows-client author: frankroj -ms.date: 11/01/2022 +ms.date: 01/03/2024 ms.topic: article ms.technology: itpro-deploy +appliesto: + - ✅ Windows 11 + - ✅ Windows 10 --- # Migrate Application Settings -You can create a custom .xml file to migrate specific line-of-business application settings or to change the default migration behavior of the User State Migration Tool (USMT) 10.0. For ScanState and LoadState to use this file, you must specify the custom .xml file on both command lines. +A custom **.xml** file can be created to migrate specific line-of-business application settings or to change the default migration behavior of the User State Migration Tool (USMT). For **ScanState** and **LoadState** to use this file, the custom **.xml** file must be specified on both command lines. -This article defines how to author a custom migration .xml file that migrates the settings of an application that isn't migrated by default using `MigApp.xml`. You should migrate the settings after you install the application, but before the user runs the application for the first time. +This article defines how to author a custom migration **.xml** file that migrates the settings of an application that isn't migrated by default using `MigApp.xml`. The settings should be migrated after the application is installed, but before the user runs the application for the first time. -This article doesn't contain information about how to migrate applications that store settings in an application-specific store, only the applications that store the information in files or in the registry. It also doesn't contain information about how to migrate the data that users create using the application. For example, if the application creates .doc files using a specific template, this article doesn't discuss how to migrate the .doc files and templates themselves. +This article doesn't contain information about how to migrate applications that store settings in an application-specific store, only the applications that store the information in files or in the registry. It also doesn't contain information about how to migrate the data that users create using the application. For example, if the application creates **.doc** files using a specific template, this article doesn't discuss how to migrate the **.doc** files and templates themselves. -## Before you begin +## Before beginning -You should identify a test computer that contains the operating system of your source computers, and the application whose settings you want to migrate. For example, if you're planning on migrating from Windows 7 to Windows 10, install Windows 7 on your test computer and then install the application. +A test computer that contains the operating system of the source computers should be identified. The test computer should also have the applications whose settings need to be migrated. For example, if migrating from Windows 10 to Windows 11, install Windows 10 on the test computer and then install the applications. ## Step 1: Verify that the application is installed on the source computer, and that it's the same version as the version to be installed on the destination computer -Before USMT migrates the settings, you need it to check whether the application is installed on the source computer, and that it's the correct version. If the application isn't installed on the source computer, you probably don't want USMT to spend time searching for the application's settings. More importantly, if USMT collects settings for an application that isn't installed, it may migrate settings that will cause the destination computer to function incorrectly. You should also investigate whether there's more than one version of the application because the new version may not store the settings in the same place. Mismatched application versions may lead to unexpected results on the destination computer. +Before USMT migrates the settings, check whether the application is installed on the source computer, and that it's the correct version. If the application isn't installed on the source computer, USMT still spends time searching for the application's settings. More importantly, if USMT collects settings for an application that isn't installed, it could migrate settings that cause the destination computer to function incorrectly. Also determine whether there's more than one version of the application because the new version could store the settings in a different location. Mismatched application versions could lead to unexpected results on the destination computer. -There are many ways to detect if an application is installed. The best practice is to check for an application uninstall key in the registry, and then search the computer for the executable file that installed the application. It's important that you check for both of these items, because sometimes different versions of the same application share the same uninstall key. So even if the key is there, it may not correspond to the version of the application that you want. +There are many ways to detect if an application is installed. The best practice is to check for an application uninstall key in the registry, and then search the computer for the executable file that installed the application. It's important to check for both of these items, because sometimes different versions of the same application share the same uninstall key. Even if the key is there, it could correspond to a different version of the application that is wanted. ### Check the registry for an application uninstall key -When many applications are installed (especially those installed using the Microsoft® Windows® Installer technology), an application uninstall key is created under: +When many applications are installed (especially those installed using the Microsoft Windows Installer technology), an application uninstall key is created under: `HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall` @@ -38,110 +41,123 @@ For example, when Adobe Acrobat Reader 7 is installed, it creates a key named: `HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall \{AC76BA86-7AD7-1033-7B44-A70000000000}` -Therefore, if a computer contains this key, then Adobe Acrobat Reader 7 is installed on the computer. You can check for the existence of a registry key using the `DoesObjectExist` helper function. +Therefore, if a computer contains this key, then Adobe Acrobat Reader 7 is installed on the computer. The existence of a registry key can be checked using the `DoesObjectExist` helper function. -Usually, you can find this key by searching under +Usually, this key can be found by searching under: `HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall` -for the name of the application, the name of the application executable file, or for the name of the company that makes the application. You can use the Registry Editor, `Regedit.exe` located in the `%SystemRoot%`, to search the registry. +for the name of the application, the name of the application executable file, or for the name of the company that makes the application. The Registry Editor, `Regedit.exe` located in the `%SystemRoot%`, can be used to search the registry. ### Check the file system for the application executable file -You should also check the application binaries for the executable that installed the application. To check for application binaries, you'll first need to determine where the application is installed and what the name of the executable is. Most applications store the installation location of the application binaries in the registry. You should search the registry for the name of the application, the name of the application executable, or for the name of the company that makes the application, until you find the registry value that contains the installation path. Once you've determined the path to the application executable, you can use the `DoesFileVersionMatch` helper function to check for the correct version of the application executable. For an example of how to use the `DoesFileVersionMatch` helper function, see the Windows Live™ Messenger section of the `MigApp.xml` file. +The application binaries for the executable that installed the application should also be checked. To check for application binaries, determine where the application is installed and what the name of the executable is. Most applications store the installation location of the application binaries in the registry. The registry should be searched on one of the following items until the registry value that contains the installation path is found: + +- The name of the application. +- The name of the application executable. +- The name of the company that makes the application. + +Once the path to the application executable is determined, the `DoesFileVersionMatch` helper function can be used to check for the correct version of the application executable. For an example of how to use the `DoesFileVersionMatch` helper function, see the Windows Live™ Messenger section of the `MigApp.xml` file. ## Step 2: Identify settings to collect and determine where each setting is stored on the computer -Next, you should go through the user interface and make a list of all of the available settings. You can reduce the list if there are settings that you don't want to migrate. To determine where each setting is stored, you'll need to change each setting and monitor the activity on the registry and the file system. You don't need to migrate the binary files and registry settings that are made when the application is installed because you'll need to reinstall the application onto the destination computer. You only need to migrate those settings that are customizable. +Next, go through the user interface and make a list of all of the available settings. The list can be reduced if there are settings that don't need to be migrated. To determine where each setting is stored, change the setting. As the setting is changed, monitor the activity on the registry and the file system through a tool such as [Process Monitor](/sysinternals/downloads/procmon). The binary files and registry settings that are created when the application is installed don't need to be migrated. When the application is reinstalled onto the destination computer, it recreates those settings. Only the customized settings need to be migrated. ### How to determine where each setting is stored -1. Download a file and registry monitoring tool, such as the Regmon and Filemon tools, from the [Windows Sysinternals Web site](/sysinternals/). +1. Download a file and registry monitoring tool, such as [Process Monitor (Procmon)](/sysinternals/downloads/procmon), from the [Sysinternals Web site](/sysinternals/). -2. Shut down as many applications as possible to limit the registry and file system activity on the computer. +1. Shut down as many applications as possible to limit the registry and file system activity on the computer. -3. Filter the output of the tools so it only displays changes being made by the application. +1. Filter the output of the tools so it only displays changes being made by the application. > [!NOTE] - > Most applications store their settings under the user profile. That is, the settings stored in the file system are under the `%UserProfile%` directory, and the settings stored in the registry are under the `HKEY_CURRENT_USER` hive. For these applications you can filter the output of the file and registry monitoring tools to show activity only under these locations. This will considerably reduce the amount of output that you will need to examine. + > + > Most applications store their settings under the user profile. That is, the settings stored in the file system are under the `%UserProfile%` directory, and the settings stored in the registry are under the `HKEY_CURRENT_USER` hive. For these applications, the output of the file and registry monitoring tools can be filtered to show activity only under these locations. This filtering considerably reduces the amount of output that needs to be examined. -4. Start the monitoring tool(s), change a setting, and look for registry and file system writes that occurred when you changed the setting. Make sure the changes you make actually take effect. For example, if you're changing a setting in Microsoft Word by selecting a check box in the **Options** dialog box, the change typically won't take effect until you close the dialog box by clicking **OK**. +1. Start the monitoring tool(s), change a setting, and look for registry and file system writes that occurred when the setting was changed. Make sure the changes made actually take effect. For example, if changing a setting in Microsoft Word by selecting a check box in the **Options** dialog box, the change typically doesn't take effect until the dialog box is closed by selecting **OK**. -5. When the setting is changed, note the changes to the file system and registry. There may be more than one file or registry values for each setting. You should identify the minimal set of file and registry changes that are required to change this setting. This set of files and registry keys is what you will need to migrate in order to migrate the setting. +1. When the setting is changed, note the changes to the file system and registry. There could be more than one file or registry values for each setting. The minimal set of file and registry changes that are required to change this setting should be identified. This set of files and registry keys is what needs to be migrated in order to migrate the setting. > [!NOTE] + > > Changing an application setting invariably leads to writing to registry keys. If possible, filter the output of the file and registry monitor tool to display only writes to files and registry keys/values. ## Step 3: Identify how to apply the gathered settings -If the version of the application on the source computer is the same as the one on the destination computer, then you don't have to modify the collected files and registry keys. By default, USMT migrates the files and registry keys from the source location to the corresponding location on the destination computer. For example, if a file was collected from the `C:\Documents and Settings\User1\My Documents` folder and the profile directory on the destination computer is located at `D:\Users\User1`, then USMT will automatically migrate the file to `D:\Users\User1\My Documents`. However, you may need to modify the location of some settings in the following three cases: +If the version of the application on the source computer is the same as the one on the destination computer, then the collected files and registry keys don't need to be modified. By default, USMT migrates the files and registry keys from the source location to the corresponding location on the destination computer. For example, if a file was collected from the `C:\Users\User1\Documents` folder and the profile directory on the destination computer is located at `D:\Users\User1`, then USMT automatically migrates the file to `D:\Users\User1\Documents`. However, the location of some settings might need to be modified in the following three cases: ### Case 1: The version of the application on the destination computer is newer than the one on the source computer -In this case, the newer version of the application may be able to read the settings from the source computer without modification. That is, the data collected from an older version of the application is sometimes compatible with the newer version of the application. However, you may need to modify the setting location if either of the following conditions is true: +In this case, the newer version of the application might be able to read the settings from the source computer without modification. That is, the data collected from an older version of the application is sometimes compatible with the newer version of the application. However, the setting location might need to be modified if either of the following conditions is true: -- **The newer version of the application has the ability to import settings from an older version.** This mapping usually happens the first time a user runs the newer version after the settings have been migrated. Some applications import settings automatically after settings are migrated. However, other applications will only do import settings if the application was upgraded from the older version. When the application is upgraded, a set of files and/or registry keys is installed that indicates the older version of the application was previously installed. If you perform a clean installation of the newer version (which is the case in most migrations), the computer doesn't contain this set of files and registry keys so the mapping doesn't occur. In order to trick the newer version of the application into initiating this import process, your migration script may need to create these files and/or registry keys on the destination computer. +- **The newer version of the application has the ability to import settings from an older version.** This mapping usually happens the first time a user runs the newer version after the settings are migrated. Some applications import settings automatically after settings are migrated. However, other applications only import settings if the application was upgraded from the older version. When the application is upgraded, a set of files and/or registry keys is installed that indicates the older version of the application was previously installed. If a clean installation of the newer version is performed, the computer doesn't contain these files and registry keys. If the files and registry keys aren't present, the mapping doesn't occur. In order to trick the newer version of the application into initiating this import process, the migration script might need to create these files and/or registry keys on the destination computer. - To identify which files and/or registry keys/values need to be created to cause the import, you should upgrade the older version of the application to the newer one and monitor the changes made to the file system and registry by using the same process described in [How to determine where each setting is stored](#how-to-determine-where-each-setting-is-stored). Once you know the set of files that the computer needs, you can use the **<addObjects>** element to add them to the destination computer. + To identify which files and/or registry keys/values need to be created so that the import works: -- **The newer version of the application can't read settings from the source computer and it's also unable to import the settings into the new format.** In this case, you'll need to create a mapping for each setting from the old locations to the new locations. To create the mapping, determine where the newer version stores each setting using the process described in [How to determine where each setting is stored](#how-to-determine-where-each-setting-is-stored). After you've created the mapping, apply the settings to the new location on the destination computer using the **<locationModify>** element, and the `RelativeMove` and `ExactMove` helper functions. + 1. Upgrade the older version of the application to the newer one. + 1. Monitor the changes made to the file system and registry by using the same process described in [How to determine where each setting is stored](#how-to-determine-where-each-setting-is-stored). + + Once the set of files that the computer needs is known, the **\** element can be used to add them to the destination computer. + +- **The newer version of the application can't read settings from the source computer and it's also unable to import the settings into the new format.** In this case, create a mapping for each setting from the old locations to the new locations. To create the mapping, determine where the newer version stores each setting using the process described in [How to determine where each setting is stored](#how-to-determine-where-each-setting-is-stored). After creating the mapping, apply the settings to the new location on the destination computer using the **\** element, and the `RelativeMove` and `ExactMove` helper functions. ### Case 2: The destination computer already contains settings for the application -We recommend that you migrate the settings after you install the application, but before the user runs the application for the first time. We recommend this process because this process ensures that there are no settings on the destination computer when you migrate the settings. If you must install the application before the migration, you should delete any existing settings using the **<destinationCleanup>** element. If for any reason you want to preserve the settings that are on the destination computer, you can use the **<merge>** element and `DestinationPriority` helper function. +Microsoft recommends migrating the settings after the application is installed, but before the user runs the application for the first time. Microsoft recommends this process because this process ensures that there are no settings on the destination computer when the settings are migrated. If the application must be installed before the migration, any existing settings should be deleted using the **\** element. If for any reason the settings need to be preserved that are on the destination computer, the **\** element and `DestinationPriority` helper function can be used. -### Case 3: The application overwrites settings when it's installed +### Case 3: The application overwrites settings when installed -We recommend that you migrate the settings after you install the application, but before the user runs the application for the first time. We recommend this process because this process ensures that there are no settings on the destination computer when you migrate the settings. Also, when some applications are installed, they overwrite any existing settings that are on the computer. In this scenario, if you migrated the data before you installed the application, your customized settings would be overwritten. This scenario is common for applications that store settings in locations that are outside of the user profile (typically these settings are settings that apply to all users). These universal settings are sometimes overwritten when an application is installed, and they're replaced by default values. To avoid this problem, you must install these applications before migrating the files and settings to the destination computer. By default with USMT, data from the source computer overwrites data that already exists in the same location on the destination computer. +Microsoft recommends migrating the settings after the application is installed, but before the user runs the application for the first time. Microsoft recommends this process because this process ensures that there are no settings on the destination computer when the settings are migrated. Also, when some applications are installed, they overwrite any existing settings that are on the computer. In this scenario, if the data was migrated before the application was installed, the customized settings would be overwritten. This scenario is common for applications that store settings in locations that are outside of the user profile (typically these settings are settings that apply to all users). These universal settings are sometimes overwritten when an application is installed, and they're replaced by default values. To avoid this problem, these applications must be installed before migrating the files and settings to the destination computer. By default with USMT, data from the source computer overwrites data that already exists in the same location on the destination computer. ## Step 4: Create the migration XML component for the application -After you have completed steps 1 through 3, you'll need to create a custom migration .xml file that migrates the application based on the information that you now have. You can use the `MigApp.xml` file as a model because it contains examples of many of the concepts discussed in this article. You can also see [Custom XML Examples](usmt-custom-xml-examples.md) for another sample .xml file. +After completing steps 1 through 3, create a custom migration **.xml** file that migrates the application based on the updated information. The `MigApp.xml` file can be used as a model because it contains examples of many of the concepts discussed in this article. Also see [Custom XML Examples](usmt-custom-xml-examples.md) for another sample **.xml** file. - > [!NOTE] - > We recommend that you create a separate .xml file instead of adding your script to the `MigApp.xml` file. This is because the `MigApp.xml` file is a very large file and it will be difficult to read and edit. In addition, if you reinstall USMT for some reason, the `MigApp.xml` file will be overwritten by the default version of the file and you will lose your customized version. +> [!NOTE] +> +> Microsoft recommends creating a separate **.xml** file instead of adding a script to the `MigApp.xml` file. A separate **.xml** file is recommended because the `MigApp.xml` file is a large file and it's difficult to read and edit. In addition, if USMT is reinstalled, the `MigApp.xml` file is overwritten with the default version of the file and the customized version is lost. > [!IMPORTANT] -> Some applications store information in the user profile, such as application installation paths, the computer name, etc., should not be migrated. You should make sure to exclude these files and registry keys from the migration. +> +> Some applications store information in the user profile, such as application installation paths, the computer name, etc. Application information stored in the user profile shouldn't be migrated and should be excluded from the migration. -Your script should do the following actions: +The script should do the following actions: -1. Check whether the application and correct version is installed by: +1. Check if the correct version of the application is installed: - - Searching for the installation uninstall key under `HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall` using the `DoesObjectExist` helper function. + - Search for the installation uninstall key under `HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall` using the `DoesObjectExist` helper function. - - Checking for the correct version of the application executable file using the `DoesFileVersionMatch` helper function. + - Check for the correct version of the application executable file using the `DoesFileVersionMatch` helper function. -2. If the correct version of the application is installed, then ensure that each setting is migrated to the appropriate location on the destination computer. +1. If the correct version of the application is installed, then ensure that each setting is migrated to the appropriate location on the destination computer. - - If the versions of the applications are the same on both the source and destination computers, migrate each setting using the **<include>** and **<exclude>** elements. + - If the versions of the applications are the same on both the source and destination computers, migrate each setting using the **\** and **\** elements. - - If the version of the application on the destination computer is newer than the one on the source computer, and the application can't import the settings, your script should either: - 1. Add the set of files that trigger the import using the **<addObjects>** element - 2. Create a mapping that applies the old settings to the correct location on the destination computer using the **<locationModify>** element, and the `RelativeMove` and `ExactMove` helper functions. + - If the version of the application on the destination computer is newer than the one on the source computer, and the application can't import the settings, the script should either: - - If you must install the application before migrating the settings, delete any settings that are already on the destination computer using the **<destinationCleanup>** element. + 1. Add the set of files that trigger the import using the **\** element. + 1. Create a mapping that applies the old settings to the correct location on the destination computer using the **\** element, and the `RelativeMove` and `ExactMove` helper functions. -For information about the .xml elements and helper functions, see [XML Elements Library](usmt-xml-elements-library.md). + - If the application must be installed before migrating the settings, delete any settings that are already on the destination computer using the **\** element. + +For information about the **.xml** elements and helper functions, see [XML Elements Library](usmt-xml-elements-library.md). ## Step 5: Test the application settings migration -On a test computer, install the operating system that will be installed on the destination computers. For example, if you're planning on migrating from Windows 7 to Windows 10, install Windows 10 and the application. Next, run LoadState on the test computer and verify that all settings migrate. Make corrections if necessary and repeat the process until all the necessary settings are migrated correctly. +On a test computer, install the operating system that will be installed on the destination computers. For example, if planning on migrating from Windows 10 to Windows 11, install Windows 11, and then install the application in Windows 11. Next, run **LoadState** on the test computer and verify that all settings migrate. Make corrections if necessary and repeat the process until all the necessary settings are migrated correctly. -To speed up the time it takes to collect and migrate the data, you can migrate only one user at a time, and you can exclude all other components from the migration except the application that you're testing. To specify only **User1** in the migration, enter: +To speed up the time it takes to collect and migrate the data, only one user can be migrated at a time. All other components can be excluded from the migration except the application that is being tested. To specify only **User1** in the migration, enter: ```cmd /ue:*\* /ui:user1 ``` -For more information, see the [Exclude files and settings](usmt-exclude-files-and-settings.md) article and the [User options](usmt-scanstate-syntax.md#user-options) section in the [ScanState syntax](usmt-scanstate-syntax.md) article. To troubleshoot a problem, check the progress log, and the ScanState and LoadState logs, which contain warnings and errors that may point to problems with the migration. +For more information, see the [Exclude files and settings](usmt-exclude-files-and-settings.md) article and the [User options](usmt-scanstate-syntax.md#user-options) section in the [ScanState syntax](usmt-scanstate-syntax.md) article. To troubleshoot a problem, check the progress log, the **ScanState** log, and the **LoadState** log. The logs contain warnings and errors that could point to problems with the migration. ## Related articles -[USMT XML reference](usmt-xml-reference.md) - -[Conflicts and precedence](usmt-conflicts-and-precedence.md) - -[XML elements library](usmt-xml-elements-library.md) - -[Log files](usmt-log-files.md) +- [USMT XML reference](usmt-xml-reference.md). +- [Conflicts and precedence](usmt-conflicts-and-precedence.md). +- [XML elements library](usmt-xml-elements-library.md). +- [Log files](usmt-log-files.md). diff --git a/windows/deployment/usmt/migration-store-types-overview.md b/windows/deployment/usmt/migration-store-types-overview.md index 25d04bc4c2..71640e70fa 100644 --- a/windows/deployment/usmt/migration-store-types-overview.md +++ b/windows/deployment/usmt/migration-store-types-overview.md @@ -1,18 +1,21 @@ --- -title: Migration Store Types Overview (Windows 10) -description: Learn about the migration store types and how to determine which migration store type best suits your needs. +title: Migration Store Types Overview +description: Learn about the migration store types and how to determine which migration store type best suits the organization's needs. manager: aaroncz ms.author: frankroj ms.prod: windows-client author: frankroj -ms.date: 11/01/2022 +ms.date: 01/03/2024 ms.topic: article ms.technology: itpro-deploy +appliesto: + - ✅ Windows 11 + - ✅ Windows 10 --- # Migration Store Types Overview -When planning your migration, you should determine which migration store type best meets your needs. As part of these considerations, determine how much space is required to run the User State Migration Tool (USMT) 10.0 components on your source and destination computers. You should also determine the space needed to create and host the migration store, whether you're using a local share, network share, or storage device. +When a migration is being planned, which migration store type best meets the organization's needs should be determined. As part of these considerations, determine how much space is required to run the User State Migration Tool (USMT) components on the source and destination computers. The space needed to create and host the migration store should also be determined, whether using a local share, network share, or storage device. ## Migration store types @@ -20,7 +23,7 @@ This section describes the three migration store types available in USMT. ### Uncompressed (UNC) -The uncompressed (UNC) migration store is an uncompressed directory with a mirror image of the folder hierarchy being migrated. Each directory and file retains the same access permissions that it has on the local file system. You can use Windows Explorer to view this migration store type. Settings are stored in a catalog file that also describes how to restore files on the destination computer. +The uncompressed (UNC) migration store is an uncompressed directory with a mirror image of the folder hierarchy being migrated. Each directory and file retains the same access permissions that it has on the local file system. Windows Explorer can be used to view this migration store type. Settings are stored in a catalog file that also describes how to restore files on the destination computer. ### Compressed @@ -28,9 +31,9 @@ The compressed migration store is a single image file that contains all files be ### Hard-Link -A hard-link migration store functions as a map that defines how a collection of bits on the hard disk are "wired" into the file system. You use the new USMT hard-link migration store in the PC Refresh scenario only. You only use hard-link migration stores in Refresh scenarios because the hard-link migration store is maintained on the local computer while the old operating system is removed and the new operating system is installed. Using a hard-link migration store saves network bandwidth and minimizes the server use needed to accomplish the migration. +A hard-link migration store functions as a map that defines how a collection of bits on the hard disk are "wired" into the file system. The USMT hard-link migration store is only used in the PC Refresh scenario. Hard-link migration stores are only used in Refresh scenarios because the hard-link migration store is maintained on the local computer. The hard-link store is maintained on the computer while the old operating system is removed and the new operating system is installed. Using a hard-link migration store saves network bandwidth and minimizes the server use needed to accomplish the migration. -You use the command-line option `/hardlink` to create a hard-link migration store, which functions the same as an uncompressed migration store. Files aren't duplicated on the local computer when user state is captured, nor are they duplicated when user state is restored. For more information, see [Hard-Link Migration Store](usmt-hard-link-migration-store.md). +The command-line option `/hardlink` is used to create a hard-link migration store, which functions the same as an uncompressed migration store. Files aren't duplicated on the local computer when user state is captured. They also aren't duplicated when user state is restored. For more information, see [Hard-Link Migration Store](usmt-hard-link-migration-store.md). The following flowchart illustrates the procedural differences between a local migration store and a remote migration store. In this example, a hard-link migration store is used for the local store. @@ -38,23 +41,32 @@ The following flowchart illustrates the procedural differences between a local m ## Local store vs. remote store -If you have enough space and you're migrating the user state back to the same computer, storing data on a local device is normally the best option to reduce server storage costs and network performance issues. You can store the data locally either on a different partition or on a removable device such as a USB flash drive (UFD). Also, depending on the imaging technology that you're using, you might be able to store the data on the partition that is being re-imaged, if the data will be protected from deletion during the process. To increase performance, store the data on high-speed drives that use a high-speed network connection. It's also good practice to ensure that the migration is the only task the server is performing. +If there's enough space and the user state is being migrated back to the same computer, storing data on a local device is normally the best option to reduce server storage costs and network performance issues. The data can also be stored locally either on a different partition or on a removable device such as a USB flash drive (UFD). Also, the data might be able to be stored on the partition that is being re-imaged if the data can be protected from deletion during the imaging process. One example of an imaging technology that is capable of storing the data on the partition that is being reimaged is Microsoft Configuration Manager. To increase performance, store the data on high-speed drives that use a high-speed network connection. It's also good practice to ensure that the migration is the only task the server is performing. -If there isn't enough local disk space, or if you're moving the user state to another computer, then you must store the data remotely such as on a shared folder, on removable media, or you can store it directly on the destination computer. For example: +If there isn't enough local disk space, or if moving the user state to another computer, then the data must be stored remotely such as in one of the following destinations: -1. Create and share `C:\store` on the destination computer -2. Run the `ScanState.exe` command on the source computer and save the files and settings to `\\\store` -3. Run the `LoadState.exe ` command on the destination computer and specify `C:\Store` as the store location. +- Shared folder. +- Removable media. +- Directly on the destination computer. -By doing this process, you don't need to save the files to a server. +For example: + +1. Create and share `C:\store` on the destination computer. + +1. Run the `ScanState.exe` command on the source computer and save the files and settings to `\\\store`. + +1. Run the `LoadState.exe` command on the destination computer and specify `C:\Store` as the store location. + +By doing this process, files don't need to be stored to a server. > [!IMPORTANT] -> If possible, have users store their data within their `%UserProfile%\My Documents` and `%UserProfile%\Application Data` folders. This will reduce the chance of USMT missing critical user data that is located in a directory that USMT is not configured to check. +> +> If possible, have users store their data within their `%UserProfile%\Documents` and `%UserProfile%\Application Data` folders. Having users store their data at these locations reduces the chance of USMT missing critical user data that is located in a directory that USMT isn't configured to check. ### The /localonly command-line option -You should use this 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). +This option should be used 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). ## Related articles -[Plan your migration](usmt-plan-your-migration.md) +- [Plan the migration](usmt-plan-your-migration.md). diff --git a/windows/deployment/usmt/offline-migration-reference.md b/windows/deployment/usmt/offline-migration-reference.md index c4c1311fb0..0c2913a370 100644 --- a/windows/deployment/usmt/offline-migration-reference.md +++ b/windows/deployment/usmt/offline-migration-reference.md @@ -1,64 +1,70 @@ --- -title: Offline Migration Reference (Windows 10) +title: Offline Migration Reference description: Offline migration enables the ScanState tool to run inside a different Windows OS than the Windows OS from which ScanState is gathering files and settings. manager: aaroncz ms.author: frankroj ms.prod: windows-client author: frankroj -ms.date: 11/01/2022 +ms.date: 01/03/2024 ms.topic: article ms.technology: itpro-deploy +appliesto: + - ✅ Windows 11 + - ✅ Windows 10 --- # Offline Migration Reference -Offline migration enables the ScanState tool to run inside a different Windows operating system than the Windows operating system from which ScanState is gathering files and settings. There are two primary offline scenarios: +Offline migration enables the **ScanState** tool to run inside a different Windows operating system than the Windows operating system from which **ScanState** is gathering files and settings. There are two primary offline scenarios: -- **Windows PE.** The ScanState tool can be run from within Windows PE, gathering files and settings from the offline Windows operating system on that machine. +- **Windows PE.** The **ScanState** tool can be run from within Windows PE, gathering files and settings from the offline Windows operating system on that machine. -- **Windows.old.** The ScanState tool can now gather files and settings from the Windows.old directory that is created during Windows installation on a partition that contains a previous installation of Windows. For example, the ScanState tool can run in Windows 10, gathering files from a previous Windows 7or Windows 8 installation contained in the Windows.old directory. +- **Windows.old.** The **ScanState** tool can gather files and settings from the **Windows.old** directory. The **Windows.old** directory is created during Windows installation on a partition that contains a previous installation of Windows. For example, the **ScanState** tool can run in Windows, gathering files from a previous Windows installation contained in the **Windows.old** directory. -When you use User State Migration Tool (USMT) 10.0 to gather and restore user state, offline migration reduces the cost of deployment by: +When using the User State Migration Tool (USMT) to gather and restore user state, offline migration reduces the cost of deployment by: -- **Reducing complexity.** In computer-refresh scenarios, migrations from the Windows.old directory reduce complexity by eliminating the need for the ScanState tool to be run before the operating system is deployed. Also, migrations from the Windows.old directory enable ScanState and LoadState to be run successively. +- **Reducing complexity.** In computer-refresh scenarios, migrations from the **Windows.old** directory reduce complexity by eliminating the need for the **ScanState** tool to be run before the operating system is deployed. Also, migrations from the **Windows.old** directory enable **ScanState** and **LoadState** to be run successively. -- **Improving performance.** When USMT runs in an offline Windows Preinstallation Environment (WinPE) environment, it has better access to the hardware resources. Running USMT in WinPE may increase performance on older machines with limited hardware resources and numerous installed software applications. +- **Improving performance.** When USMT runs in an offline Windows Preinstallation Environment (WinPE) environment, it has better access to the hardware resources. Running USMT in WinPE can increase performance on older machines with limited hardware resources and numerous installed software applications. -- **New recovery scenario.** In scenarios where a machine no longer restarts properly, it might be possible to gather user state with the ScanState tool from within WinPE. +- **New recovery scenario.** In scenarios where a machine no longer restarts properly, it might be possible to gather user state with the **ScanState** tool from within WinPE. -## What will migrate offline? +## What migrates offline? The following user data and settings migrate offline, similar to an online migration: -- Data and registry keys specified in MigXML +- Data and registry keys specified in MigXML. -- User accounts +- User accounts. -- Application settings +- Application settings. -- Limited set of operating-system settings +- Limited set of operating-system settings. -- EFS files +- EFS files. -- Internet Explorer Favorites +- Favorites. -For exceptions to what you can migrate offline, see [What Does USMT Migrate?](usmt-what-does-usmt-migrate.md) +For exceptions to what can be migrated offline, see [What Does USMT Migrate?](usmt-what-does-usmt-migrate.md) ## What offline environments are supported? +All currently supported + The following table defines the supported combination of online and offline operating systems in USMT. |Running Operating System|Offline Operating System| -|--- |--- | -|WinPE 5.0 or greater, with the MSXML library|Windows 7, Windows 8, Windows 10| -|Windows 7, Windows 8, Windows 10|Windows.old directory| +|---|---| +|Currently supported version of WinPE, with the MSXML library|Windows 7, Windows 8, Windows 10, Windows 11| +|Windows 10, Windows 11|**Windows.old** directory| > [!NOTE] -> It is possible to run the ScanState tool while the drive remains encrypted by suspending Windows BitLocker Drive Encryption before booting into WinPE. For more information, see [this Microsoft site](/previous-versions/windows/it-pro/windows-7/ee424315(v=ws.10)). +> +> It is possible to run the **ScanState** tool while the drive remains encrypted by suspending Windows BitLocker Drive Encryption before booting into WinPE. For more information, see [BitLocker operations guide: Suspend and resume](/windows/security/operating-system-security/data-protection/bitlocker/operations-guide#suspend-and-resume). If using a Microsoft Configuration Manager task sequence, see [Task sequence steps: Disable BitLocker](/mem/configmgr/osd/understand/task-sequence-steps#BKMK_DisableBitLocker). ## User-group membership and profile control -User-group membership isn't preserved during offline migrations. You must configure a **<ProfileControl>** section in the `Config.xml` file to specify the groups that the migrated users should be made members of. The following example places all migrated users into the Users group: +User-group membership isn't preserved during offline migrations. A **\** section must be configured in the `Config.xml` file to specify the groups that the migrated users should be made members of. The following example places all migrated users into the Users group: ```xml @@ -84,62 +90,90 @@ An offline migration can either be enabled by using a configuration file on the |Component|Option|Description| |--- |--- |--- | -|*ScanState.exe*|**/offline:***<path to Offline.xml>*|This command-line option enables the offline-migration mode and requires a path to an Offline.xml configuration file.| -|*ScanState.exe*|**/offlineWinDir:***<Windows directory>*|This command-line option enables the offline-migration mode and starts the migration from the location specified. It's only for use in WinPE offline scenarios where the migration is occurring from a Windows directory.| -|*ScanState.exe*|**/OfflineWinOld:***<Windows.old directory>*|This command-line option enables the offline migration mode and starts the migration from the location specified. It's only intended to be used in Windows.old migration scenarios, where the migration is occurring from a Windows.old directory.| +|*ScanState.exe*|**/offline:***\*|This command-line option enables the offline-migration mode and requires a path to an Offline.xml configuration file.| +|*ScanState.exe*|**/offlineWinDir:***\*|This command-line option enables the offline-migration mode and starts the migration from the location specified. It's only for use in WinPE offline scenarios where the migration is occurring from a Windows directory.| +|*ScanState.exe*|**/OfflineWinOld:***\*|This command-line option enables the offline migration mode and starts the migration from the location specified. Only use in **Windows.old** migration scenarios, where the migration is occurring from a **Windows.old** directory.| -You can use only one of the `/offline`, `/offlineWinDir`, or `/OfflineWinOld` command-line options at a time. USMT doesn't support using more than one together. +Only one of the `/offline`, `/offlineWinDir`, or `/OfflineWinOld` command-line options can be used at a time. USMT doesn't support using more than one together. ## Environment variables -The following system environment variables are necessary in the scenarios outlined below. +System environment variables are necessary in the scenarios outlined in the following table: |Variable|Value|Scenario| |--- |--- |--- | -|*USMT_WORKING_DIR*|Full path to a working directory|Required when USMT binaries are located on read-only media, which doesn't support the creation of log files or temporary storage. To set the system environment variable, at a command prompt type the following command: 
Set USMT_WORKING_DIR=[path to working directory]
| -*|MIG_OFFLINE_PLATFORM_ARCH*|32 or 64|While operating offline, this environment variable defines the architecture of the offline system, if the system doesn't match the WinPE and `ScanState.exe` architecture. This environment variable enables the 32-bit ScanState application to gather data from a computer with 64-bit architecture, or the 64-bit ScanState application to gather data from a computer with 32-bit architecture. Specifying the architecture is required when auto-detection of the offline architecture doesn't function properly. For example, to set this system environment variable for a 32-bit architecture, at a command prompt type the following command: 
Set MIG_OFFLINE_PLATFORM_ARCH=32
| +|**USMT_WORKING_DIR**|Full path to a working directory|Required when USMT binaries are located on read-only media, which doesn't support the creation of log files or temporary storage. To set the system environment variable, at a command prompt type the following command:

`Set USMT_WORKING_DIR=`| +|**MIG_OFFLINE_PLATFORM_ARCH**|32 or 64|While operating offline, this environment variable defines the architecture of the offline system, if the system doesn't match the WinPE and `ScanState.exe` architecture. This environment variable enables the 32-bit **ScanState** application to gather data from a computer with 64-bit architecture, or the 64-bit **ScanState** application to gather data from a computer with 32-bit architecture. Specifying the architecture is required when auto-detection of the offline architecture doesn't function properly. For example, to set this system environment variable for a 32-bit architecture, at a command prompt type the following command:

`Set MIG_OFFLINE_PLATFORM_ARCH=32`| ## Offline.xml elements -Use an `Offline.xml` file when running the ScanState tool on a computer that has multiple Windows directories. The `Offline.xml` file specifies which directories to scan for windows files. An `Offline.xml` file can be used with the `/offline` option as an alternative to specifying a single Windows directory path with the `/offlineDir` option. +Use an `Offline.xml` file when running the **ScanState** tool on a computer that has multiple Windows directories. The `Offline.xml` file specifies which directories to scan for windows files. An `Offline.xml` file can be used with the `/offline` option as an alternative to specifying a single Windows directory path with the `/offlineDir` option. -### <offline> +### \ This element contains other elements that define how an offline migration is to be performed. -Syntax: `` `` +Syntax: -### <winDir> +```xml + +``` -This element is a required child of **<offline>** and contains information about how the offline volume can be selected. The migration will be performed from the first element of **<winDir>** that contains a valid Windows system volume. +### \ -Syntax: `` `` +This element is a required child of **\** and contains information about how the offline volume can be selected. The migration is performed from the first element of **\** that contains a valid Windows system volume. -### <path> +Syntax: -This element is a required child of **<winDir>** and contains a file path pointing to a valid Windows directory. Relative paths are interpreted from the ScanState tool's working directory. +```xml + +``` -Syntax: ` C:\Windows ` +### \ --or- +This element is a required child of **\** and contains a file path pointing to a valid Windows directory. Relative paths are interpreted from the **ScanState** tool's working directory. -Syntax, when used with the **<mappings>** element: ` C:\, D:\ ` +Syntax: -### <mappings> +```xml + C:\Windows +``` -This element is an optional child of **<offline>**. When specified, the **<mappings>** element will override the automatically detected WinPE drive mappings. Each child **<path>** element will provide a mapping from one system volume to another. Additionally, mappings between folders can be provided, since an entire volume can be mounted to a specific folder. +or when used with the **\** element: -Syntax: `` `` +Syntax: -### <failOnMultipleWinDir> +```xml + C:\, D:\ +``` -This element is an optional child of **<offline>**. The **<failOnMultipleWinDir>** element allows the user to specify that the migration should fail when USMT detects that there are multiple instances of Windows installed on the source machine. When the **<failOnMultipleWinDir>** element isn't present, the default behavior is that the migration doesn't fail. +### \ -Syntax: `1` +This element is an optional child of **\**. When specified, the **\** element overrides the automatically detected WinPE drive mappings. Each child **\** element provides a mapping from one system volume to another. Additionally, mappings between folders can be provided, since an entire volume can be mounted to a specific folder. --or- +Syntax: -Syntax: `0` +```xml + +``` + +### \ + +This element is an optional child of **\**. The **\** element allows the user to specify that the migration should fail when USMT detects that there are multiple instances of Windows installed on the source machine. When the **\** element isn't present, the default behavior is that the migration doesn't fail. + +Syntax: + +```xml +1 +``` + +or + +Syntax: + +```xml +0 +``` ### Offline .xml Example @@ -158,4 +192,4 @@ The following XML example illustrates some of the elements discussed earlier in ## Related articles -[Plan your migration](usmt-plan-your-migration.md) +- [Plan the migration](usmt-plan-your-migration.md). diff --git a/windows/deployment/usmt/understanding-migration-xml-files.md b/windows/deployment/usmt/understanding-migration-xml-files.md index d39b9bf79e..5530d60b05 100644 --- a/windows/deployment/usmt/understanding-migration-xml-files.md +++ b/windows/deployment/usmt/understanding-migration-xml-files.md @@ -1,52 +1,57 @@ --- -title: Understanding Migration XML Files (Windows 10) -description: Learn how to modify the behavior of a basic User State Migration Tool (USMT) 10.0 migration by using XML files. +title: Understanding Migration XML Files +description: Learn how to modify the behavior of a basic User State Migration Tool (USMT) migration by using XML files. manager: aaroncz ms.author: frankroj ms.prod: windows-client author: frankroj -ms.date: 11/23/2022 +ms.date: 01/03/2024 ms.topic: article ms.technology: itpro-deploy +appliesto: + - ✅ Windows 11 + - ✅ Windows 10 --- # Understanding migration XML files -You can modify the behavior of a basic User State Migration Tool (USMT) 10.0 migration by using XML files; these files provide instructions on where and how the USMT tools should gather and apply files and settings. USMT includes three XML files that you can use to customize a basic migration: the `MigDocs.xml` and `MigUser.xml` files, which modify how files are discovered on the source computer, and the MigApps.xml file, which is required in order to migrate supported application settings. You can also create and edit custom XML files and a `Config.xml` file to further customize your migration. +The behavior of a basic User State Migration Tool (USMT) migration can be modified by using XML files. These files provide instructions on where and how the USMT tools should gather and apply files and settings. USMT includes three XML files that can be used to customize a basic migration: the `MigDocs.xml` and `MigUser.xml` files, which modify how files are discovered on the source computer, and the MigApps.xml file, which is required in order to migrate supported application settings. Custom XML files and a `Config.xml` file can be created and edited to further customize the migration. This article provides an overview of the default and custom migration XML files and includes guidelines for creating and editing a customized version of the `MigDocs.xml` file. The `MigDocs.xml` file uses the new `GenerateDocPatterns` function available in USMT to automatically find user documents on a source computer. ## Overview of the Config.xml file -The `Config.xml` file is the configuration file created by the `/genconfig` option of the ScanState tool; it can be used to modify which operating-system components are migrated by USMT. The `Config.xml` file can be used with other XML files, such as in the following example: +The `Config.xml` file is the configuration file created by the `/genconfig` option of the **ScanState** tool. It can be used to modify which operating-system components USMT migrates. The `Config.xml` file can be used with other XML files, such as in the following example: `ScanState.exe /i:migapps.xml /i:MigDocs.xml /genconfig:c:\myFolder\Config.xml` When used this way, the `Config.xml` file tightly controls aspects of the migration, including user profiles, data, and settings, without modifying or creating other XML files. For more information about the `Config.xml` file, see [Customize USMT XML Files](usmt-customize-xml-files.md) and [Config.xml File](usmt-configxml-file.md). > [!NOTE] -> When modifying the XML elements in the `Config.xml` file, you should edit an element and set the **migrate** property to **no**, rather than deleting the element from the file. If you delete the element instead of setting the property, the component may still be migrated by rules in other XML files. +> +> When modifying the XML elements in the `Config.xml` file, set the **migrate** property on an element to **no** instead of deleting the element from the file. If the element is deleted instead of setting the property, rules in other XML files can still migrate the component. ## Overview of the MigApp.xml file -The `MigApp.xml` file installed with USMT includes instructions to migrate the settings for the applications listed in [What Does USMT Migrate?](usmt-what-does-usmt-migrate.md). You must include the `MigApp.xml` file when using the ScanState and LoadState tools, by using the `/i` option in order to migrate application settings. The `MigDocs.xml` and `MigUser.xml` files don't migrate application settings. You can create a custom XML file to include additional applications. For more information, see [Customize USMT XML Files](usmt-customize-xml-files.md). +The `MigApp.xml` file installed with USMT includes instructions to migrate the settings for the applications listed in [What Does USMT Migrate?](usmt-what-does-usmt-migrate.md). In order to migrate application settings, the `MigApp.xml` file must be included when using the **ScanState** and **LoadState** tools by using the `/i` option. The `MigDocs.xml` and `MigUser.xml` files don't migrate application settings. A custom XML file can be created to include additional applications. For more information, see [Customize USMT XML Files](usmt-customize-xml-files.md). > [!IMPORTANT] -> The MigApps.xml file will only detect and migrate .pst files that are linked to Microsoft Office Outlook. For more information about migrating .pst files that are not linked to Outlook, see [Sample migration rules for customized versions of XML files](#sample-migration-rules-for-customized-versions-of-xml-files). +> +> The `MigApps.xml` file only detects and migrates **.pst** files that are linked to Microsoft Office Outlook. For more information about migrating **.pst** files that aren't linked to Outlook, see [Sample migration rules for customized versions of XML files](#sample-migration-rules-for-customized-versions-of-xml-files). ## Overview of the MigDocs.xml file -The `MigDocs.xml` file uses the new `GenerateDocPatterns` helper function to create instructions for USMT to migrate files from the source computer, based on the location of the files. You can use the `MigDocs.xml` file with the ScanState and LoadState tools to perform a more targeted migration than using USMT without XML instructions. +The `MigDocs.xml` file uses the new `GenerateDocPatterns` helper function to create instructions for USMT to migrate files from the source computer, based on the location of the files. The `MigDocs.xml` file can be used with the **ScanState** and **LoadState** tools to perform a more targeted migration than using USMT without XML instructions. The default `MigDocs.xml` file migrates the following data: - All files on the root of the drive except `%WINDIR%`, `%PROGRAMFILES%`, `%PROGRAMDATA%`, or `%USERS%`. -- All folders in the root directory of all fixed drives. For example: `c:\data_mail\*[*]` +- All folders in the root directory of all fixed drives. For example: `c:\data_mail\*[*]`. -- All files from the root of the Profiles folder, except for files in the system profile. For example: `c:\users\name[mail.pst]` +- All files from the root of the Profiles folder, except for files in the system profile. For example: `c:\users\name[mail.pst]`. -- All folders from the root of the Profiles folder, except for the system-profile folders. For example: `c:\users\name\new folder\*[*]` +- All folders from the root of the Profiles folder, except for the system-profile folders. For example: `c:\users\name\new folder\*[*]`. - Standard shared folders: @@ -92,7 +97,7 @@ The default `MigDocs.xml` file migrates the following data: - FOLDERID_RecordedTV -The default `MigDocs.xml` file won't migrate the following data: +The default `MigDocs.xml` file doesn't migrate the following data: - Files tagged with both the **hidden** and **system** attributes. @@ -102,11 +107,11 @@ The default `MigDocs.xml` file won't migrate the following data: - Folders that contain installed applications. -You can also use the `/genmigxml` option with the ScanState tool to review and modify what files will be migrated. +The `/genmigxml` option can be used with the **ScanState** tool to review and modify what files are migrated. ## Overview of the MigUser.xml file -The `MigUser.xml` file includes instructions for USMT to migrate user files based on file name extensions. You can use the `MigUser.xml` file with the ScanState and LoadState tools to perform a more targeted migration than using USMT without XML instructions. The `MigUser.xml` file will gather all files from the standard user-profile folders, and any files on the computer with the specified file name extensions. +The `MigUser.xml` file includes instructions for USMT to migrate user files based on file name extensions. The `MigUser.xml` file can be used with the **ScanState** and **LoadState** tools to perform a more targeted migration than using USMT without XML instructions. The `MigUser.xml` file gathers all files from the standard user-profile folders, and any files on the computer with the specified file name extensions. The default `MigUser.xml` file migrates the following data: @@ -133,38 +138,41 @@ The default `MigUser.xml` file migrates the following data: `.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. The default `MigUser.xml` file doesn't migrate the following data: - Files tagged with both the **Hidden** and **System** attributes. -- Files and folders on removable drives, +- Files and folders on removable drives. - Data from the `%WINDIR%`, `%PROGRAMFILES%`, `%PROGRAMDATA%` folders. - ACLS for files in folders outside the user profile. -You can make a copy of the `MigUser.xml` file and modify it to include or exclude standard user-profile folders and file name extensions. If you know all of the extensions for the files you want to migrate from the source computer, use the `MigUser.xml` file to move all of your relevant data, regardless of the location of the files. However, this provision may result in a migration that contains more files than intended. For example, if you choose to migrate all .jpg files, you may migrate image files such as thumbnails and logos from legacy applications that are installed on the source computer. +The `MigUser.xml` file can be copied and then the copy modified to include or exclude standard user-profile folders and file name extensions. If all of the extensions for the files that need to be migrated from the source computer are known, use the `MigUser.xml` file to move all of the relevant data, regardless of the location of the files. However, adding in all file extensions that need to be migrated to the `MigUser.xml` file can result in a migration that contains more files than intended. For example, if all **.jpg** files are migrated, it can also migrate image files such as thumbnails and logos from legacy applications that are installed on the source computer. > [!NOTE] -> Each file name extension you include in the rules within the `MigUser.xml` file increases the amount of time needed for the ScanState tool to gather the files for the migration. If you are migrating more than 300 file types, you may experience a slow migration. For more information about other ways to organize the migration of your data, see the [Using multiple XML files](#using-multiple-xml-files) section of this article. +> +> Each file name extension included in the rules within the `MigUser.xml` file increases the amount of time needed for the **ScanState** tool to gather the files for the migration. If more than 300 file types are being migrated, the migration experience can be slow. For more information about other ways to organize the migration of the data, see the [Using multiple XML files](#using-multiple-xml-files) section of this article. ## Using multiple XML files -You can use multiple XML files with the ScanState and LoadState tools. Each of the default XML files included with or generated by USMT is configured for a specific component of the migration. You can also use custom XML files to supplement these default files with more migration rules. +Multiple XML files can be used with the **ScanState** and **LoadState** tools. Each of the default XML files included with or generated by USMT is configured for a specific component of the migration. Custom XML files can also be used to supplement these default files with more migration rules. |XML migration file|Modifies the following components:| |--- |--- | -|*Config.xml file*|Operating-system components such as desktop wallpaper and background theme.
You can also overload `Config.xml` to include some application and document settings by generating the `Config.xml` file with the other default XML files. For more information, see [Customize USMT XML Files](usmt-customize-xml-files.md) and [Config.xml File](usmt-configxml-file.md).| -|*MigApps.xml file*|Applications settings.| -|*MigUser.xml* or *MigDocs.xml* files|User files and profile settings.| -|*Custom XML files*|Application settings, user profile settings, or user files, beyond the rules contained in the other XML files.| +|**Config.xml file**|Operating-system components such as desktop wallpaper and background theme.
The `Config.xml` can also be extended to include some application and document settings by generating the `Config.xml` file with the other default XML files. For more information, see [Customize USMT XML Files](usmt-customize-xml-files.md) and [Config.xml File](usmt-configxml-file.md).| +|**MigApps.xml file**|Applications settings.| +|**MigUser.xml** or **MigDocs.xml** files|User files and profile settings.| +|**Custom XML files**|Application settings, user profile settings, or user files, beyond the rules contained in the other XML files.| -For example, you can use all of the XML migration file types for a single migration, as in the following example: +For example, all of the XML migration file types can be used for a single migration, as in the following example: ```cmd ScanState.exe /config:c:\myFolder\Config.xml /i:migapps.xml /i:MigDocs.xml /i:CustomRules.xml @@ -173,54 +181,61 @@ ScanState.exe /config:c:\myFolder\Config.xml /i:migapps.xml /i:MigDocs.x ### XML rules for migrating user files > [!IMPORTANT] -> You should not use the `MigUser.xml` and `MigDocs.xml` files together in the same command. Using both XML files can result in duplication of some migrated files. This occurs when conflicting target-location instructions are given in each XML file. The target file will be stored once during the migration, but will be applied by each XML file to a different location on the destination computer. +> +> The `MigUser.xml` and `MigDocs.xml` files shouldn't be used together in the same command. Using both XML files can result in duplication of some migrated files. Duplication of some migrated files can occur when conflicting target-location instructions are given in each XML file. The target file is stored once during the migration, but each XML file applies the file to a different location on the destination computer. -If your data set is unknown or if many files are stored outside of the standard user-profile folders, the `MigDocs.xml` is a better choice than the `MigUser.xml` file, because the `MigDocs.xml` file will gather a broader scope of data. The `MigDocs.xml` file migrates folders of data based on location. The `MigUser.xml` file migrates only the files with the specified file name extensions. +If the data set is unknown or if many files are stored outside of the standard user-profile folders, the `MigDocs.xml` is a better choice than the `MigUser.xml` file, because the `MigDocs.xml` file gathers a broader scope of data. The `MigDocs.xml` file migrates folders of data based on location. The `MigUser.xml` file migrates only the files with the specified file name extensions. -If you want more control over the migration, you can create custom XML files. See [Creating and editing a custom XML file](#creating-and-editing-a-custom-xml-file) for more information. +For more control over the migration, create custom XML files. For more information on creating custom XML files, see [Creating and editing a custom XML file](#creating-and-editing-a-custom-xml-file). ## Creating and editing a custom XML file -You can use the `/genmigxml` command-line option to determine which files will be included in your migration. The `/genmigxml` option creates a file in a location you specify, so that you can review the XML rules and make modifications as necessary. +The `/genmigxml` command-line option can be used to determine which files are included in the migration. The `/genmigxml` option creates a file in a specified location. The XML rules in the file can then be reviewed and if necessary, modifications made. > [!NOTE] -> If you reinstall USMT, the default migration XML files will be overwritten and any customizations you make directly to these files will be lost. Consider creating separate XML files for your custom migration rules and saving them in a secure location. +> +> If USMT is reinstalled, the default migration XML files are overwritten and any customizations made to these files are lost. Consider creating separate XML files for the custom migration rules and saving them in a secure location. To generate the XML migration rules file for a source computer: 1. Select **Start** > **All Programs** > **Accessories** -2. Right-click **Command Prompt**, and then select **Run as**. +1. Right-click **Command Prompt**, and then select **Run as**. -3. Select an account with administrator privileges, supply a password, and then select **OK**. +1. Select an account with administrator privileges, supply a password, and then select **OK**. -4. At the command prompt, enter: +1. At the command prompt, enter: ```cmd cd /d ScanState.exe /genmigxml: ``` - Where *<USMTpath>* is the location on your source computer where you've saved the USMT files and tools, and *<filepath.xml>* is the full path to a file where you can save the report. For example, enter: + where: + + - **\** - location on the source computer of the saved USMT files and tools. + - **\** - full path to a file where the report can be saved. + + For example, enter: ```cmd cd /d c:\USMT - ScanState.exe /genmigxml:"C:\Documents and Settings\USMT Tester\Desktop\genMig.xml" + ScanState.exe /genmigxml:"C:\Users\USMT Tester\Desktop\genMig.xml" ``` ### The GenerateDocPatterns function -The `MigDocs.xml` file calls the `GenerateDocPatterns` function, which takes three Boolean values. You can change the settings to modify the way the `MigDocs.xml` file generates the XML rules for migration. +The `MigDocs.xml` file calls the `GenerateDocPatterns` function, which takes three Boolean values. The settings can be changed to modify the way the `MigDocs.xml` file generates the XML rules for migration. - `ScanProgramFiles`: This argument is valid only when the `GenerateDocPatterns` function is called in a system context. This argument determines whether or not to scan the Program Files directory to gather registered file name extensions for known applications. **Default value**: False - For example, when set to **TRUE**, the function discovers and migrates .doc files under the Microsoft Office directory, because .doc is a file name extension registered to a Microsoft Office application. The `GenerateDocPatterns` function generates this inclusion pattern for `.doc` files: + For example, when set to **TRUE**, the function discovers and migrates **.doc** files under the Microsoft Office directory, because **.doc** is a file name extension registered to a Microsoft Office application. The `GenerateDocPatterns` function generates this inclusion pattern for `.doc` files: `C:\Program Files\Microsoft Office[.doc]` - If a child folder of an included folder contains an installed application, ScanProgramFiles will also create an exclusion rule for the child folder. All folders under the application folder will be scanned recursively for registered file name extensions. + If a child folder of an included folder contains an installed application, `ScanProgramFiles` also creates an exclusion rule for the child folder. All folders under the application folder are scanned recursively for registered file name extensions. - `IncludePatterns`: This argument determines whether to generate exclude or include patterns in the XML. When this argument is set to **TRUE**, the `GenerateDocPatterns` function generates include patterns, and the function must be added under the `` element. Changing this argument to **FALSE** generates exclude patterns and the function must be added under the `` element. @@ -268,7 +283,10 @@ To create exclude data patterns: ### Understanding the system and user context -The migration XML files contain two <component> elements with different **context** settings. The system context applies to files on the computer that aren't stored in the User Profiles directory, while the user context applies to files that are particular to an individual user. +The migration XML files contain two \ elements with different **context** settings: + +- The system context applies to files on the computer that aren't stored in the User Profiles directory. +- The user context applies to files that are particular to an individual user. #### System context @@ -319,27 +337,29 @@ The user context includes rules for data in the User Profiles directory. When ca - FOLDERID_RecordedTV > [!NOTE] -> Rules contained in a component that is assigned the user context will be run for each user profile on the computer. Files that are scanned multiple times by the `MigDocs.xml` files will only be copied to the migration store once; however, a large number of rules in the user context can slow down the migration. Use the system context when it is applicable. +> +> Rules contained in a component that is assigned the user context runs for each user profile on the computer. Files that are scanned multiple times by the `MigDocs.xml` files are only copied to the migration store once. However, a large number of rules in the user context can slow down the migration. Use the system context when it's applicable. ### Sample migration rules for customized versions of XML files -> [!NOTE] +> [!TIP] +> > For best practices and requirements for customized XML files in USMT, see [Customize USMT XML Files](usmt-customize-xml-files.md) and [General Conventions](usmt-general-conventions.md). ### Exclude rules usage examples -In the examples below, the source computer has a .txt file called "new text document" in a directory called "new folder". The default `MigDocs.xml` behavior migrates the new text document.txt file and all files contained in the "new folder" directory. The rules generated by the function are: +In the following examples, the source computer has a **.txt** file called `new text document` in a directory called `new folder`. The default `MigDocs.xml` behavior migrates the new text `document.txt` file and all files contained in the `new folder` directory. The rules generated by the function are: | Rule | Syntax | |--- |--- | |Rule 1|`d:\new folder[new text document.txt]`| |Rule 2|`d:\new folder[]`| -To exclude the new text document.txt file and any .txt files in "new folder", you can do the following modification: +To exclude the new text `document.txt` file and any **.txt** files in `new folder`, the following modifications can be made: #### Example 1: Exclude all .txt files in a folder -To exclude Rule 1, there needs to be an exact match of the file name. However, for Rule 2, you can create a pattern to exclude files by using the file name extension. +To exclude Rule 1, there needs to be an exact match of the file name. However, for Rule 2, a pattern can be created to exclude files by using the file name extension. ```xml @@ -352,7 +372,7 @@ To exclude Rule 1, there needs to be an exact match of the file name. However, f #### Example 2: Use the UnconditionalExclude element to give a rule precedence over include rules -If you don't know the file name or location of the file, but you do know the file name extension, you can use the `GenerateDrivePatterns` function. However, the rule will be less specific than the default include rule generated by the `MigDocs.xml` file, so it will not have precedence. You must use the <UnconditionalExclude> element to give this rule precedence over the default include rule. For more information about the order of precedence for XML migration rules, see [Conflicts and Precedence](usmt-conflicts-and-precedence.md). +If the file name or location of the file isn't known, but the file name extension is known, the `GenerateDrivePatterns` function can be used. However, the rule is less specific than the default include rule generated by the `MigDocs.xml` file, so it doesn't have precedence. The \ element must be used to give this rule precedence over the default include rule. For more information about the order of precedence for XML migration rules, see [Conflicts and Precedence](usmt-conflicts-and-precedence.md). ```xml @@ -364,7 +384,7 @@ If you don't know the file name or location of the file, but you do know the fil #### Example 3: Use a UserandSystem context component to run rules in both contexts -If you want the **<UnconditionalExclude>** element to apply to both the system and user context, you can create a third component using the **UserandSystem** context. Rules in this component will be run in both contexts. +To apply the **\** element to both the system and user context, a third component can be created using the **UserandSystem** context. Rules in this component run in both contexts. ```xml @@ -381,15 +401,15 @@ If you want the **<UnconditionalExclude>** element to apply to both the sy ``` -For more examples of exclude rules that you can use in custom migration XML files, see [Exclude Files and Settings](usmt-exclude-files-and-settings.md). +For more examples of exclude rules that can be used in custom migration XML files, see [Exclude Files and Settings](usmt-exclude-files-and-settings.md). ### Include rules usage examples -The application data directory is the most common location that you would need to add an include rule for. The `GenerateDocPatterns` function excludes this location by default. If your company uses an application that saves important data to this location, you can create include rules to migrate the data. For example, the default location for .pst files is: `%CSIDL_LOCAL_APPDATA%\Microsoft\Outlook`. The `MigApp.xml` file contains migration rules to move only those .pst files that are linked to Microsoft Outlook. To include .pst files that aren't linked, you can do the following modification: +The application data directory is the most common location that an include rule would need to be added for. The `GenerateDocPatterns` function excludes this location by default. If the organization uses an application that saves important data to this location, include rules can be created to migrate the data. For example, the default location for **.pst** files is: `%CSIDL_LOCAL_APPDATA%\Microsoft\Outlook`. The `MigApp.xml` file contains migration rules to move only those **.pst** files that are linked to Microsoft Outlook. To include **.pst** files that aren't linked, the following modification can be made: #### Example 1: Include a file name extension in a known user folder -This rule will include .pst files that are located in the default location, but aren't linked to Microsoft Outlook. Use the user context to run this rule for each user on the computer. +This rule includes **.pst** files that are located in the default location, but aren't linked to Microsoft Outlook. Use the user context to run this rule for each user on the computer. ```xml @@ -401,7 +421,7 @@ This rule will include .pst files that are located in the default location, but #### Example 2: Include a file name extension in Program Files -For locations outside the user profile, such as the Program Files folder, you can add the rule to the system context component. +For locations outside the user profile, such as the Program Files folder, the rule can be added to the system context component. ```xml @@ -411,19 +431,19 @@ For locations outside the user profile, such as the Program Files folder, you ca ``` -For more examples of include rules that you can use in custom migration XML files, see [Include Files and Settings](usmt-include-files-and-settings.md). +For more examples of include rules that can be used in custom migration XML files, see [Include Files and Settings](usmt-include-files-and-settings.md). -> [!NOTE] +> [!TIP] +> > For more information about the order of precedence for XML migration rules, see [Conflicts and Precedence](usmt-conflicts-and-precedence.md). ## Next steps -You can include additional rules for the migration in the `MigDocs.xml` file or other XML migration files. For example, you can use the `` element to move files from the folder where they were gathered to a different folder, when they're applied to the destination computer. +Additional rules for the migration can be included in the `MigDocs.xml` file or other XML migration files. For example, the `` element can be used to move files from the folder where they were gathered to a different folder, when they're applied to the destination computer. -You can use an XML schema (MigXML.xsd) file to validate the syntax of your customized XML files. For more information, see [USMT Resources](usmt-resources.md). +An XML schema (`MigXML.xsd`) file can be used to validate the syntax of the customized XML files. For more information, see [USMT Resources](usmt-resources.md). ## Related articles -[Exclude files and settings](usmt-exclude-files-and-settings.md) - -[Include files and settings](usmt-include-files-and-settings.md) +- [Exclude files and settings](usmt-exclude-files-and-settings.md). +- [Include files and settings](usmt-include-files-and-settings.md). diff --git a/windows/deployment/usmt/usmt-best-practices.md b/windows/deployment/usmt/usmt-best-practices.md index 98f95d0597..c7a079cf31 100644 --- a/windows/deployment/usmt/usmt-best-practices.md +++ b/windows/deployment/usmt/usmt-best-practices.md @@ -1,135 +1,140 @@ --- -title: USMT Best Practices (Windows 10) -description: This article discusses general and security-related best practices when using User State Migration Tool (USMT) 10.0. +title: USMT Best Practices +description: This article discusses general and security-related best practices when using User State Migration Tool (USMT). manager: aaroncz ms.author: frankroj ms.prod: windows-client author: frankroj -ms.date: 11/01/2022 +ms.date: 01/02/2024 ms.topic: article ms.technology: itpro-deploy +appliesto: + - ✅ Windows 11 + - ✅ Windows 10 --- # USMT best practices -This article discusses general and security-related best practices when using User State Migration Tool (USMT) 10.0. +This article discusses general and security-related best practices when using User State Migration Tool (USMT). ## General best practices -- **Install applications before running the LoadState tool** +- **Install applications before running the LoadState tool.** - Though it isn't always essential, it's best practice to install all applications on the destination computer before restoring the user state. Installing applications before restoring user state helps ensure that migrated settings are preserved. + Though it isn't always essential, it's best practice to install all applications on the destination computer before restoring the user state. Installing applications before restoring user state helps ensure that migrated settings are preserved. -- **Don't use MigUser.xml and MigDocs.xml together** +- **Don't use MigUser.xml and MigDocs.xml together.** - If you use both .xml files, some migrated files may be duplicated if conflicting instructions are given about target locations. You can use the `/genmigxml` command-line option to determine which files will be included in your migration, and to determine if any modifications are necessary. For more information, see [Identify file types, files, and folders](usmt-identify-file-types-files-and-folders.md). + If both `MigUser.xml` and `MigDocs.xml` are used together, some migrated files can be duplicated if conflicting instructions are given about target locations. The `/genmigxml` command-line option can be used to determine which files are included in the migration, and to determine if any modifications are necessary. For more information, see [Identify file types, files, and folders](usmt-identify-file-types-files-and-folders.md). -- **Use MigDocs.xml for a better migration experience** +- **Use MigDocs.xml for a better migration experience.** - If your data set is unknown or if many files are stored outside of the standard user-profile folders, the `MigDocs.xml` file is a better choice than the `MigUser.xml` file, because the `MigDocs.xml` file will gather a broader scope of data. The `MigDocs.xml` file migrates folders of data based on location, and on registered file type by querying the registry for registered application extensions. The `MigUser.xml` file migrates only the files with the specified file extensions. + If the data set is unknown or if many files are stored outside of the standard user-profile folders, the `MigDocs.xml` file is a better choice than the `MigUser.xml` file, because the `MigDocs.xml` file gathers a broader scope of data. The `MigDocs.xml` file migrates folders of data based on location, and on registered file type by querying the registry for registered application extensions. The `MigUser.xml` file migrates only the files with the specified file extensions. -- **Close all applications before running either the ScanState or LoadState tools** +- **Close all applications before running either the ScanState or LoadState tools.** - Although using the `/vsc` switch can allow the migration of many files that are open with another application, it's a best practice to close all applications in order to ensure all files and settings migrate. Without the `/vsc` or `/c` switch USMT will fail when it can't migrate a file or setting. When you use the `/c` option, USMT will ignore any files or settings that it can't migrate and log an error each time. + Although using the `/vsc` switch can allow the migration of many files that are open with another application, it's a best practice to close all applications in order to ensure all files and settings migrate. Without the `/vsc` or `/c` switch, USMT fails when it can't migrate a file or setting. When the `/c` option is used, USMT ignores any files or settings that it can't migrate and log an error each time. -- **Log off after you run the LoadState** +- **Log off after running the LoadState.** - Some settings, such as fonts, wallpaper, and screensaver settings, won't take effect until the next time the user logs on. For this reason, you should sign out after you run the LoadState tool. + Some settings, such as fonts, wallpaper, and screensaver settings, won't take effect until the next time the user logs on. For this reason, sign out after running the **LoadState** tool. -- **Managed environment** +- **Managed environment.** - To create a managed environment, you can move all of the end user's documents into My Documents (%CSIDL\_PERSONAL%). We recommend that you migrate files into the smallest-possible number of folders on the destination computer. Minimizing folders will help you to clean up files on the destination computer, if the `LoadState.exe` command fails before completion. + To create a managed environment, all of the end user's documents can be moved into the **Documents** folder (%CSIDL\_PERSONAL%). Microsoft recommends migrating files into the smallest-possible number of folders on the destination computer. Minimizing folders helps to clean up files on the destination computer if the `LoadState.exe` command fails before completion. -- **Chkdsk.exe** +- **Chkdsk.exe.** - We recommend that you run **Chkdsk.exe** before running the ScanState and LoadState tools. **Chkdsk.exe** creates a status report for a hard disk drive and lists and corrects common errors. For more information about the **Chkdsk.exe** tool, see [Chkdsk](/previous-versions/windows/it-pro/windows-xp/bb490876(v=technet.10)). + Microsoft recommends running **Chkdsk.exe** before running the **ScanState** and **LoadState** tools. **Chkdsk.exe** creates a status report for a hard disk drive and lists and corrects common errors. For more information about the **Chkdsk.exe** tool, see [Chkdsk](/previous-versions/windows/it-pro/windows-xp/bb490876(v=technet.10)). -- **Migrate in groups** +- **Migrate in groups.** - If you decide to perform the migration while users are using the network, it's best to migrate user accounts in groups. To minimize the impact on network performance, determine the size of the groups based on the size of each user account. Migrating in phases also allows you to make sure each phase is successful before starting the next phase. Using this method, you can make any necessary modifications to your plan between groups. + If the migration is performed while users are using the network, it's best to migrate user accounts in groups. To minimize the effect on network performance, determine the size of the groups based on the size of each user account. Migrating in phases also allows making sure each phase is successful before starting the next phase. When this method is, any necessary modifications can be made to the plan between groups. ## Security best practices -As the authorized administrator, it is your responsibility to protect the privacy of the users and maintain security during and after the migration. In particular, you must consider the following issues: +As the authorized administrator, it's the responsibility to protect the privacy of the users and maintain security during and after the migration. In particular, the following issues must be considered: -- **Encrypting File System (EFS)** +- **Encrypting File System (EFS).** - Take extreme caution when migrating encrypted files, because the end user doesn't need to be logged on to capture the user state. By default, USMT fails if an encrypted file is found. For specific instructions about EFS best practices, see [Migrate EFS Files and Certificates](usmt-migrate-efs-files-and-certificates.md). + Take extreme caution when migrating encrypted files, because the end user doesn't need to be logged on to capture the user state. By default, USMT fails if an encrypted file is found. For specific instructions about EFS best practices, see [Migrate EFS Files and Certificates](usmt-migrate-efs-files-and-certificates.md). - > [!NOTE] - > If you migrate an encrypted file without also migrating the certificate, end users will not be able to access the file after the migration. + > [!NOTE] + > + > If an encrypted file is migrated without also migrating the certificate, end users won't be able to access the file after the migration. -- **Encrypt the store** +- **Encrypt the store.** - Consider using the `/encrypt` option with the `ScanState.exe` command and the `/decrypt` option with the `LoadState.exe` command. However, use extreme caution with this set of options, because anyone who has access to the `ScanState.exe` command-line script also has access to the encryption key. + Consider using the `/encrypt` option with the `ScanState.exe` command and the `/decrypt` option with the `LoadState.exe` command. However, use extreme caution with this set of options, because anyone who has access to the `ScanState.exe` command-line script also has access to the encryption key. -- **Virus Scan** +- **Virus Scan.** - We recommend that you scan both the source and destination computers for viruses before running USMT. In addition, you should scan the destination computer image. To help protect data from viruses, we strongly recommend running an antivirus utility before migration. + Microsoft recommends to scan both the source and destination computers for viruses before running USMT. In addition, the destination computer image should be scanned. To help protect data from viruses, Microsoft strongly recommends running an antivirus utility before migration. -- **Maintain security of the file server and the deployment server** +- **Maintain security of the file server and the deployment server.** - We recommend that you manage the security of the file and deployment servers. It's important to make sure that the file server where you save the store is secure. You must also secure the deployment server, to ensure that the user data that is in the log files isn't exposed. We also recommend that you only transmit data over a secure Internet connection, such as a virtual private network. For more information about network security, see [Microsoft Security Compliance Manager](https://www.microsoft.com/download/details.aspx?id=53353). + Microsoft recommends managing the security of the file and deployment servers. It's important to make sure that the file server where the store is saved is secure. The deployment server must also be secured to ensure that the user data that is in the log files isn't exposed. Microsoft also recommends to only transmit data over a secure network connection, such as a virtual private network. For more information about network security, see [Microsoft Security Compliance Manager](https://www.microsoft.com/download/details.aspx?id=53353). -- **Password Migration** +- **Password Migration.** - To ensure the privacy of the end users, USMT doesn't migrate passwords, including passwords for applications such as Windows Live™ Mail, Microsoft Internet Explorer®, and Remote Access Service (RAS) connections and mapped network drives. It's important to make sure that end users know their passwords. + To ensure the privacy of the end users, USMT doesn't migrate passwords, including passwords for applications or mapped network drives. It's important to make sure that end users know their passwords. -- **Local Account Creation** +- **Local Account Creation.** - Before you migrate local accounts, see the Migrating Local Accounts section in the [Identify Users](usmt-identify-users.md) article. + Before local accounts are migrated, see the Migrating Local Accounts section in the [Identify Users](usmt-identify-users.md) article. ## XML file best practices -- **Specify the same set of mig\*.xml files in both the ScanState and the LoadState tools** +- **Specify the same set of mig\*.xml files in both the ScanState and the LoadState tools.** - If you used a particular set of mig\*.xml files in the ScanState tool, either called through the `/auto` option, or individually through the `/i` option, then you should use same option to call the exact same mig\*.xml files in the LoadState tool. + If a particular set of mig\*.xml files are used with the **ScanState** tool, either called through the `/auto` option, or individually through the `/i` option, then the same option should be used to call the exact same mig\*.xml files in the **LoadState** tool. -- **The <CustomFileName> in the migration urlid should match the name of the file** +- **The \ in the migration urlid should match the name of the file.** - Although it isn't a requirement, it's good practice for **<CustomFileName>** to match the name of the file. For example, the following example is from the `MigApp.xml` file: + Although it isn't a requirement, it's good practice for **\** to match the name of the file. For example, the following example is from the `MigApp.xml` file: - ```xml - - - ``` + ```xml + + + ``` -- **Use the XML Schema (MigXML.xsd) when authoring .xml files to validate syntax** +- **Use the XML Schema (MigXML.xsd) when authoring .xml files to validate syntax.** - The `MigXML.xsd` schema file shouldn't be included on the command line or in any of the .xml files. + The `MigXML.xsd` schema file shouldn't be included on the command line or in any of the **.xml** files. -- **Use the default migration XML files as models** +- **Use the default migration XML files as models.** - To create a custom .xml file, you can use the migration .xml files as models to create your own. If you need to migrate user data files, model your custom .xml file on `MigUser.xml`. To migrate application settings, model your custom .xml file on the `MigApp.xml` file. + To create a custom **.xml** file, migration **.xml** files can be used as models to create customized versions. If user data files need to be migrated, model the custom **.xml** file on `MigUser.xml`. To migrate application settings, model the custom **.xml** file on the `MigApp.xml` file. -- **Consider the impact on performance when using the <context> parameter** +- **Consider the impact on performance when using the \ parameter.** - Your migration performance can be affected when you use the **<context>** element with the **<component>** element; for example, as in when you want to encapsulate logical units of file- or path-based **<include>** and **<exclude>** rules. + The migration performance can be affected when the **\** element is used with the **\** element. For example, when encapsulating logical units of file- or path-based **\** and **\** rules. - In the **User** context, a rule is processed one time for each user on the system. + In the **User** context, a rule is processed one time for each user on the system. + + In the **System** context, a rule is processed one time for the system. - In the **System** context, a rule is processed one time for the system. + In the **UserAndSystem** context, a rule is processed one time for each user on the system and one time for the system. - In the **UserAndSystem** context, a rule is processed one time for each user on the system and one time for the system. + > [!NOTE] + > + > The number of times a rule is processed doesn't affect the number of times a file is migrated. The USMT migration engine ensures that each file migrates only once. - > [!NOTE] - > The number of times a rule is processed does not affect the number of times a file is migrated. The USMT migration engine ensures that each file migrates only once. +- **Microsoft recommends to create a separate .xml file instead of adding .xml code to one of the existing migration .xml files.** -- **We recommend that you create a separate .xml file instead of adding your .xml code to one of the existing migration .xml files** + For example, for code that migrates the settings for an application, the code shouldn't just be added to the `MigApp.xml` file. - For example, if you have code that migrates the settings for an application, you shouldn't just add the code to the `MigApp.xml` file. +- **Custom .xml files shouldn't be created to alter the operating system settings that are migrated.** -- **You should not create custom .xml files to alter the operating system settings that are migrated** + Manifest files determine what settings are migrated. Manifest files can't be modified. Since manifest files can't be modified, to exclude certain operating system settings from the migration, create and modify a `Config.xml` file instead. - These settings are migrated by manifests and you can't modify those files. If you want to exclude certain operating system settings from the migration, you should create and modify a `Config.xml` file. +- **The asterisk (\*) wildcard character can be used in any migration XML file that is created.** -- **You can use the asterisk (\*) wildcard character in any migration XML file that you create** - - > [!NOTE] - > The question mark is not valid as a wildcard character in USMT .xml files. + > [!NOTE] + > + > The question mark isn't valid as a wildcard character in USMT **.xml** files. ## Related articles -[Migration store encryption](usmt-migration-store-encryption.md) - -[Plan your migration](usmt-plan-your-migration.md) +- [Migration store encryption](usmt-migration-store-encryption.md). +- [Plan the migration](usmt-plan-your-migration.md). diff --git a/windows/deployment/usmt/usmt-choose-migration-store-type.md b/windows/deployment/usmt/usmt-choose-migration-store-type.md index ab33c29403..bcee347165 100644 --- a/windows/deployment/usmt/usmt-choose-migration-store-type.md +++ b/windows/deployment/usmt/usmt-choose-migration-store-type.md @@ -1,30 +1,37 @@ --- -title: Choose a Migration Store Type (Windows 10) -description: Learn how to choose a migration store type and estimate the amount of disk space needed for computers in your organization. +title: Choose a Migration Store Type +description: Learn how to choose a migration store type and estimate the amount of disk space needed for computers in the organization. manager: aaroncz ms.author: frankroj ms.prod: windows-client author: frankroj -ms.date: 11/01/2022 +ms.date: 01/03/2024 ms.topic: article ms.technology: itpro-deploy +appliesto: + - ✅ Windows 11 + - ✅ Windows 10 --- # Choose a migration store type -One of the main considerations for planning your migration is to determine which migration store type best meets your needs. As part of these considerations, determine how much space is required to run the User State Migration Tool (USMT) 10.0 components on your source and destination computers, and how much space is needed to create and host the migration store, whether you're using a local share, network share, or storage device. The final consideration is ensuring that user date integrity is maintained by encrypting the migration store. +One of the main considerations for planning the migration is to determine which migration store type best meets the organization's needs. As part of these considerations, determine the following items: + +- How much space is required to run the User State Migration Tool (USMT) components on the source and destination computers. +- How much space is needed to create and host the migration store. +- Whether a local share, network share, or storage device should be used. +- Ensure that user date integrity is maintained by encrypting the migration store. ## In this section | Link | Description | |--- |--- | -|[Migration store types overview](migration-store-types-overview.md)|Choose the migration store type that works best for your needs and migration scenario.| -|[Estimate migration store size](usmt-estimate-migration-store-size.md)|Estimate the amount of disk space needed for computers in your organization based on information about your organization's infrastructure.| +|[Migration store types overview](migration-store-types-overview.md)|Choose the migration store type that works best for the organization's needs and migration scenario.| +|[Estimate migration store size](usmt-estimate-migration-store-size.md)|Estimate the amount of disk space needed for computers in the organization based on information about the organization's infrastructure.| |[Hard-link migration store](usmt-hard-link-migration-store.md)|Learn about hard-link migration stores and the scenarios in which they're used.| |[Migration store encryption](usmt-migration-store-encryption.md)|Learn about the using migration store encryption to protect user data integrity during a migration.| ## Related articles -[Plan your migration](usmt-plan-your-migration.md) - -[User State Migration Tool (USMT) how-to topics](usmt-how-to.md) +- [Plan the migration](usmt-plan-your-migration.md) +- [User State Migration Tool (USMT) how-articles](usmt-how-to.md) diff --git a/windows/deployment/usmt/usmt-command-line-syntax.md b/windows/deployment/usmt/usmt-command-line-syntax.md index 55cfe5e69c..9c39155386 100644 --- a/windows/deployment/usmt/usmt-command-line-syntax.md +++ b/windows/deployment/usmt/usmt-command-line-syntax.md @@ -1,23 +1,26 @@ --- -title: User State Migration Tool (USMT) Command-line Syntax (Windows 10) -description: Learn about the User State Migration Tool (USMT) command-line syntax for using the ScanState tool, LoadState tool, and UsmtUtils tool. +title: User State Migration Tool (USMT) Command-line Syntax +description: Learn about the User State Migration Tool (USMT) command-line syntax for using the **ScanState** tool, **LoadState** tool, and UsmtUtils tool. manager: aaroncz ms.author: frankroj ms.prod: windows-client author: frankroj -ms.date: 11/01/2022 +ms.date: 01/03/2024 ms.topic: article ms.technology: itpro-deploy +appliesto: + - ✅ Windows 11 + - ✅ Windows 10 --- # User State Migration Tool (USMT) command-line syntax -The User State Migration Tool (USMT) 10.0 migrates user files and settings during large deployments of Windows. To improve and simplify the migration process, USMT captures desktop, network, and application settings in addition to a user's files. USMT then migrates these items to a new Windows installation. +The User State Migration Tool (USMT) migrates user files and settings during large deployments of Windows. To improve and simplify the migration process, USMT captures desktop, network, and application settings in addition to a user's files. USMT then migrates these items to a new Windows installation. ## In this Section | Link | Description | |--- |--- | -|[ScanState syntax](usmt-scanstate-syntax.md)|Lists the command-line options for using the ScanState tool.| -|[LoadState syntax](usmt-loadstate-syntax.md)|Lists the command-line options for using the LoadState tool.| +|[**ScanState** syntax](usmt-scanstate-syntax.md)|Lists the command-line options for using the **ScanState** tool.| +|[LoadState syntax](usmt-loadstate-syntax.md)|Lists the command-line options for using the **LoadState** tool.| |[UsmtUtils syntax](usmt-utilities.md)|Lists the command-line options for using the UsmtUtils tool.| diff --git a/windows/deployment/usmt/usmt-common-migration-scenarios.md b/windows/deployment/usmt/usmt-common-migration-scenarios.md index 183565827a..0b9d8c0c79 100644 --- a/windows/deployment/usmt/usmt-common-migration-scenarios.md +++ b/windows/deployment/usmt/usmt-common-migration-scenarios.md @@ -1,109 +1,119 @@ --- -title: Common Migration Scenarios (Windows 10) -description: See how the User State Migration Tool (USMT) 10.0 is used when planning hardware and/or operating system upgrades. +title: Common Migration Scenarios +description: See how the User State Migration Tool (USMT) is used when planning hardware and/or operating system upgrades. manager: aaroncz ms.author: frankroj ms.prod: windows-client author: frankroj -ms.date: 11/01/2022 +ms.date: 01/03/2024 ms.topic: article ms.technology: itpro-deploy +appliesto: + - ✅ Windows 11 + - ✅ Windows 10 --- # Common Migration Scenarios -You use the User State Migration Tool (USMT) 10.0 when hardware and/or operating system upgrades are planned for a large number of computers. USMT manages the migration of an end-user's digital identity by capturing the user's operating-system settings, application settings, and personal files from a source computer and reinstalling them on a destination computer after the upgrade has occurred. +The User State Migration Tool (USMT) can be used when hardware and/or operating system upgrades are planned for a large number of computers. USMT manages the migration of an end-user's digital identity by capturing from a source computer the following user's items: -One common scenario is when the operating system is upgraded on existing hardware without the hardware being replaced. This scenario is referred to as *PC-refresh*. A second common scenario is known as *PC replacement*, where one piece of hardware is being replaced, typically by newer hardware and a newer operating system. +- Operating-system settings. +- Application settings. +- Personal files. + +Once these items are capture, they're reinstalled on a destination computer after the upgrade completes. + +One common scenario is when the operating system is upgraded on existing hardware without the hardware being replaced. This scenario is referred to as **PC-refresh**. A second common scenario is known as **PC replacement**, where one piece of hardware is being replaced, typically by newer hardware and a newer operating system. ## PC-refresh -The following diagram shows a PC-refresh migration, also known as a computer refresh migration. First, the administrator migrates the user state from a source computer to an intermediate store. After installing the operating system, the administrator migrates the user state back to the source computer. +The following diagram shows a PC-refresh migration, also known as a computer refresh migration. First, the administrator migrates the user state from a source computer to an intermediate store. After the administrator installs the operating system, they migrate the user state back to the source computer. ![usmt pc refresh scenario.](images/dep-win8-l-usmt-pcrefresh.jpg) ### Scenario One: PC-refresh offline using Windows PE and a hard-link migration store -A company has received funds to update the operating system on all of its computers in the accounting department to Windows 10. Each employee will keep the same computer, but the operating system on each computer will be updated. In this scenario, the update is being handled offline, without a network connection. An administrator uses Windows Preinstallation Environment (WinPE) and a hard-link migration store to save each user state to their respective computer. +An organization receives funds to update the operating system on all of its computers in the accounting department to the latest supported version of Windows. Each employee keeps the same computer, but the operating system on each computer will be updated. In this scenario, the update is being handled offline, without a network connection. An administrator uses Windows Preinstallation Environment (WinPE) and a hard-link migration store to save each user state to their respective computer. 1. On each computer, the administrator boots the machine into WinPE and runs the **ScanState** command-line tool, specifying the `/hardlink /nocompress` command-line options. **ScanState** saves the user state to a hard-link migration store on each computer, improving performance by minimizing network traffic and minimizing migration failures on computers with limited space available on the hard drive. -2. On each computer, the administrator installs the company's standard operating environment (SOE) which includes Windows 10 and other company applications. +1. On each computer, the administrator installs the organization's standard operating environment (SOE) which includes the latest supported version of Windows and other organization applications. -3. The administrator runs the **LoadState** command-line tool on each computer. **LoadState** restores each user state back to each computer. +1. The administrator runs the **LoadState** command-line tool on each computer. **LoadState** restores each user state back to each computer. ### Scenario Two: PC-refresh using a compressed migration store -A company has received funds to update the operating system on all of its computers to Windows 10. Each employee will keep the same computer, but the operating system on each computer will be updated. In this scenario, an administrator uses a compressed migration store to save the user states to a server. +An organization receives funds to update the operating system on all of its computers to the latest supported version of Windows. Each employee keeps the same computer, but the operating system on each computer will be updated. In this scenario, an administrator uses a compressed migration store to save the user states to a server. 1. The administrator runs the **ScanState** command-line tool on each computer. **ScanState** saves each user state to a server. -2. On each computer, the administrator installs the company's standard SOE that includes Windows 10 and other company applications. +1. On each computer, the administrator installs the organization's standard SOE that includes the latest supported version of Windows and other organization applications. -3. The administrator runs the **LoadState** command-line tool on each source computer, and **LoadState** restores each user state back to the computer. +1. The administrator runs the **LoadState** command-line tool on each source computer, and **LoadState** restores each user state back to the computer. ### Scenario Three: PC-refresh using a hard-link migration store -A company has received funds to update the operating system on all of its computers to Windows 10. Each employee will keep the same computer, but the operating system on each computer will be updated. In this scenario, an administrator uses a hard-link migration store to save each user state to their respective computer. +An organization receives funds to update the operating system on all of its computers to the latest supported version of Windows. Each employee keeps the same computer, but the operating system on each computer will be updated. In this scenario, an administrator uses a hard-link migration store to save each user state to their respective computer. 1. The administrator runs the **ScanState** command-line tool on each computer, specifying the `/hardlink /nocompress` command-line options. **ScanState** saves the user state to a hard-link migration store on each computer, improving performance by minimizing network traffic and minimizing migration failures on computers with limited space available on the hard drive. -2. On each computer, the administrator installs the company's SOE that includes Windows 10 and other company applications. +1. On each computer, the administrator installs the organization's SOE that includes the latest supported version of Windows and other organization applications. -3. The administrator runs the **LoadState** command-line tool on each computer. **LoadState** restores each user state back on each computer. +1. The administrator runs the **LoadState** command-line tool on each computer. **LoadState** restores each user state back on each computer. ### Scenario Four: PC-refresh using Windows.old folder and a hard-link migration store -A company has decided to update the operating system on all of its computers to Windows 10. Each employee will keep the same computer, but the operating system on each computer will be updated. In this scenario, an administrator uses Windows.old and a hard-link migration store to save each user state to their respective computer. +An organization decides to update the operating system on all of its computers to the latest supported version of Windows. Each employee keeps the same computer, but the operating system on each computer will be updated. In this scenario, an administrator uses **Windows.old** and a hard-link migration store to save each user state to their respective computer. -1. The administrator clean installs Windows 10 on each computer, making sure that the Windows.old directory is created by installing Windows 10 without formatting or repartitioning and by selecting a partition that contains the previous version of Windows. +1. The administrator clean installs the latest supported version of Windows on each computer. During the install, they make sure that the **Windows.old** directory is created by taking the following actions: -2. On each computer, the administrator installs the company's SOE that includes company applications. + - Performing the install without formatting or repartitioning the disk. + - Selecting a partition that contains the previous version of Windows. -3. The administrator runs the **ScanState** and **LoadState** command-line tools successively on each computer while specifying the `/hardlink /nocompress` command-line options. +1. On each computer, the administrator installs the organization's SOE that includes organization applications. + +1. The administrator runs the **ScanState** and **LoadState** command-line tools successively on each computer while specifying the `/hardlink /nocompress` command-line options. ## PC-replacement -The following diagram shows a PC-replacement migration. First, the administrator migrates the user state from the source computer to an intermediate store. After installing the operating system on the destination computer, the administrator migrates the user state from the store to the destination computer. +The following diagram shows a PC-replacement migration. First, the administrator migrates the user state from the source computer to an intermediate store. After the administrator installs the operating system on the destination computer, they migrate the user state from the store to the destination computer. ![usmt pc replace scenario.](images/dep-win8-l-usmt-pcreplace.jpg) ### Scenario One: Offline migration using Windows PE and an external migration store -A company is allocating 20 new computers to users in the accounting department. The users each have a source computer with their files and settings. In this scenario, migration is being handled offline, without a network connection. +An organization is allocating 20 new computers to users in the accounting department. The users each have a source computer with their files and settings. In this scenario, migration is being handled offline, without a network connection. 1. On each source computer, an administrator boots the machine into WinPE and runs **ScanState** to collect the user state to either a server or an external hard disk. -2. On each new computer, the administrator installs the company's SOE that includes Windows 10 and other company applications. +1. On each new computer, the administrator installs the organization's SOE that includes the latest supported version of Windows and other organization applications. -3. On each of the new computers, the administrator runs the **LoadState** tool, restoring each user state from the migration store to one of the new computers. +1. On each of the new computers, the administrator runs the **LoadState** tool, restoring each user state from the migration store to one of the new computers. ### Scenario Two: Manual network migration -A company receives 50 new laptops for their managers and needs to reallocate 50 older laptops to new employees. In this scenario, an administrator runs the **ScanState** tool from the cmd prompt on each computer to collect the user states and save them to a server in a compressed migration store. +An organization receives 50 new laptops for their managers and needs to reallocate 50 older laptops to new employees. In this scenario, an administrator runs the **ScanState** tool from the cmd prompt on each computer to collect the user states and save them to a server in a compressed migration store. 1. The administrator runs the **ScanState** tool on each of the manager's old laptops, and saves each user state to a server. -2. On the new laptops, the administrator installs the company's SOE, which includes Windows 10 and other company applications. +1. On the new laptops, the administrator installs the organization's SOE, which includes the latest supported version of Windows and other organization applications. -3. The administrator runs the **LoadState** tool on the new laptops to migrate the managers' user states to the appropriate computer. The new laptops are now ready for the managers to use. +1. The administrator runs the **LoadState** tool on the new laptops to migrate the managers' user states to the appropriate computer. The new laptops are now ready for the managers to use. -4. On the old computers, the administrator installs the company's SOE, which includes Windows 10, Microsoft Office, and other company applications. The old computers are now ready for the new employees to use. +1. On the old computers, the administrator installs the organization's SOE, which includes the latest supported version of Windows, Microsoft Office, and other organization applications. The old computers are now ready for the new employees to use. ### Scenario Three: Managed network migration -A company is allocating 20 new computers to users in the accounting department. The users each have a source computer that contains their files and settings. An administrator uses a management technology such as a sign-in script or a batch file to run **ScanState** on each source computer to collect the user states and save them to a server in a compressed migration store. +An organization is allocating 20 new computers to users in the accounting department. The users each have a source computer that contains their files and settings. An administrator uses a management technology such as a sign-in script or a batch file to run **ScanState** on each source computer to collect the user states and save them to a server in a compressed migration store. 1. On each source computer, the administrator runs the **ScanState** tool using Microsoft Configuration Manager, Microsoft Deployment Toolkit (MDT), a sign-in script, a batch file, or a non-Microsoft management technology. **ScanState** collects the user state from each source computer and then saves it to a server. -2. On each new computer, the administrator installs the company's SOE, which includes Windows 10 and other company applications. +1. On each new computer, the administrator installs the organization's SOE, which includes the latest supported version of Windows and other organization applications. -3. On each of the new computers, the administrator runs the **LoadState** tool using Microsoft Configuration Manager, a sign-in script, a batch file, or a non-Microsoft management technology. **LoadState** migrates each user state from the migration store to one of the new computers. +1. On each of the new computers, the administrator runs the **LoadState** tool using Microsoft Configuration Manager, a sign-in script, a batch file, or a non-Microsoft management technology. **LoadState** migrates each user state from the migration store to one of the new computers. ## Related articles -[Plan your migration](usmt-plan-your-migration.md) - -[Choose a migration store type](usmt-choose-migration-store-type.md) - -[Offline migration reference](offline-migration-reference.md) +- [Plan the migration](usmt-plan-your-migration.md). +- [Choose a migration store type](usmt-choose-migration-store-type.md). +- [Offline migration reference](offline-migration-reference.md). diff --git a/windows/deployment/usmt/usmt-configxml-file.md b/windows/deployment/usmt/usmt-configxml-file.md index a144f93cd4..50d35e7bcb 100644 --- a/windows/deployment/usmt/usmt-configxml-file.md +++ b/windows/deployment/usmt/usmt-configxml-file.md @@ -1,53 +1,65 @@ --- -title: Config.xml File (Windows 10) -description: Learn how the Config.xml file is an optional User State Migration Tool (USMT) 10.0 file that you can create using the /genconfig option with the ScanState.exe tool. +title: Config.xml File +description: Learn how the Config.xml file is an optional User State Migration Tool (USMT) file that can be created using the /genconfig option with the ScanState.exe tool. manager: aaroncz ms.author: frankroj ms.prod: windows-client author: frankroj -ms.date: 11/01/2022 +ms.date: 01/03/2024 ms.topic: article ms.technology: itpro-deploy +appliesto: + - ✅ Windows 11 + - ✅ Windows 10 --- # Config.xml File -The `Config.xml` file is an optional User State Migration Tool (USMT) 10.0 file that you can create using the `/genconfig` option with the ScanState tool. If you want to include all of the default components, and don't want to change the default store-creation or profile-migration behavior, you don't need to create a `Config.xml` file. +The `Config.xml` file is an optional User State Migration Tool (USMT) file that can be created using the `/genconfig` option with the **ScanState** tool. If all of the default components should be included and no changes need to be made to the default store-creation or profile-migration behavior, a `Config.xml` file doesn't need to be created. -However, if you're satisfied with the default migration behavior defined in the `MigApp.xml`, `MigUser.xml` and `MigDocs.xml` files, but you want to exclude certain components, you can create and modify a `Config.xml` file and leave the other .xml files unchanged. For example, you must create and modify the `Config.xml` file if you want to exclude any of the operating-system settings that are migrated. It's necessary to create and modify this file if you want to change any of the default store-creation or profile-migration behavior. +However, if the default migration behavior defined in the `MigApp.xml`, `MigUser.xml` and `MigDocs.xml` files is satisfactory, but certain components need to be excluded, a `Config.xml` file can be created and modified while leaving the other **.xml** files unchanged. For example, a `Config.xml` file must be created to exclude any of the operating-system settings that are migrated. It's necessary to create and modify the `Config.xml` file to change any of the default store-creation or profile-migration behavior. -The `Config.xml` file has a different format than the other migration .xml files, because it doesn't contain any migration rules. It contains only a list of the operating-system components, applications, user documents that can be migrated, and user-profile policy and error-control policy. For this reason, excluding components using the `Config.xml` file is easier than modifying the migration .xml files, because you don't need to be familiar with the migration rules and syntax. However, you can't use wildcard characters in this file. +The `Config.xml` file has a different format than the other migration **.xml** files, because it doesn't contain any migration rules. It contains only a list of the operating-system components, applications, user documents that can be migrated, and user-profile policy and error-control policy. For this reason, excluding components using the `Config.xml` file is easier than modifying the migration **.xml** files, because familiarization with the migration rules and syntax isn't needed. However, wildcard characters can't be used in this file. For more information about using the `Config.xml` file with other migration files, such as the `MigDocs.xml` and `MigApps.xml` files, see [Understanding Migration XML Files](understanding-migration-xml-files.md). > [!NOTE] -> To exclude a component from the `Config.xml` file, set the **migrate** value to **no**. Deleting the XML tag for the component from the `Config.xml` file will not exclude the component from your migration. +> +> To exclude a component from the `Config.xml` file, set the **migrate** value to **no**. Deleting the XML tag for the component from the `Config.xml` file doesn't exclude the component from the migration. ## Migration Policies -In USMT there are new migration policies that can be configured in the `Config.xml` file. For example, you can configure additional **<ErrorControl>**, **<ProfileControl>**, and **<HardLinkStoreControl>** options. The following elements and parameters are for use in the `Config.xml` file only. +In USMT, there are migration policies that can be configured in the `Config.xml` file. For example, **\**, **\**, and **\** options can be configured. The following elements and parameters are for use in the `Config.xml` file only. -### <Policies> +### \ -The **<Policies>** element contains elements that describe the policies that USMT follows while creating a migration store. Valid children of the **<Policies>** element are **<ErrorControl>** and **<HardLinkStoreControl>**. The **<Policies>** element is a child of **<Configuration>**. +The **\** element contains elements that describe the policies that USMT follows while creating a migration store. Valid children of the **\** element are **\** and **\**. The **\** element is a child of **\**. -Syntax: `` `` +Syntax: -### <ErrorControl> +```xml + +``` -The **<ErrorControl>** element is an optional element you can configure in the `Config.xml` file. The configurable **<ErrorControl>** rules support only the environment variables for the operating system that is running and the currently logged-on user. As a workaround, you can specify a path using the (\*) wildcard character. +### \ + +The **\** element is an optional element that can be configured in the `Config.xml` file. The configurable **\** rules support only the environment variables for the operating system that is running and the currently logged-on user. As a workaround, a path can be specified using the (\*) wildcard character. - **Number of occurrences**: Once for each component -- **Parent elements**: The **<Policies>** element +- **Parent elements**: The **\** element -- **Child elements**: The **<fileError>** and **<registryError>** element +- **Child elements**: The **\** and **\** element -Syntax: `` `` +Syntax: -The following example specifies that all locked files, regardless of their location (including files in C:\\Users), should be ignored. However, the migration fails if any file in C:\\Users can't be accessed because of any other reason. In the example below, the **<ErrorControl>** element ignores any problems in migrating registry keys that match the supplied pattern, and it resolves them to an **Access denied** error. +```xml + +``` -Additionally, the order in the **<ErrorControl>** section implies priority. In this example, the first **<nonFatal>** tag takes precedence over the second **<fatal>** tag. This precedence is applied, regardless of how many tags are listed. +The following example specifies that all locked files, regardless of their location (including files in C:\\Users), should be ignored. However, the migration fails if any file in C:\\Users can't be accessed because of any other reason. In the following example, the **\** element ignores any problems in migrating registry keys that match the supplied pattern, and it resolves them to an **Access denied** error. + +Additionally, the order in the **\** section implies priority. In this example, the first **\** tag takes precedence over the second **\** tag. This precedence is applied, regardless of how many tags are listed. ```xml @@ -62,94 +74,120 @@ Additionally, the order in the **<ErrorControl>** section implies priority ``` > [!IMPORTANT] -> The configurable **<ErrorControl>** rules support only the environment variables for the operating system that is running and the currently logged-on user. As a workaround, you can specify a path using the (\*) wildcard character. +> +> The configurable **\** rules support only the environment variables for the operating system that is running and the currently logged-on user. As a workaround, a path using the (\*) wildcard character can be specified. -### <fatal> +### \ -The **<fatal>** element isn't required. +The **\** element isn't required. - **Number of occurrences**: Once for each component -- **Parent elements**: **<fileError>** and **<registryError>** +- **Parent elements**: **\** and **\** - **Child elements**: None. -Syntax: `` *<pattern>* `` +Syntax: + +```xml + +``` |Parameter|Required|Value| |--- |--- |--- | |errorCode|No|"any" or "*specify system error message here*"| -You use the **<fatal>** element to specify that errors matching a specific pattern should cause USMT to halt the migration. +The **\** element can be used to specify that errors matching a specific pattern should cause USMT to halt the migration. -### <fileError> +### \ -The **<fileError>** element isn't required. +The **\** element isn't required. - **Number of occurrences**: Once for each component -- **Parent elements**: **<ErrorControl>** +- **Parent elements**: **\** -- **Child elements**: **<nonFatal>** and **<fatal>** +- **Child elements**: **\** and **\** -Syntax: `` `` +Syntax: -You use the **<fileError>** element to represent the behavior associated with file errors. +```xml + +``` -### <nonFatal> +The **\** element can be used to represent the behavior associated with file errors. -The **<nonFatal>** element isn't required. +### \ + +The **\** element isn't required. - **Number of occurrences**: Once for each component -- **Parent elements**: The **<fileError>** and **<registryError>** elements. +- **Parent elements**: The **\** and **\** elements. - **Child elements**: None. -Syntax: `` *<pattern>* `` +Syntax: + +```xml + +``` |Parameter|Required|Value| |--- |--- |--- | -|**<errorCode>**|No|"any" or "*specify system error message here*". If system error messages aren't specified, the default behavior applies the parameter to all system error messages.| +|**\**|No|"any" or "*specify system error message*". If system error messages aren't specified, the default behavior applies the parameter to all system error messages.| -You use the **<nonFatal>** element to specify that errors matching a specific pattern shouldn't cause USMT to halt the migration. +The **\** element can be used to specify that errors matching a specific pattern shouldn't cause USMT to halt the migration. -### <registryError> +### \ -The **<registryError>** element isn't required. +The **\** element isn't required. - **Number of occurrences**: Once for each component -- **Parent elements**: **<ErrorControl>** +- **Parent elements**: **\** -- **Child elements**: **<nonfatal>** and **<fatal>** +- **Child elements**: **\** and **\** -Syntax: `` `` +Syntax: + +```xml + +``` |Parameter|Required|Value| |--- |--- |--- | -|**<errorCode>**|No|"any" or "*specify system error message here*". If system error messages aren't specified, the default behavior applies the parameter to all system error messages.| +|**\**|No|"any" or "*specify system error message here*". If system error messages aren't specified, the default behavior applies the parameter to all system error messages.| -You use the **<registryError>** element to specify that errors matching a specific pattern shouldn't cause USMT to halt the migration. +The **\** element can be used to specify that errors matching a specific pattern shouldn't cause USMT to halt the migration. -### <HardLinkStoreControl> +### \ -The **<HardLinkStoreControl>** element contains elements that describe how to handle files during the creation of a hard-link migration store. Its only valid child is **<fileLocked>**. +The **\** element contains elements that describe how to handle files during the creation of a hard-link migration store. Its only valid child is **\**. -Syntax: `` `` +Syntax: + +```xml + +``` - **Number of occurrences**: Once for each component -- **Parent elements**: **<Policies>** +- **Parent elements**: **\** -- **Child elements**: **<fileLocked>** +- **Child elements**: **\** -Syntax: `` `` +Syntax: -The **<HardLinkStoreControl>** sample code below specifies that hard links can be created to locked files only if the locked file resides somewhere under C:\\Users\\. Otherwise, a file-access error occurs when a locked file is encountered that can't be copied, even though is technically possible for the link to be created. +```xml + +``` + +The following **\** sample code specifies that hard links can be created to locked files only if the locked file resides somewhere under C:\\Users\\. Otherwise, a file-access error occurs when a locked file is encountered that can't be copied, even though is technically possible for the link to be created. > [!IMPORTANT] -> The **<ErrorControl>** section can be configured to conditionally ignore file access errors, based on the file's location. +> +> The **\** section can be configured to conditionally ignore file access errors, based on the file's location. ```xml @@ -165,45 +203,69 @@ The **<HardLinkStoreControl>** sample code below specifies that hard links ``` -### <fileLocked> +### \ -The **<fileLocked>** element contains elements that describe how to handle files that are locked for editing. The rules defined by the **<fileLocked>** element are processed in the order in which they appear in the XML file. +The **\** element contains elements that describe how to handle files that are locked for editing. The rules defined by the **\** element are processed in the order in which they appear in the XML file. -Syntax: `` `` +Syntax: -### <createHardLink> +```xml + +``` -The **<createHardLink>** element defines a standard MigXML pattern that describes file paths where hard links should be created, even if the file is locked for editing by another application. +### \ -Syntax: `` *<pattern>* `` +The **\** element defines a standard MigXML pattern that describes file paths where hard links should be created, even if the file is locked for editing by another application. -### <errorHardLink> +Syntax: -The **<errorHardLink>** element defines a standard MigXML pattern that describes file paths where hard links shouldn't be created if the file is locked for editing by another application. USMT will attempt to copy files under these paths into the migration store. However, if that isn't possible, **Error\_Locked** is thrown. This error is a standard Windows application programming interface (API) error that can be captured by the **<ErrorControl>** section to either cause USMT to skip the file or abort the migration. +```xml + +``` -Syntax: `` *<pattern>* `` +### \ -### <ProfileControl> +The **\** element defines a standard MigXML pattern that describes file paths where hard links shouldn't be created if the file is locked for editing by another application. USMT attempts to copy files under these paths into the migration store. However, if that isn't possible, **Error\_Locked** is thrown. This error is a standard Windows application programming interface (API) error that can be captured by the **\** section to either cause USMT to skip the file or abort the migration. -This element is used to contain other elements that establish rules for migrating profiles, users, and policies around local group membership during the migration. **<ProfileMigration>** is a child of **<Configuration>**. +Syntax: -Syntax: <`ProfileControl>` `` +```xml + +``` -### <localGroups> +### \ -This element is used to contain other elements that establish rules for how to migrate local groups. **<localGroups>** is a child of **<ProfileControl>**. +This element is used to contain other elements that establish rules for migrating profiles, users, and policies around local group membership during the migration. **\** is a child of **\**. -Syntax: `` `` +Syntax: -### <mappings> +```xml + +``` + +### \ + +This element is used to contain other elements that establish rules for how to migrate local groups. **\** is a child of **\**. + +Syntax: + +```xml + +``` + +### \ This element is used to contain other elements that establish mappings between groups. -Syntax: `` `` +Syntax: -### <changeGroup> +```xml + +``` -This element describes the source and destination groups for a local group membership change during the migration. It's a child of **<localGroups>**. The following parameters are defined: +### \ + +This element describes the source and destination groups for a local group membership change during the migration. It's a child of **\**. The following parameters are defined: |Parameter|Required|Value| |--- |--- |--- | @@ -211,25 +273,38 @@ This element describes the source and destination groups for a local group membe |To|Yes|A local group that the users are to be moved to during the migration.| |appliesTo|Yes|nonmigratedUsers, migratedUsers, AllUsers. This value defines which users the change group operation should apply to.| -The valid and required children of **<changeGroup>** are **<include>** and **<exclude>**. Although both can be children at the same time, only one is required. +The valid and required children of **\** are **\** and **\**. Although both can be children at the same time, only one is required. -Syntax: `` `` +Syntax: -### <include> +```xml + +``` -This element specifies that its required child, *<pattern>*, should be included in the migration. +### \ -Syntax: `` `` +This element specifies that its required child, *\*, should be included in the migration. -### <exclude> +Syntax: -This element specifies that its required child, *<pattern>*, should be excluded from the migration. +```xml + +``` -Syntax: `` `` +### \ + +This element specifies that its required child, *\*, should be excluded from the migration. + +Syntax: + +```xml + +``` ## Sample Config.xml File -Refer to the following sample `Config.xml` file for more details about items you can choose to exclude from a migration. +The following sample `Config.xml` file contains detailed examples about items that can be excluded from a migration. +

@@ -430,4 +505,4 @@ Refer to the following sample `Config.xml` file for more details about items you ## Related articles -[USMT XML reference](usmt-xml-reference.md) +- [USMT XML reference](usmt-xml-reference.md). diff --git a/windows/deployment/usmt/usmt-conflicts-and-precedence.md b/windows/deployment/usmt/usmt-conflicts-and-precedence.md index b3c5c22025..de97180e05 100644 --- a/windows/deployment/usmt/usmt-conflicts-and-precedence.md +++ b/windows/deployment/usmt/usmt-conflicts-and-precedence.md @@ -1,40 +1,43 @@ --- -title: Conflicts and Precedence (Windows 10) -description: In this article, learn how User State Migration Tool (USMT) 10.0 deals with conflicts and precedence. +title: Conflicts and Precedence +description: In this article, learn how User State Migration Tool (USMT) deals with conflicts and precedence. manager: aaroncz ms.author: frankroj ms.prod: windows-client author: frankroj -ms.date: 11/01/2022 +ms.date: 01/03/2024 ms.topic: article ms.technology: itpro-deploy +appliesto: + - ✅ Windows 11 + - ✅ Windows 10 --- # Conflicts and precedence -When you include, exclude, and reroute files and settings, it's important to know how User State Migration Tool (USMT) 10.0 deals with conflicts and precedence. When working with USMT, the following are the most important conflicts and precedence guidelines to keep in mind. +When including, excluding, and rerouting files and settings, it's important to know how User State Migration Tool (USMT) deals with conflicts and precedence. The following are the most important conflicts and precedence guidelines to keep in mind when working with USMT. -- **If there are conflicting rules within a component, the most specific rule is applied.** However, the **<unconditionalExclude>** rule is an exception because it takes precedence over all others. Directory names take precedence over file extensions. For examples, see [What happens when there are conflicting <include> and <exclude> rules?](#what-happens-when-there-are-conflicting-include-and-exclude-rules) and the first example in [<include> and <exclude> rules precedence examples](#include-and-exclude-rules-precedence-examples) later in this article. +- **If there are conflicting rules within a component, the most specific rule is applied.** However, the **\** rule is an exception because it takes precedence over all others. Directory names take precedence over file extensions. For examples, see [What happens when there are conflicting \ and \ rules?](#what-happens-when-there-are-conflicting-include-and-exclude-rules) and the first example in [\ and \ rules precedence examples](#include-and-exclude-rules-precedence-examples) later in this article. -- **Only rules inside the same component can affect each other, depending on specificity.** Rules that are in different components don't affect each other, except for the **<unconditionalExclude>** rule. +- **Only rules inside the same component can affect each other, depending on specificity.** Rules that are in different components don't affect each other, except for the **\** rule. -- **If the rules are equally specific, <exclude> takes precedence over <include>.** For example, if you use the **<exclude>** rule to exclude a file and use the **<include>** rule to include the same file, the file will be excluded. +- **If the rules are equally specific, \ takes precedence over \.** For example, if the **\** rule is used to exclude a file and use the **\** rule to include the same file, the file is excluded. -- **The ordering of components does not matter.** It doesn't matter which components are listed in which .xml file, because each component is processed independently of the other components across all of the .xml files. +- **The ordering of components does not matter.** It doesn't matter which components are listed in which **.xml** file, because each component is processed independently of the other components across all of the **.xml** files. -- **The ordering of the <include> and <exclude> rules within a component does not matter.** +- **The ordering of the \ and \ rules within a component does not matter.** -- **You can use the <unconditionalExclude> element to globally exclude data.** This element excludes objects, regardless of any other **<include>** rules that are in the .xml files. For example, you can use the **<unconditionalExclude>** element to exclude all MP3 files on the computer or to exclude all files from `C:\UserData`. +- **The \ element can be used to globally exclude data.** This element excludes objects, regardless of any other **\** rules that are in the **.xml** files. For example, the **\** element can be used to exclude all MP3 files on the computer or to exclude all files from `C:\UserData`. ## General ### What is the relationship between rules that are located within different components? -Only rules inside the same component can affect each other, depending on specificity, except for the **<unconditionalExclude>** rule. Rules that are in different components don't affect each other. If there's an **<include>** rule in one component and an identical **<exclude>** rule in another component, the data will be migrated because the two rules are independent of each other. +Only rules inside the same component can affect each other, depending on specificity, except for the **\** rule. Rules that are in different components don't affect each other. If there's an **\** rule in one component and an identical **\** rule in another component, the data is migrated because the two rules are independent of each other. -If you have an **<include>** rule in one component and a **<locationModify>** rule in another component for the same file, the file will be migrated in both places. That is, it will be included based on the **<include>** rule, and it will be migrated based on the **<locationModify>** rule. +If an **\** rule is in one component and a **\** rule is in another component for the same file, the file is migrated in both places. That is, the file is included based on the **\** rule, and the file is migrated based on the **\** rule. -The following .xml file migrates all files from C:\\Userdocs, including .mp3 files, because the **<exclude>** rule is specified in a separate component. +The following **.xml** file migrates all files from C:\\Userdocs, including **.mp3** files, because the **\** rule is specified in a separate component. ```xml @@ -68,7 +71,7 @@ The following .xml file migrates all files from C:\\Userdocs, including .mp3 fil ### How does precedence work with the Config.xml file? -Specifying `migrate="no"` in the `Config.xml` file is the same as deleting the corresponding component from the migration .xml file. However, if you set `migrate="no"` for My Documents, but you have a rule similar to the one shown below in a migration .xml file (which includes all of the .doc files from My Documents), then only the .doc files will be migrated, and all other files will be excluded. +Specifying `migrate="no"` in the `Config.xml` file is the same as deleting the corresponding component from the migration **.xml** file. However, if `migrate="no"` is set for the **Documents** folder, but a rule similar to the following rule exists in a migration **.xml** file (which includes all of the **.doc** files from the **Documents** folder), then only the **.doc** files is migrated, and all other files are excluded: ```xml @@ -80,27 +83,27 @@ Specifying `migrate="no"` in the `Config.xml` file is the same as deleting the c ### How does USMT process each component in an .xml file with multiple components? -The ordering of components doesn't matter. Each component is processed independently of other components. For example, if you have an **<include>** rule in one component and a **<locationModify>** rule in another component for the same file, the file will be migrated in both places. That is, it will be included based on the **<include>** rule, and it will be migrated based on the **<locationModify>** rule. +The ordering of components doesn't matter. Each component is processed independently of other components. For example, if an **\** rule is in one component and a **\** rule is in another component for the same file, the file is migrated in both places. That is, the file is included based on the **\** rule, and the file is migrated based on the **\** rule. ### How are rules processed? There are two broad categories of rules. -- **Rules that affect the behavior of both the ScanState and LoadState tools**. For example, the **<include>**, **<exclude>**, and **<unconditionalExclude>** rules are processed for each component in the .xml files. For each component, USMT creates an include list and an exclude list. Some of the rules in the component might be discarded due to specificity, but all of the remaining rules are processed. For each **<include>** rule, USMT iterates through the elements to see if any of the locations need to be excluded. USMT enumerates all of the objects and creates a list of objects it's going to collect for each user. Once the list is complete, each of the objects is stored or migrated to the destination computer. +- **Rules that affect the behavior of both the ScanState and LoadState tools**. For example, the **\**, **\**, and **\** rules are processed for each component in the **.xml** files. For each component, USMT creates an include list and an exclude list. Some of the rules in the component might be discarded due to specificity, but all of the remaining rules are processed. For each **\** rule, USMT iterates through the elements to see if any of the locations need to be excluded. USMT enumerates all of the objects and creates a list of objects it's going to collect for each user. Once the list is complete, each of the objects is stored or migrated to the destination computer. -- **Rules that affect the behavior of only the LoadState tool**. For example, the **<locationModify>**, **<contentModify>**, and **<destinationCleanup>** rules don't affect ScanState. They're processed only with LoadState. First, the LoadState tool determines the content and location of each component based on the **<locationModify>** and **<contentModify>** rules. Then, LoadState processes all of the **<destinationCleanup>** rules and deletes data from the destination computer. Lastly, LoadState applies the components to the computer. +- **Rules that affect the behavior of only the LoadState tool**. For example, the **\**, **\**, and **\** rules don't affect ScanState. They're processed only with LoadState. First, the **LoadState** tool determines the content and location of each component based on the **\** and **\** rules. Then, **LoadState** processes all of the **\** rules and deletes data from the destination computer. Lastly, **LoadState** applies the components to the computer. ### How does USMT combine all of the .xml files that I specify on the command line? -USMT doesn't distinguish the .xml files based on their name or content. It processes each component within the files separately. USMT supports multiple .xml files only to make it easier to maintain and organize the components within them. Because USMT uses a urlid to distinguish each component from the others, be sure that each .xml file that you specify on the command line has a unique migration urlid. +USMT doesn't distinguish the **.xml** files based on their name or content. It processes each component within the files separately. USMT supports multiple **.xml** files only to make it easier to maintain and organize the components within them. Because USMT uses a urlid to distinguish each component from the others, be sure that each **.xml** file that is specified on the command line has a unique migration urlid. -## The <include> and <exclude> rules +## The \ and \ rules -### What happens when there are conflicting <include> and <exclude> rules? +### What happens when there are conflicting \ and \ rules? -If there are conflicting rules within a component, the most specific rule is applied, except with the **<unconditionalExclude>** rule, which takes precedence over all other rules. If the rules are equally specific, then the data won't be migrated. For example if you exclude a file, and include the same file, the file won't be migrated. If there are conflicting rules within different components, the rules don't affect each other because each component is processed independently. +If there are conflicting rules within a component, the most specific rule is applied, except with the **\** rule, which takes precedence over all other rules. If the rules are equally specific, then the data isn't migrated. For example if the same file is both excluded and included, the file isn't migrated. If there are conflicting rules within different components, the rules don't affect each other because each component is processed independently. -In the following example, mp3 files won't be excluded from the migration. The mp3 files won't be excluded because directory names take precedence over the file extensions. +In the following example, mp3 files aren't excluded from the migration. The mp3 files aren't excluded because directory names take precedence over the file extensions. ```xml @@ -115,9 +118,9 @@ In the following example, mp3 files won't be excluded from the migration. The mp ``` -### <include> and <exclude> rules precedence examples +### \ and \ rules precedence examples -These examples explain how USMT deals with **<include>** and **<exclude>** rules. When the rules are in different components, the resulting behavior will be the same regardless of whether the components are in the same or in different migration .xml files. +These examples explain how USMT deals with **\** and **\** rules. When the rules are in different components, the resulting behavior is the same regardless of whether the components are in the same or in different migration **.xml** files. - [Including and excluding files](#including-and-excluding-files) @@ -125,42 +128,42 @@ These examples explain how USMT deals with **<include>** and **<exclude ### Including and excluding files -| If you have the following code in the same component | Resulting behavior | Explanation | +| If the following code exists in the same component | Resulting behavior | Explanation | |-----|-----|-----| -|
  • Include rule: <pattern type="File">C:\Dir1* []</pattern>
  • Exclude rule: <pattern type="File">C:* [.txt]</pattern>
| Migrates all files and subfolders in Dir1 (including all .txt files in C:). | The **<exclude>** rule doesn't affect the migration because the **<include>** rule is more specific. | -|
  • Include rule: <pattern type="File">C:\Dir1* []</pattern>
  • Exclude rule: <pattern type="File">C:\Dir1\Dir2* [.txt]</pattern>
| Migrates all files and subfolders in C:\Dir1, except the .txt files in C:\Dir1\Dir2 and its subfolders. | Both rules are processed as intended. | -|
  • Include rule: <pattern type="File">C:\Dir1* []</pattern>
  • Exclude rule: <pattern type="File">C:\Dir1\ * [.txt]</pattern>
| Migrates all files and subfolders in C:\Dir1, except the .txt files in C:\Dir1 and its subfolders. | Both rules are processed as intended. | -|
  • Include rule: <pattern type="File">C:\Dir1\Dir2* [.txt]</pattern>
  • Exclude rule: <pattern type="File">C:\Dir1\Dir2* [.txt]</pattern>
| Nothing will be migrated. | The rules are equally specific, so the **<exclude>** rule takes precedence over the **<include>** rule. | -|
  • Include rule: C:\Dir1* [.txt]
  • Exclude rule: C:\Dir1\Dir2* []
| Migrates the .txt files in Dir1 and the .txt files from subfolders other than Dir2.
No files are migrated from Dir2 or its subfolders. | Both rules are processed as intended. | -|
  • Include rule: C:\Dir1\Dir2* []
  • Exclude rule: C:\Dir1* [.txt]
| Migrates all files and subfolders of Dir2, except the .txt files from Dir1 and any subfolders of Dir1 (including Dir2). | Both rules are processed as intended. | +|
  • Include rule: \C:\Dir1* []\
  • Exclude rule: \C:* [.txt]\
| Migrates all files and subfolders in Dir1 (including all **.txt** files in C:). | The **\** rule doesn't affect the migration because the **\** rule is more specific. | +|
  • Include rule: \C:\Dir1* []\
  • Exclude rule: \C:\Dir1\Dir2* [.txt]\
| Migrates all files and subfolders in C:\Dir1, except the **.txt** files in C:\Dir1\Dir2 and its subfolders. | Both rules are processed as intended. | +|
  • Include rule: \C:\Dir1* []\
  • Exclude rule: \C:\Dir1\ * [.txt]\
| Migrates all files and subfolders in C:\Dir1, except the **.txt** files in C:\Dir1 and its subfolders. | Both rules are processed as intended. | +|
  • Include rule: \C:\Dir1\Dir2* [.txt]\
  • Exclude rule: \C:\Dir1\Dir2* [.txt]\
| Nothing is migrated. | The rules are equally specific, so the **\** rule takes precedence over the **\** rule. | +|
  • Include rule: C:\Dir1* [.txt]
  • Exclude rule: C:\Dir1\Dir2* []
| Migrates the **.txt** files in Dir1 and the **.txt** files from subfolders other than Dir2.
No files are migrated from Dir2 or its subfolders. | Both rules are processed as intended. | +|
  • Include rule: C:\Dir1\Dir2* []
  • Exclude rule: C:\Dir1* [.txt]
| Migrates all files and subfolders of Dir2, except the **.txt** files from Dir1 and any subfolders of Dir1 (including Dir2). | Both rules are processed as intended. | -| If you have the following code in different components | Resulting behavior | Explanation | +| If the following code exists in different components | Resulting behavior | Explanation | |-----|----|----| -| Component 1:
  • Include rule: <pattern type="File">C:\Dir1* []</pattern>
  • Exclude rule: <pattern type="File">C:\Dir1\Dir2* [.txt]</pattern>

Component 2:
  • Include rule: <pattern type="File">C:\Dir1\Dir2* [.txt]</pattern>
  • Exclude rule: <pattern type="File">C:\Dir1* []</pattern>
| Migrates all files and subfolders of C:\Dir1\ (including C:\Dir1\Dir2). | Rules that are in different components don't affect each other, except for the **<unconditionalExclude>** rule. Therefore, in this example, although some .txt files were excluded when Component 1 was processed, they were included when Component 2 was processed. | -| Component 1:
  • Include rule: C:\Dir1\Dir2* []

Component 2:
  • Exclude rule: C:\Dir1* [.txt]
| Migrates all files and subfolders from Dir2 except the .txt files in C:\Dir1 and its subfolders. | Both rules are processed as intended. | -| Component 1:
  • Exclude rule: C:\Dir1\Dir2* []

Component 2:
  • Include rule: C:\Dir1* [.txt]
| Migrates all .txt files in Dir1 and any subfolders. | Component 1 doesn't contain an **<include>** rule, so the **<exclude>** rule isn't processed. | +| Component 1:
  • Include rule: \C:\Dir1* []\
  • Exclude rule: \C:\Dir1\Dir2* [.txt]\

Component 2:
  • Include rule: \C:\Dir1\Dir2* [.txt]\
  • Exclude rule: \C:\Dir1* []\
| Migrates all files and subfolders of C:\Dir1\ (including C:\Dir1\Dir2). | Rules that are in different components don't affect each other, except for the **\** rule. Therefore, in this example, although some **.txt** files were excluded when Component 1 was processed, they were included when Component 2 was processed. | +| Component 1:
  • Include rule: C:\Dir1\Dir2* []

Component 2:
  • Exclude rule: C:\Dir1* [.txt]
| Migrates all files and subfolders from Dir2 except the **.txt** files in C:\Dir1 and its subfolders. | Both rules are processed as intended. | +| Component 1:
  • Exclude rule: C:\Dir1\Dir2* []

Component 2:
  • Include rule: C:\Dir1* [.txt]
| Migrates all **.txt** files in Dir1 and any subfolders. | Component 1 doesn't contain an **\** rule, so the **\** rule isn't processed. | ### Including and excluding registry objects -| If you have the following code in the same component | Resulting behavior | Explanation | +| If the following code exists in the same component | Resulting behavior | Explanation | |-----|-----|-----| -|
  • Include rule:
    HKLM\Software\Microsoft\Command Processor* []
  • Exclude Rule:
    HKLM\Software\Microsoft\Command Processor [DefaultColor]
| Migrates all keys in HKLM\Software\Microsoft\Command Processor except DefaultColor. | Both rules are processed as intended. | -|
  • Include rule:
    HKLM\Software\Microsoft\Command Processor [DefaultColor]
  • Exclude Rule:
    HKLM\Software\Microsoft\Command Processor* []
| Migrates only DefaultColor in HKLM\Software\Microsoft\Command Processor. | DefaultColor is migrated because the **<include>** rule is more specific than the **<exclude>** rule. | -|
  • Include rule:
    HKLM\Software\Microsoft\Command Processor [DefaultColor]
  • Exclude rule:
    HKLM\Software\Microsoft\Command Processor [DefaultColor]
| Doesn't migrate DefaultColor. | The rules are equally specific, so the **<exclude>** rule takes precedence over the <include> rule. | +|
  • Include rule:
    HKLM\Software\Microsoft\Command Processor* []
  • Exclude Rule:
    HKLM\Software\Microsoft\Command Processor [DefaultColor]
| Migrates all keys in HKLM\Software\Microsoft\Command Processor except DefaultColor. | Both rules are processed as intended. | +|
  • Include rule:
    HKLM\Software\Microsoft\Command Processor [DefaultColor]
  • Exclude Rule:
    HKLM\Software\Microsoft\Command Processor* []
| Migrates only DefaultColor in HKLM\Software\Microsoft\Command Processor. | DefaultColor is migrated because the **\** rule is more specific than the **\** rule. | +|
  • Include rule:
    HKLM\Software\Microsoft\Command Processor [DefaultColor]
  • Exclude rule:
    HKLM\Software\Microsoft\Command Processor [DefaultColor]
| Doesn't migrate DefaultColor. | The rules are equally specific, so the **\** rule takes precedence over the \ rule. | -| If you have the following code in different components | Resulting behavior | Explanation | +| If the following code exists in different components | Resulting behavior | Explanation | |-----|-----|-----| -| Component 1:
  • Include rule:
    HKLM\Software\Microsoft\Command Processor [DefaultColor]
  • Exclude rule:
    HKLM\Software\Microsoft\Command Processor* []

Component 2:
  • Include rule:
    HKLM\Software\Microsoft\Command Processor* []
  • Exclude rule:
    HKLM\Software\Microsoft\Command Processor [DefaultColor]
| Migrates all the keys/values under HKLM\Software\Microsoft\Command Processor. | Rules that are in different components don't affect each other, except for the **<unconditionalExclude>** rule. Therefore, in this example, the objects that were excluded when Component 1 was processed were included when Component 2 was processed. | +| Component 1:
  • Include rule:
    HKLM\Software\Microsoft\Command Processor [DefaultColor]
  • Exclude rule:
    HKLM\Software\Microsoft\Command Processor* []

Component 2:
  • Include rule:
    HKLM\Software\Microsoft\Command Processor* []
  • Exclude rule:
    HKLM\Software\Microsoft\Command Processor [DefaultColor]
| Migrates all the keys/values under HKLM\Software\Microsoft\Command Processor. | Rules that are in different components don't affect each other, except for the **\** rule. In this example, the objects that were excluded when Component 1 was processed were included when Component 2 was processed. | ## File collisions ### What is the default behavior when there are file collisions? -If there isn't a **<merge>** rule, the default behavior for the registry is for the source to overwrite the destination. The default behavior for files is for the source to be renamed incrementally: for example, OriginalFileName(1).OriginalExtension, OriginalFileName(2).OriginalExtension, and so on. +If there isn't a **\** rule, the default behavior for the registry is for the source to overwrite the destination. The default behavior for files is for the source to be renamed incrementally: for example, OriginalFileName(1).OriginalExtension, OriginalFileName(2).OriginalExtension, and so on. -### How does the <merge> rule work when there are file collisions? +### How does the \ rule work when there are file collisions? -When 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 for **C:\\\* \[\*\]** set to **sourcePriority()** and another **<merge>** rule for **C:\\subfolder\\\* \[\*\]** set to **destinationPriority()** , then USMT uses the **destinationPriority()** rule because it's the most specific. +When a collision is detected, USMT selects the most specific **\** rule and apply it to resolve the conflict. For example, if a **\** rule exists for **C:\\\* \[\*\]** set to **sourcePriority()** and another **\** rule for **C:\\subfolder\\\* \[\*\]** set to **destinationPriority()** , then USMT uses the **destinationPriority()** rule because it's the most specific. ### Example scenario @@ -178,7 +181,7 @@ The destination computer contains the following files: - `C:\Data\SampleB.txt` -You have a custom .xml file that contains the following code: +A custom **.xml** file contains the following code: ```xml @@ -188,7 +191,7 @@ You have a custom .xml file that contains the following code: ``` -For this example, the following information describes the resulting behavior if you add the code to your custom .xml file. +For this example, the following information describes the resulting behavior if the code is added to the custom **.xml** file. #### Example 1 @@ -200,7 +203,7 @@ For this example, the following information describes the resulting behavior if ``` -**Result**: During ScanState, all the files will be added to the store. During LoadState, only `C:\Data\SampleA.txt` will be restored. +**Result**: During ScanState, all the files are added to the store. During LoadState, only `C:\Data\SampleA.txt` is restored. #### Example 2 @@ -212,8 +215,8 @@ For this example, the following information describes the resulting behavior if ``` -**Result**: During ScanState, all the files will be added to the store. -During LoadState, all the files will be restored, overwriting the existing files on the destination computer. +**Result**: During ScanState, all the files are added to the store. +During LoadState, all the files are restored, overwriting the existing files on the destination computer. #### Example 3 @@ -225,12 +228,12 @@ During LoadState, all the files will be restored, overwriting the existing files ``` -**Result**: During ScanState, all the files will be added to the store. During LoadState, the following actions will occur: +**Result**: During ScanState, all the files are added to the store. During LoadState, the following actions occur: -- `C:\Data\SampleA.txt` will be restored. -- `C:\Data\SampleB.txt` will be restored, overwriting the existing file on the destination computer. -- `C:\Data\Folder\SampleB.txt` won't be restored. +- `C:\Data\SampleA.txt` is restored. +- `C:\Data\SampleB.txt` is restored, overwriting the existing file on the destination computer. +- `C:\Data\Folder\SampleB.txt` aren't restored. ## Related articles -[USMT XML reference](usmt-xml-reference.md) +[USMT XML reference](usmt-xml-reference.md). diff --git a/windows/deployment/usmt/usmt-custom-xml-examples.md b/windows/deployment/usmt/usmt-custom-xml-examples.md index 73cf61e887..5784abdf38 100644 --- a/windows/deployment/usmt/usmt-custom-xml-examples.md +++ b/windows/deployment/usmt/usmt-custom-xml-examples.md @@ -1,20 +1,23 @@ --- -title: Custom XML Examples (Windows 10) -description: Use custom XML examples to learn how to migrate an unsupported application, migrate files and registry keys, and migrate the My Videos folder. +title: Custom XML Examples +description: Use custom XML examples to learn how to migrate an unsupported application, migrate files and registry keys, and migrate the Videos folder. manager: aaroncz ms.author: frankroj ms.prod: windows-client author: frankroj ms.topic: article ms.technology: itpro-deploy -ms.date: 11/01/2022 +ms.date: 01/03/2024 +appliesto: + - ✅ Windows 11 + - ✅ Windows 10 --- # Custom XML Examples ## Example 1: Migrating an unsupported application -The following template is a template for the sections that you need to migrate your application. The template isn't functional on its own, but you can use it to write your own .xml file. +The following template is a template for the sections that are needed to migrate applications. The template isn't functional on its own, but it can be used to write custom **.xml** file. **Template**
@@ -89,19 +92,19 @@ The following template is a template for the sections that you need to migrate y ## Example 2: Migrating the My Videos folder -The following sample is a custom .xml file named `CustomFile.xml` that migrates **My Videos** for all users, if the folder exists on the source computer. +The following sample is a custom **.xml** file named `CustomFile.xml` that migrates the **Videos** folder for all users, if the folder exists on the source computer. -- **Sample condition**: Verifies that **My Videos** exists on the source computer: +- **Sample condition**: Verifies that the **Videos** folder exists on the source computer: `MigXmlHelper.DoesObjectExist("File","%CSIDL_MYVIDEO%")` -- **Sample filter**: Filters out the shortcuts in **My Videos** that don't resolve on the destination computer: +- **Sample filter**: Filters out the shortcuts in the **Videos** folder that don't resolve on the destination computer: `` - This filter has no effect on files that aren't shortcuts. For example, if there's a shortcut in **My Videos** on the source computer that points to `C:\Folder1`, that shortcut will be migrated only if `C:\Folder1` exists on the destination computer. However, all other files, such as .mp3 files, migrate without any filtering. + This filter has no effect on files that aren't shortcuts. For example, if there's a shortcut in the **Videos** folder on the source computer that points to `C:\Folder1`, that shortcut is migrated only if `C:\Folder1` exists on the destination computer. However, all other files, such as **.mp3** files, migrate without any filtering. -- **Sample pattern**: Migrates **My Videos** for all users: +- **Sample pattern**: Migrates the **Videos** folder for all users: `%CSIDL_MYVIDEO%* [*]` @@ -137,7 +140,7 @@ The following sample is a custom .xml file named `CustomFile.xml` that migrates ## Example 3: Migrating files and registry keys -The sample patterns describe the behavior in the following example .xml file. +The sample patterns describe the behavior in the following example **.xml** file. - **Sample pattern**: Migrates all instances of the file `Usmttestfile.txt` from all subdirectories under `%ProgramFiles%\USMTTestFolder`: @@ -195,7 +198,7 @@ The sample patterns describe the behavior in the following example .xml file. ## Example 4: Migrating specific folders from various locations -The behavior for this custom .xml file is described within the `` tags in the code. +The behavior for this custom **.xml** file is described within the `` tags in the code. **XML file**
@@ -275,6 +278,5 @@ The behavior for this custom .xml file is described within the `` t ## Related articles -[USMT XML reference](usmt-xml-reference.md) - -[Customize USMT XML files](usmt-customize-xml-files.md) +- [USMT XML reference](usmt-xml-reference.md). +- [Customize USMT XML files](usmt-customize-xml-files.md). diff --git a/windows/deployment/usmt/usmt-customize-xml-files.md b/windows/deployment/usmt/usmt-customize-xml-files.md index 7964757619..9f102208a9 100644 --- a/windows/deployment/usmt/usmt-customize-xml-files.md +++ b/windows/deployment/usmt/usmt-customize-xml-files.md @@ -1,77 +1,83 @@ --- -title: Customize USMT XML Files (Windows 10) +title: Customize USMT XML Files description: Learn how to customize USMT XML files. Also, learn about the migration XML files that are included with USMT. manager: aaroncz ms.author: frankroj ms.prod: windows-client author: frankroj -ms.date: 11/01/2022 +ms.date: 01/03/2024 ms.topic: article ms.technology: itpro-deploy +appliesto: + - ✅ Windows 11 + - ✅ Windows 10 --- # Customize USMT XML files ## Overview -If you want the ScanState and LoadState tools to use any of the migration .xml files, specify these files at the command line using the `/i` option. Because the ScanState and LoadState tools need the .xml files to control the migration, specify the same set of .xml files for both the `ScanState.exe` and `LoadState.exe` commands. However, you don't have to specify the `Config.xml` file with the `/config` option, unless you want to exclude some of the files and settings that you migrated to the store. For example, you might want to migrate the My Documents folder to the store but not to the destination computer. To achieve this scenario, modify the `Config.xml` file and specify the updated file with the `LoadState.exe` command. Then the `LoadState.exe` command will migrate only the files and settings that you want to migrate. +To use any of the migration **.xml** files with the **ScanState** and **LoadState** tools, specify these files at the command line using the `/i` option. Because the **ScanState** and **LoadState** tools need the **.xml** files to control the migration, specify the same set of **.xml** files for both the `ScanState.exe` and `LoadState.exe` commands. However, the `Config.xml` file with the `/config` option doesn't need to be specified, unless some of the migrated files and settings from the store need to be excluded. For example, to migrate the **Documents** folder to the store but not to the destination computer. To achieve this scenario, modify the `Config.xml` file and specify the updated file with the `LoadState.exe` command. The `LoadState.exe` command then only migrates the desired files and settings. -If you leave out an .xml file from the `LoadState.exe` command, all of the data in the store that was migrated with the missing .xml files will be migrated. However, the migration rules that were specified with the `ScanState.exe` command won't apply. For example, if you leave out an .xml file, and it contains a rerouting rule such as: +If an **.xml** file is left out from the `LoadState.exe` command, all of the data in the store that was migrated with the missing **.xml** files are migrated. However, the migration rules that were specified with the `ScanState.exe` command don't apply. For example, if an **.xml** file is left out, and it contains a rerouting rule such as: `MigsysHelperFunction.RelativeMove("c:\data", "%CSIDL_PERSONAL%")` -USMT won't reroute the files, and they'll be migrated to `C:\data`. +USMT doesn't reroute the files, and they're migrated to `C:\data`. To modify the migration, do one or more of the following. -- **Modify the migration .xml files.** If you want to exclude a portion of a component, for example, you want to migrate C:\\ but exclude all of the .mp3 files, or if you want to move data to a new location on the destination computer, modify the .xml files. To modify these files, you must be familiar with the migration rules and syntax. If you want ScanState and LoadState to use these files, specify them at the command line when each command is entered. +- **Modify the migration .xml files.** To exclude a portion of a component, modify the **.xml** files. For example, to migrate C:\\ but exclude all of the **.mp3** files, or to move data to a new location on the destination computer. To modify these files, familiarity with the migration rules and syntax is a must. For **ScanState** and **LoadState** to use these files, specify them at the command line when each command is entered. -- **Create a custom .xml file.** You can also create a custom .xml file to migrate settings for another application, or to change the migration behavior to suit your needs. For ScanState and LoadState to use this file, specify them on both command lines. +- **Create a custom .xml file.** A custom **.xml** file can also be created to migrate settings for another application, or to change the migration behavior to suit the organization's needs. For **ScanState** and **LoadState** to use this file, specify them on both command lines. -- **Create and modify a Config.xml file.** Create and modify a `Config.xml` file if you want to exclude an entire component from the migration. For example, you can use a `Config.xml` file to exclude the entire My Documents folder, or exclude the settings for an application. Excluding components using a `Config.xml` file is easier than modifying the migration .xml files because you don't need to be familiar with the migration rules and syntax. In addition, using a `Config.xml` file is the only way to exclude the operating system settings from being migrated. +- **Create and modify a Config.xml file.** Create and modify a `Config.xml` file to exclude an entire component from the migration. For example, a `Config.xml` file can be used to exclude the entire **Documents** folder, or exclude the settings for an application. Excluding components using a `Config.xml` file is easier than modifying the migration **.xml** files because familiarity with the migration rules and syntax isn't needed. In addition, using a `Config.xml` file is the only way to exclude the operating system settings from being migrated. For more information about excluding data, see the [Exclude Files and Settings](usmt-exclude-files-and-settings.md) article. ## Migration .xml files -This section describes the migration .xml files that are included with USMT. Each file contains migration rules that control which components are migrated and where they're migrated to on the destination computer. +This section describes the migration **.xml** files that are included with USMT. Each file contains migration rules that control which components are migrated and where they're migrated to on the destination computer. > [!NOTE] -> You can use the asterisk (\*) wildcard character in each of these files. However, you cannot use a question mark (?) as a wildcard character. +> +> The asterisk (\*) wildcard character can be used in each of these files. However, a question mark (?) can't be used as a wildcard character. - **The MigApp.xml file.** Specify this file with both the `ScanState.exe` and `LoadState.exe` commands to migrate application settings. -- **The MigDocs.xml file.** Specify this file with both the ScanState and LoadState tools to migrate all user folders and files that are found by the **MigXmlHelper.GenerateDocPatterns** helper function. This helper function finds user data that resides on the root of any drive and in the Users directory. However, it doesn't find and migrate any application data, program files, or any files in the Windows directory. You can modify the `MigDocs.xml` file. +- **The MigDocs.xml file.** Specify this file with both the **ScanState** and **LoadState** tools to migrate all user folders and files that are found by the **MigXmlHelper.GenerateDocPatterns** helper function. This helper function finds user data that resides on the root of any drive and in the Users directory. However, it doesn't find and migrate any application data, program files, or any files in the Windows directory. The `MigDocs.xml` file can be modified. -- **The MigUser.xml file.** Specify this file with both the `ScanState.exe` and `LoadState.exe` commands to migrate user folders, files, and file types. You can modify the `MigUser.xml` file. This file doesn't contain rules that migrate specific user accounts. The only way to specify which user accounts to migrate is on the command line using the ScanState and the LoadState user options. +- **The MigUser.xml file.** Specify this file with both the `ScanState.exe` and `LoadState.exe` commands to migrate user folders, files, and file types. The `MigUser.xml` file can be modified. This file doesn't contain rules that migrate specific user accounts. The only way to specify which user accounts to migrate is on the command line by using the [ScanState User options](usmt-scanstate-syntax.md#user-options) and the [LoadState User options](usmt-loadstate-syntax.md#user-options). > [!NOTE] +> > Don't use the `MigUser.xml` and `MigDocs.xml` files together. For more information, see the [Identify file types, files, and folders](usmt-identify-file-types-files-and-folders.md) and [USMT best practices](usmt-best-practices.md) articles. ## Custom .xml files -You can create custom .xml files to customize the migration for your unique needs. For example, you may want to create a custom file to migrate a line-of-business application or to modify the default migration behavior. If you want `ScanState.exe` and `LoadState.exe` to use this file, specify it with both commands. For more information, see the [Custom XML examples](usmt-custom-xml-examples.md) article. +Custom **.xml** files can be created to customize the migration for the organization's unique needs. For example, a custom **.xml** file can be created to migrate a line-of-business application or to modify the default migration behavior. For `ScanState.exe` and `LoadState.exe` to use this file, specify it with both commands. For more information, see the [Custom XML examples](usmt-custom-xml-examples.md) article. ## The Config.xml file -The `Config.xml` file is an optional file that you create using the `/genconfig` option with the `ScanState.exe` command. You should create and modify this file if you want to exclude certain components from the migration. In addition, you must create and modify this file if you want to exclude any of the operating system settings from being migrated. The `Config.xml` file format is different from the migration .xml files because it doesn't contain any migration rules. It contains only a list of the operating system components, applications, and the user documents that can be migrated. For an example, see the [Config.xml File](usmt-configxml-file.md) article. For this reason, excluding components using this file is easier than modifying the migration .xml files because you don't need to be familiar with the migration rules and syntax. However, you can't use wildcard characters in a `Config.xml` file. +The `Config.xml` file is an optional file that is created using the `/genconfig` option with the `ScanState.exe` command. This file should be created and modified to exclude certain components from the migration. In addition, this file must be created and modified to exclude any of the operating system settings from being migrated. The `Config.xml` file format is different from the migration **.xml** files because it doesn't contain any migration rules. It contains only a list of the operating system components, applications, and the user documents that can be migrated. For an example, see the [Config.xml File](usmt-configxml-file.md) article. For this reason, excluding components using the `Config.xml` file is easier than modifying the migration **.xml** files. With the `Config.xml`, familiarity with the migration rules and syntax isn't. However, wildcard characters can't be used in a `Config.xml` file. -If you want to include all of the default components, you don't need to create the `Config.xml` file. Alternatively, if you're satisfied with the default migration behavior defined in the `MigApp.xml`, `MigDocs.xml`, and `MigUser.xml` files, and you want to exclude only some components, you can create and modify a `Config.xml` file and leave the other .xml files in their original state. +To include all of the default components, a `Config.xml` file doesn't need to be created. Alternatively, if the default migration behavior defined in the `MigApp.xml`, `MigDocs.xml`, and `MigUser.xml` files are satisfactory, and only some components need to be excluded, a `Config.xml` file can be created. The other **.xml** files can be left in their original state. -When you run the `ScanState.exe` command with the `/genconfig` option, `ScanState.exe` reads the other .xml files that you specify using the `/i` option to create a custom list of components that can be migrated from the computer. This file will contain only operating system components, applications, and the user document sections that are in both of the .xml files and that are installed on the computer when you run the `ScanState.exe` command with the `/genconfig` option. Therefore, you should create this file on a source computer that contains all of the components, applications, and settings that will be present on the destination computers. Creating the file on the source computer will ensure that this file contains every component that can be migrated. The components are organized into sections: <Applications>, <WindowsComponents>, and <Documents>. To choose not to migrate a component, change its entry to `migrate="no"`. +When the `ScanState.exe` command is run with the `/genconfig` option, `ScanState.exe` reads the other **.xml** files that are specified using the `/i` option to create a custom list of components that can be migrated from the computer. This file contains only operating system components, applications, and the user document sections that are in both of the **.xml** files and that are installed on the computer when the `ScanState.exe` command is run with the `/genconfig` option. Therefore, this file should be created on a source computer that contains all of the components, applications, and settings that are present on the destination computers. Creating the file on the source computer ensures that this file contains every component that can be migrated. The components are organized into sections: \, \, and \. To choose not to migrate a component, change its entry to `migrate="no"`. -After you create this file, you need to specify it only with the `ScanState.exe` command using the `/Config` option for it to affect the migration. However, if you want to exclude additional data that you migrated to the store, modify the `Config.xml` file and specify the updated file with the `LoadState.exe` command. For example, if you collected the My Documents folder in the store, but you decide that you don't want to migrate the My Documents folder to a destination computer, you can modify the `Config.xml` file to indicate `migrate="no"` before you run the `LoadState.exe` command, and the file won't be migrated. For more information about the precedence that takes place when excluding data, see the [Exclude files and settings](usmt-exclude-files-and-settings.md) article. +After this file is created, it only needs to be specified with the `ScanState.exe` command using the `/Config` option for it to affect the migration. However, if additional data that was migrated to the store needs to be excluded, modify the `Config.xml` file and specify the updated file with the `LoadState.exe` command. For example, if the **Documents** folder is collected in the store, but the **Documents** folder doesn't need to be migrated to a destination computer, the `Config.xml` file can be modified to indicate `migrate="no"` before the `LoadState.exe` command runs, and the file aren't be migrated. For more information about the precedence that takes place when excluding data, see the [Exclude files and settings](usmt-exclude-files-and-settings.md) article. In addition, note the following functionality with the `Config.xml` file: -- If a parent component is removed from the migration in the `Config.xml` file by specifying `migrate="no"`, all of its child components will automatically be removed from the migration, even if the child component is set to `migrate="yes"`. +- If a parent component is removed from the migration in the `Config.xml` file by specifying `migrate="no"`, all of its child components are automatically removed from the migration, even if the child component is set to `migrate="yes"`. -- If you mistakenly have two lines of code for the same component where one line specifies `migrate="no"` and the other line specifies `migrate="yes"`, the component will be migrated. +- If mistakenly two lines of code exist for the same component where one line specifies `migrate="no"` and the other line specifies `migrate="yes"`, the component is migrated. -- In USMT, there are several migration policies that can be configured in the `Config.xml` file. For example, you can configure additional **<ErrorControl>**, **<ProfileControl>**, and **<HardLinkStoreControl>** options. For more information, see the [Config.xml File](usmt-configxml-file.md) article. +- In USMT, there are several migration policies that can be configured in the `Config.xml` file. For example, additional **\**, **\**, and **\** options can be configured. For more information, see the [Config.xml File](usmt-configxml-file.md) article. > [!NOTE] -> To exclude a component from the `Config.xml` file, set the **migrate** value to **"no"**. Deleting the XML tag for the component from the `Config.xml` file will not exclude the component from your migration. +> +> To exclude a component from the `Config.xml` file, set the **migrate** value to **"no"**. Deleting the XML tag for the component from the `Config.xml` file doesn't exclude the component from the migration. ### Examples @@ -79,7 +85,7 @@ In addition, note the following functionality with the `Config.xml` file: `ScanState.exe /i:MigApp.xml /i:MigDocs.xml /genconfig:Config.xml /v:5` -- The following command creates an encrypted store using the `Config.xml` file and the default migration .xml files: +- The following command creates an encrypted store using the `Config.xml` file and the default migration **.xml** files: `ScanState.exe \\server\share\migration\mystore /i:MigApp.xml /i:MigDocs.xml /o /config:Config.xml /v:5 /encrypt /key:"mykey"` @@ -89,14 +95,11 @@ In addition, note the following functionality with the `Config.xml` file: ## Additional information -- For more information about how to change the files and settings that are migrated, see the [User State Migration Tool (USMT) how-to topics](usmt-how-to.md). - -- For more information about each .xml element, see the [XML elements library](usmt-xml-elements-library.md) article. - +- For more information about how to change the files and settings that are migrated, see the [User State Migration Tool (USMT) how-to articles](usmt-how-to.md). +- For more information about each **.xml** element, see the [XML elements library](usmt-xml-elements-library.md) article. - For answers to common questions, see ".xml files" in the [Frequently asked questions](usmt-faq.yml) article. ## Related articles -[User State Migration Tool (USMT) command-line syntax](usmt-command-line-syntax.md) - -[USMT resources](usmt-resources.md) +- [User State Migration Tool (USMT) command-line syntax](usmt-command-line-syntax.md). +- [USMT resources](usmt-resources.md). diff --git a/windows/deployment/usmt/usmt-determine-what-to-migrate.md b/windows/deployment/usmt/usmt-determine-what-to-migrate.md index 67138078a2..3fd59322ea 100644 --- a/windows/deployment/usmt/usmt-determine-what-to-migrate.md +++ b/windows/deployment/usmt/usmt-determine-what-to-migrate.md @@ -1,28 +1,36 @@ --- -title: Determine What to Migrate (Windows 10) -description: Determine migration settings for standard or customized for the User State Migration Tool (USMT) 10.0. +title: Determine What to Migrate +description: Determine migration settings for standard or customized for the User State Migration Tool (USMT). manager: aaroncz ms.author: frankroj ms.prod: windows-client author: frankroj -ms.date: 11/01/2022 +ms.date: 01/03/2024 ms.topic: article ms.technology: itpro-deploy +appliesto: + - ✅ Windows 11 + - ✅ Windows 10 --- # Determine what to migrate -By default, User State Migration Tool (USMT) 10.0 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 what settings you would like the user to be able to configure, if any, and what settings you would like 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, Internet Explorer security settings, and desktop configuration are some of the items you can choose to standardize. +However, when considering what settings to migrate, also consider: -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: +- What settings the user can configure, if any. +- What settings should be standardized. -- A baseline for all computers, including standard hardware drivers -- Core operating system features -- Core productivity applications, especially if they are under volume licensing +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, 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. +- Core productivity applications, especially if they are under volume licensing. - Core utilities. -- A standard set of security features, as outlined in the organization's corporate policy +- A standard set of security features, as outlined in the organization's corporate policy. Using an SOE can vastly simplify the migration and reduce overall deployment challenges. @@ -31,10 +39,10 @@ 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)|Determine and locate the standard, company-specified, and non-standard locations of the file types, files, folders, and settings that you want to migrate.| +|[Identify file types, files, and folders](usmt-identify-file-types-files-and-folders.md)|For the following items that need to be migrated:
  • File types.
  • Files.
  • Folders.
  • Settings.
determine where these items might be located. For example:
  • Standard default OS locations.
  • Organization-specified locations.
  • Non-standard locations.
| ## Related articles -[What does USMT migrate?](usmt-what-does-usmt-migrate.md) +- [What does USMT migrate?](usmt-what-does-usmt-migrate.md). diff --git a/windows/deployment/usmt/usmt-estimate-migration-store-size.md b/windows/deployment/usmt/usmt-estimate-migration-store-size.md index e994e3640b..943f389168 100644 --- a/windows/deployment/usmt/usmt-estimate-migration-store-size.md +++ b/windows/deployment/usmt/usmt-estimate-migration-store-size.md @@ -1,77 +1,86 @@ --- -title: Estimate Migration Store Size (Windows 10) -description: Estimate the disk space requirement for a migration so that you can use User State Migration Tool (USMT). +title: Estimate Migration Store Size +description: Estimate the disk space requirement for a migration so that the User State Migration Tool (USMT) can be used. manager: aaroncz ms.author: frankroj ms.prod: windows-client author: frankroj -ms.date: 11/01/2022 +ms.date: 01/03/2024 ms.topic: article ms.technology: itpro-deploy +appliesto: + - ✅ Windows 11 + - ✅ Windows 10 --- # Estimate migration store size -The disk space requirements for a migration are dependent on the size of the migration store and the type of migration. You can estimate the amount of disk space needed for computers in your organization based on information about your organization's infrastructure. You can also calculate the disk space requirements using the ScanState tool. +The disk space requirements for a migration are dependent on the size of the migration store and the type of migration. The amount of disk space needed for computers in the organization can be estimated based on information about the organization's infrastructure. Disk space requirements can also be calculated using the **ScanState** tool. ## Hard disk space requirements -- **Store**: For non-hard-link migrations, you should ensure that there's enough available disk space at the location where you'll save your store to contain the data being migrated. You can save your store to another partition, an external storage device such as a USB flash drive or a server. For more information, see [Choose a Migration Store Type](usmt-choose-migration-store-type.md). +- **Store**: For non-hard-link migrations, ensure that there's enough available disk space at the location where the store is saved. The store contains the data being migrated. The store can be saved to another partition, an external storage device such as a USB flash drive, or a server. For more information, see [Choose a Migration Store Type](usmt-choose-migration-store-type.md). - **Source Computer**: The source computer needs enough available space for the following items: - - **E250 megabytes (MB) minimum of hard disk space**: Space is needed to support the User State Migration Tool (USMT) 10.0 operations, for example, growth in the page file. If every volume involved in the migration is formatted as NTFS, 250 MB should be enough space to ensure success for almost every hard-link migration, regardless of the size of the migration. The USMT tools won't create the migration store if 250 MB of disk space isn't available. + - **E250 megabytes (MB) minimum of hard disk space**: Space is needed to support the User State Migration Tool (USMT) operations, for example, growth in the page file. If every volume involved in the migration is formatted as NTFS, 250 MB should be enough space to ensure success for almost every hard-link migration, regardless of the size of the migration. The USMT tool that captures data (ScanState) doesn't create the migration store if 250 MB of disk space isn't available. - - **Temporary space for USMT to run**: Extra disk space for the USMT tools to operate is required. This disk space requirement doesn't include the minimum 250 MB needed to create the migration store. The amount of temporary space required can be calculated using the ScanState tool. + - **Temporary space for USMT to run**: Extra disk space is required for the USMT tools to operate. This disk space requirement doesn't include the minimum 250 MB needed to create the migration store. The amount of temporary space required can be calculated using the **ScanState** tool. - **Hard-link migration store**: It isn't necessary to estimate the size of a hard-link migration store. The only case where the hard-link store can be large is when non-NTFS file volumes exist on the system and those volumes contain data being migrated. - **Destination computer**: The destination computer needs enough available space for the following components: - - **Operating system** + - **Operating system**. - - **Applications** + - **Applications**. - **Data being migrated**: Data being migrated includes files and registry information. - - **Temporary space for USMT to run**: Extra disk space for the USMT tools to operate is required. The amount of temporary space required can be calculated using the ScanState tool. + - **Temporary space for USMT to run**: Extra disk space is required for the USMT tools to operate. The amount of temporary space required can be calculated using the **ScanState** tool. -## Calculate disk space requirements using the ScanState tool +## Calculate disk space requirements using the **ScanState** tool -You can use the ScanState tool to calculate the disk space requirements for a particular compressed or uncompressed migration. It isn't necessary to estimate the migration store size for a hard-link migration since this method doesn't create a separate migration store. The ScanState tool provides disk space requirements for the state of the computer at the time the tool is run. The state of the computer may change during day-to-day use so it's recommended that you use the calculations as an estimate when planning your migration. +The **ScanState** tool can be used to calculate the disk space requirements for a particular compressed or uncompressed migration. It isn't necessary to estimate the migration store size for a hard-link migration since this method doesn't create a separate migration store. The **ScanState** tool provides disk space requirements for the state of the computer at the time the tool is run. The state of the computer might change during day-to-day use. For this reason, use the calculations as an estimate when planning the migration. -To run the ScanState tool on the source computer with USMT installed: +To run the **ScanState** tool on the source computer with USMT installed: 1. Open a command prompt with administrator privileges. -2. Navigate to the USMT tools. For example, enter: +1. Navigate to the USMT tools. For example, enter: ```cmd - cd /d "C:\Program Files (x86)\Windows Kits\8.0\Assessment and Deployment Kit\User State Migration Tool\" + cd /d "C:\Program Files (x86)\Windows Kits\10.0\Assessment and Deployment Kit\User State Migration Tool\" ``` - where *<architecture>* is x86 or amd64. + where *\* is x86 or amd64. -3. Run the **ScanState** tool to generate an XML report of the space requirements. At the command prompt, enter: +1. Run the **ScanState** tool to generate an XML report of the space requirements. At the command prompt, enter: ```cmd ScanState.exe /p: ``` - Where *<StorePath>* is a path to a directory where the migration store will be saved and *<path to a file>* is the path and filename where the XML report for space requirements will be saved. For example: + Where: + + - *\* is a path to a directory where the migration store is saved. + - *\* is the path and filename where the XML report for space requirements is saved. + + For example: ```cmd ScanState.exe c:\store /p:c:\spaceRequirements.xml ``` - Although a migration store isn't created by running this command, the *<StorePath>* is still a required parameter. + Although a migration store isn't created by running this command, the *\* is still a required parameter. -The ScanState tool also allows you to estimate disk space requirements based on a customized migration. For example, you might not want to migrate the My Documents folder to the destination computer. You can specify this condition in a configuration file when you run the ScanState tool. For more information, see [Customize USMT XML files](usmt-customize-xml-files.md). +The **ScanState** tool also allows estimation of disk space requirements based on a customized migration. For example, the **Documents** folder might need to be migrated to the destination computer. This condition can be specified in a configuration file when the **ScanState** tool is run. For more information, see [Customize USMT XML files](usmt-customize-xml-files.md). > [!NOTE] -> To preserve the functionality of existing applications or scripts that require the previous behavior of USMT, the `/p` option is still available in USMT without having to specify the path to a file. See [Monitoring Options](usmt-scanstate-syntax.md#monitoring-options) for more information. +> +> To preserve the functionality of existing applications or scripts that require the previous behavior of USMT, the `/p` option is still available in USMT without having to specify the path to a file. For more information, see [Monitoring Options](usmt-scanstate-syntax.md#monitoring-options). -The space requirements report provides two elements, <**storeSize**> and <**temporarySpace**>. The <**temporarySpace**> value shows the disk space, in bytes, that USMT uses to operate during the migration but it doesn't include the minimum 250 MB needed to support USMT. The <**storeSize**> value shows the disk space, in bytes, required to host the migration store contents on both the source and destination computers. The following example shows a report generated using `/p:`*<path to a file>*. +The space requirements report provides two elements, \<**storeSize**\> and \<**temporarySpace**\>. The \<**temporarySpace**\> value shows the disk space, in bytes, that USMT uses to operate during the migration but it doesn't include the minimum 250 MB needed to support USMT. The \<**storeSize**\> value shows the disk space, in bytes, required to host the migration store contents on both the source and destination computers. The following example shows a report generated using `/p:`*\*. ```xml @@ -85,25 +94,26 @@ The space requirements report provides two elements, <**storeSize**> and & ``` -Additionally, USMT performs a compliance check for a required minimum of 250 MB of available disk space and won't create a store if the compliance check fails. +Additionally, USMT performs a compliance check for a required minimum of 250 MB of available disk space and doesn't create a store if the compliance check fails. ## Estimating migration store size -Determine how much space you'll need to store the migrated data. You should base your calculations on the volume of e-mail, personal documents, and system settings for each user. The best way to estimate the required space is to survey several computers to arrive at an average for the size of the store that you'll need. +Determine how much space is needed to store the migrated data. Calculations should be based on the volume of e-mail, personal documents, and system settings for each user. The best way to estimate the required space is to survey several computers to arrive at an average for the size of the store that is needed. -The amount of space that is required in the store will vary, depending on the local storage strategies your organization uses. For example, one key element that determines the size of migration data sets is e-mail storage. If e-mail is stored centrally, data sets will be smaller. If e-mail is stored locally, such as offline-storage files, data sets will be larger. Mobile users will typically have larger data sets than workstation users. You should perform tests and inventory the network to determine the average data set size in your organization. +The amount of space that is required in the store varies and depends on the local storage strategies the organization uses. For example, one key element that determines the size of migration data sets is e-mail storage. If e-mail is stored centrally, data sets are smaller. If e-mail is stored locally, such as offline-storage files, data sets are larger. Mobile users typically have larger data sets than workstation users. Tests should be performed and the network inventoried to determine the average data set size in the organization. > [!NOTE] -> You can create a space-estimate file (`Usmtsize.txt`) to estimate the size of the store by using the legacy `/p` command-line option . +> +> A space-estimate file (`Usmtsize.txt`) can be created to estimate the size of the store by using the legacy `/p` command-line option. -When trying to determine how much disk space you'll need, consider the following issues: +When trying to determine how much disk space is needed, consider the following issues: - **E-mail**: If users deal with a large volume of e-mail or keep e-mail on their local computers instead of on a mail server, the e-mail can take up as much disk space as all other user files combined. Prior to migrating user data, make sure that users who store e-mail locally synchronize their inboxes with their mail server. -- **User documents**: Frequently, all of a user's documents fit into less than 50 MB of space, depending on the types of files involved. This estimate assumes typical office work, such as word-processing documents and spreadsheets. This estimate can vary substantially based on the types of documents that your organization uses. For example, an architectural firm that predominantly uses computer-aided design (CAD) files needs much more space than a law firm that primarily uses word-processing documents. You don't need to migrate the documents that users store on file servers through mechanisms such as Folder Redirection, as long as users will have access to these locations after the migration. +- **User documents**: Frequently, all of a user's documents fit into less than 50 MB of space, depending on the types of files involved. This estimate assumes typical office work, such as word-processing documents and spreadsheets. This estimate can vary substantially based on the types of documents that the organization uses. For example, an architectural firm that predominantly uses computer-aided design (CAD) files needs more space than a law firm that primarily uses word-processing documents. Documents that users store on file servers through mechanisms such as Folder Redirection don't need to be migrated, as long as users will have access to these locations after the migration. -- **User system settings**: Five megabytes is adequate space to save the registry settings. This requirement can fluctuate, however, based on the number of applications that have been installed. It's rare, however, for the user-specific portion of the registry to exceed 5 MB. +- **User system settings**: Five megabytes is adequate space to save the registry settings. This requirement can fluctuate, however, based on the number of applications that are installed. It's rare, however, for the user-specific portion of the registry to exceed 5 MB. ## Related articles -[Common migration scenarios](usmt-common-migration-scenarios.md) +- [Common migration scenarios](usmt-common-migration-scenarios.md). diff --git a/windows/deployment/usmt/usmt-exclude-files-and-settings.md b/windows/deployment/usmt/usmt-exclude-files-and-settings.md index d7c0f5e4fd..eaa1b73d0a 100644 --- a/windows/deployment/usmt/usmt-exclude-files-and-settings.md +++ b/windows/deployment/usmt/usmt-exclude-files-and-settings.md @@ -1,40 +1,43 @@ --- -title: Exclude Files and Settings (Windows 10) +title: Exclude Files and Settings description: In this article, learn how to exclude files and settings when creating a custom .xml file and a Config.xml file. manager: aaroncz ms.author: frankroj ms.prod: windows-client author: frankroj -ms.date: 09/18/2023 +ms.date: 01/03/2024 ms.topic: article ms.technology: itpro-deploy +appliesto: + - ✅ Windows 11 + - ✅ Windows 10 --- # Exclude files and settings -When you specify the migration .xml files, `MigApp.xml`, `MigDocs.xml`, and `MigUser.xml`, the User State Migration Tool (USMT) 10.0 migrates the settings and components listed, as discussed in [What does USMT migrate?](usmt-what-does-usmt-migrate.md) You can create a custom .xml file to further specify what to include or exclude in the migration. In addition, you can create a `Config.xml` file to exclude an entire component from a migration. You can't, however, exclude users by using the migration .xml files or the `Config.xml` file. The only way to specify which users to include and exclude is by using the user options on the command line in the ScanState tool. For more information, see the [User options](usmt-scanstate-syntax.md#user-options) section of the [ScanState syntax](usmt-scanstate-syntax.md) article. +When the migration **.xml** files `MigApp.xml`, `MigDocs.xml`, and `MigUser.xml` are specified, the User State Migration Tool (USMT) migrates the settings and components listed, as discussed in [What does USMT migrate?](usmt-what-does-usmt-migrate.md) A custom **.xml** file can be created to further specify what to include or exclude in the migration. In addition, a `Config.xml` file can be created to exclude an entire component from a migration. However, users can't be excluded by using the migration **.xml** files or the `Config.xml` file. The only way to specify which users to include and exclude is by using the user options on the command line in the **ScanState** tool. For more information, see the [User options](usmt-scanstate-syntax.md#user-options) section of the [ScanState syntax](usmt-scanstate-syntax.md) article. Methods to customize the migration and include and exclude files and settings include: -- [Create a custom .xml file](#create-a-custom-xml-file). You can use the following elements to specify what to exclude: +- [Create a custom .xml file](#create-a-custom-xml-file). The following elements can be used to specify what to exclude: - - [Include and exclude](#include-and-exclude): You can use the **<include>** and **<exclude>** elements to exclude objects with conditions. For example, you can migrate all files located in the `C:\` drive, except any `.mp3` files. It's important to remember that [Conflicts and precedence](usmt-conflicts-and-precedence.md) apply to these elements. + - [Include and exclude](#include-and-exclude): The **\** and **\** elements can be used to exclude objects with conditions. For example, all files located in the `C:\` drive can be migrated, except any `.mp3` files. It's important to remember that [Conflicts and precedence](usmt-conflicts-and-precedence.md) apply to these elements. - - [unconditionalExclude](#example-1-how-to-migrate-all-files-from-c-except-mp3-files): You can use the **<unconditionalExclude>** element to globally exclude data. This element takes precedence over all other include and exclude rules in the .xml files. Therefore, this element excludes objects regardless of any other **<include>** rules that are in the .xml files. For example, you can exclude all .mp3 files on the computer, or you can exclude all files from C:\\UserData. + - [unconditionalExclude](#example-1-how-to-migrate-all-files-from-c-except-mp3-files): The **\** element can be used to globally exclude data. This element takes precedence over all other include and exclude rules in the **.xml** files. Therefore, this element excludes objects regardless of any other **\** rules that are in the **.xml** files. For example, all **.mp3** files can be excluded on the computer, or all files from C:\\UserData can be excluded. -- [Create a Config.xml file](#create-a-config-xml-file): You can create and modify a `Config.xml` file to exclude an entire component from the migration. For example, you can use this file to exclude the settings for one of the default applications. In addition, creating and modifying a `Config.xml` file is the only way to exclude the operating-system settings that are migrated to computers running Windows. Excluding components using this file is easier than modifying the migration .xml files because you don't need to be familiar with the migration rules and syntax. +- [Create a Config.xml file](#create-a-config-xml-file): A `Config.xml` file can be created and modified to exclude an entire component from the migration. For example, this file can be used to exclude the settings for one of the default applications. In addition, creating and modifying a `Config.xml` file is the only way to exclude the operating-system settings that are migrated to computers running Windows. Excluding components using this file is easier than modifying the migration **.xml** files because familiarity with the migration rules and syntax isn't required. ## Create a custom .xml file -We recommend that you create a custom .xml file instead of modifying the default migration .xml files. When you use a custom .xml file, you can keep your changes separate from the default .xml file, which makes it easier to track your modifications. +Microsoft recommends creating a custom **.xml** file instead of modifying the default migration **.xml** files. When a custom **.xml** file is used, the changes can be kept separate from the default **.xml** file, which makes it easier to track the modifications. -### <include> and <exclude> +### \ and \ -The migration .xml files, `MigApp.xml`, `MigDocs.xml`, and `MigUser.xml`, contain the **<component>** element, which typically represents a self-contained component or an application such as Microsoft® Office Outlook® and Word. To exclude the files and registry settings that are associated with these components, use the **<include>** and **<exclude>** elements. For example, you can use these elements to migrate all files and settings with pattern X except files and settings with pattern Y, where Y is more specific than X. For the syntax of these elements, see [USMT XML Reference](usmt-xml-reference.md). +The migration **.xml** files, `MigApp.xml`, `MigDocs.xml`, and `MigUser.xml`, contain the **\** element, which typically represents a self-contained component or an application such as Microsoft Office Outlook and Word. To exclude the files and registry settings that are associated with these components, use the **\** and **\** elements. For example, these elements can be used to migrate all files and settings with pattern X except files and settings with pattern Y, where Y is more specific than X. For the syntax of these elements, see [USMT XML Reference](usmt-xml-reference.md). > [!NOTE] > -> If you specify an **<exclude>** rule, always specify a corresponding **<include>** rule. Otherwise, if you don't specify an **<include>** rule, the specific files or settings aren't included. They're already excluded from the migration. Thus, an unaccompanied **<exclude>** rule is unnecessary. +> If an **\** rule is specified, always specify a corresponding **\** rule. Otherwise, if an **\** rule isn't specified, the specific files or settings aren't included. They're already excluded from the migration. Thus, an unaccompanied **\** rule is unnecessary. - [Example 1: How to migrate all files from C:\\ except .mp3 files](#example-1-how-to-migrate-all-files-from-c-except-mp3-files) @@ -48,7 +51,7 @@ The migration .xml files, `MigApp.xml`, `MigDocs.xml`, and `MigUser.xml`, contai ### Example 1: How to migrate all files from `C:\` except `.mp3` files -The following .xml file migrates all files located on the C: drive, except any .mp3 files. +The following **.xml** file migrates all files located on the C: drive, except any **.mp3** files. ```xml @@ -75,7 +78,7 @@ The following .xml file migrates all files located on the C: drive, except any . ### Example 2: How to migrate all files located in `C:\Data` except files in `C:\Data\tmp` -The following .xml file migrates all files and subfolders in `C:\Data`, except the files and subfolders in `C:\Data\tmp`. +The following **.xml** file migrates all files and subfolders in `C:\Data`, except the files and subfolders in `C:\Data\tmp`. ```xml @@ -101,7 +104,7 @@ The following .xml file migrates all files and subfolders in `C:\Data`, except t ### Example 3: How to exclude the files in a folder but include all subfolders -The following .xml file migrates any subfolders in `C:\`EngineeringDrafts`, but excludes all files that are in `C:\EngineeringDrafts`. +The following **.xml** file migrates any subfolders in `C:\EngineeringDrafts`, but excludes all files that are in `C:\EngineeringDrafts`. ```xml @@ -127,7 +130,7 @@ The following .xml file migrates any subfolders in `C:\`EngineeringDrafts`, but ### Example 4: How to exclude a file from a specific folder -The following .xml file migrates all files and subfolders in `C:\EngineeringDrafts`, except for the `Sample.doc` file in `C:\EngineeringDrafts`. +The following **.xml** file migrates all files and subfolders in `C:\EngineeringDrafts`, except for the `Sample.doc` file in `C:\EngineeringDrafts`. ```xml @@ -153,13 +156,13 @@ The following .xml file migrates all files and subfolders in `C:\EngineeringDraf ### Example 5: How to exclude a file from any location -To exclude a Sample.doc file from any location on the C: drive, use the **<pattern>** element. If multiple files exist with the same name on the C: drive, all of these files are excluded. +To exclude a Sample.doc file from any location on the C: drive, use the **\** element. If multiple files exist with the same name on the C: drive, all of these files are excluded. ```xml C:\* [Sample.doc] ``` -To exclude a Sample.doc file from any drive on the computer, use the **<script>** element. If multiple files exist with the same name, all of these files are excluded. +To exclude a Sample.doc file from any drive on the computer, use the **\** element. If multiple files exist with the same name, all of these files are excluded. ```xml @@ -171,7 +174,7 @@ Here are some examples of how to use XML to exclude files, folders, and registry ##### Example 1: How to exclude all `.mp3` files -The following .xml file excludes all `.mp3` files from the migration: +The following **.xml** file excludes all `.mp3` files from the migration: ```xml @@ -192,7 +195,7 @@ The following .xml file excludes all `.mp3` files from the migration: ##### Example 2: How to exclude all of the files on a specific drive -The following .xml file excludes only the files located on the C: drive. +The following **.xml** file excludes only the files located on the C: drive. ```xml @@ -213,7 +216,7 @@ The following .xml file excludes only the files located on the C: drive. ##### Example 3: How to exclude registry keys -The following .xml file unconditionally excludes the `HKEY_CURRENT_USER` registry key and all of its subkeys. +The following **.xml** file unconditionally excludes the `HKEY_CURRENT_USER` registry key and all of its subkeys. ```xml @@ -240,7 +243,7 @@ The following .xml file unconditionally excludes the `HKEY_CURRENT_USER` registr ##### Example 4: How to Exclude `C:\Windows` and `C:\Program Files` -The following .xml file unconditionally excludes the system folders of `C:\Windows` and `C:\Program Files`. All `*.docx`, `*.xls` and `*.ppt` files aren't migrated because the **<unconditionalExclude>** element takes precedence over the **<include>** element. +The following **.xml** file unconditionally excludes the system folders of `C:\Windows` and `C:\Program Files`. All `*.docx`, `*.xls` and `*.ppt` files aren't migrated because the **\** element takes precedence over the **\** element. ```xml @@ -270,22 +273,21 @@ The following .xml file unconditionally excludes the system folders of `C:\Windo ## Create a Config XML File -You can create and modify a `Config.xml` file if you want to exclude components from the migration. Excluding components using this file is easier than modifying the migration .xml files because you don't need to be familiar with the migration rules and syntax. `Config.xml` is an optional file that you can create using the `/genconfig` command-line option with the ScanState tool. For example, you can use the `Config.xml` file to exclude the settings for one of the default applications. In addition, creating and modifying this file is the only way to exclude the operating-system settings that are migrated to computers running Windows. +A `Config.xml` file can be created and modified to exclude components from the migration. Excluding components using this file is easier than modifying the migration **.xml** files because familiarity with the migration rules and syntax isn't required. `Config.xml` is an optional file that can be created using the `/genconfig` command-line option with the **ScanState** tool. For example, the `Config.xml` file can be used to exclude the settings for one of the default applications. In addition, creating and modifying this file is the only way to exclude the operating-system settings that are migrated to computers running Windows. -- **To exclude the settings for a default application:** Specify `migrate="no"` for the application under the **<Applications>** section of the `Config.xml` file. +- **To exclude the settings for a default application:** Specify `migrate="no"` for the application under the **\** section of the `Config.xml` file. -- **To exclude an operating system setting:** Specify `migrate="no"` for the setting under the **<WindowsComponents>** section. +- **To exclude an operating system setting:** Specify `migrate="no"` for the setting under the **\** section. -- **To exclude My Documents:** Specify `migrate="no"` for **My Documents** under the **<Documents>** section. Any **<include>** rules in the .xml files are still applied. For example, if you have a rule that includes all the .docx files in My Documents, then .docx files are still migrated. However, any additional files that aren't .docx aren't migrated. +- **To exclude the Documents folder:** Specify `migrate="no"` for the **Documents** folder under the **\** section. Any **\** rules in the **.xml** files are still applied. For example, if a rule exists that includes all the **.docx** files in the **Documents** folder, then **.docx** files are still migrated. However, any additional files that aren't **.docx** aren't migrated. For more information, see [Config.xml File](usmt-configxml-file.md). > [!NOTE] > -> To exclude a component from the `Config.xml` file, set the **migrate** value to **"no"**. Deleting the XML tag for the component from the `Config.xml` file doesn't exclude the component from your migration. +> To exclude a component from the `Config.xml` file, set the **migrate** value to **"no"**. Deleting the XML tag for the component from the `Config.xml` file doesn't exclude the component from the migration. ## Related articles -- [Customize USMT XML files](usmt-customize-xml-files.md) - -- [USMT XML reference](usmt-xml-reference.md) +- [Customize USMT XML files](usmt-customize-xml-files.md). +- [USMT XML reference](usmt-xml-reference.md). diff --git a/windows/deployment/usmt/usmt-extract-files-from-a-compressed-migration-store.md b/windows/deployment/usmt/usmt-extract-files-from-a-compressed-migration-store.md index 0e973ffb4e..fabb39e360 100644 --- a/windows/deployment/usmt/usmt-extract-files-from-a-compressed-migration-store.md +++ b/windows/deployment/usmt/usmt-extract-files-from-a-compressed-migration-store.md @@ -1,18 +1,21 @@ --- -title: Extract Files from a Compressed USMT Migration Store (Windows 10) +title: Extract Files from a Compressed USMT Migration Store description: In this article, learn how to extract files from a compressed User State Migration Tool (USMT) migration store. manager: aaroncz ms.author: frankroj ms.prod: windows-client author: frankroj -ms.date: 11/01/2022 +ms.date: 01/03/2024 ms.topic: article ms.technology: itpro-deploy +appliesto: + - ✅ Windows 11 + - ✅ Windows 10 --- # Extract files from a compressed USMT migration store -When you migrate files and settings during a typical PC-refresh migration, you usually create a compressed migration store file on the intermediate store. This migration store is a single image file that contains all files being migrated as well as a catalog file. To protect the compressed file, you can encrypt it by using different encryption algorithms. When you migrate the file back to the source computer after the operating system is installed, you can run the **UsmtUtils** command with the `/extract` option to recover the files from the compressed migration store. You can also use the **UsmtUtils** command with the `/extract` option any time you need to recover data from a migration store. +When files and settings are migrated during a typical PC-refresh migration, a compressed migration store file is usually created on the intermediate store. This migration store is a single image file that contains all files being migrated as well as a catalog file. To protect the compressed file, it can be encrypted by using different encryption algorithms. When the file is migrated back to the source computer after the operating system is installed, the **UsmtUtils** command can be run with the `/extract` option to recover the files from the compressed migration store. The **UsmtUtils** command with the `/extract` option can also be used any time data needs to be recovered from a migration store. Options used with the `/extract` option can specify: @@ -22,7 +25,7 @@ Options used with the `/extract` option can specify: - Include and exclude patterns for selective data extraction. -In addition, you can specify the file patterns that you want to extract by using the `/i` option to include file patterns or the `/e` option to exclude file patterns. When both the `/i` option and the `/e` option are used in the same command, include patterns take precedence over exclude patterns. Note that this is different from the include and exclude rules used in the **ScanState** and **LoadState** tools. +In addition, the file patterns that need to be extracted can be specified by using the `/i` option to include file patterns or the `/e` option to exclude file patterns. When both the `/i` option and the `/e` option are used in the same command, include patterns take precedence over exclude patterns. The `/i` and the `/e` options are different from the include and exclude rules used in the **ScanState** and **LoadState** tools. ## To run the UsmtUtils tool with the /extract option @@ -34,23 +37,23 @@ UsmtUtils.exe /extract [/i:] [/e:** is the location where the USMT files and tools are saved. -- **<filePath>** is the location of the migration store. +- **\** is the location of the migration store. -- **<destination path>** is the location of the file where you want the **/extract** option to put the extracted migration store contents. +- **\** is the location of the file where the **/extract** option should put the extracted migration store contents. -- **<includePattern>** specifies the pattern for the files to include in the extraction. +- **\** specifies the pattern for the files to include in the extraction. -- **<excludePattern>** specifies the pattern for the files to omit from the extraction. +- **\** specifies the pattern for the files to omit from the extraction. -- **<AlgID>** is the cryptographic algorithm that was used to create the migration store on the `ScanState.exe` command line. +- **\** is the cryptographic algorithm that was used to create the migration store on the `ScanState.exe` command line. -- **<logfile>** is the location and name of the log file. +- **\** is the location and name of the log file. -- **<keystring>** is the encryption key that was used to encrypt the migration store. +- **\** is the encryption key that was used to encrypt the migration store. -- **<filename>** is the location and name of the text file that contains the encryption key. +- **\** is the location and name of the text file that contains the encryption key. ### To extract all files from a compressed migration store @@ -80,18 +83,16 @@ UsmtUtils.exe /extract D:\MyMigrationStore\USMT\store.mig /e:*.exe C:\ExtractedS ### To extract file types using the include pattern and the exclude pattern -To extract files from a compressed migration store, and to exclude files of one type (such as .exe files) while including only specific files, use both the include pattern and the exclude pattern, as in this example: +When files are extracted from a compressed migration store, both the include and the exclude patterns can be used at the same time. Files of one type can be excluded while files of another type can be included. For example: ```cmd UsmtUtils.exe /extract D:\MyMigrationStore\USMT\store.mig /i:myProject.* /e:*.exe C:\ExtractedStore /o ``` -In this example, if there is a myProject.exe file, it will also be extracted because the include pattern option takes precedence over the exclude pattern option. +In this example, if there's a **myProject.exe** file, the file is also extracted because the include pattern option takes precedence over the exclude pattern option. ## Related articles -[UsmtUtils syntax](usmt-utilities.md) - -[Return codes](/troubleshoot/windows-client/deployment/usmt-return-codes) - -[Verify the condition of a compressed migration store](verify-the-condition-of-a-compressed-migration-store.md) +- [UsmtUtils syntax](usmt-utilities.md). +- [Return codes](/troubleshoot/windows-client/deployment/usmt-return-codes). +- [Verify the condition of a compressed migration store](verify-the-condition-of-a-compressed-migration-store.md). diff --git a/windows/deployment/usmt/usmt-faq.yml b/windows/deployment/usmt/usmt-faq.yml index f22b052e29..3f948afe24 100644 --- a/windows/deployment/usmt/usmt-faq.yml +++ b/windows/deployment/usmt/usmt-faq.yml @@ -1,7 +1,7 @@ ### YamlMime:FAQ metadata: - title: 'Frequently Asked Questions (Windows 10)' - description: 'Learn about frequently asked questions and recommended solutions for migrations using User State Migration Tool (USMT) 10.0.' + title: 'USMT Frequently Asked Questions' + description: 'Learn about frequently asked questions and recommended solutions for migrations using User State Migration Tool (USMT).' ms.assetid: 813c13a7-6818-4e6e-9284-7ee49493241b ms.prod: windows-client ms.technology: itpro-deploy @@ -11,11 +11,16 @@ metadata: ms.mktglfcycl: deploy ms.sitesec: library audience: itpro - ms.date: 11/01/2022 + ms.date: 01/03/2024 ms.topic: faq title: Frequently Asked Questions summary: | - The following sections provide frequently asked questions and recommended solutions for migrations using User State Migration Tool (USMT) 10.0. + **Applies to:** + + - Windows 11 + - Windows 10 + + The following sections provide frequently asked questions and recommended solutions for migrations using User State Migration Tool (USMT). sections: @@ -33,54 +38,66 @@ sections: - Uncompressed store - question: | - Can I store the files and settings directly on the destination computer or do I need a server? + Can the files and settings be stored directly on the destination computer or is a server needed? answer: | - You don't need to save the files to a server. If you're moving the user state to a new computer, you can create the store on a shared folder, on media that you can remove, such as a USB flash drive (UFD), or you can store it directly on the destination computer, as in the following steps: + Files don't need to be saved to a server. If moving the user state to a new computer, the store can be created on: + + - A shared folder. + - On removable media, such as a USB flash drive (UFD). + - Directly on the destination computer. + + To store it directly on the destination computer: 1. Create and share the directory `C:\store` on the destination computer. - 2. Run the **ScanState** tool on the source computer and save the files and settings to `\\\store` + 1. Run the **ScanState** tool on the source computer and save the files and settings to `\\\store` - 3. Run the **LoadState** tool on the destination computer and specify `C:\store` as the store location. + 1. Run the **LoadState** tool on the destination computer and specify `C:\store` as the store location. - question: | - Can I migrate data between operating systems with different languages? + Can data be migrated between operating systems with different languages? answer: | No. USMT doesn't support migrating data between operating systems with different languages; the source computer's operating-system language must match the destination computer's operating-system language. - question: | - Can I change the location of the temporary directory on the destination computer? + Can the location of the temporary directory on the destination computer be changed? answer: | Yes. The environment variable `USMT\_WORKING\_DIR` can be changed to an alternative temporary directory. There are some offline migration scenarios where changing the temporary directory is necessary, for example, when the USMT binaries are located on read-only Windows Preinstallation Environment (WinPE) boot media. - question: | - How do I install USMT? + How is USMT installed? answer: | - Because USMT is included in Windows Assessment and Deployment Kit (Windows ADK), you need to install the Windows ADK package on at least one computer in your environment. The USMT binaries can then be copied from the USMT directory located on the original computer where the Windows ADK was installed to additional client computers. + Because USMT is included in Windows Assessment and Deployment Kit (Windows ADK), the Windows ADK package needs to be installed on at least one computer in the environment. The USMT binaries can then be copied from the USMT directory located on the original computer where the Windows ADK was installed to additional client computers. - question: | - How do I uninstall USMT? + How is USMT uninstalled? answer: | - If you've installed the Windows ADK on the computer, uninstalling Windows ADK will uninstall USMT. For client computers that don't have the Windows ADK installed, you can delete the USMT directory to uninstall USMT. + For computers that have the Windows ADK installed, uninstalling the Windows ADK from the computer uninstalls USMT. For client computers that don't have the Windows ADK installed, the USMT directory can be deleted to uninstall USMT. - name: Files and Settings questions: - question: | - How can I exclude a folder or a certain type of file from the migration? + How can a folder or a certain type of file be excluded from the migration? answer: | - You can use the **<unconditionalExclude>** element to globally exclude data from the migration. For example, you can use this element to exclude all MP3 files on the computer or to exclude all files from `C:\UserData`. This element excludes objects regardless of any other **<include>** rules that are in the .xml files. For an example, see **<unconditionalExclude>** in the [Exclude files and settings](usmt-exclude-files-and-settings.md) article. For the syntax of this element, see [XML elements library](usmt-xml-elements-library.md). + The **\** element can be used to globally exclude data from the migration. For example, this element can be used to exclude all MP3 files on the computer or to exclude all files from `C:\UserData`. This element excludes objects regardless of any other **\** rules that are in the **.xml** files. For an example, see **\** in the [Exclude files and settings](usmt-exclude-files-and-settings.md) article. For the syntax of this element, see [XML elements library](usmt-xml-elements-library.md). - question: | What happens to files that were located on a drive that don't exist on the destination computer? answer: | - USMT migrates the files to the `%SystemDrive%` while maintaining the correct folder hierarchy. For example, if `E:\data\File.pst` is on the source computer, but the destination computer doesn't have an E:\\ drive, the file will be migrated to `C:\data\File.pst`, if C:\\ is the system drive. This behavior holds true even when **<locationModify>** rules attempt to move data to a drive that doesn't exist on the destination computer. + USMT migrates the files to the `%SystemDrive%` while maintaining the correct folder hierarchy. For example: + + - `E:\data\File.pst` is on the source computer. + - Destination computer doesn't have an E:\\ drive. + - C:\\ is the system drive on the destination computer. + + the file is migrated to `C:\data\File.pst`. This behavior holds true even when **\** rules attempt to move data to a drive that doesn't exist on the destination computer. - name: USMT .xml Files questions: - question: | - Where can I get examples of USMT .xml files? + Where are there examples of USMT **.xml** files? answer: | - The following articles include examples of USMT .xml files: + The following articles include examples of USMT **.xml** files: - [Exclude files and settings](usmt-exclude-files-and-settings.md) @@ -91,37 +108,37 @@ sections: - [Custom XML examples](usmt-custom-xml-examples.md) - question: | - Can I use custom .xml files that were written for USMT 5.0? + Can custom **.xml** files that were written for USMT 5.0 be used? answer: | - Yes. You can use custom .xml files that were written for USMT 5.0 with USMT for Windows 10. However, in order to use new USMT functionality, you must revisit your custom USMT files and refresh them to include the new command-line options and XML elements. + Yes. Custom **.xml** files that were written for USMT 5.0 can be used with newer versions of USMT. However, in order to use new USMT functionality, the custom USMT files must be revisited and refreshed to include the new command-line options and XML elements. - question: | - How can I validate the .xml files? + How can the **.xml** files be validated? answer: | - You can use the USMT XML Schema (`MigXML.xsd`) to write and validate migration .xml files. + The USMT XML Schema (`MigXML.xsd`) can be used to write and validate migration **.xml** files. - question: | - Why must I list the .xml files with both the `ScanState.exe` and `LoadState.exe` commands? + Why must the **.xml** files be included with both the `ScanState.exe` and `LoadState.exe` commands? answer: | - The .xml files aren't copied to the store as in previous versions of USMT. Because the **ScanState** and **LoadState** tools need the .xml files to control the migration, you must specify the same set of .xml files for the `ScanState.exe` and `LoadState.exe` commands. If you used a particular set of mig\*.xml files in the **ScanState** tool, either called through the `/auto` option, or individually through the `/i` option, then you should use same option to call the exact same mig\*.xml files in the **LoadState** tool. However, you don't have to specify the `Config.xml` file, unless you want to exclude some of the files and settings that you migrated to the store. For example, you might want to migrate the **My Documents** folder to the store, but not to the destination computer. To do this type of migration, modify the `Config.xml` file and specify the updated file with the `LoadState.exe` command. **LoadState** will migrate only the files and settings that you want to migrate. + The **.xml** files aren't copied to the store as in previous versions of USMT. Because the **ScanState** and **LoadState** tools need the **.xml** files to control the migration, the same set of **.xml** files must be specified for the `ScanState.exe` and `LoadState.exe` commands. If a particular set of mig\*.xml files were used in the **ScanState** tool, either called through the `/auto` option, or individually through the `/i` option, then the same option should be used to call the exact same mig\*.xml files in the **LoadState** tool. However, the `Config.xml` file doesn't need to be specified, unless files and settings that were migrated to the store need to be excluded. For example, the **Documents** folder might be migrated to the store, but not to the destination computer. To do this type of migration, modify the `Config.xml` file and specify the updated file with the `LoadState.exe` command. **LoadState** migrates only the desired files and settings. - If you exclude an .xml file from the `LoadState.exe` command, then all of the data that is in the store that was migrated with the missing .xml files will be migrated. However, the migration rules that were specified for the `ScanState.exe` command won't apply. For example, if you exclude a `MigApp.xml` file that has a rerouting rule such as `MigsysHelperFunction.RelativeMove("c:\data", "%CSIDL_PERSONAL%")`, USMT won't reroute the files. Instead, it will migrate them to `C:\data`. + If an **.xml** file is excluded from the `LoadState.exe` command, then all of the data in the store that was migrated with the missing **.xml** files are migrated. However, the migration rules that were specified for the `ScanState.exe` command don't apply. For example, if a `MigApp.xml` file that has a rerouting rule such as `MigsysHelperFunction.RelativeMove("c:\data", "%CSIDL_PERSONAL%")` is excluded, USMT doesn't reroute the files. Instead, it migrates them to `C:\data`. - question: | - Which files can I modify and specify on the command line? + Which files can be modified and specified on the command line? answer: | - You can specify the `MigUser.xml` and `MigApp.xml` files on the command line. You can modify each of these files. The migration of operating system settings is controlled by the manifests, which you can't modify. If you want to exclude certain operating-system settings or any other components, create and modify the `Config.xml` file. + The `MigUser.xml`, `MigApp.xml`, and `MigDocs.xml` files can be specified on the command line. Each of these files can be modified. Manifests control the migration of operating system settings. Manifests can't be modified. To exclude certain operating-system settings or any other components, create and modify the `Config.xml` file. - question: | - What happens if I don't specify the .xml files on the command line? + What happens if the **.xml** files aren't specified on the command line? answer: | - **ScanState** - If you don't specify any files with the `ScanState.exe` command, all user accounts and default operating system components are migrated. + If no files are specified with the `ScanState.exe` command, all user accounts and default operating system components are migrated. - **LoadState** - If you don't specify any files with the `LoadState.exe` command, all data that is in the store is migrated. However, any target-specific migration rules that were specified in .xml files with the `ScanState.exe` command won't apply. For example, if you exclude a `MigApp.xml` file that has a rerouting rule such as `MigsysHelperFunction.RelativeMove("c:\data", "%CSIDL_PERSONAL%")`, USMT won't reroute the files. Instead, it will migrate them to `C:\data`. + If no files are specified with the `LoadState.exe` command, all data that is in the store is migrated. However, any target-specific migration rules that were specified in **.xml** files with the `ScanState.exe` command doesn't apply. For example, if a `MigApp.xml` file that has a rerouting rule such as `MigsysHelperFunction.RelativeMove("c:\data", "%CSIDL_PERSONAL%")` is excluded, USMT doesn't reroute the files. Instead, it migrates them to `C:\data`. - name: Conflicts and Precedence questions: @@ -135,8 +152,6 @@ additionalContent: | ## Related topics - [User State Migration Tool (USMT) Troubleshooting](usmt-troubleshooting.md) - - [Extract files from a compressed USMT migration store](usmt-extract-files-from-a-compressed-migration-store.md) - - [Verify the condition of a compressed migration store](verify-the-condition-of-a-compressed-migration-store.md) + - [User State Migration Tool (USMT) Troubleshooting](usmt-troubleshooting.md). + - [Extract files from a compressed USMT migration store](usmt-extract-files-from-a-compressed-migration-store.md). + - [Verify the condition of a compressed migration store](verify-the-condition-of-a-compressed-migration-store.md). diff --git a/windows/deployment/usmt/usmt-general-conventions.md b/windows/deployment/usmt/usmt-general-conventions.md index a7078f7b0b..ed822d7993 100644 --- a/windows/deployment/usmt/usmt-general-conventions.md +++ b/windows/deployment/usmt/usmt-general-conventions.md @@ -1,58 +1,61 @@ --- -title: General Conventions (Windows 10) +title: General Conventions description: Learn about general XML guidelines and how to use XML helper functions in the XML Elements library to change migration behavior. manager: aaroncz ms.author: frankroj ms.prod: windows-client author: frankroj -ms.date: 11/01/2022 +ms.date: 01/03/2024 ms.topic: article ms.technology: itpro-deploy +appliesto: + - ✅ Windows 11 + - ✅ Windows 10 --- # General conventions -This topic describes the XML helper functions. +This article describes the XML helper functions. ## General XML guidelines -Before you modify the .xml files, become familiar with the following guidelines: +Before modifying the **.xml** files, become familiar with the following guidelines: -- **XML schema** +- **XML schema.** - You can use the User State Migration Tool (USMT) 10.0 XML schema, MigXML.xsd, to write and validate migration .xml files. + The User State Migration Tool (USMT) XML schema, `MigXML.xsd`, can be used to write and validate migration **.xml** files. -- **Conflicts** +- **Conflicts.** In general, when there are conflicts within the XML schema, the most specific pattern takes precedence. For more information, see [Conflicts and precedence](usmt-conflicts-and-precedence.md). -- **Required elements** +- **Required elements.** - The required elements for a migration .xml file are **<migration>**, **<component>**, **<role>**, and **<rules>**. + The required elements for a migration **.xml** file are **\**, **\**, **\**, and **\**. -- **Required child elements** +- **Required child elements.** - - USMT doesn't fail with an error if you don't specify the required child elements. However, you must specify the required child elements for the parent element to affect the migration. + - USMT doesn't fail with an error if the required child elements aren't specified. However, the required child elements must be specified for the parent element to affect the migration. - - The required child elements apply only to the first definition of the element. If these elements are defined and then referred to using their name, the required child elements don't apply. For example, if you define `` in **<namedElements>**, and you specify `` in **<component>** to refer to this element, the definition inside **<namedElements>** must have the required child elements, but the **<component>** element doesn't need to have the required child elements. + - The required child elements apply only to the first definition of the element. If these elements are defined and then referred to using their name, the required child elements don't apply. For example, if `` is defined in **\**, and `` is specified in **\** to refer to this element, the definition inside **\** must have the required child elements, but the **\** element doesn't need to have the required child elements. -- **File names with brackets** +- **File names with brackets.** - If you're migrating a file that has a bracket character (\[ or \]) in the file name, you must insert a carat (^) character directly before the bracket for the bracket character 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]`. + If a file that has a bracket character (\[ or \]) in the file name is being migrated, a carat (^) character must be inserted. The carat (^) character must be directly before the bracket for the bracket character to be valid. For example, if there's a file named **file].txt**, `c:\documents\mydocs [file^].txt]` must be specified instead of `c:\documents\mydocs [file].txt]`. -- **Using quotation marks** +- **Using quotation marks.** - When you surround code in quotation marks, you can use either double ("") or single (') quotation marks. + When code is surrounded in quotation marks, either the double ("") or the single (') quotation marks can be used. ## Helper functions -You can use the XML helper functions in the [XML elements library](usmt-xml-elements-library.md) to change migration behavior. Before you use these functions in an .xml file, note the following items: +The XML helper functions in the [XML elements library](usmt-xml-elements-library.md) can be used to change migration behavior. Before using these functions in an **.xml** file, note the following items: -- **All of the parameters are strings** +- **All of the parameters are strings.** -- **You can leave NULL parameters blank** +- **NULL parameters can be left blank.** - As with parameters with a default value convention, if you have a NULL parameter at the end of a list, you can leave it out. For example, the following function: + As with parameters with a default value convention, if there's a NULL parameter at the end of a list, it can be left out. For example, the following function: ```cmd SomeFunction("My String argument",NULL,NULL) @@ -64,20 +67,36 @@ You can use the XML helper functions in the [XML elements library](usmt-xml-elem SomeFunction("My String argument") ``` -- **The encoded location used in all the helper functions is an unambiguous string representation for the name of an object** +- **The encoded location used in all 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 format makes a clear distinction between nodes and leaves. + The encoded location is composed of the node part, optionally followed by the leaf enclosed in square brackets. This format makes a clear distinction between nodes and leaves. - For example, specify the file `C:\Windows\Notepad.exe`: **c:\\Windows\[Notepad.exe\]**. Similarly, specify the directory `C:\Windows\System32` like this: **c:\\Windows\\System32**; note the absence of the **\[\]** characters. + For example, specify the file + + `C:\Windows\Notepad.exe` + + as + + **c:\\Windows\[Notepad.exe\]** + + Similarly, specify the directory + + `C:\Windows\System32` + + as + + **c:\\Windows\\System32** + + Note the absence of the **\[\]** characters in second example. The registry is represented in a similar way. 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\[\]**. -- **You specify a location pattern in a way that is similar to how you specify an actual location** +- **A location pattern is specified in a way that is similar to how an actual location is specified.** 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, **c:\\Windows\\\*\[\*\]** must be specified. ## Related articles -[USMT XML reference](usmt-xml-reference.md) +- [USMT XML reference](usmt-xml-reference.md). diff --git a/windows/deployment/usmt/usmt-hard-link-migration-store.md b/windows/deployment/usmt/usmt-hard-link-migration-store.md index 13a65a73e1..9a2f6667d8 100644 --- a/windows/deployment/usmt/usmt-hard-link-migration-store.md +++ b/windows/deployment/usmt/usmt-hard-link-migration-store.md @@ -1,78 +1,86 @@ --- -title: Hard-Link Migration Store (Windows 10) +title: Hard-Link Migration Store description: Use of a hard-link migration store for a computer-refresh scenario drastically improves migration performance and significantly reduces hard-disk utilization. manager: aaroncz ms.author: frankroj ms.prod: windows-client author: frankroj -ms.date: 11/01/2022 +ms.date: 01/03/2024 ms.topic: article ms.technology: itpro-deploy +appliesto: + - ✅ Windows 11 + - ✅ Windows 10 --- # Hard-Link Migration Store -A **hard-link migration store** enables you to perform an in-place migration where all user state is maintained on the computer while the old operating system is removed and the new operating system is installed. This functionality is what makes **hard-link migration store** best suited for the computer-refresh scenario. Use of a hard-link migration store for a computer-refresh scenario drastically improves migration performance and significantly reduces hard-disk utilization, reduces deployment costs, and enables entirely new migration scenarios. +A **hard-link migration store** enables an in-place migration to be performed where all user state is maintained on the computer while the old operating system is removed and the new operating system is installed. This functionality is what makes **hard-link migration store** best suited for the computer-refresh scenario. Use of a hard-link migration store for a computer-refresh scenario drastically improves migration performance and significantly reduces hard-disk utilization, reduces deployment costs, and enables entirely new migration scenarios. ## When to use a hard-link migration -You can use a hard-link migration store when your planned migration meets both of the following criteria: +A hard-link migration store can be used when the planned migration meets both of the following criteria: -- You're upgrading the operating system on existing hardware rather than migrating to new computers. +- The operating system is being upgraded on existing hardware rather than migrating to new computers. -- You're upgrading the operating system on the same volume of the computer. +- The operating system is being upgraded on the same volume of the computer. -You can't use a hard-link migration store if your planned migration includes any of the following tasks: +A hard-link migration store can't be used if the planned migration includes any of the following tasks: -- You're migrating data from one computer to a second computer. +- Data is being migrated from one computer to a different computer. -- You're migrating data from one volume on a computer to another volume, for example from `C:` to `D:`. +- Data is being migrating from one volume on a computer to another volume on the same computer, for example from `C:` to `D:`. -- You're formatting or repartitioning the disk outside of Windows Setup, or specifying a disk format or repartition during Windows Setup that will remove the migration store. +- The disk containing the migration store is being formatted or repartitioned disk either outside of Windows Setup or during Windows Setup. ## Understanding a hard-link migration The hard-link migration store is created using the command-line option, `/hardlink`, and is equivalent to other migration-store types. However, it differs in that hard links are utilized to keep files stored on the source computer during the migration. Keeping the files in place on the source computer eliminates the redundant work of duplicating files. It also enables the performance benefits and reduction in disk utilization that define this scenario. -When you create a hard link, you give an existing file one more path. For instance, you could create a hard link to `c:\file1.txt` called `c:\hard link\myFile.txt`. These two paths relate to the same file. If you open `c:\file1.txt`, make changes, and save the file, you'll see those changes when you open `c:\hard link\myFile.txt`. If you delete `c:\file1.txt`, the file still exists on your computer as `c:\hardlink\myFile.txt`. You must delete both references to the file in order to delete the file. +When a hard link is created, an existing file is given one more path. For instance, a hard link to `c:\file1.txt` can be created called `c:\hard link\myFile.txt`. These two paths relate to the same file. If `c:\file1.txt` is opened, then changes made to the file followed by the file being saved, those changes are seen when `c:\hard link\myFile.txt` is opened. If `c:\file1.txt` is deleted, the file still exists on the computer as `c:\hardlink\myFile.txt`. Both references to the file must be deleted in order to delete the file. > [!NOTE] -> A hard link can only be created for a file on the same volume. If you copy a hard-link migration store to another drive or external device, the files, and not the links, are copied, as in a non-compressed migration-store scenario. +> +>A hard link can only be created for a file on the same volume. If a hard-link migration store is copied to another drive or external device, the files, and not the links, are copied, as in a non-compressed migration-store scenario. For more information about hard links, see [Hard Links and Junctions](/windows/win32/fileio/hard-links-and-junctions) -In most aspects, a hard-link migration store is identical to an uncompressed migration store. It's located where specified by the **ScanState.exe** command-line tool and you can view the contents of the store by using Windows Explorer. Once created, it can be deleted or copied to another location without changing user state. Restoring a hard-link migration store is similar to restoring any other migration store. However, as with creating the store, the same hard-link functionality is used to keep files in-place. +In most aspects, a hard-link migration store is identical to an uncompressed migration store. The hard-link migration store is located as specified by the **ScanState.exe** command-line tool. The contents of the store can be viewed by using Windows Explorer. Once created, it can be deleted or copied to another location without changing user state. Restoring a hard-link migration store is similar to restoring any other migration store. However, as with creating the store, the same hard-link functionality is used to keep files in-place. -As a best practice, it's recommended that you delete the hard-link migration store after you confirm that the **LoadState** tool has successfully migrated the files. Since **LoadState** has created new paths to the files on the new installation of a Windows operating system, deleting the hard links in the migration store will only delete one path to the files, and won't delete the actual files or the paths to them from the new operating system. +As a best practice, delete the hard-link migration store after confirming that the files are successfully migrated via the **LoadState** tool. Since **LoadState** creates new paths to the files on the new installation of a Windows operating system, deleting the hard links in the migration store only deletes one path to the files. It doesn't delete the actual files or the paths to them from the new operating system. > [!IMPORTANT] -> Using the `/c` option will force the **LoadState** tool to continue applying files when non-fatal errors occur. If you use the `/c` option, you should verify that no errors are reported in the logs before deleting the hard-link migration store in order to avoid data loss. +> +> Using the `/c` option forces the **LoadState** tool to continue applying files when non-fatal errors occur. If the `/c` option is used, verify that no errors are reported in the logs before deleting the hard-link migration store in order to avoid data loss. Keeping the hard-link migration store can result in extra disk space being consumed or problems with some applications for the following reasons: -- Applications reporting file-system statistics, for example, space used and free space, might incorrectly report these statistics while the hard-link migration store is present. The file may be reported twice because of the two paths that reference that file. +- Applications reporting file-system statistics, for example, space used and free space, might incorrectly report these statistics while the hard-link migration store is present. The file might be reported twice because of the two paths that reference that file. -- A hard link may lose its connection to the original file. Some applications save changes to a file by creating a temporary file and then renaming the original to a backup filename. The path that wasn't used to open the file in this application will continue to refer to the unmodified file. The unmodified file that isn't in use is taking up more disk space. You should create the hard-link migration store just before you perform the migration, and not use applications once the store is created, in order to make sure you're migrating the latest versions of all files. +- A hard link might lose its connection to the original file. Some applications save changes to a file by creating a temporary file and then renaming the original to a backup filename. The path that wasn't used to open the file in this application continues to refer to the unmodified file. The unmodified file that isn't in use is taking up more disk space. The hard-link migration store should be created just before the migration is performed. Once the store is created, applications shouldn't be used in order to make sure the latest versions of all files are being migrating. -- Editing the file by using different paths simultaneously may result in data corruption. +- Editing the file by using different paths simultaneously might result in data corruption. > [!IMPORTANT] +> > The read-only file attribute on migrated files is lost when the hard-link migration store is deleted. This is due to a limitation in NTFS file system hard links. ## Hard-link migration scenario -For example, a company has decided to deploy Windows 10 on all of their computers. Each employee will keep the same computer, but the operating system on each computer will be updated. +For example, an organization decides to deploy the latest supported version of Windows on all of their computers. Each employee keeps the same computer, but the operating system on each computer will be updated. 1. An administrator runs the **ScanState** command-line tool on each computer, specifying the `/hardlink` command-line option. The **ScanState** tool saves the user state to a hard-link migration store on each computer, improving performance by reducing file duplication, except in certain specific instances. > [!NOTE] - > As a best practice, we recommend that you do not create your hard-link migration store until just before you perform the migration in order to migrate the latest versions of your files. You should not use your software applications on the computer after creating the migration store until you have finished migrating your files with **LoadState**. + > + > As a best practice, Microsoft recommends not to create the hard-link migration store until just before the migration is performed in order to migrate the latest versions of files. Software applications shouldn't be used on the computer after creating the migration store until files finish migrating with **LoadState**. -2. On each computer, an administrator installs the company's standard operating environment (SOE), which includes Windows 10 and other applications the company currently uses. +1. On each computer, an administrator installs the organization's standard operating environment (SOE), which includes the latest supported version of Windows and other applications the organization currently uses. -3. An administrator runs the **LoadState** command-line tool on each computer. The **LoadState** tool restores user state back on each computer. +1. An administrator runs the **LoadState** command-line tool on each computer. The **LoadState** tool restores user state back on each computer. > [!NOTE] +> > During the update of a domain-joined computer, the profiles of users whose SID cannot be resolved will not be migrated. When using a hard-link migration store, it could cause a data loss. ## Hard-link migration store details @@ -85,46 +93,52 @@ The `/hardlink` command-line option proceeds with creating the migration store o ### Hard-link store size estimation -It isn't necessary to estimate the size of a hard-link migration store since hard-link migration store on NTFS volumes will be relatively small and require much less incremental space than other store options. Estimating the size of a migration store is only useful in scenarios where the migration store is large. The only case where the local store can be large with hard-link migrations is when non-NTFS file systems exist on the system and the non-NTFS files system contain data that needs to be migrated. Since NTFS has been the default file system format for Windows XP and newer operating systems, this situation is unusual. +It isn't necessary to estimate the size of a hard-link migration store since a hard-link migration store on an NTFS volume is relatively small and require much less incremental space than other store options. Estimating the size of a migration store is only useful in scenarios where the migration store is large. The only case where the local store can be large with hard-link migrations is: + +- A non-NTFS file system exists on the system. +- The non-NTFS files system contains data that needs to be migrated. + +Since NTFS is the default file system format for all currently supported versions of Windows, this situation is unusual. ### Migration store path on multiple volumes -Separate hard-link migration stores are created on each NTFS volume that contain data being migrated. In this scenario, the primary migration-store location will be specified on the command line, and should be the operating-system volume. Migration stores with identical names and directory names will be created on every volume containing data being migrated. For example: +Separate hard-link migration stores are created on each NTFS volume that contain data being migrated. In this scenario, the primary migration-store location is specified on the command line, and should be the operating-system volume. Migration stores with identical names and directory names are created on every volume containing data being migrated. For example: - ```cmd + ```cmd ScanState.exe /hardlink c:\USMTMIG […] ``` -Running this command on a system that contains the operating system on the C: drive and the user data on the D: drive will generate migration stores in the following locations, assuming that both drives are NTFS: +Running this command on a system that contains the operating system on the C: drive and the user data on the D: drive generates migration stores in the following locations, assuming that both drives are NTFS: `C:\USMTMIG\` `D:\USMTMIG\` -The drive you specify on the command line for the hard-link migration store is important, because it defines where the **master migration store** should be placed. The **master migration store** is the location where data migrating from non-NTFS volumes is stored. This volume must have enough space to contain all of the data that comes from non-NTFS volumes. As in other scenarios, if a migration store already exists at the specified path, the `/o` option must be used to overwrite the existing data in the store. +The drive specified on the command line for the hard-link migration store is important, because it defines where the **master migration store** should be placed. The **master migration store** is the location where data migrating from non-NTFS volumes is stored. This volume must have enough space to contain all of the data that comes from non-NTFS volumes. As in other scenarios, if a migration store already exists at the specified path, the `/o` option must be used to overwrite the existing data in the store. ### Location modifications -Location modifications that redirect migrated content from one volume to a different volume have an adverse impact on the performance of a hard-link migration. This impact is because the migrating data that must cross system volumes can't remain in the hard-link migration store, and must be copied across the system volumes. +Location modifications that redirect migrated content from one volume to a different volume have an adverse effect on the performance of a hard-link migration. Performance is affected because the migrating data that must cross system volumes can't remain in the hard-link migration store. They must be copied across the system volumes. ### Migrating Encrypting File System (EFS) certificates and files To migrate Encrypting File System (EFS) files to a new installation of an operating system on the same volume of the computer, specify the `/efs:hardlink` option in the `ScanState.exe` command-line syntax. -If the EFS files are being restored to a different partition, you should use the `/efs:copyraw` option instead of the `/efs:hardlink` option. Hard links can only be created for files on the same volume. Moving the files to another partition during the migration requires a copy of the files to be created on the new partition. The `/efs:copyraw` option will copy the files to the new partition in encrypted format. +If the EFS files are being restored to a different partition, the `/efs:copyraw` option should be used instead of the `/efs:hardlink` option. Hard links can only be created for files on the same volume. Moving the files to another partition during the migration requires a copy of the files to be created on the new partition. The `/efs:copyraw` option copies the files to the new partition in encrypted format. For more information, see [Migrate EFS files and certificates](usmt-migrate-efs-files-and-certificates.md) and [Encrypted file options](usmt-scanstate-syntax.md#encrypted-file-options). ### Migrating locked files with the hard-link migration store -Files that are locked by an application or the operating system are handled differently when using a hard-link migration store. +When an application or the operating system has a lock on a file, the file is handled differently when using a hard-link migration store. -Files that are locked by the operating system can't remain in place and must be copied into the hard-link migration store. As a result, selecting many operating-system files for migration significantly reduces performance during a hard-link migration. As a best practice, we recommend that you don't migrate any files out of the `\Windows` directory, which minimizes performance-related issues. +Operating system locked files can't remain in place and must be copied into the hard-link migration store. As a result, selecting many operating-system files for migration significantly reduces performance during a hard-link migration. As a best practice, Microsoft recommends not migrating any files out of the `\Windows` directory, which minimizes performance-related issues. -Files that are locked by an application are treated the same in hard-link migrations as in other scenarios when the volume shadow-copy service isn't being utilized. The volume shadow-copy service can't be used with hard-link migrations. However, by modifying the new **<HardLinkStoreControl>** section in the `Config.xml` file, it's possible to enable the migration of files locked by an application. +Application locked files are treated the same in hard-link migrations as in other scenarios when the volume shadow-copy service isn't being utilized. The volume shadow-copy service can't be used with hard-link migrations. However, by modifying the new **\** section in the `Config.xml` file, it's possible to enable the migration of files locked by an application. > [!IMPORTANT] -> There are some scenarios in which modifying the **<HardLinkStoreControl>** section in the `Config.xml` file makes it more difficult to delete a hard-link migration store. In these scenarios, you must use `UsmtUtils.exe` to schedule the migration store for deletion on the next restart. +> +> There are some scenarios in which modifying the **\** section in the `Config.xml` file makes it more difficult to delete a hard-link migration store. In these scenarios, `UsmtUtils.exe` must be used to schedule the migration store for deletion on the next restart. ## XML elements in the Config.xml file @@ -132,14 +146,15 @@ A new section in the `Config.xml` file allows optional configuration of some of | Element | Description | |--- |--- | -| **<Policies>** | This element contains elements that describe the policies that USMT follows while creating a migration store. | -| **<HardLinkStoreControl>** | This element contains elements that describe how to handle files during the creation of a hard link migration store. | -| **<fileLocked>** | This element contains elements that describe how to handle files that are locked for editing. | -| **<createHardLink>** | This element defines a standard MigXML pattern that describes file paths where hard links should be created, even if the file is locked for editing by another application.

Syntax: `` [pattern] `` | -| **<errorHardLink>** | This element defines a standard MigXML pattern that describes file paths where hard links shouldn't be created, if the file is locked for editing by another application.

`` [pattern] `` | +| **\** | This element contains elements that describe the policies that USMT follows while creating a migration store. | +| **\** | This element contains elements that describe how to handle files during the creation of a hard link migration store. | +| **\** | This element contains elements that describe how to handle files that are locked for editing. | +| **\** | This element defines a standard MigXML pattern that describes file paths where hard links should be created, even if the file is locked for editing by another application.

Syntax: `` [pattern] `` | +| **\** | This element defines a standard MigXML pattern that describes file paths where hard links shouldn't be created, if the file is locked for editing by another application.

`` [pattern] `` | > [!IMPORTANT] -> You must use the `/nocompress` option with the `/HardLink` option. +> +> The `/nocompress` option must be used with the `/HardLink` option. The following XML sample specifies that files locked by an application under the `\Users` directory can remain in place during the migration. It also specifies that locked files that aren't located in the `\Users` directory should result in the **File in Use** error. It's important to exercise caution when specifying the paths using the **``** tag in order to minimize scenarios that make the hard-link migration store more difficult to delete. @@ -156,4 +171,4 @@ The following XML sample specifies that files locked by an application under the ## 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-how-it-works.md b/windows/deployment/usmt/usmt-how-it-works.md index 751bdc54ee..762709204e 100644 --- a/windows/deployment/usmt/usmt-how-it-works.md +++ b/windows/deployment/usmt/usmt-how-it-works.md @@ -1,5 +1,5 @@ --- -title: How USMT Works (Windows 10) +title: How USMT Works description: Learn how USMT works and how it includes two tools that migrate settings and data - ScanState and LoadState. manager: aaroncz ms.author: frankroj @@ -7,69 +7,71 @@ ms.prod: windows-client author: frankroj ms.topic: article ms.technology: itpro-deploy -ms.date: 11/01/2022 +ms.date: 01/03/2024 +appliesto: + - ✅ Windows 11 + - ✅ Windows 10 --- # How USMT works USMT includes two tools that migrate settings and data: **ScanState** and **LoadState**. **ScanState** collects information from the source computer, and **LoadState** applies that information to the destination computer. -- [How USMT works](#how-usmt-works) - - [The ScanState process](#the-scanstate-process) - - [The LoadState process](#the-loadstate-process) - - [Related articles](#related-articles) - - > [!NOTE] - > For more information about how USMT processes the rules and the XML files, see [Conflicts and precedence](usmt-conflicts-and-precedence.md). +> [!NOTE] +> +> For more information about how USMT processes the rules and the XML files, see [Conflicts and precedence](usmt-conflicts-and-precedence.md). ## The ScanState process -When you run the **ScanState** tool on the source computer, it goes through the following process: +When the **ScanState** tool runs on the source computer, it goes through the following process: 1. It parses and validates the command-line parameters, creates the `ScanState.log` file, and then begins logging. -2. It collects information about all of the migration components that need to be migrated. A *migration component* is a logical group of files, registry keys, and values. For example, the set of files, registry keys, and values that store the settings of Adobe Acrobat is grouped into a single migration component. +1. It collects information about all of the migration components that need to be migrated. A *migration component* is a logical group of files, registry keys, and values. For example, the set of files, registry keys, and values that store the settings of Adobe Acrobat is grouped into a single migration component. There are three types of components: - - Components that migrate the operating system settings + - Components that migrate the operating system settings. - - Components that migrate application settings + - Components that migrate application settings. - - Components that migrate users' files + - Components that migrate users' files. - The **ScanState** tool collects information about the application settings and user data components from the .xml files that are specified on the command line. + The **ScanState** tool collects information about the application settings and user data components from the **.xml** files that are specified on the command line. - In Windows 7, and Windows 8, the manifest files control how the operating-system settings are migrated. You can't modify these files. If you want to exclude certain operating-system settings, you must create and modify a `Config.xml` file. + In currently supported versions of Windows, the manifest files control how the operating-system settings are migrated. These files can't be modified. To exclude certain operating-system settings, a `Config.xml` file must be created and modified. -3. **ScanState** determines which user profiles should be migrated. By default, all user profiles on the source computer are migrated. However, you can include and exclude users using the User Options. The public profile in a source computer running Windows 7, Windows 8, and Windows 10 is always migrated, and you can't exclude these profiles from the migration. +1. **ScanState** determines which user profiles should be migrated. By default, all user profiles on the source computer are migrated. However, users can be included and excluded using the [User options](usmt-scanstate-syntax.md#user-options). The System profile and the Public profile in a source computer running currently supported versions of Windows is always migrated, and these profiles can't be excluded from the migration. -4. In the **Scanning** phase, **ScanState** does the following for each user profile selected for migration: +1. In the **Scanning** phase, **ScanState** does the following for each user profile selected for migration: 1. For each component, **ScanState** checks the type of the component. If the current user profile is the system profile and the component type is **System** or **UserAndSystem**, the component is selected for this user. Otherwise, the component is ignored. Alternatively, if the current user profile isn't the system profile and the component type is **User** or **UserAndSystem**, the component is selected for this user. Otherwise, this component is ignored. > [!NOTE] - > From this point on, **ScanState** does not distinguish between components that migrate operating-system settings, those that migrate application settings, and those that migrate users' files. **ScanState** processes all components in the same way. + > + > From this point on, **ScanState** doesn't distinguish between components that migrate operating-system settings, components that migrate application settings, and components that migrate users' files. **ScanState** processes all components in the same way. - 2. Each component that is selected in the previous step is processed further. Any profile-specific variables (such as **CSIDL_PERSONAL**) are evaluated in the context of the current profile. For example, if the profile that is being processed belongs to **User1**, then **CSIDL_PERSONAL** would expand to `C:\Users\User1\Documents`, assuming that the user profiles are stored in the `C:\Users` directory. + 1. Each component that is selected in the previous step is processed further. Any profile-specific variables (such as **CSIDL_PERSONAL**) are evaluated in the context of the current profile. For example, if the profile that is being processed belongs to **User1**, then **CSIDL_PERSONAL** would expand to `C:\Users\User1\Documents`, assuming that the user profiles are stored in the `C:\Users` directory. - 3. For each selected component, **ScanState** evaluates the **<detects>** section. If the condition in the **<detects>** section evaluates to false, the component isn't processed any further. Otherwise, the processing of this component continues. + 1. For each selected component, **ScanState** evaluates the **\** section. If the condition in the **\** section evaluates to false, the component isn't processed any further. Otherwise, the processing of this component continues. - 4. For each selected component, **ScanState** evaluates the **<rules>** sections. For each **<rules>** section, if the current user profile is the system profile and the context of the **<rules>** section is **System** or **UserAndSystem**, the rule is processed further. Otherwise, this rule is ignored. Alternatively, if the current user profile isn't the system profile and the context of the **<rules>** section is **User** or **UserAndSystem**, the rule is processed further. Otherwise, this rule is ignored. + 1. For each selected component, **ScanState** evaluates the **\** sections. For each **\** section, if the current user profile is the system profile and the context of the **\** section is **System** or **UserAndSystem**, the rule is processed further. Otherwise, this rule is ignored. Alternatively, if the current user profile isn't the system profile and the context of the **\** section is **User** or **UserAndSystem**, the rule is processed further. Otherwise, this rule is ignored. - 5. **ScanState** creates a list of migration units that need to be migrated by processing the various subsections under this **<rules>** section. Each unit is collected if it's mentioned in an **<include>** subsection, as long as there isn't a more specific rule for it in an **<exclude>** subsection in the same **<rules>** section. For more information about precedence in the .xml files, see [Conflicts and precedence](usmt-conflicts-and-precedence.md). + 1. **ScanState** creates a list of migration units that need to be migrated by processing the various subsections under this **\** section. Each unit is collected if the unit is mentioned in an **\** subsection, as long as there isn't a more specific rule for it in an **\** subsection in the same **\** section. For more information about precedence in the **.xml** files, see [Conflicts and precedence](usmt-conflicts-and-precedence.md). - In addition, any migration unit (such as a file, registry key, or set of registry values) that is in an <UnconditionalExclude> section isn't migrated. + In addition, any migration unit (such as a file, registry key, or set of registry values) that is in an \ section isn't migrated. > [!NOTE] - > **ScanState** ignores some subsections such as <destinationCleanup> and <locationModify>. These sections are evaluated only on the destination computer. + > + > **ScanState** ignores some subsections such as \ and \. These sections are evaluated only on the destination computer. -5. In the **Collecting** phase, **ScanState** creates a master list of the migration units by combining the lists that were created for each selected user profile. +1. In the **Collecting** phase, **ScanState** creates a central list of the migration units by combining the lists that were created for each selected user profile. -6. In the **Saving** phase, **ScanState** writes the migration units that were collected to the store location. +1. In the **Saving** phase, **ScanState** writes the migration units that were collected to the store location. > [!NOTE] - > **ScanState** does not modify the source computer in any way. + > + > **ScanState** doesn't modify the source computer in any way. ## The LoadState process @@ -77,45 +79,48 @@ The **LoadState** process is similar to the **ScanState** process. The **ScanSta 1. **ScanState** parses and validates the command-line parameters, creates the `ScanState.log` file, and then begins logging. -2. **LoadState** collects information about the migration components that need to be migrated. +1. **LoadState** collects information about the migration components that need to be migrated. - **LoadState** obtains information for the application-settings components and user-data components from the migration .xml files that are specified by the `LoadState.exe` command. + **LoadState** obtains information for the application-settings components and user-data components from the migration **.xml** files that are specified by the `LoadState.exe` command. - In Windows 7, Windows 8, and Windows 10, the manifest files control how the operating-system settings are migrated. You can't modify these files. If you want to exclude certain operating-system settings, you must create and modify a `Config.xml` file. + In currently supported versions of Windows, the manifest files control how the operating-system settings are migrated. These files can't be modified. To exclude certain operating-system settings, a `Config.xml` file must be created and modified. -3. **LoadState** determines which user profiles should be migrated. By default, all user profiles present on the source computer are migrated. However, you can include and exclude users using the **User Options**. The system profile, the Public profile in a source computer running Windows 7, Windows 8, and Windows 10 is always migrated and you can't exclude these profiles from the migration. +1. **LoadState** determines which user profiles should be migrated. By default, all user profiles present on the source computer are migrated. However, users can be included and excluded using the [User options](usmt-loadstate-syntax.md#user-options). The System profile and the Public profile in a source computer running currently supported versions of Windows is always migrated and these profiles can't be excluded from the migration. - - If you're migrating local user accounts and if the accounts don't already exist on the destination computer, you must use the `/lac` command-line option. If you don't specify the `/lac` option, any local user accounts that aren't already present on the destination computer, aren't migrated. + - If local user accounts are being migrated and if the accounts don't already exist on the destination computer, the `/lac` command-line option must be used. If the `/lac` option isn't specified, any local user accounts that aren't already present on the destination computer, aren't migrated. - - The `/md` and `/mu` options are processed to rename the user profile on the destination computer, if they've been included when the `LoadState.exe` command was specified. + - When specified with the `LoadState.exe` command, the `/md` and `/mu` options are processed to rename the user profile on the destination computer. - For each user profile selected from the store, **LoadState** creates a corresponding user profile on the destination computer. The destination computer doesn't need to be connected to the domain for domain user profiles to be created. If USMT can't determine a domain, it attempts to apply the settings to a local account. For more information, see [Identify Users](usmt-identify-users.md). -4. In the **Scanning** phase, **LoadState** does the following for each user profile: +1. In the **Scanning** phase, **LoadState** does the following for each user profile: 1. For each component, **LoadState** checks the type of the component. If the current user profile is the system profile and the component type is **System** or **UserAndSystem**, the component is selected for this user. Otherwise, the component is ignored. Alternatively, if the current user profile isn't the system profile and the component type is **User** or **UserAndSystem**, the component is selected for this user. Otherwise, this component is ignored. > [!NOTE] - > From this point on, **LoadState** does not distinguish between components that migrate operating-system settings, those that migrate application settings, and those that migrate users' files. **LoadState** evaluates all components in the same way. + > + > From this point on, **LoadState** doesn't distinguish between components that migrate operating-system settings, components that migrate application settings, and components that migrate users' files. **LoadState** evaluates all components in the same way. - 2. Each component that is selected is processed further. Any profile-specific variables (such as **CSIDL_PERSONAL**) are evaluated in the context of the current profile. For example, if the profile being processed belongs to **User1**, then **CSIDL_PERSONAL** would expand to `C:\Users\User1\Documents` (assuming that the user profiles are stored in the `C:\Users` directory). + 1. Each component that is selected is processed further. Any profile-specific variables (such as **CSIDL_PERSONAL**) are evaluated in the context of the current profile. For example, if the profile being processed belongs to **User1**, then **CSIDL_PERSONAL** would expand to `C:\Users\User1\Documents` (assuming that the user profiles are stored in the `C:\Users` directory). > [!NOTE] - > **LoadState** ignores the **<detects>** section specified in a component. At this point, all specified components are considered to be detected and are selected for migration. + > + > **LoadState** ignores the **\** section specified in a component. At this point, all specified components are considered to be detected and are selected for migration. - 3. For each selected component, **LoadState** evaluates the **<rules>** sections. For each **<rules>** section, if the current user profile is the system profile and the context of the **<rules>** section is **System** or **UserAndSystem**, the rule is processed further. Otherwise, this rule is ignored. Alternatively, if the current user profile isn't the system profile and the context of the **<rules>** section is **User** or **UserAndSystem**, the rule is processed further. Otherwise, this rule is ignored. + 1. For each selected component, **LoadState** evaluates the **\** sections. For each **\** section, if the current user profile is the system profile and the context of the **\** section is **System** or **UserAndSystem**, the rule is processed further. Otherwise, this rule is ignored. Alternatively, if the current user profile isn't the system profile and the context of the **\** section is **User** or **UserAndSystem**, the rule is processed further. Otherwise, this rule is ignored. - 4. **LoadState** creates a master list of migration units by processing the various subsections under the **<rules>** section. Each migration unit that is in an **<include>** subsection is migrated as long, as there isn't a more specific rule for it in an **<exclude>** subsection in the same **<rules>** section. For more information about precedence, see [Conflicts and precedence](usmt-conflicts-and-precedence.md). + 1. **LoadState** creates a central list of migration units by processing the various subsections under the **\** section. Each migration unit that is in an **\** subsection is migrated as long, as there isn't a more specific rule for it in an **\** subsection in the same **\** section. For more information about precedence, see [Conflicts and precedence](usmt-conflicts-and-precedence.md). - 5. **LoadState** evaluates the destination computer-specific subsections, for example, the **<destinationCleanup>** and **<locationModify>** subsections. + 1. **LoadState** evaluates the destination computer-specific subsections, for example, the **\** and **\** subsections. - 6. If the destination computer is running Windows 7, Windows 8, or Windows 10, then the migunits that were collected by **ScanState** using downlevel manifest files are processed by **LoadState** using the corresponding Component Manifest for Windows 7. The downlevel manifest files aren't used during **LoadState**. + 1. If the destination computer is running a currently supported version of Windows, then the migunits that were collected by **ScanState** using downlevel manifest files are processed by **LoadState** using the corresponding Component Manifest from the downlevel Windows version. The downlevel manifest files aren't used during **LoadState**. > [!IMPORTANT] - > It is important to specify the .xml files with the `LoadState.exe` command if you want **LoadState** to use them. Otherwise, any destination-specific rules, such as **<locationModify>**, in these .xml files are ignored, even if the same .xml files were provided when the `ScanState.exe` command ran. + > + > For **LoadState** to use the **.xml** files, it's important to specify them with the `LoadState.exe` command. Otherwise, any destination-specific rules, such as **\**, in these **.xml** files are ignored, even if the same **.xml** files were provided when the `ScanState.exe` command ran. -5. In the **Apply** phase, **LoadState** writes the migration units that were collected to the various locations on the destination computer. If there are conflicts and there isn't a **<merge>** rule for the object, the default behavior for the registry is for the source to overwrite the destination. The default behavior for files is for the source to be renamed incrementally, for example, OriginalFileName(1).OriginalExtension. Some settings, such as fonts, wallpaper, and screen-saver settings, don't take effect until the next time the user logs on. For this reason, you should sign out when the `LoadState.exe` command actions have completed. +1. In the **Apply** phase, **LoadState** writes the migration units that were collected to the various locations on the destination computer. If there are conflicts and there isn't a **\** rule for the object, the default behavior for the registry is for the source to overwrite the destination. The default behavior for files is for the source to be renamed incrementally, for example, OriginalFileName(1).OriginalExtension. Some settings, such as fonts, wallpaper, and screen-saver settings, don't take effect until the next time the user logs on. For this reason, sign out when the `LoadState.exe` command actions are finished. ## Related articles -[User State Migration Tool (USMT) command-line syntax](usmt-command-line-syntax.md) +- [User State Migration Tool (USMT) command-line syntax](usmt-command-line-syntax.md). diff --git a/windows/deployment/usmt/usmt-how-to.md b/windows/deployment/usmt/usmt-how-to.md index 0b38e19dbe..c955bcb324 100644 --- a/windows/deployment/usmt/usmt-how-to.md +++ b/windows/deployment/usmt/usmt-how-to.md @@ -1,34 +1,37 @@ --- -title: User State Migration Tool (USMT) How-to articles (Windows 10) -description: Reference the articles in this article to learn how to use User State Migration Tool (USMT) 10.0 to perform specific tasks. +title: User State Migration Tool (USMT) How-to articles +description: Reference the articles in this article to learn how to use User State Migration Tool (USMT) to perform specific tasks. manager: aaroncz ms.author: frankroj ms.prod: windows-client author: frankroj -ms.date: 11/01/2022 +ms.date: 01/03/2024 ms.topic: article ms.technology: itpro-deploy +appliesto: + - ✅ Windows 11 + - ✅ Windows 10 --- # User State Migration Tool (USMT) how-to articles -The following table lists articles that describe how to use User State Migration Tool (USMT) 10.0 to perform specific tasks. +The following table lists articles that describe how to use User State Migration Tool (USMT) to perform specific tasks. ## In this section | Link | Description | |------ |----------- | -|[Exclude files and settings](usmt-exclude-files-and-settings.md)|Create a custom .xml file to exclude files, file types, folders, or registry settings from your migration.| +|[Exclude files and settings](usmt-exclude-files-and-settings.md)|Create a custom **.xml** file to exclude files, file types, folders, or registry settings from the migration.| |[Extract files from a compressed USMT migration store](usmt-extract-files-from-a-compressed-migration-store.md)|Recover files from a compressed migration store after installing the operating system.| -|[Include files and settings](usmt-include-files-and-settings.md)|Create a custom .xml file to include files, file types, folders, or registry settings in your migration.| -|[Migrate application settings](migrate-application-settings.md)|Migrate the settings of an application that the MigApp.xml file doesn't include by default.| +|[Include files and settings](usmt-include-files-and-settings.md)|Create a custom **.xml** file to include files, file types, folders, or registry settings in the migration.| +|[Migrate application settings](migrate-application-settings.md)|Migrate the settings of an application that the `MigApp.xml` file doesn't include by default.| |[Migrate EFS files and certificates](usmt-migrate-efs-files-and-certificates.md)|Migrate Encrypting File System (EFS) certificates by using USMT.| -|[Migrate user accounts](usmt-migrate-user-accounts.md)|Specify the users to include and exclude in your migration.| -|[Reroute files and settings](usmt-reroute-files-and-settings.md)|Create a custom .xml file to reroute files and settings during a migration.| +|[Migrate user accounts](usmt-migrate-user-accounts.md)|Specify the users to include and exclude in the migration.| +|[Reroute files and settings](usmt-reroute-files-and-settings.md)|Create a custom **.xml** file to reroute files and settings during a migration.| |[Verify the condition of a compressed migration store](verify-the-condition-of-a-compressed-migration-store.md)|Determine whether a compressed migration store is intact, or whether it contains corrupt files or a corrupt catalog.| ## Related articles -- [User State Migration Tool (USMT) overview topics](usmt-topics.md) -- [User State Migration Tool (USMT) troubleshooting](usmt-troubleshooting.md) -- [User State Migration Toolkit (USMT) reference](usmt-reference.md) +- [User State Migration Tool (USMT) overview topics](usmt-topics.md). +- [User State Migration Tool (USMT) troubleshooting](usmt-troubleshooting.md). +- [User State Migration Toolkit (USMT) reference](usmt-reference.md). diff --git a/windows/deployment/usmt/usmt-identify-application-settings.md b/windows/deployment/usmt/usmt-identify-application-settings.md index 101e8b5666..d76eb75973 100644 --- a/windows/deployment/usmt/usmt-identify-application-settings.md +++ b/windows/deployment/usmt/usmt-identify-application-settings.md @@ -1,30 +1,33 @@ --- -title: Identify Applications Settings (Windows 10) -description: Identify which applications and settings you want to migrate before using the User State Migration Tool (USMT). +title: Identify Applications Settings +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: 11/01/2022 +ms.date: 01/03/2024 ms.topic: article ms.technology: itpro-deploy +appliesto: + - ✅ Windows 11 + - ✅ Windows 10 --- # 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 -First, create and prioritize a list of applications that need to be migrated. It may be helpful to review the application lists and decide which applications will be redeployed and which applications will be retired. Often, what applications are migrated are prioritized based on a combination of how widely the application is used and how complex the application is. +First, create and prioritize a list of applications that need to be migrated. It might be helpful to review the application lists and decide which applications need to be redeployed and which applications need to be retired. Often, how the application is used and how complex the application is determines the priority of what applications are migrated. -Next, identify an application owner to be in charge of each application. Application ownership identification is necessary because the developers won't be experts on all of the applications in the organization. The application owner should have the most experience with an application. The application owner provides insight into how the organization installs, configures, and uses the application. +Next, identify an application owner to be in charge of each application. Application ownership identification is necessary because the developers aren't be experts on all of the applications in the organization. The application owner should have the most experience with an application. The application owner provides insight into how the organization installs, configures, and uses the application. ## 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: +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: - Is the destination version of the application newer than the source version? @@ -32,9 +35,9 @@ 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. +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. ## Locating where settings are stored @@ -42,4 +45,4 @@ See [Migrate application settings](migrate-application-settings.md) and follow t ## Related articles -[Determine what to migrate](usmt-determine-what-to-migrate.md) +- [Determine what to migrate](usmt-determine-what-to-migrate.md). diff --git a/windows/deployment/usmt/usmt-identify-file-types-files-and-folders.md b/windows/deployment/usmt/usmt-identify-file-types-files-and-folders.md index 049a88b921..3f31587cc7 100644 --- a/windows/deployment/usmt/usmt-identify-file-types-files-and-folders.md +++ b/windows/deployment/usmt/usmt-identify-file-types-files-and-folders.md @@ -1,40 +1,44 @@ --- -title: Identify File Types, Files, and Folders (Windows 10) -description: Learn how to identify the file types, files, folders, and settings that you want to migrate when you're planning your migration. +title: Identify File Types, Files, and Folders +description: Identify the file types, files, folders, and settings that need to be migrated when planning the migration. manager: aaroncz ms.author: frankroj ms.prod: windows-client author: frankroj -ms.date: 11/01/2022 +ms.date: 01/03/2024 ms.topic: article ms.technology: itpro-deploy +appliesto: + - ✅ Windows 11 + - ✅ Windows 10 --- # Identify file types, files, and folders -When planning for your migration, if not using MigDocs.xml, you should identify the file types, files, folders, and settings that you want to migrate. First, you should determine the standard file locations on each computer, such as **My Documents** , `C:\Data` , and company-specified locations, such as `\\EngineeringDrafts`. Next, you should determine and locate the non-standard locations. For non-standard locations, consider the following items: +When a migration is planned and `MigDocs.xml` isn't being used, the file types, files, folders, and settings that need to be migrated should be identified. First, the standard file locations on each computer, such as the **Documents** folder, `C:\Data` , and organization-specified locations, such as `\\EngineeringDrafts`, should be determined. Next, non-standard locations should be determined and located. For non-standard locations, consider the following items: -- **File types**. Consider which file types need to be included and excluded from the migration. You can create this list based on common applications used in your organization. Applications normally use specific file name extensions. For example, Microsoft Office Word primarily uses `.doc`, `.docx` and `.dotx` file name extension. However, it also uses other file types, such as templates (`.dot` files), on a less frequent basis. +- **File types**: Consider which file types need to be included and excluded from the migration. This list can be created based on common applications used in the organization. Applications normally use specific file name extensions. For example, Microsoft Office Word primarily uses `.doc`, `.docx` and `.dotx` file name extension. However, it also uses other file types, such as templates (`.dot` files), on a less frequent basis. -- **Excluded locations**. Consider the locations on the computer that should be excluded from the migration (for example, `%WINDIR%` and **Program Files**). +- **Excluded locations**: Consider the locations on the computer that should be excluded from the migration (for example, `%WINDIR%` and **Program Files**). -- **New locations**. Decide where files should be migrated to on the destination computer, such as **My Documents**, a designated folder, or a folder matching the files' name and location on the source computer. For example, you might have shared data on source machine or you might wish to clean up documents outside the user profiles on the source system. Identify any data that needs to be redirected to a new location in the apply phase. Redirection can be accomplished with location modify rules. +- **New locations**: Decide where files should be migrated to on the destination computer, such as the **Documents** folder, a designated folder, or a folder matching the files' name and location on the source computer. For example, shared data might exist on the source machine or documents outside the user profiles on the source system might need to be cleaned up. Identify any data that needs to be redirected to a new location in the Apply phase. Redirection can be accomplished with location modify rules. -Once you've verified which files and file types that the end users work with regularly, you'll need to locate them. Files may be saved to a single folder or scattered across a drive. A good starting point for finding files types to include is to look at the registered file types on the computer. +Once which files and file types that the end users work with regularly is verified, locate the files and file types. Files might be saved to a single folder or scattered across a drive. A good starting point for finding files types to include is to look at the registered file types on the computer. -To find the registered file types on a computer running Windows 7, Windows 8, Windows 10, or Windows 11: +To find the registered file types on a computer running a currently supported version of Windows: -1. Open **Control Panel** -2. Make sure **View by:** is set to **Category** and then select **Programs**. +1. Right-click the **Start Menu** and select **Settings**. -3. Select **Default Programs** +1. When the **Settings** window opens, select **Apps**. -4. select **Associate a file type or protocol with a program**. +1. Select **Default apps**. -5. On this screen, the registered file types are displayed. +1. Scroll down and then select **Choose defaults by file type** or **Choose default apps by file type**. -For more information about how to change the file types, files, and folders that are migrated when you specify the MigUser.xml file, see [User State Migration Tool (USMT) how-to topics](usmt-how-to.md). +1. In the window that opens, the registered file types are displayed. + +For more information about how to change the file types, files, and folders that are migrated when the `MigUser.xml` file is specified, see [User State Migration Tool (USMT) how-to articles](usmt-how-to.md). ## Related articles -[Determine what to migrate](usmt-determine-what-to-migrate.md) +- [Determine what to migrate](usmt-determine-what-to-migrate.md). diff --git a/windows/deployment/usmt/usmt-identify-operating-system-settings.md b/windows/deployment/usmt/usmt-identify-operating-system-settings.md index 6781531b60..4810e4528f 100644 --- a/windows/deployment/usmt/usmt-identify-operating-system-settings.md +++ b/windows/deployment/usmt/usmt-identify-operating-system-settings.md @@ -1,44 +1,64 @@ --- -title: Identify Operating System Settings (Windows 10) -description: Identify which system settings you want to migrate, then use the User State Migration Tool (USMT) to select settings and keep the default values for all others. +title: Identify Operating System Settings +description: Identify which system settings need to be migrated. The User State Migration Tool (USMT) can then be used to select settings and keep the default values for all others. manager: aaroncz ms.author: frankroj ms.prod: windows-client author: frankroj -ms.date: 11/01/2022 +ms.date: 01/03/2024 ms.topic: article ms.technology: itpro-deploy +appliesto: + - ✅ Windows 11 + - ✅ Windows 10 --- # Identify operating system settings -When planning for your migration, you should identify which operating system settings you want to migrate and to what extent you want to create a new standard environment on each of the computers. User State Migration Tool (USMT) 10.0 enables you to migrate select settings and keep the default values for all others. The operating system settings include the following parameters: +When the migration is being planned, which operating system settings need to be migrated should be identified. Additionally, to what extent a new standard environment should be created on each of the computers should also be identified. User State Migration Tool (USMT) enables migrating select settings and keep the default values for all others. The operating system settings include the following parameters: - **Appearance** - The appearance factor includes items such as wallpaper, colors, sounds, and the location of the taskbar. + The appearance factor includes items such as wallpaper, colors, sounds, and the location of the taskbar. - **Action** - The action factor includes items such as the key-repeat rate, whether double-clicking a folder opens it in a new window or the same window, and whether you need to single-click or double-click an item to open it. + The action factor includes items such as: + + - The key-repeat rate. + - Whether double-clicking a folder opens it in a new window or the same window. + - Whether single-clicking or double-clicking an item opens it. - **Internet** - The Internet factor includes the settings that let you connect to the Internet and control how your browser operates. The settings include items such as your home page URL, favorites, bookmarks, cookies, security settings, dial-up connections, and proxy settings. + The Internet factor includes the settings needed to connect to the Internet and controls how the browser operates. The settings include items such as the home page URL, favorites, bookmarks, cookies, security settings, and proxy settings. These settings might not be supported in all browsers. - **Mail** - The mail factor includes the information that you need to connect to your mail server, your signature file, views, mail rules, local mail, and contacts. + The mail factor includes the information needed to connect the mail server, the signature file, views, mail rules, local mail, and contacts. These settings might not be supported in all email applications. -To help you decide which settings to migrate, you should consider any previous migration experiences and the results of any surveys and tests that you've conducted. You should also consider the number of help-desk calls related to operating-system settings that you've had in the past, and are able to handle in the future. Also decide how much of the new operating-system functionality you want to take advantage of. +To help determine which settings to migrate, consider any previous migration experiences and the results of any conducted surveys and tests. Also consider the number of help-desk calls related to operating-system settings from the past, and are able to handle in the future. Also decide how much of the new operating-system functionality needs to be taken advantage of. -You should migrate any settings that users need to get their jobs done, those settings that make the work environment comfortable, and those settings that will reduce help-desk calls after the migration. Although it's easy to dismiss migrating user preferences, you should consider the factor of users spending a significant amount of time restoring items such as wallpaper, screen savers, and other customizable user-interface features. Most users don't remember how these settings were applied. Although these items aren't critical to migration success, migrating these items increases user productivity and overall satisfaction of the migration process. +Settings that should be migrated include: + +- Settings that allow users need to get their jobs done. +- Settings that make the work environment comfortable. +- Settings that will reduce help-desk calls after the migration. + +Although it's easy to dismiss migrating user preferences, the factor should be considered of users spending time restoring items such as: + +- Wallpaper. +- Screen savers. +- Other customizable user-interface features. + +Most users don't remember how these settings were applied. Although these items aren't critical to migration success, migrating these items increases user productivity and overall satisfaction of the migration process. > [!NOTE] -> For more information about how to change the operating-system settings that are migrated, see [User State Migration Tool (USMT) how-to topics](usmt-how-to.md). +> +> For more information about how to change the operating-system settings that are migrated, see [User State Migration Tool (USMT) how-to articles](usmt-how-to.md). For information about the operating-system settings that USMT migrates, see [What does USMT migrate?](usmt-what-does-usmt-migrate.md) ## Related articles -[Determine What to Migrate](usmt-determine-what-to-migrate.md) +- [Determine What to Migrate](usmt-determine-what-to-migrate.md). diff --git a/windows/deployment/usmt/usmt-identify-users.md b/windows/deployment/usmt/usmt-identify-users.md index 40a4f58cb6..32f38a7d39 100644 --- a/windows/deployment/usmt/usmt-identify-users.md +++ b/windows/deployment/usmt/usmt-identify-users.md @@ -1,6 +1,6 @@ --- -title: Identify Users (Windows 10) -description: Learn how to identify users you plan to migrate, and how to migrate local accounts and domain accounts. +title: Identify Users +description: Learn how to identify users that need to be migrated, and how to migrate local accounts and domain accounts. manager: aaroncz ms.author: frankroj ms.prod: windows-client @@ -8,25 +8,29 @@ author: frankroj ms.topic: article ms.localizationpriority: medium ms.technology: itpro-deploy -ms.date: 11/01/2022 +ms.date: 01/03/2024 +appliesto: + - ✅ Windows 11 + - ✅ Windows 10 --- # Identify users -It's important to carefully consider how you plan to migrate users. By default, all users are migrated by User State Migration Tool (USMT) 5.0. You must specify which users to include by using the command line. You can't specify users in the .xml files. For instructions on how to migrate users, see [Migrate user accounts](usmt-migrate-user-accounts.md). +It's important to carefully consider and plan how users are migrated. By default, User State Migration Tool (USMT) migrates all users. Which users to include must be specified by using the command line. Users can't be specified in the **.xml** files. For instructions on how to migrate users, see [Migrate user accounts](usmt-migrate-user-accounts.md). ## Migrating local accounts Before migrating local accounts, be aware of the following items: -- **You must explicitly specify that local accounts that are not on the destination computer should be migrated**. If you're migrating local accounts and the local account doesn't exist on the destination computer, you must use the `/lac` option when using the `LoadState.exe` command. If the `/lac` option isn't specified, no local user accounts will be migrated. +- **Local accounts that aren't on the destination computer must be explicitly specified if they should be migrated.** If migrating local accounts and the local account doesn't exist on the destination computer, the `/lac` option must be specified when using the `LoadState.exe` command. If the `/lac` option isn't specified, no local user accounts are migrated. -- **Consider whether to enable user accounts that are new to the destination computer.** The `/lae` option enables the account that was created with the `/lac` option. However, if you create a disabled local account by using only the `/lac` option, a local administrator must enable the account on the destination computer. +- **Consider whether to enable user accounts that are new to the destination computer.** The `/lae` option enables the account that was created with the `/lac` option. However, if a disabled local account is created by using only the `/lac` option, a local administrator must enable the account on the destination computer. -- **Be careful when specifying a password for local accounts.** If you create the local account with a blank password, anyone could sign in that account on the destination computer. If you create the local account with a password, the password is available to anyone with access to the USMT command-line tools. +- **Be careful when specifying a password for local accounts.** If the local account is created with a blank password, anyone could sign in that account on the destination computer. If the local account is created with a password, the password is available to anyone with access to the USMT command-line tools. > [!NOTE] -> If there are multiple users on a computer, and you specify a password with the `/lac` option, all migrated users will have the same password. +> +> If there are multiple users on a computer, and a password is specified with the `/lac` option, all migrated users have the same password. ## Migrating domain accounts @@ -36,22 +40,24 @@ The source and destination computers don't need to be connected to the domain fo USMT provides several options to migrate multiple users on a single computer. The following command-line options specify which users to migrate. -- **Specifying users.** You can specify which users to migrate with the `/all`, `/ui`, `/uel`, and `/ue` options with both the **ScanState** and **LoadState** command-line tools. +- **Specifying users.** Which users to migrate can be specified with the `/all`, `/ui`, `/uel`, and `/ue` options with both the **ScanState** and **LoadState** command-line tools. > [!IMPORTANT] - > The `/uel` option excludes users based on the **LastModified** date of the `Ntuser.dat` file. The `/uel` option is not valid in offline migrations. + > + > The `/uel` option excludes users based on the **LastModified** date of the `Ntuser.dat` file. The `/uel` option isn't valid in offline migrations. -- **Moving users to another domain.** You can move user accounts to another domain using the `/md` option with the **LoadState** command-line tool. +- **Moving users to another domain.** User accounts can be moved to another domain using the `/md` option with the **LoadState** command-line tool. -- **Creating local accounts.** You can create and enable local accounts using the `/lac` and `/lae` options with the **LoadState** command-line tool. +- **Creating local accounts.** Local accounts can be created and enabled using the `/lac` and `/lae` options with the **LoadState** command-line tool. -- **Renaming user accounts.** You can rename user accounts using the `/mu` option. +- **Renaming user accounts.** User accounts can be renamed using the `/mu` option. > [!NOTE] - >By default, if a user name is not specified in any of the command-line options, the user will be migrated. + > + > By default, if a user name isn't specified in any of the command-line options, the user is migrated. ## Related articles -- [Determine what to migrate](usmt-determine-what-to-migrate.md) -- [ScanState syntax](usmt-scanstate-syntax.md) -- [LoadState syntax](usmt-loadstate-syntax.md) +- [Determine what to migrate](usmt-determine-what-to-migrate.md). +- [ScanState syntax](usmt-scanstate-syntax.md). +- [LoadState syntax](usmt-loadstate-syntax.md). diff --git a/windows/deployment/usmt/usmt-include-files-and-settings.md b/windows/deployment/usmt/usmt-include-files-and-settings.md index 8e5821354c..aa295527cb 100644 --- a/windows/deployment/usmt/usmt-include-files-and-settings.md +++ b/windows/deployment/usmt/usmt-include-files-and-settings.md @@ -1,22 +1,25 @@ --- -title: Include Files and Settings (Windows 10) -description: Specify the migration .xml files you want, then use the User State Migration Tool (USMT) 10.0 to migrate the settings and components specified. +title: Include Files and Settings +description: Specify the migration .xml files that are needed, then use the User State Migration Tool (USMT) to migrate the settings and components specified. manager: aaroncz ms.author: frankroj ms.prod: windows-client author: frankroj -ms.date: 11/01/2022 +ms.date: 01/03/2024 ms.topic: article ms.technology: itpro-deploy +appliesto: + - ✅ Windows 11 + - ✅ Windows 10 --- # Include Files and Settings -When you specify the migration .xml files, User State Migration Tool (USMT) 10.0 migrates the settings and components specified in [What does USMT migrate?](usmt-what-does-usmt-migrate.md). To include additional files and settings, we recommend that you create a custom .xml file, and then include this file when using both the `ScanState.exe` and `LoadState.exe` commands. By creating a custom .xml file, you can keep your changes separate from the default .xml files, which makes it easier to track your modifications. +When the migration **.xml** files are specified, User State Migration Tool (USMT) migrates the settings and components specified in [What does USMT migrate?](usmt-what-does-usmt-migrate.md). To include additional files and settings, Microsoft recommends creating a custom **.xml** file, and then include this file when using both the `ScanState.exe` and `LoadState.exe` commands. Creating a custom **.xml** file allows changes to be kept separate from the default **.xml** files. Creating a custom **.xml** file makes it easier to track modifications. ## Migrate a single registry key -The following .xml file migrates a single registry key. +The following **.xml** file migrates a single registry key. ```xml @@ -41,7 +44,7 @@ The following examples show how to migrate a folder from a specific drive, and f ### Migrate a folder from a specific drive -- **Including subfolders.** The following .xml file migrates all files and subfolders from `C:\EngineeringDrafts` to the destination computer. +- **Including subfolders.** The following **.xml** file migrates all files and subfolders from `C:\EngineeringDrafts` to the destination computer. ```xml @@ -60,7 +63,7 @@ The following examples show how to migrate a folder from a specific drive, and f ``` -- **Excluding subfolders.** The following .xml file migrates all files from `C:\EngineeringDrafts`, but it doesn't migrate any subfolders within `C:\EngineeringDrafts`. +- **Excluding subfolders.** The following **.xml** file migrates all files from `C:\EngineeringDrafts`, but it doesn't migrate any subfolders within `C:\EngineeringDrafts`. ```xml @@ -81,7 +84,7 @@ The following examples show how to migrate a folder from a specific drive, and f ### Migrate a folder from any location -The following .xml file migrates all files and subfolders of the `EngineeringDrafts` folder from any drive on the computer. If multiple folders exist with the same name, then all files with this name are migrated. +The following **.xml** file migrates all files and subfolders of the `EngineeringDrafts` folder from any drive on the computer. If multiple folders exist with the same name, then all files with this name are migrated. ```xml @@ -101,7 +104,7 @@ The following .xml file migrates all files and subfolders of the `EngineeringDra ``` -The following .xml file migrates all files and subfolders of the `EngineeringDrafts` folder from any location on the `C:\` drive. If multiple folders exist with the same name, they're all migrated. +The following **.xml** file migrates all files and subfolders of the `EngineeringDrafts` folder from any location on the `C:\` drive. If multiple folders exist with the same name, they're all migrated. ```xml @@ -123,12 +126,12 @@ The following .xml file migrates all files and subfolders of the `EngineeringDra ## Migrate a file type into a specific folder -The following .xml file migrates `.mp3` files located in the specified drives on the source computer into the `C:\Music` folder on the destination computer. +The following **.xml** file migrates `.mp3` files located in the specified drives on the source computer into the `C:\Music` folder on the destination computer. ```xml - All .mp3 files to My Documents + All .mp3 files to the Documents folder @@ -152,7 +155,7 @@ The following .xml file migrates `.mp3` files located in the specified drives on The following examples show how to migrate a file from a specific folder, and how to migrate a file from any location. -- **To migrate a file from a folder.** The following .xml file migrates only the `Sample.doc` file from `C:\EngineeringDrafts` on the source computer to the destination computer. +- **To migrate a file from a folder.** The following **.xml** file migrates only the `Sample.doc` file from `C:\EngineeringDrafts` on the source computer to the destination computer. ```xml @@ -171,13 +174,13 @@ The following examples show how to migrate a file from a specific folder, and ho ``` -- **To migrate a file from any location.** To migrate the `Sample.doc` file from any location on the `C:\` drive, use the **<pattern>** element, as the following example shows. If multiple files exist with the same name on the `C:\` drive, all of files with this name are migrated. +- **To migrate a file from any location.** To migrate the `Sample.doc` file from any location on the `C:\` drive, use the **\** element, as the following example shows. If multiple files exist with the same name on the `C:\` drive, all of files with this name are migrated. ```xml C:\* [Sample.doc] ``` - To migrate the Sample.doc file from any drive on the computer, use <script> as the following example shows. If multiple files exist with the same name, all files with this name are migrated. + To migrate the Sample.doc file from any drive on the computer, use \ as the following example shows. If multiple files exist with the same name, all files with this name are migrated. ```xml @@ -185,10 +188,7 @@ The following examples show how to migrate a file from a specific folder, and ho ## Related articles -[Customize USMT XML files](usmt-customize-xml-files.md) - -[Custom XML examples](usmt-custom-xml-examples.md) - -[Conflicts and precedence](usmt-conflicts-and-precedence.md) - -[USMT XML reference](usmt-xml-reference.md) +- [Customize USMT XML files](usmt-customize-xml-files.md). +- [Custom XML examples](usmt-custom-xml-examples.md). +- [Conflicts and precedence](usmt-conflicts-and-precedence.md). +- [USMT XML reference](usmt-xml-reference.md). diff --git a/windows/deployment/usmt/usmt-loadstate-syntax.md b/windows/deployment/usmt/usmt-loadstate-syntax.md index e5c04fe082..5c3033977b 100644 --- a/windows/deployment/usmt/usmt-loadstate-syntax.md +++ b/windows/deployment/usmt/usmt-loadstate-syntax.md @@ -1,45 +1,44 @@ --- -title: LoadState Syntax (Windows 10) -description: Learn about the syntax and usage of the command-line options available when you use the LoadState command. +title: LoadState Syntax +description: Learn about the syntax and usage of the command-line options available when using the LoadState command. manager: aaroncz ms.author: frankroj ms.prod: windows-client author: frankroj -ms.date: 11/01/2022 +ms.date: 01/03/2024 ms.topic: article ms.technology: itpro-deploy +appliesto: + - ✅ Windows 11 + - ✅ Windows 10 --- # LoadState syntax -The `LoadState.exe` command is used with the User State Migration Tool (USMT) 10.0 to restore a store previously captured by the `ScanState.exe` command onto a destination computer. This article discusses the `LoadState.exe` command syntax and the options available with it. +The `LoadState.exe` command is used with the User State Migration Tool (USMT) to restore a store previously captured by the `ScanState.exe` command onto a destination computer. This article discusses the `LoadState.exe` command syntax and the options available with it. -## Before you begin +## Before beginning -Before you run the `LoadState.exe` command, note the following items: +Before running the `LoadState.exe` command, note the following items: -- To ensure that all operating system settings migrate, we recommend that you run the `LoadState.exe` commands in administrator mode from an account with administrative credentials. +- To ensure that all operating system settings migrate, Microsoft recommends running `LoadState.exe` commands in administrator mode from an account with administrative credentials. - For information about software requirements for running the `LoadState.exe` command, see [USMT requirements](usmt-requirements.md). -- You should sign out after you run the `LoadState.exe` command. Some settings, such as example, fonts, wallpaper, and screensaver settings, won't take effect until the next time the user logs in. +- Sign out after running the `LoadState.exe` command. Some settings, such as example, fonts, wallpaper, and screensaver settings, won't take effect until the next time the user logs in. -- Unless otherwise specified, you can use each option only once when running a tool on the command line. +- Unless otherwise specified, each option can only be used once when running a tool from the command line. -- **LoadState** doesn't require domain controller access to apply domain profiles. This functionality is available without any additional configuration. It isn't necessary for the source computer to have had domain controller access when the user profile was gathered using **ScanState**. However, domain profiles are inaccessible until the destination computer is joined to the domain. +- **LoadState** doesn't require domain controller access to apply domain profiles. This functionality is available without any additional configuration. It isn't necessary for the source computer to have domain controller access when the user profile was gathered using **ScanState**. However, domain profiles are inaccessible until the destination computer is joined to the domain. -- The [Incompatible command-line options](#incompatible-command-line-options) table lists which options you can use together and which command-line options are incompatible. +- The [Incompatible command-line options](#incompatible-command-line-options) table lists which options can be used together and which command-line options are incompatible. ## Syntax -This section explains the syntax and usage of the command-line options available when you use the `LoadState.exe` command. The options can be specified in any order. If the option contains a parameter, you can specify either a colon or space separator. +This section explains the syntax and usage of the command-line options available when using the `LoadState.exe` command. The options can be specified in any order. If the option contains a parameter, either a colon or space separator can be specified. The `LoadState.exe` command's syntax is: - - > LoadState.exe *StorePath* \[/i:\[*Path*\\\]*FileName*\] \[/v:*VerbosityLevel*\] \[/nocompress\] \[/decrypt /key:*KeyString*|/keyfile:\[Path\\\]*FileName*\] \[/l:\[*Path*\\\]*FileName*\] \[/progress:\[*Path*\\\]*FileName*\] \[/r:*TimesToRetry*\] \[/w:*SecondsToWait*\] \[/c\] \[/all\] \[/ui:\[*DomainName*|*ComputerName*\\\]*UserName*\] \[/ue:\[\[*DomainName*|*ComputerName*\\\]*UserName*\] \[/uel:*NumberOfDays*|*YYYY/MM/DD*|0\] \[/md:*OldDomain*:*NewDomain*\] \[/mu:*OldDomain*\\*OldUserName*:\[*NewDomain*\\\]*NewUserName*\] \[/lac:\[*Password*\]\] \[/lae\] \[/config:\[*Path*\\\]*FileName*\] \[/?|help\] For example, to decrypt the store and migrate the files and settings to a computer, type the following command: @@ -48,58 +47,58 @@ For example, to decrypt the store and migrate the files and settings to a comput ## Storage options -USMT provides the following options that you can use to specify how and where the migrated data is stored. +USMT provides the following options that can be used to specify how and where the migrated data is stored. | Command-Line Option | Description | |--- |--- | -| **StorePath** | Indicates the folder where the files and settings data are stored. You must specify *StorePath* when using the `LoadState.exe` command. You can't specify more than one *StorePath*. | -| **/decrypt /key**:*KeyString*
or
**/decrypt /key**:"*Key String*"
or
**/decrypt /keyfile**:[*Path*]*FileName* | Decrypts the store with the specified key. With this option, you'll need to specify the encryption key in one of the following ways:
  • `/key`:*KeyString* specifies the encryption key. If there's a space in *KeyString*, you must surround the argument with quotation marks (`"`).
  • `/keyfile`:*FilePathAndName* specifies a text (`.txt`) file that contains the encryption key

*KeyString* can't exceed 256 characters.
The `/key` and `/keyfile` options can't be used on the same command line.
The `/decrypt` and `/nocompress` options can't be used on the same command line.
**Important**
Use caution when using the `/key` or `keyfile` options. For example, anyone who has access to scripts that run the `LoadState.exe` command with these options will also have access to the encryption key.

For example:
`LoadState.exe /i:MigApp.xml /i:MigDocs.xml \server\share\migration\mystore /decrypt /key:mykey` | +| **StorePath** | Indicates the folder where the files and settings data are stored. *StorePath* must be specified when using the `LoadState.exe` command. More than one *StorePath* can't be specified. | +| **/decrypt /key**:*KeyString*
or
**/decrypt /key**:"*Key String*"
or
**/decrypt /keyfile**:[*Path*]*FileName* | Decrypts the store with the specified key. With this option, the encryption key needs to be specified in one of the following ways:
  • `/key`:*KeyString* specifies the encryption key. If there's a space in *KeyString*, the argument must be surrounded with quotation marks (`"`).
  • `/keyfile`:*FilePathAndName* specifies a text (`.txt`) file that contains the encryption key

*KeyString* can't exceed 256 characters.
The `/key` and `/keyfile` options can't be used on the same command line.
The `/decrypt` and `/nocompress` options can't be used on the same command line.
**Important**
Use caution when using the `/key` or `keyfile` options. For example, anyone who has access to scripts that run the `LoadState.exe` command with these options also have access to the encryption key.

For example:
`LoadState.exe /i:MigApp.xml /i:MigDocs.xml \server\share\migration\mystore /decrypt /key:mykey` | | **/decrypt**:*"encryption strength"* | The `/decrypt` option accepts a command-line parameter to define the encryption strength specified for the migration store encryption. For more information about supported encryption algorithms, see [Migration Store Encryption](usmt-migration-store-encryption.md). | | **/hardlink** | Enables user-state data to be restored from a hard-link migration store. The `/nocompress` parameter must be specified with `/hardlink` option. | -| **/nocompress** | Specifies that the store isn't compressed. You should only use this option in testing environments. We recommend that you use a compressed store during your actual migration. This option can't be used with the `/decrypt` option.
For example:
`LoadState.exe /i:MigApp.xml /i:MigDocs.xml \server\share\migration\mystore /nocompress` | +| **/nocompress** | Specifies that the store isn't compressed. This option should only be used in testing environments. Microsoft recommends using a compressed store during the actual migration. This option can't be used with the `/decrypt` option.
For example:
`LoadState.exe /i:MigApp.xml /i:MigDocs.xml \server\share\migration\mystore /nocompress` | ## Migration rule options -USMT provides the following options to specify what files you want to migrate. +USMT provides the following options to specify what files to migrate. | Command-Line Option | Description | |--- |--- | -| **/i**:[*Path*]*FileName* | **(include)**
Specifies an .xml file that contains rules that define what state to migrate. You can specify this option multiple times to include all of your .xml files (`MigApp.xml`, `MigSys.xml`, `MigDocs.xml` and any custom .xml files that you create). *Path* can be either a relative or full path. If you don't specify the *Path* variable, then *FileName* must be located in the current directory.

For more information about which files to specify, see the "XML files" section of the [Frequently Asked Questions](usmt-faq.yml) article. | -| **/config**:[*Path*]*FileName* | Specifies the `Config.xml` file that the `LoadState.exe` command should use. You can't specify this option more than once on the command line. *Path* can be either a relative or full path. If you don't specify the *Path* variable, then the *FileName* must be located in the current directory.

This example migrates the files and settings based on the rules in the `Config.xml`, `MigDocs.xml`, and `MigApp.xml` files:

`LoadState.exe \server\share\migration\mystore /config:Config.xml /i:MigDocs.xml /i:MigApp.xml /v:5 /l:LoadState.log` | -| **/auto**:*"path to script files"* | This option enables you to specify the location of the default .xml files and then launch your migration. If no path is specified, USMT will use the directory where the USMT binaries are located. The `/auto` option has the same effect as using the following options: `/i:MigDocs.xml` `/i:MigApp.xml /v:5`. | +| **/i**:[*Path*]*FileName* | **(include)**
Specifies an **.xml** file that contains rules that define what data to migrate. This option can be specified multiple times to include all of the **.xml** files (`MigApp.xml`, `MigSys.xml`, `MigDocs.xml` and any custom **.xml** files that are created). *Path* can be either a relative or full path. If the *Path* variable isn't specified, then *FileName* must be located in the current directory.

For more information about which files to specify, see the "XML files" section of the [Frequently Asked Questions](usmt-faq.yml) article. | +| **/config**:[*Path*]*FileName* | Specifies the `Config.xml` file that the `LoadState.exe` command should use. This option can't be specified more than once on the command line. *Path* can be either a relative or full path. If the *Path* variable isn't specified, then the *FileName* must be located in the current directory.

This example migrates the files and settings based on the rules in the `Config.xml`, `MigDocs.xml`, and `MigApp.xml` files:

`LoadState.exe \server\share\migration\mystore /config:Config.xml /i:MigDocs.xml /i:MigApp.xml /v:5 /l:LoadState.log` | +| **/auto**:*"path to script files"* | This option enables specifying the location of the default **.xml** files. If no path is specified, USMT uses the directory where the USMT binaries are located. The `/auto` option has the same effect as using the following options: `/i:MigDocs.xml` `/i:MigApp.xml /v:5`. | ## Monitoring options -USMT provides several command-line options that you can use to analyze problems that occur during migration. +USMT provides several command-line options that can be used to analyze problems that occur during migration. | Command-Line Option | Description | |--- |--- | -| **/l**:[*Path*]*FileName* | Specifies the location and name of the **LoadState** log. You can't store any of the log files in *StorePath*. *Path* can be either a relative or full path. If you don't specify the *Path* variable, then the log will be created in the current directory. You can specify the `/v` option to adjust the verbosity of the log.

If you run the `LoadState.exe` command from a shared network resource, you must specify the `l` option, or USMT will fail with the error:

***USMT was unable to create the log file(s)***

To fix this issue, make sure to specify the `/l` option when running `LoadState.exe` from a shared network resource. | -| **/v**:*``* | **(Verbosity)**

Enables verbose output in the **LoadState** log file. The default value is 0.
You can set the *VerbosityLevel* to one of the following levels:
  • **0** - Only the default errors and warnings are enabled.
  • **1** - Enables verbose output.
  • **4** - Enables error and status output.
  • **5** - Enables verbose and status output.
  • **8** - Enables error output to a debugger.
  • **9** - Enables verbose output to a debugger.
  • **12** - Enables error and status output to a debugger.
  • **13** - Enables verbose, status, and debugger output.

For example:
`LoadState.exe \server\share\migration\mystore /v:5 /i:MigDocs.xml /i:MigApp.xml` | -| **/progress**:[*Path*]*FileName* | Creates the optional progress log. You can't store any of the log files in *StorePath*. *Path* can be either a relative or full path. If you don't specify the *Path* variable, then *FileName* will be created in the current directory.

For example:
`LoadState.exe /i:MigApp.xml /i:MigDocs.xml \server\share\migration\mystore /progress:Progress.log /l:loadlog.log` | -| **/c** | When this option is specified, the `LoadState.exe` command will continue to run, even if non-fatal errors occur. Any files or settings that cause an error are logged in the progress log. For example, if there's a large file that won't fit on the computer, the `LoadState.exe` command will log an error and continue with the migration. Without the `/c` option, the `LoadState.exe` command will exit on the first error. You can use the new <**ErrorControl**> section in the `Config.xml` file to specify which file or registry read/write errors can be safely ignored and which might cause the migration to fail. This error control enables the `/c` command-line option to safely skip all input/output (I/O) errors in your environment. In addition, the `/genconfig` option now generates a sample <**ErrorControl**> section that is enabled by specifying error messages and desired behaviors in the `Config.xml` file. | -| **/r**:*``* | **(Retry)**

Specifies the number of times to retry when an error occurs while migrating the user state from a server. The default is three times. This option is useful in environments where network connectivity isn't reliable.

While restoring the user state, the `/r` option won't recover data that is lost due to a network-hardware failure, such as a faulty or disconnected network cable, or when a virtual private network (VPN) connection fails. The retry option is intended for large, busy networks where connectivity is satisfactory, but communication latency is a problem. | -| **/w**:*``* | **(Wait)**

Specifies the time to wait, in seconds, before retrying a network file operation. The default is 1 second. | +| **/l**:[*Path*]*FileName* | Specifies the location and name of the **LoadState** log. The log files can't be stored in *StorePath*. *Path* can be either a relative or full path. If the *Path* variable isn't specified, then the log is created in the current directory. The `/v` option can be specified to adjust the verbosity of the log.

If running the `LoadState.exe` command from a shared network resource, the `l` option must be specified, or USMT fails with the error:

***USMT was unable to create the log file(s)***

To fix this issue, make sure to specify the `/l` option when running `LoadState.exe` from a shared network resource. | +| **/v**:*``* | **(Verbosity)**

Enables verbose output in the **LoadState** log file. The default value is 0.
The *VerbosityLevel* can be set to one of the following levels:
  • **0** - Only the default errors and warnings are enabled.
  • **1** - Enables verbose output.
  • **4** - Enables error and status output.
  • **5** - Enables verbose and status output.
  • **8** - Enables error output to a debugger.
  • **9** - Enables verbose output to a debugger.
  • **12** - Enables error and status output to a debugger.
  • **13** - Enables verbose, status, and debugger output.

For example:
`LoadState.exe \server\share\migration\mystore /v:5 /i:MigDocs.xml /i:MigApp.xml` | +| **/progress**:[*Path*]*FileName* | Creates the optional progress log. The log files can't be stored in *StorePath*. *Path* can be either a relative or full path. If the *Path* variable isn't specified, then *FileName* is created in the current directory.

For example:
`LoadState.exe /i:MigApp.xml /i:MigDocs.xml \server\share\migration\mystore /progress:Progress.log /l:loadlog.log` | +| **/c** | When this option is specified, the `LoadState.exe` command continues to run, even if non-fatal errors occur. Any files or settings that cause an error are logged in the progress log. For example, if there's a large file that doesn't fit on the computer, the `LoadState.exe` command logs an error and continue with the migration. Without the `/c` option, the `LoadState.exe` command exits on the first error. The \<**ErrorControl**\> section can be used in the `Config.xml` file to specify which file or registry read/write errors can be safely ignored and which might cause the migration to fail. This error control enables the `/c` command-line option to safely skip all input/output (I/O) errors in the environment. In addition, the `/genconfig` option now generates a sample \<**ErrorControl**\> section that is enabled by specifying error messages and desired behaviors in the `Config.xml` file. | +| **/r**:*``* | **(Retry)**

Specifies the number of times to retry when an error occurs while migrating the user state from a server. The default is three times. This option is useful in environments where network connectivity isn't reliable.

When the user state is being restored, the `/r` option doesn't recover data that is lost due to a network-hardware failure, such as a faulty or disconnected network cable, or when a virtual private network (VPN) connection fails. The retry option is intended for large, busy networks where connectivity is satisfactory, but communication latency is a problem. | +| **/w**:*``* | **(Wait)**

Specifies the time to wait, in seconds, before retrying a network file operation. The default is 1 second. | | **/?** or **/help** | Displays Help on the command line. | ## User options -By default, all users are migrated. The only way to specify which users to include and exclude is by using the following options. You can't exclude users in the migration .xml files or by using the `Config.xml` file. For more information, see [Identify Users](usmt-identify-users.md). +By default, all users are migrated. The only way to specify which users to include and exclude is by using the following options. Users can't be excluded in the migration **.xml** files or by using the `Config.xml` file. For more information, see [Identify Users](usmt-identify-users.md). | Command-Line Option | Description | |--- |--- | -| **/all** | Migrates all of the users on the computer.

USMT migrates all user accounts on the computer, unless you specifically exclude an account with the `/ue` or `/uel` options. For this reason, you don't need to specify this option on the command line. However, if you choose to use the `/all` option, you can't also use the `/ui`, `/ue` or `/uel` options. | -| **/ui**:*DomainName UserName*
or
**/ui**:*"DomainName User Name"*
or
**/ui**:*ComputerName LocalUserName* | **(User include)**

Migrates the specified user. By default, all users are included in the migration. Therefore, this option is helpful only when used with the `/ue` option. You can specify multiple `/ui` options, but you can't use the `/ui` option with the `/all` option. *DomainName* and *UserName* can contain the asterisk (`*`) wildcard character. When you specify a user name that contains spaces, you'll need to surround it with quotations marks (`"`).

For example, to include only **User2** from the Corporate domain, enter:

`/ue:* /ui:corporate\user2`

**Note**
If a user is specified for inclusion with the `/ui` option and also specified to be excluded with either the `/ue` or `/uel` options, the user will be included in the migration.

For more examples, see the descriptions of the `/uel`, `/ue`, and `/ui` options in this table. | -| **/uel**:*``*
or
**/uel**:*``*
or
**/uel**:0 | **(User exclude based on last logon)**

Migrates only the users that logged onto the source computer within the specified time period, based on the **Last Modified** date of the Ntuser.dat file on the source computer. The `/uel` option acts as an include rule. For example, the `/uel:30` option migrates users who logged on, or whose user account was modified, within the last 30 days from the date when the `ScanState.exe` command is run. You can specify the number of days or you can specify a date. You can't use this option with the `/all` option. USMT retrieves the last sign-in information from the local computer, so the computer doesn't need to be connected to the network when you run this option. In addition, if a domain user has signed into another computer, that sign-in instance isn't considered by USMT.
**Note**
The `/uel` option isn't valid in offline migrations.

Examples:
  • `/uel:0` migrates accounts that were logged on to the source computer when the `ScanState.exe` command was run.
  • `/uel:90` migrates users who have logged on, or whose accounts have been otherwise modified, within the last 90 days.
  • `/uel:1` migrates users whose accounts have been modified within the last 24 hours.
  • `/uel:2020/2/15` migrates users who have logged on or whose accounts have been modified since February 15, 2020.

For example:
`LoadState.exe /i:MigApp.xml /i:MigDocs.xml \server\share\migration\mystore /uel:0` | -| **/ue**:*DomainName\UserName*
or
**/ue** *"DomainName\User Name"*
or
**/ue**:*ComputerName\LocalUserName* | **(User exclude)**

Excludes the specified users from the migration. You can specify multiple `/ue` options but you can't use the `/ue` option with the `/all` option. *DomainName* and *UserName* can contain the asterisk (`*`) wildcard character. When you specify a user name that contains spaces, you'll need to surround it with quotation marks (`"`).

For example:
`LoadState.exe /i:MigApp.xml /i:MigDocs.xml \server\share\migration\mystore /ue:contoso\user1`
For more examples, see the descriptions of the `/uel`, `/ue`, and `/ui` options in this table. | -| **/md**:*OldDomain*:*NewDomain*
or
**/md**:*LocalComputerName:NewDomain* | **(Move domain)**

Specifies a new domain for the user. Use this option to change the domain for users on a computer or to migrate a local user to a domain account. *OldDomain* may contain the asterisk () wildcard character.

You can specify this option more than once. You may want to specify multiple `/md` options if you're consolidating users across multiple domains to a single domain. For example, you could specify the following to consolidate the users from the Corporate and FarNorth domains into the Fabrikam domain: `/md:corporate:fabrikam` and `/md:farnorth:fabrikam`.

If there are conflicts between two `/md` commands, the first rule that you specify is applied. For example, if you specify the `/md:corporate:fabrikam` and `/md:corporate:farnorth` commands, then Corporate users would be mapped to the Fabrikam domain.
**Note**
If you specify an *OldDomain* that didn't exist on the source computer, the `LoadState.exe` command will appear to complete successfully, without an error or warning. However, in this case, users won't be moved to *NewDomain* but will remain in their original domain. For example, if you misspell **contoso** and you instead specify **/md:contso:fabrikam**, the users will remain in **contoso** on the destination computer.

For example:
`LoadState.exe /i:MigApp.xml /i:MigDocs.xml \server\share\migration\mystore`
` /progress:Progress.log /l:LoadState.log /md:contoso:fabrikam` | -| **/mu**:*OldDomain OldUserName*:[*NewDomain*]*NewUserName*
or
**/mu**:*OldLocalUserName*:*NewDomain NewUserName* | **(Move user)**

Specifies a new user name for the specified user. If the store contains more than one user, you can specify multiple `/mu` options. You can't use wildcard characters with this option.

For example:
`LoadState.exe /i:MigApp.xml /i:MigDocs.xml \server\share\migration\mystore`
`/progress:Progress.log /l:LoadState.log /mu:contoso\user1:fabrikam\user1` | -| **/lac**:[*Password*] | **(Local account create)**

Specifies that if a user account is a local (non-domain) account, and it doesn't exist on the destination computer, USMT will create the account on the destination computer but it will be disabled. To enable the account, you must also use the `/lae` option.

If the `/lac` option isn't specified, any local user accounts that don't already exist on the destination computer won't be migrated.

*Password* is the password for the newly created account. An empty password is used by default.
**Caution**
Use the *Password* variable with caution because it's provided in plain text and can be obtained by anyone with access to the computer that is running the `LoadState.exe` command.
Also, if the computer has multiple users, all migrated users will have the same password.

For example:
`LoadState.exe /i:MigApp.xml /i:MigDocs.xml \server\share\migration\mystore`

For instructions, see [Migrate user accounts](usmt-migrate-user-accounts.md). | -| `/lae` | **(Local account enable)**

Enables the account that was created with the `/lac` option. You must specify the `/lac` option with this option.

For example:
`LoadState.exe /i:MigApp.xml /i:MigDocs.xml \server\share\migration\mystore`
`/progress:Progress.log /l:LoadState.log /lac:password /lae`

For instructions, see [Migrate user accounts](usmt-migrate-user-accounts.md). | +| **/all** | Migrates all of the users on the computer.

USMT migrates all user accounts on the computer, unless an account is specifically excluded with the `/ue` or `/uel` options. For this reason, this option doesn't need to be specified on the command line. However, if using the `/all` option, the `/ui`, `/ue` or `/uel` options can't also be used. | +| **/ui**:*DomainName UserName*
or
**/ui**:*"DomainName User Name"*
or
**/ui**:*ComputerName LocalUserName* | **(User include)**

Migrates the specified user. By default, all users are included in the migration. Therefore, this option is helpful only when used with the `/ue` option. Multiple `/ui` options can be specified, but the `/ui` option can't be used with the `/all` option. *DomainName* and *UserName* can contain the asterisk (`*`) wildcard character. When user name that contains spaces is specified, it needs to be surrounded with quotations marks (`"`).

For example, to include only **User2** from the Corporate domain, enter:

`/ue:* /ui:corporate\user2`

**Note**
If a user is specified for inclusion with the `/ui` option and also specified to be excluded with either the `/ue` or `/uel` options, the user is included in the migration.

For more examples, see the descriptions of the `/uel`, `/ue`, and `/ui` options in this table. | +| **/uel**:*``*
or
**/uel**:*``*
or
**/uel**:0 | **(User exclude based on last logon)**

Migrates only the users that logged onto the source computer within the specified time period, based on the **Last Modified** date of the **Ntuser.dat** file on the source computer. The `/uel` option acts as an include rule. For example, the `/uel:30` option migrates users who logged on, or whose user account was modified, within the last 30 days from the date when the `ScanState.exe` command is run. The number of days can be specified or a date can be specified. This option can't be used with the `/all` option. USMT retrieves the last sign-in information from the local computer, so the computer doesn't need to be connected to the network when running this option. In addition, if a domain user signs into another computer, USMT doesn't consider that sign-in instance.
**Note**
The `/uel` option isn't valid in offline migrations.

Examples:
  • `/uel:0` migrates accounts that were logged on to the source computer when the `ScanState.exe` command was run.
  • `/uel:90` migrates users who logged on, or whose accounts were otherwise modified, within the last 90 days.
  • `/uel:1` migrates users whose accounts were modified within the last 24 hours.
  • `/uel:2020/2/15` migrates users who logged on or whose accounts modified since February 15, 2020.

For example:
`LoadState.exe /i:MigApp.xml /i:MigDocs.xml \server\share\migration\mystore /uel:0` | +| **/ue**:*DomainName\UserName*
or
**/ue** *"DomainName\User Name"*
or
**/ue**:*ComputerName\LocalUserName* | **(User exclude)**

Excludes the specified users from the migration. Multiple `/ue` options can be used but the `/ue` option can't be used with the `/all` option. *DomainName* and *UserName* can contain the asterisk (`*`) wildcard character. When a user name that contains spaces is specified, it needs to be surround with quotation marks (`"`).

For example:
`LoadState.exe /i:MigApp.xml /i:MigDocs.xml \server\share\migration\mystore /ue:contoso\user1`
For more examples, see the descriptions of the `/uel`, `/ue`, and `/ui` options in this table. | +| **/md**:*OldDomain*:*NewDomain*
or
**/md**:*LocalComputerName:NewDomain* | **(Move domain)**

Specifies a new domain for the user. Use this option to change the domain for users on a computer or to migrate a local user to a domain account. *OldDomain* might contain the asterisk () wildcard character.

This option can be specified more than once. If consolidating users across multiple domains to a single domain, multiple `/md` options might need to be specified. For example, to consolidate the users from the Corporate and FarNorth domains into the Fabrikam domain, specify the following settings: `/md:corporate:fabrikam` and `/md:farnorth:fabrikam`.

If there are conflicts between two `/md` commands, the first rule specified is applied. For example, if the `/md:corporate:fabrikam` and `/md:corporate:farnorth` commands are specified, then Corporate users would be mapped to the Fabrikam domain.
**Note**
If a domain that didn't exist on the source computer is specified, the `LoadState.exe` command appears to complete successfully, without an error or warning. However, in this case, users aren't moved to *NewDomain* but instead remain in their original domain. For example, if **contoso** is misspelled and instead **/md:contso:fabrikam** is specified, the users remain in **contoso** on the destination computer.

For example:
`LoadState.exe /i:MigApp.xml /i:MigDocs.xml \server\share\migration\mystore`
`/progress:Progress.log /l:LoadState.log /md:contoso:fabrikam` | +| **/mu**:*OldDomain OldUserName*:[*NewDomain*]*NewUserName*
or
**/mu**:*OldLocalUserName*:*NewDomain NewUserName* | **(Move user)**

Specifies a new user name for the specified user. If the store contains more than one user, multiple `/mu` options can be specified. Wildcard characters can't be used with this option.

For example:
`LoadState.exe /i:MigApp.xml /i:MigDocs.xml \server\share\migration\mystore`
`/progress:Progress.log /l:LoadState.log /mu:contoso\user1:fabrikam\user1` | +| **/lac**:[*Password*] | **(Local account create)**

If a user account is:
  • A local (non-domain) account
  • An account that doesn't exist on the destination computer
this setting specifies to create the account on the destination computer. However, the account is disabled. To enable the account, the `/lae` option must also be used.

If the `/lac` option isn't specified, any local user accounts that don't already exist on the destination computer aren't migrated.

*Password* is the password for the newly created account. An empty password is used by default.
**Caution**
Use the *Password* variable with caution. The *Password* variable is provided in plain text and anyone with access to the computer that is running the `LoadState.exe` command can obtain the password.
Also, if the computer has multiple users, all migrated users have the same password.

For example:
`LoadState.exe /i:MigApp.xml /i:MigDocs.xml \server\share\migration\mystore`

For instructions, see [Migrate user accounts](usmt-migrate-user-accounts.md). | +| `/lae` | **(Local account enable)**

Enables the account that was created with the `/lac` option. The `/lac` option must be specified with this option.

For example:
`LoadState.exe /i:MigApp.xml /i:MigDocs.xml \server\share\migration\mystore`
`/progress:Progress.log /l:LoadState.log /lac:password /lae`

For instructions, see [Migrate user accounts](usmt-migrate-user-accounts.md). | ### Examples for the /ui and /ue options -The following examples apply to both the **/ui** and **/ue** options. You can replace the **/ue** option with the **/ui** option to include, rather than exclude, the specified users. +The following examples apply to both the **/ui** and **/ue** options. The **/ue** option can be replaced with the **/ui** option to include, rather than exclude, the specified users. | Behavior | Command | |--- |--- | @@ -112,52 +111,53 @@ The following examples apply to both the **/ui** and **/ue** options. You can re ### Using the options together -You can use the `/uel`, `/ue` and `/ui` options together to migrate only the users that you want migrated. +The `/uel`, `/ue` and `/ui` options can be used together to migrate only the users that need to be migrated. -**The /ui option has precedence over the /ue and /uel options.** If a user is included using the `/ui` option and also excluded using either the `/ue` or `/uel` options, the user will be included in the migration. For example, if you specify `/ui:contoso\* /ue:contoso\user1`, then User1 will be migrated, because the `/ui` option takes precedence over the `/ue` option. +**The /ui option has precedence over the /ue and /uel options.** If a user is included using the `/ui` option and also excluded using either the `/ue` or `/uel` options, the user is included in the migration. For example, if `/ui:contoso\* /ue:contoso\user1` is specified, then User1 is migrated, because the `/ui` option takes precedence over the `/ue` option. -**The /uel option takes precedence over the /ue option.** If a user has logged on within the specified time period set by the `/uel` option, that user's profile will be migrated even if they're excluded by using the `/ue` option. For example, if you specify `/ue:contoso\user1 /uel:14`, the User1 will be migrated if they've logged on to the computer within the last 14 days. +**The /uel option takes precedence over the /ue option.** If a user logged on within the specified time period set by the `/uel` option, that user's profile is migrated even if they're excluded by using the `/ue` option. For example, if `/ue:contoso\user1 /uel:14` is specified, then User1 is migrated if they logged on to the computer within the last 14 days. | Behavior | Command | |--- |--- | | Include only User2 from the Fabrikam domain and exclude all other users. | `/ue:* /ui:fabrikam\user2` | | Include only the local user named User1 and exclude all other users. | `/ue:* /ui:user1` | -| Include only the domain users from Contoso, except Contoso\User1. | This behavior can't be completed using a single command. Instead, to migrate this set of users, you'll need to specify the following options:
  • Using the **ScanState** command-line tool, enter:
    `/ue:* /ui:contoso`
  • Using the **LoadState** command-line tool, enter:
    `/ue:contoso\user1`
| +| Include only the domain users from Contoso, except Contoso\User1. | This behavior can't be completed using a single command. Instead, to migrate this set of users, specify the following options:
  • Using the **ScanState** command-line tool, enter:
    `/ue:* /ui:contoso`
  • Using the **LoadState** command-line tool, enter:
    `/ue:contoso\user1`
| | Include only local (non-domain) users. | `/ue: /ui:%computername%*` | ## Incompatible command-line options -The following table indicates which command-line options aren't compatible with the `LoadState.exe` command. If the table entry for a particular combination is blank, the options are compatible, and you can use them together. The X symbol means that the options aren't compatible. For example, you can't use the `/nocompress` option with the `/encrypt` option. +The following table indicates which command-line options aren't compatible with the `LoadState.exe` command. If the table entry for a particular combination has a ✔️, the options are compatible, and they can be used together. The ❌ symbol means that the options aren't compatible. For example, the `/nocompress` option can't be used with the `/encrypt` option. | Command-Line Option | /keyfile | /nocompress | /genconfig | /all | |--- |--- |--- |--- |--- | -| **/i** | | | | | -| **/v** | | | | | -| **/nocompress** | | N/A | X | | -| **/key** | X | | X | | -| **/decrypt** | Required* | X | X | | -| **/keyfile** | N/A | | X | | -| **/l** | | | | | -| **/progress** | | | X | | -| **/r** | | | X | | -| **/w** | | | X | | -| **/c** | | | X | | -| **/p** | | | X | N/A | -| **/all** | | | X | | -| **/ui** | | | X | X | -| **/ue** | | | X | X | -| **/uel** | | | X | X | -| **/genconfig** | | | N/A | | -| **/config** | | | X | | -| *StorePath* | | | | | -| **/md** | | | | | -| **/mu** | | | | | -| **/lae** | | | | | -| **/lac** | | | | | +| **/i** | ✔️ | ✔️ | ✔️ | ✔️ | +| **/v** | ✔️ | ✔️ | ✔️ | ✔️ | +| **/nocompress** | ✔️ | N/A | ❌ | ✔️ | +| **/key** | ❌ | ✔️ | ❌ | ✔️ | +| **/decrypt** | Required* | ❌ | ❌ | ✔️ | +| **/keyfile** | N/A | ✔️ | ❌ | ✔️ | +| **/l** | ✔️ | ✔️ | ✔️ | ✔️ | +| **/progress** | ✔️ | ✔️ | ❌ | ✔️ | +| **/r** | ✔️ | ✔️ | ❌ | ✔️ | +| **/w** | ✔️ | ✔️ | ❌ | ✔️ | +| **/c** | ✔️ | ✔️ | ❌ | ✔️ | +| **/p** | ✔️ | ✔️ | ❌ | N/A | +| **/all** | ✔️ | ✔️ | ❌ | ✔️ | +| **/ui** | ✔️ | ✔️ | ❌ | ❌ | +| **/ue** | ✔️ | ✔️ | ❌ | ❌ | +| **/uel** | ✔️ | ✔️ | ❌ | ❌ | +| **/genconfig** | ✔️ | ✔️ | N/A | ✔️ | +| **/config** | ✔️ | ✔️ | ❌ | ✔️ | +| *StorePath* | ✔️ | ✔️ | ✔️ | ✔️ | +| **/md** | ✔️ | ✔️ | ✔️ | ✔️ | +| **/mu** | ✔️ | ✔️ | ✔️ | ✔️ | +| **/lae** | ✔️ | ✔️ | ✔️ | ✔️ | +| **/lac** | ✔️ | ✔️ | ✔️ | ✔️ | > [!NOTE] -> You must specify either the `/key` or `/keyfile` option with the `/encrypt` option. +> +> Either the `/key` or `/keyfile` option must be specified with the `/decrypt` option. ## Related articles -[XML elements library](usmt-xml-elements-library.md) +- [XML elements library](usmt-xml-elements-library.md). diff --git a/windows/deployment/usmt/usmt-log-files.md b/windows/deployment/usmt/usmt-log-files.md index ad51352c37..e76bb02593 100644 --- a/windows/deployment/usmt/usmt-log-files.md +++ b/windows/deployment/usmt/usmt-log-files.md @@ -1,28 +1,24 @@ --- -title: Log Files (Windows 10) -description: Learn how to use User State Migration Tool (USMT) 10.0 logs to monitor your migration and to troubleshoot errors and failed migrations. +title: USMT Log Files +description: Learn how to use User State Migration Tool (USMT) logs to monitor the migration and to troubleshoot errors and failed migrations. manager: aaroncz ms.author: frankroj ms.prod: windows-client author: frankroj -ms.date: 11/01/2022 +ms.date: 01/03/2024 ms.topic: article ms.technology: itpro-deploy +appliesto: + - ✅ Windows 11 + - ✅ Windows 10 --- # USMT log files -You can use User State Migration Tool (USMT) 10.0 logs to monitor your migration and to troubleshoot errors and failed migrations. This article describes the available command-line options to enable USMT logs, and new XML elements that configure which types of errors are fatal and should halt the migration, which types are non-fatal and should be skipped so that the migration can continue. +User State Migration Tool (USMT) logs can be used to monitor the migration and to troubleshoot errors and failed migrations. This article describes the available command-line options to enable USMT logs. It also describes new XML elements that can be used to configure: -[Log command-line options](#log-command-line-options) - -[ScanState and LoadState logs](#scanstate-and-loadstate-logs) - -[Progress log](#progress-log) - -[List files log](#list-files-log) - -[Diagnostic log](#diagnostic-log) +- Which types of errors are fatal and should halt the migration. +- Which types are non-fatal and should be skipped so that the migration can continue. ## Log command-line options @@ -37,21 +33,22 @@ The following table describes each command-line option related to logs, and it p |Set the environment variable **MIG_ENABLE_DIAG** to a path to an XML file.|`USMTDiag.xml`|The diagnostic log contains detailed system environment information, user environment information, and information about the migration units (migunits) being gathered and their contents.| > [!NOTE] -> You cannot store any of the log files in *StorePath*. If you do, the log will be overwritten when USMT is run. +> +> The log files can't be stored in *StorePath*. If the log files are stored in *StorePath*, the log files are overwritten when USMT runs. ## ScanState and LoadState logs - **ScanState** and **LoadState** logs are text files that are create when you run the **ScanState** and **LoadState** tools. You can use these logs to help monitor your migration. The content of the log depends on the command-line options that you use and the verbosity level that you specify. For more information about verbosity levels, see [Monitoring options](usmt-scanstate-syntax.md#monitoring-options) in [ScanState syntax](usmt-scanstate-syntax.md). + **ScanState** and **LoadState** logs are text files that are created when the **ScanState** and **LoadState** tools run. These logs can be used to help monitor the migration. The content of the log depends on the command-line options that are used and the verbosity level that is specified. For more information about verbosity levels, see [Monitoring options](usmt-scanstate-syntax.md#monitoring-options) in [ScanState syntax](usmt-scanstate-syntax.md). ## Progress log -You can create a progress log using the `/progress` option. External tools, such as Microsoft System Center Operations Manager, can parse the progress log to update your monitoring systems. The first three fields in each line are fixed as follows: +A progress log can be created using the `/progress` option. External tools, such as Microsoft System Center Operations Manager, can parse the progress log to update the monitoring systems. The first three fields in each line are fixed as follows: -- **Date:** Date, in the format of *day* *shortNameOfTheMonth* *year*. For example: 08 Jun 2006. +- **Date:** Date, in the format of *day* *shortNameOfTheMonth* *year*. For example: 08 Jun 2023. - **Local time:** Time, in the format of *hrs*:*minutes*:*seconds* (using a 24-hour clock). For example: 13:49:13. -- **Migration time:** Duration of time that USMT was run, in the format of *hrs:minutes:seconds*. For example: 00:00:10. +- **Migration time:** Duration of time that USMT was run, in the format of *hrs:minutes:seconds*. For example: 00:00:20. The remaining fields are key/value pairs as indicated in the following table. @@ -62,15 +59,15 @@ The remaining fields are key/value pairs as indicated in the following table. | *computerName* | The name of the source or destination computer on which USMT was run. | | *commandLine* | The full command used to run USMT. | | *PHASE* | Reports that a new phase in the migration is starting. This key can be one of the following values:
  • Initializing
  • Scanning
  • Collecting
  • Saving
  • Estimating
  • Applying
| -| *detectedUser* |
  • For the **ScanState** tool, this key are the users USMT detected on the source computer that can be migrated.
  • For the **LoadState** tool, this key are the users USMT detected in the store that can be migrated.
| +| *detectedUser* |
  • For the **ScanState** tool, this key is the users USMT detected on the source computer that can be migrated.
  • For the **LoadState** tool, this key is the users USMT detected in the store that can be migrated.
| | *includedInMigration* | Defines whether the user profile/component is included for migration. Valid values are **Yes** or **No**. | | *forUser* | Specifies either of the following values:
  • The user state being migrated.
  • *This Computer*, meaning files and settings that aren't associated with a user.
| | *detectedComponent* | Specifies a component detected by USMT.
  • For *ScanState*, this key is a component or application that is installed on the source computer.
  • For **LoadState**, this key is a component or application that was detected in the store.
| | *totalSizeInMBToTransfer* | Total size of the files and settings to migrate in megabytes (MB). | -| *totalPercentageCompleted* | Total percentage of the migration that has been completed by either **ScanState** or **LoadState**. | +| *totalPercentageCompleted* | Total percentage of the migration that is completed by either **ScanState** or **LoadState**. | | *collectingUser* | Specifies which user **ScanState** is collecting files and settings for. | | *totalMinutesRemaining* | Time estimate, in minutes, for the migration to complete. | -| *error* | Type of non-fatal error that occurred. This key can be one of the following values:
  • **UnableToCopy**: Unable to copy to store because the disk on which the store is located is full.
  • **UnableToOpen**: Unable to open the file for migration because the file is opened in non-shared mode by another application or service.
  • **UnableToCopyCatalog**: Unable to copy because the store is corrupted.
  • **UnableToAccessDevice**: Unable to access the device.
  • **UnableToApply**: Unable to apply the setting to the destination computer.
| +| *error* | Type of non-fatal error that occurred. This key can be one of the following values:
  • **UnableToCopy**: Unable to copy to store because the disk on which the store is located is full.
  • **UnableToOpen**: Unable to open the file for migration because another application or service has the file open in non-shared mode.
  • **UnableToCopyCatalog**: Unable to copy because the store is corrupted.
  • **UnableToAccessDevice**: Unable to access the device.
  • **UnableToApply**: Unable to apply the setting to the destination computer.
| | *objectName* | The name of the file or setting that caused the non-fatal error. | | *action* | Action taken by USMT for the non-fatal error. The values are:
  • **Ignore**: Non-fatal error ignored and the migration continued because the **/c** option was specified on the command line.
  • **Abort**: Stopped the migration because the **/c** option wasn't specified.
| | *errorCode* | The errorCode or return value. | @@ -83,45 +80,45 @@ The List files log (`Listfiles.txt`) provides a list of the files that were migr ## Diagnostic log -You can obtain the diagnostic log by setting the environment variable **MIG_ENABLE_DIAG** to a path to an XML file. +The diagnostic log can be obtained by setting the environment variable **MIG_ENABLE_DIAG** to a path to an XML file. The diagnostic log contains: -- Detailed system environment information +- Detailed system environment information. -- Detailed user environment information +- Detailed user environment information. -- Information about the migration units (migunits) being gathered and their contents +- Information about the migration units (migunits) being gathered and their contents. ## Using the Diagnostic Log -The diagnostic log is essentially a report of all the migration units (migunits) included in the migration. A migunit is a collection of data that is identified by the component it's associated with in the XML files. The migration store is made up of all the migunits in the migration. The diagnostic log can be used to verify which migunits were included in the migration and can be used for troubleshooting while authoring migration XML files. +The diagnostic log is essentially a report of all the migration units (migunits) included in the migration. A migunit is a collection of data. In the XML files, the component identifies the migunit that the migunit is associated with. The migration store is made up of all the migunits in the migration. The diagnostic log can be used to verify which migunits were included in the migration and can be used for troubleshooting while authoring migration XML files. -The following examples describe common scenarios in which you can use the diagnostic log. +The following examples describe common scenarios in which the diagnostic log can be used. **Why is this file not migrating when I authored an "include" rule for it?** Let's imagine that we have the following directory structure and that we want the **data** directory to be included in the migration along with the **New Text Document.txt** file in the **New Folder**. The directory of `C:\data` contains: -```console -01/21/2009 10:08 PM . -01/21/2009 10:08 PM .. -01/21/2009 10:08 PM New Folder -01/21/2009 09:19 PM 13 test (1).txt -01/21/2009 09:19 PM 13 test.txt +```cmd +12/21/2023 01:08 PM . +12/21/2023 01:08 PM .. +12/21/2023 01:08 PM New Folder +12/21/2023 01:19 PM 13 test (1).txt +12/21/2023 01:19 PM 13 test.txt 2 File(s) 26 bytes ``` The directory of `C:\data\New Folder` contains: -```console -01/21/2009 10:08 PM . -01/21/2009 10:08 PM .. -01/21/2009 10:08 PM 0 New Text Document.txt +```cmd +12/21/2023 01:08 PM . +12/21/2023 01:08 PM .. +12/21/2023 01:08 PM 0 New Text Document.txt 1 File(s) 0 bytes ``` -To migrate these files you author the following migration XML: +To migrate these files the following migration XML is authored: ```xml @@ -143,28 +140,28 @@ To migrate these files you author the following migration XML: ``` -However, upon testing the migration you notice that the **New Text Document.txt** file isn't included in the migration. To troubleshoot this failure, the migration can be repeated with the environment variable **MIG_ENABLE_DIAG** set such that the diagnostic log is generated. Upon searching the diagnostic log for the component **DATA1**, the following XML section is discovered: +However, upon testing the migration, the **New Text Document.txt** file is noticed that it wasn't included in the migration. To troubleshoot this failure, the migration can be repeated with the environment variable **MIG_ENABLE_DIAG** set such that the diagnostic log is generated. Searching the diagnostic log for the component **DATA1** reveals the following XML section: ```xml - - - - - + + + + + - - - - - + + + + + ``` -Analysis of this XML section reveals the migunit that was created when the migration rule was processed. The **<Perform>** section details the actual files that were scheduled for gathering and the result of the gathering operation. The **New Text Document.txt** file doesn't appear in this section, which confirms that the migration rule wasn't correctly authored. +Analysis of this XML section reveals the migunit that was created when the migration rule was processed. The **\** section details the actual files that were scheduled for gathering and the result of the gathering operation. The **New Text Document.txt** file doesn't appear in this section, which confirms that the migration rule wasn't correctly authored. -An analysis of the [XML elements library](usmt-xml-elements-library.md) reference article reveals that the [**<pattern>**](usmt-xml-elements-library.md#pattern) tag needs to be modified as follows: +An analysis of the [XML elements library](usmt-xml-elements-library.md) reference article reveals that the [**\**](usmt-xml-elements-library.md#pattern) tag needs to be modified as follows: ```xml c:\data\* [*] @@ -174,14 +171,14 @@ When the migration is performed again with the modified tag, the diagnostic log ```xml - + - + @@ -191,33 +188,33 @@ When the migration is performed again with the modified tag, the diagnostic log ``` -This diagnostic log confirms that the modified **<pattern>** value enables the migration of the file. +This diagnostic log confirms that the modified **\** value enables the migration of the file. **Why is this file migrating when I authored an exclude rule excluding it?** -In this scenario, you have the following directory structure and you want all files in the **Data** directory to migrate, except for text files. The `C:\Data` folder contains: +In this scenario, the following directory structure exists and all files in the **Data** directory should migrate, except for text files. The `C:\Data` folder contains: -```console +```cmd Directory of C:\Data -01/21/2009 10:08 PM . -01/21/2009 10:08 PM .. -01/21/2009 10:08 PM New Folder -01/21/2009 09:19 PM 13 test (1).txt -01/21/2009 09:19 PM 13 test.txt +12/21/2023 01:08 PM . +12/21/2023 01:08 PM .. +12/21/2023 01:08 PM New Folder +12/21/2023 01:19 PM 13 test (1).txt +12/21/2023 01:19 PM 13 test.txt 2 File(s) 26 bytes ``` The `C:\Data\New Folder\` contains: -```console -01/21/2009 10:08 PM . -01/21/2009 10:08 PM .. -01/21/2009 10:08 PM 0 New Text Document.txt +```cmd +12/21/2023 01:08 PM . +12/21/2023 01:08 PM .. +12/21/2023 01:08 PM 0 New Text Document.txt 1 File(s) 0 bytes ``` -You author the following migration XML: +The following migration XML is authored: ```xml @@ -245,11 +242,11 @@ You author the following migration XML: ``` -However, upon testing the migration you notice that all the text files are still included in the migration. In order to troubleshoot this issue, the migration can be performed with the environment variable **MIG_ENABLE_DIAG** set so that the diagnostic log is generated. Upon searching the diagnostic log for the component **DATA1**, the following XML section is discovered: +However, upon testing the migration, all the text files are noticed that they're still included in the migration. In order to troubleshoot this issue, the migration can be performed with the environment variable **MIG_ENABLE_DIAG** set so that the diagnostic log is generated. Searching the diagnostic log for the component **DATA1** reveals the following XML section: ```xml - + @@ -259,7 +256,7 @@ However, upon testing the migration you notice that all the text files are still - + @@ -271,7 +268,7 @@ However, upon testing the migration you notice that all the text files are still ``` -Upon reviewing the diagnostic log, you confirm that the files are still migrating, and that it's a problem with the authored migration XML rule. You author an update to the migration XML script as follows: +When the diagnostic log is reviewed, the files are still migrating is confirmed, and that it's a problem with the authored migration XML rule. An update is authored to the migration XML script as follows: ```xml @@ -302,11 +299,11 @@ Upon reviewing the diagnostic log, you confirm that the files are still migratin ``` -Your revised migration XML script excludes the files from migrating, as confirmed in the diagnostic log: +The revised migration XML script excludes the files from migrating, as confirmed in the diagnostic log: ```xml - + @@ -316,7 +313,7 @@ Your revised migration XML script excludes the files from migrating, as confirme - + @@ -327,9 +324,6 @@ Your revised migration XML script excludes the files from migrating, as confirme ## Related articles -[XML elements library](usmt-xml-elements-library.md) - -[ScanState syntax](usmt-scanstate-syntax.md) - -[LoadState syntax](usmt-loadstate-syntax.md) - +- [XML elements library](usmt-xml-elements-library.md). +- [ScanState syntax](usmt-scanstate-syntax.md). +- [LoadState syntax](usmt-loadstate-syntax.md). diff --git a/windows/deployment/usmt/usmt-migrate-efs-files-and-certificates.md b/windows/deployment/usmt/usmt-migrate-efs-files-and-certificates.md index c19ee33c65..07c64a00c9 100644 --- a/windows/deployment/usmt/usmt-migrate-efs-files-and-certificates.md +++ b/windows/deployment/usmt/usmt-migrate-efs-files-and-certificates.md @@ -1,13 +1,16 @@ --- -title: Migrate EFS Files and Certificates (Windows 10) +title: Migrate EFS Files and Certificates description: Learn how to migrate Encrypting File System (EFS) certificates. Also, learn where to find information about how to identify file types, files, and folders. manager: aaroncz ms.author: frankroj ms.prod: windows-client author: frankroj -ms.date: 11/01/2022 +ms.date: 01/03/2024 ms.topic: article ms.technology: itpro-deploy +appliesto: + - ✅ Windows 11 + - ✅ Windows 10 --- # Migrate EFS files and certificates @@ -16,7 +19,7 @@ This article describes how to migrate Encrypting File System (EFS) certificates. ## To migrate EFS files and certificates -Encrypting File System (EFS) certificates will be migrated automatically. However, by default, the User State Migration Tool (USMT) 10.0 fails if an encrypted file is found unless you specify an `/efs` option. Therefore when a device has EFS encrypted files, you must specify the `/efs` option with any one of the following parameters: +Encrypting File System (EFS) certificates are migrated automatically. However, by default, the User State Migration Tool (USMT) fails if an encrypted file is found unless the `/efs` option is specified. Therefore when a device has EFS encrypted files, the `/efs` option must be specified with any one of the following parameters: - `abort` - `skip` @@ -24,23 +27,23 @@ Encrypting File System (EFS) certificates will be migrated automatically. Howeve - `copyraw` - `hardlink` -when running the `ScanState.exe` command to migrate the encrypted files. Then, when you run the `LoadState.exe` command on the destination computer, the encrypted file and the EFS certificate will be automatically migrated. +when running the `ScanState.exe` command to migrate the encrypted files. Then, when the `LoadState.exe` command is run on the destination computer, the encrypted file and the EFS certificate are automatically migrated. > [!NOTE] -> The `/efs` options are not used with the `LoadState.exe` command. +> +> The `/efs` options aren't used with the `LoadState.exe` command. -Before using the **ScanState** tool for a migration that includes encrypted files and EFS certificates, you must ensure that all files in an encrypted folder are encrypted as well or remove the encryption attribute from folders that contain unencrypted files. If the encryption attribute has been removed from a file but not from the parent folder, the file will be encrypted during the migration using the credentials of the account used to run the **LoadState** tool. +Before using the **ScanState** tool for a migration that includes encrypted files and EFS certificates, all files in an encrypted folder must also be encrypted. Otherwise, remove the encryption attribute from folders that contain unencrypted files. If the encryption attribute is removed from a file but not from the parent folder, the file is encrypted during the migration using the credentials of the account used to run the **LoadState** tool. -You can run the [Cipher.exe](/windows-server/administration/windows-commands/cipher) tool at a Windows command prompt to review and change encryption settings on files and folders. For example, to remove encryption from a folder, at a command prompt enter: +The [Cipher.exe](/windows-server/administration/windows-commands/cipher) tool can be run at a Windows command prompt to review and change encryption settings on files and folders. For example, to remove encryption from a folder, at a command prompt enter: ```cmd cipher.exe /D /S: ``` -where *<Path>* is the full path of the topmost parent directory where the encryption attribute is set. +where *\* is the full path of the topmost parent directory where the encryption attribute is set. ## Related articles -[What does USMT migrate?](usmt-what-does-usmt-migrate.md) - -[Identify file types, files, and folders](usmt-identify-file-types-files-and-folders.md) +- [What does USMT migrate?](usmt-what-does-usmt-migrate.md). +- [Identify file types, files, and folders](usmt-identify-file-types-files-and-folders.md). diff --git a/windows/deployment/usmt/usmt-migrate-user-accounts.md b/windows/deployment/usmt/usmt-migrate-user-accounts.md index d4ecef51aa..792d49e9b4 100644 --- a/windows/deployment/usmt/usmt-migrate-user-accounts.md +++ b/windows/deployment/usmt/usmt-migrate-user-accounts.md @@ -1,18 +1,21 @@ --- -title: Migrate User Accounts (Windows 10) +title: Migrate User Accounts description: Learn how to migrate user accounts and how to specify which users to include and exclude by using the User options on the command line. manager: aaroncz ms.author: frankroj ms.prod: windows-client author: frankroj -ms.date: 11/01/2022 +ms.date: 01/03/2024 ms.topic: article ms.technology: itpro-deploy +appliesto: + - ✅ Windows 11 + - ✅ Windows 10 --- # Migrate User Accounts -By default, all users are migrated. The only way to specify which users to include and exclude is on the command line by using the User options. You can't specify users in the migration XML files or by using the `Config.xml` file. +By default, all users are migrated. The only way to specify which users to include and exclude is on the command line by using the [ScanState User options](usmt-scanstate-syntax.md#user-options) and the [LoadState User options](usmt-loadstate-syntax.md#user-options). Users can't be specified in the migration XML files or by using the `Config.xml` file. ## To migrate all user accounts and user settings @@ -20,30 +23,31 @@ Links to detailed explanations of commands are available in the [Related article 1. Sign into the source computer as an administrator. -2. Enter the following `ScanState.exe` command line in a command prompt window: +1. Enter the following `ScanState.exe` command line in a command prompt window: ```cmd ScanState.exe \\server\share\migration\mystore /i:MigDocs.xml /i:MigApp.xml /o ```` -3. Sign into the destination computer as an administrator. +1. Sign into the destination computer as an administrator. -4. Enter one of the following `LoadState.exe ` command lines in a command prompt window: +1. Enter one of the following `LoadState.exe` command lines in a command prompt window: - - If you're migrating domain accounts, enter: + - If migrating domain accounts, enter: ```cmd LoadState.exe \\server\share\migration\mystore /i:MigDocs.xml /i:MigApp.xml ``` - - If you're migrating local accounts along with domain accounts, enter: + - If migrating local accounts along with domain accounts, enter: ```cmd LoadState.exe \\server\share\migration\mystore /i:MigDocs.xml /i:MigApp.xml /lac /lae ``` > [!NOTE] - > You do not have to specify the `/lae` option, which enables the account that was created with the `/lac` option. Instead, you can create a disabled local account by specifying only the `/lac` option, and then a local administrator needs to enable the account on the destination computer. + > + > The `/lae` option doesn't need to be specified, which enables the account that was created with the `/lac` option. Instead, create a disabled local account by specifying only the `/lac` option, and then a local administrator needs to enable the account on the destination computer. ## To migrate two domain accounts (User1 and User2) @@ -51,15 +55,15 @@ Links to detailed explanations of commands are available in the [Related article 1. Sign into the source computer as an administrator. -2. Enter the following `ScanState.exe` command line in a command prompt window: +1. Enter the following `ScanState.exe` command line in a command prompt window: ```cmd ScanState.exe \\server\share\migration\mystore /ue:*\* /ui:contoso\user1 /ui:fabrikam\user2 /i:MigDocs.xml /i:MigApp.xml /o ``` -3. Sign into the destination computer as an administrator. +1. Sign into the destination computer as an administrator. -4. Enter the following `LoadState.exe ` command line in a command prompt window: +1. Enter the following `LoadState.exe` command line in a command prompt window: ```cmd LoadState.exe \\server\share\migration\mystore /i:MigDocs.xml /i:MigApp.xml @@ -71,15 +75,15 @@ Links to detailed explanations of commands are available in the [Related article 1. Sign into the source computer as an administrator. -2. Enter the following `ScanState.exe` command line in a command prompt window: +1. Enter the following `ScanState.exe` command line in a command prompt window: ```cmd ScanState.exe \\server\share\migration\mystore /ue:*\* /ui:contoso\user1 /ui:contoso\user2 /i:MigDocs.xml /i:MigApp.xml /o ``` -3. Sign into the destination computer as an administrator. +1. Sign into the destination computer as an administrator. -4. Enter the following `LoadState.exe ` command line in a command prompt window: +1. Enter the following `LoadState.exe` command line in a command prompt window: ```cmd LoadState.exe \\server\share\migration\mystore /mu:contoso\user1:fabrikam\user1 /mu:contoso\user2:fabrikam\user2 /i:MigDocs.xml /i:MigApp.xml @@ -87,8 +91,6 @@ Links to detailed explanations of commands are available in the [Related article ## Related articles -[Identify users](usmt-identify-users.md) - -[ScanState syntax](usmt-scanstate-syntax.md) - -[LoadState syntax](usmt-loadstate-syntax.md) +- [Identify users](usmt-identify-users.md). +- [ScanState syntax](usmt-scanstate-syntax.md). +- [LoadState syntax](usmt-loadstate-syntax.md). diff --git a/windows/deployment/usmt/usmt-migration-store-encryption.md b/windows/deployment/usmt/usmt-migration-store-encryption.md index f136ae0f31..b79eec1a7c 100644 --- a/windows/deployment/usmt/usmt-migration-store-encryption.md +++ b/windows/deployment/usmt/usmt-migration-store-encryption.md @@ -1,5 +1,5 @@ --- -title: Migration Store Encryption (Windows 10) +title: Migration Store Encryption description: Learn how the User State Migration Tool (USMT) enables support for stronger encryption algorithms, called Advanced Encryption Standard (AES). manager: aaroncz ms.author: frankroj @@ -8,17 +8,20 @@ author: frankroj ms.date: 11/01/2022 ms.topic: article ms.technology: itpro-deploy +appliesto: + - ✅ Windows 11 + - ✅ Windows 10 --- # Migration store encryption -This article discusses User State Migration Tool (USMT) 10.0 options for migration store encryption to protect the integrity of user data during a migration. +This article discusses User State Migration Tool (USMT) options for migration store encryption to protect the integrity of user data during a migration. ## USMT encryption options USMT enables support for stronger encryption algorithms, called Advanced Encryption Standard (AES), in several bit-level options. AES is a National Institute of Standards and Technology (NIST) specification for the encryption of electronic data. -The encryption algorithm you choose must be specified for both the `ScanState.exe` and the `LoadState.exe` commands, so that these commands can create or read the store during encryption and decryption. The new encryption algorithms can be specified on the `ScanState.exe` and the `LoadState.exe` command lines by using the `/encrypt`:*encryptionstrength* and the `/decrypt`:*encryptionstrength* command-line options. All of the encryption application programming interfaces (APIs) used by USMT are available in Windows 7, Windows 8, and Windows 10 operating systems. However, export restrictions might limit the set of algorithms that are available to computers in certain locales. You can use the `UsmtUtils.exe` file to determine which encryption algorithms are available to the computers' locales before you begin the migration. +The chosen encryption algorithm must be specified for both the `ScanState.exe` and the `LoadState.exe` commands, so that these commands can create or read the store during encryption and decryption. The new encryption algorithms can be specified on the `ScanState.exe` and the `LoadState.exe` command lines by using the `/encrypt`:*encryption_strength* and the `/decrypt`:*encryption_strength* command-line options. All of the encryption application programming interfaces (APIs) used by USMT are available in currently supported versions of Windows. However, export restrictions might limit the set of algorithms that are available to computers in certain locales. The `UsmtUtils.exe` file can be used to determine which encryption algorithms are available to the computers' locales before the migration begins. The following table describes the command-line encryption options in USMT. @@ -28,8 +31,9 @@ The following table describes the command-line encryption options in USMT. |*LoadState*|**/decrypt**<*AES, AES_128, AES_192, AES_256, 3DES, 3DES_112*>|This option and argument specify that the store must be decrypted and which algorithm to use. When the algorithm argument isn't provided, the **LoadState** tool employs the **3DES** algorithm.| > [!IMPORTANT] -> Some encryption algorithms may not be available on your systems. You can verify which algorithms are available by running the `UsmtUtils.exe` command with the `/ec` option. For more information, see [UsmtUtils syntax](usmt-utilities.md). +> +> Some encryption algorithms might not be available on some systems. Which algorithms are available can be verified by running the `UsmtUtils.exe` command with the `/ec` option. For more information, see [UsmtUtils syntax](usmt-utilities.md). ## 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-overview.md b/windows/deployment/usmt/usmt-overview.md index dae39a70bd..75b410826c 100644 --- a/windows/deployment/usmt/usmt-overview.md +++ b/windows/deployment/usmt/usmt-overview.md @@ -1,27 +1,32 @@ --- title: User State Migration Tool (USMT) overview -description: Learn about using User State Migration Tool (USMT) 10.0 to streamline and simplify user state migration during large deployments of Windows operating systems. +description: Learn about using User State Migration Tool (USMT) to streamline and simplify user state migration during large deployments of Windows operating systems. ms.prod: windows-client ms.technology: itpro-deploy author: frankroj manager: aaroncz ms.author: frankroj -ms.date: 11/01/2022 +ms.date: 01/03/2024 ms.topic: overview ms.collection: - highpri - tier2 +appliesto: + - ✅ Windows 11 + - ✅ Windows 10 --- # User State Migration Tool (USMT) overview -You can use User State Migration Tool (USMT) 10.0 to streamline and simplify user state migration during large deployments of Windows operating systems. USMT captures user accounts, user files, operating system settings, and application settings, and then migrates them to a new Windows installation. You can use USMT for both PC replacement and PC refresh migrations. For more information, see [Common migration scenarios](usmt-common-migration-scenarios.md). +The User State Migration Tool (USMT) can be used to streamline and simplify user state migration during large deployments of Windows operating systems. USMT captures user accounts, user files, operating system settings, and application settings, and then migrates them to a new Windows installation. USMT can be used for both PC replacement and PC refresh migrations. For more information, see [Common migration scenarios](usmt-common-migration-scenarios.md). -USMT enables you to do the following actions: +USMT enables the following actions: -- Configure your migration according to your business needs by using the migration rule (.xml) files to control exactly which files and settings are migrated and how they're migrated. For more information about how to modify these files, see [USMT XML reference](usmt-xml-reference.md). -- Fit your customized migration into your automated deployment process by using the **ScanState** and **LoadState** tools, which control collecting and restoring the user files and settings. For more information, see [User State Migration Tool (USMT) command-line syntax](usmt-command-line-syntax.md). -- Perform offline migrations. You can run migrations offline by using the ScanState command in Windows Preinstallation Environment (WinPE) or you can perform migrations from previous installations of Windows contained in Windows.old directories. For more information about migration types, see [Choose a migration store Type](usmt-choose-migration-store-type.md) and [Offline migration reference](offline-migration-reference.md). +- Configure the migration according to the organization's business needs by using the migration rule (.xml) files to control exactly which files and settings are migrated and how they're migrated. For more information about how to modify these files, see [USMT XML reference](usmt-xml-reference.md). + +- Fit the customized migration into the automated deployment process by using the **ScanState** and **LoadState** tools, which control collecting and restoring the user files and settings. For more information, see [User State Migration Tool (USMT) command-line syntax](usmt-command-line-syntax.md). + +- Perform offline migrations. Migrations can be run offline by using the **ScanState** command in Windows Preinstallation Environment (WinPE) or migrations can be performed from previous installations of Windows contained in **Windows.old** directories. For more information about migration types, see [Choose a migration store Type](usmt-choose-migration-store-type.md) and [Offline migration reference](offline-migration-reference.md). ## Benefits @@ -36,7 +41,7 @@ USMT provides the following benefits to businesses that are deploying Windows op ## Limitations -USMT is intended for administrators who are performing large-scale automated deployments. If you're only migrating the user states of a few computers, you can use [PCmover Express](https://go.microsoft.com/fwlink/?linkid=620915). PCmover isn't a free utility. PCmover Express is a tool created by Microsoft's partner, Laplink. +USMT is intended for administrators who are performing large-scale automated deployments. If the user states of only a few computers are being migrated, [PCmover Express](https://go.microsoft.com/fwlink/?linkid=620915) can be used. PCmover isn't a free utility. PCmover Express is a tool created by Microsoft's partner, Laplink. There are some scenarios in which the use of USMT isn't recommended. These scenarios include: @@ -45,4 +50,4 @@ There are some scenarios in which the use of USMT isn't recommended. These scena ## Related articles -- [User State Migration Tool (USMT) technical reference](usmt-technical-reference.md) +- [User State Migration Tool (USMT) technical reference](usmt-technical-reference.md). diff --git a/windows/deployment/usmt/usmt-plan-your-migration.md b/windows/deployment/usmt/usmt-plan-your-migration.md index e7f255af34..7b3d61b533 100644 --- a/windows/deployment/usmt/usmt-plan-your-migration.md +++ b/windows/deployment/usmt/usmt-plan-your-migration.md @@ -1,33 +1,36 @@ --- -title: Plan Your Migration (Windows 10) -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: 11/01/2022 +ms.date: 01/03/2024 ms.topic: article ms.technology: itpro-deploy +appliesto: + - ✅ Windows 11 + - ✅ Windows 10 --- -# Plan your migration +# Plan the migration -Before you use the User State Migration Tool (USMT) 10.0 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 may 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 may be more comprehensive than the restoration data for backup purposes, restoring data or settings for applications that you won't install 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 | Link | Description | |--- |--- | -|[Common migration scenarios](usmt-common-migration-scenarios.md)|Determine whether you'll perform a refresh migration or a replace migration.| +|[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 -[USMT XML reference](usmt-xml-reference.md) +- [USMT XML reference](usmt-xml-reference.md). diff --git a/windows/deployment/usmt/usmt-recognized-environment-variables.md b/windows/deployment/usmt/usmt-recognized-environment-variables.md index 7e377402d1..c939a9179d 100644 --- a/windows/deployment/usmt/usmt-recognized-environment-variables.md +++ b/windows/deployment/usmt/usmt-recognized-environment-variables.md @@ -1,25 +1,28 @@ --- title: Recognized environment variables -description: Learn how to use environment variables to identify folders that may be different on different computers. +description: Learn how to use environment variables to identify folders that can be different on different computers. ms.prod: windows-client ms.technology: itpro-deploy manager: aaroncz ms.author: frankroj author: frankroj -ms.date: 11/01/2022 +ms.date: 01/03/2024 ms.topic: conceptual ms.collection: - highpri - tier2 +appliesto: + - ✅ Windows 11 + - ✅ Windows 10 --- # Recognized environment variables -When using the XML files `MigDocs.xml`, `MigApp.xml`, and `MigUser.xml`, you can use environment variables to identify folders that may be different on different computers. Constant special item ID list (CSIDL) values provide a way to identify folders that applications use frequently but may not have the same name or location on any given computer. For example, the **Documents** folder may be `C:\Users\\My Documents` on one computer and `C:\Documents and Settings\\My Documents` on another. You can use the asterisk (\*) wildcard character in `MigUser.xml`, `MigApp.xml` and `MigDoc.xml` files. However, you can't use the asterisk (\*) wildcard characters in the `Config.xml` file. +When the XML files `MigDocs.xml`, `MigApp.xml`, and `MigUser.xml` are used, the environment variables can be used to identify folders that can be different on different computers. Constant special item ID list (CSIDL) values provide a way to identify folders that applications use frequently but could have different names or locations on any given computer. For example, the **Documents** folder could be `C:\Users\\Documents` on one computer and `C:\Users\\My Documents` on another. The asterisk (\*) wildcard character can be used in the `MigUser.xml`, `MigApp.xml` and `MigDoc.xml` files. However, the asterisk (\*) wildcard character can't be used in the `Config.xml` file. ## Variables that are processed for the operating system and in the context of each user -You can use these variables within sections in the .xml files with `context=UserAndSystem`, `context=User`, and `context=System`. +These variables can be used within sections in the **.xml** files with `context=UserAndSystem`, `context=User`, and `context=System`. |Variable|Explanation| |--- |--- | @@ -40,8 +43,8 @@ You can use these variables within sections in the .xml files with `context=User |*CSIDL_COMMON_STARTUP*|The file-system directory that contains the programs that appear in the Startup folder for all users. A typical path is `C:\ProgramData\Microsoft\Windows\Start Menu\Programs\Startup`.| |*CSIDL_COMMON_TEMPLATES*|The file-system directory that contains the templates that are available to all users. A typical path is `C:\ProgramData\Microsoft\Windows\Templates`.| |*CSIDL_COMMON_VIDEO*|The file-system directory that serves as a repository for video files common to all users. A typical path is `C:\Users\Public\Videos`.| -|*CSIDL_DEFAULT_APPDATA*|Refers to the Appdata folder inside `%DEFAULTUSERPROFILE%`.| -|C*SIDL_DEFAULT_LOCAL_APPDATA*|Refers to the local Appdata folder inside `%DEFAULTUSERPROFILE%`.| +|*CSIDL_DEFAULT_APPDATA*|Refers to the `Appdata` folder inside `%DEFAULTUSERPROFILE%`.| +|C*SIDL_DEFAULT_LOCAL_APPDATA*|Refers to the local `Appdata` folder inside `%DEFAULTUSERPROFILE%`.| |*CSIDL_DEFAULT_COOKIES*|Refers to the Cookies folder inside `%DEFAULTUSERPROFILE%`.| |*CSIDL_DEFAULT_CONTACTS*|Refers to the Contacts folder inside `%DEFAULTUSERPROFILE%`.| |*CSIDL_DEFAULT_DESKTOP*|Refers to the Desktop folder inside `%DEFAULTUSERPROFILE%`.| @@ -50,10 +53,10 @@ You can use these variables within sections in the .xml files with `context=User |*CSIDL_DEFAULT_HISTORY*|Refers to the History folder inside `%DEFAULTUSERPROFILE%`.| |*CSIDL_DEFAULT_INTERNET_CACHE*|Refers to the Internet Cache folder inside `%DEFAULTUSERPROFILE%`.| |*CSIDL_DEFAULT_PERSONAL*|Refers to the Personal folder inside `%DEFAULTUSERPROFILE%`.| -|*CSIDL_DEFAULT_MYDOCUMENTS*|Refers to the My Documents folder inside `%DEFAULTUSERPROFILE%`.| -|*CSIDL_DEFAULT_MYPICTURES*|Refers to the My Pictures folder inside `%DEFAULTUSERPROFILE%`.| -|*CSIDL_DEFAULT_MYMUSIC*|Refers to the My Music folder inside `%DEFAULTUSERPROFILE%`.| -|*CSIDL_DEFAULT_MYVIDEO*|Refers to the My Videos folder inside `%DEFAULTUSERPROFILE%`.| +|*CSIDL_DEFAULT_MYDOCUMENTS*|Refers to the Documents folder inside `%DEFAULTUSERPROFILE%`.| +|*CSIDL_DEFAULT_MYPICTURES*|Refers to the Pictures folder inside `%DEFAULTUSERPROFILE%`.| +|*CSIDL_DEFAULT_MYMUSIC*|Refers to the Music folder inside `%DEFAULTUSERPROFILE%`.| +|*CSIDL_DEFAULT_MYVIDEO*|Refers to the Videos folder inside `%DEFAULTUSERPROFILE%`.| |*CSIDL_DEFAULT_RECENT*|Refers to the Recent folder inside `%DEFAULTUSERPROFILE%`.| |*CSIDL_DEFAULT_SENDTO*|Refers to the Send To folder inside `%DEFAULTUSERPROFILE%`.| |*CSIDL_DEFAULT_STARTMENU*|Refers to the Start Menu folder inside `%DEFAULTUSERPROFILE%`.| @@ -83,12 +86,12 @@ You can use these variables within sections in the .xml files with `context=User ## Variables that are recognized only in the user context -You can use these variables in the .xml files within sections with `context=User` and `context=UserAndSystem`. +These variables can be used in the **.xml** files within sections with `context=User` and `context=UserAndSystem`. |Variable|Explanation| |--- |--- | |*APPDATA*|Same as **CSIDL_APPDATA**.| -|*CSIDL_ADMINTOOLS*|The file-system directory that is used to store administrative tools for an individual user. The Microsoft® Management Console (MMC) saves customized consoles to this directory, which roams with the user profile.| +|*CSIDL_ADMINTOOLS*|The file-system directory that is used to store administrative tools for an individual user. The Microsoft Management Console (MMC) saves customized consoles to this directory, which roams with the user profile.| |*CSIDL_ALTSTARTUP*|The file-system directory that corresponds to the user's non-localized Startup program group.| |*CSIDL_APPDATA*|The file-system directory that serves as a common repository for application-specific data. A typical path is `C:\Users\\AppData\Roaming`.| |*CSIDL_BITBUCKET*|The virtual folder that contains the objects in the user's Recycle Bin.| @@ -99,20 +102,20 @@ You can use these variables in the .xml files within sections with `context=User |*CSIDL_COOKIES*|The file-system directory that serves as a common repository for Internet cookies. A typical path is `C:\Users\\AppData\Roaming\Microsoft\Windows\Cookies`.| |*CSIDL_DESKTOP*|The virtual folder representing the Windows desktop.| |*CSIDL_DESKTOPDIRECTORY*|The file-system directory used to physically store file objects on the desktop, which shouldn't be confused with the desktop folder itself. A typical path is `C:\Users\\Desktop`.| -|*CSIDL_DRIVES*|The virtual folder representing My Computer that contains everything on the local computer: storage devices, printers, and Control Panel. The folder may also contain mapped network drives.| +|*CSIDL_DRIVES*|The virtual folder representing **This PC** that contains everything on the local computer: storage devices, printers, and Control Panel. The folder could also contain mapped network drives.| |*CSIDL_FAVORITES*|The file-system directory that serves as a common repository for the user's favorites. A typical path is `C:\Users\\Favorites`.| |*CSIDL_HISTORY*|The file-system directory that serves as a common repository for Internet history items.| |*CSIDL_INTERNET*|A virtual folder for Internet Explorer.| |*CSIDL_INTERNET_CACHE*|The file-system directory that serves as a common repository for temporary Internet files. A typical path is `C:\Users\\AppData\Local\Microsoft\Windows\Temporary Internet Files`| |*CSIDL_LOCAL_APPDATA*|The file-system directory that serves as a data repository for local, non-roaming applications. A typical path is `C:\Users\\AppData\Local`.| -|*CSIDL_MYDOCUMENTS*|The virtual folder representing My Documents.A typical path is `C:\Users\\Documents`.| +|*CSIDL_MYDOCUMENTS*|The virtual folder representing the **Documents** folder.A typical path is `C:\Users\\Documents`.| |*CSIDL_MYMUSIC*|The file-system directory that serves as a common repository for music files. A typical path is `C:\Users\\Music`.| |*CSIDL_MYPICTURES*|The file-system directory that serves as a common repository for image files. A typical path is `C:\Users\\Pictures`.| |*CSIDL_MYVIDEO*|The file-system directory that serves as a common repository for video files. A typical path is `C:\Users\\Videos`.| -|*CSIDL_NETHOOD*|A file-system directory that contains the link objects that may exist in the My Network Places virtual folder. It isn't the same as *CSIDL_NETWORK*, which represents the network namespace root. A typical path is `C:\Users\\AppData\Roaming\Microsoft\Windows\Network Shortcuts`.| -|*CSIDL_NETWORK*|A virtual folder representing My Network Places, the root of the network namespace hierarchy.| -|*CSIDL_PERSONAL*|The virtual folder representing the My Documents desktop item. This value is equivalent to **CSIDL_MYDOCUMENTS**. A typical path is `C:\Documents and Settings\\My Documents`.| -|*CSIDL_PLAYLISTS*|The virtual folder used to store play albums, typically `C:\Users\\My Music\Playlists`.| +|*CSIDL_NETHOOD*|A file-system directory that contains the link objects that could exist in the **Network** virtual folder. It isn't the same as *CSIDL_NETWORK*, which represents the network namespace root. A typical path is `C:\Users\\AppData\Roaming\Microsoft\Windows\Network Shortcuts`.| +|*CSIDL_NETWORK*|A virtual folder representing the **Network** desktop item, the root of the network namespace hierarchy.| +|*CSIDL_PERSONAL*|The virtual folder representing the **\** desktop item. This value is equivalent to **CSIDL_MYDOCUMENTS**. A typical path is `C:\User\\Documents`.| +|*CSIDL_PLAYLISTS*|The virtual folder used to store play albums, typically `C:\Users\\Music\Playlists`.| |*CSIDL_PRINTERS*|The virtual folder that contains installed printers.| |*CSIDL_PRINTHOOD*|The file-system directory that contains the link objects that can exist in the Printers virtual folder. A typical path is `C:\Users\\AppData\Roaming\Microsoft\Windows\Printer Shortcuts`.| |*CSIDL_PROFILE*|The user's profile folder. A typical path is `C:\Users\`.| diff --git a/windows/deployment/usmt/usmt-reference.md b/windows/deployment/usmt/usmt-reference.md index fdf20145f0..1dae5a4d13 100644 --- a/windows/deployment/usmt/usmt-reference.md +++ b/windows/deployment/usmt/usmt-reference.md @@ -1,13 +1,16 @@ --- -title: User State Migration Toolkit (USMT) Reference (Windows 10) +title: User State Migration Toolkit (USMT) Reference description: Use this User State Migration Toolkit (USMT) article to learn details about USMT, like operating system, hardware, and software requirements, and user prerequisites. manager: aaroncz ms.author: frankroj ms.prod: windows-client author: frankroj -ms.date: 11/01/2022 +ms.date: 01/03/2024 ms.topic: article ms.technology: itpro-deploy +appliesto: + - ✅ Windows 11 + - ✅ Windows 10 --- # User State Migration Toolkit (USMT) reference @@ -18,16 +21,14 @@ ms.technology: itpro-deploy |--- |--- | |[USMT requirements](usmt-requirements.md)|Describes operating system, hardware, and software requirements, and user prerequisites.| |[USMT best practices](usmt-best-practices.md)|Discusses general and security-related best practices when using USMT.| -|[How USMT works](usmt-how-it-works.md)|Learn about the processes behind the ScanState and LoadState tools.| -|[Plan your migration](usmt-plan-your-migration.md)|Choose what to migrate and the best migration scenario for your enterprise.| +|[How USMT works](usmt-how-it-works.md)|Learn about the processes behind the **ScanState** and **LoadState** tools.| +|[Plan the migration](usmt-plan-your-migration.md)|Choose what to migrate and the best migration scenario for the organization.| |[User State Migration Tool (USMT) command-line syntax](usmt-command-line-syntax.md)|Explore command-line options for the ScanState, LoadState, and UsmtUtils tools.| |[USMT XML reference](usmt-xml-reference.md)|Learn about customizing a migration with XML files.| |[Offline Migration reference](offline-migration-reference.md)|Find requirements, best practices, and other considerations for performing a migration offline.| ## Related articles -[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 Tool (USMT) troubleshooting](usmt-troubleshooting.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 Tool (USMT) troubleshooting](usmt-troubleshooting.md). diff --git a/windows/deployment/usmt/usmt-requirements.md b/windows/deployment/usmt/usmt-requirements.md index 87a290ad93..fc7b587b94 100644 --- a/windows/deployment/usmt/usmt-requirements.md +++ b/windows/deployment/usmt/usmt-requirements.md @@ -1,59 +1,69 @@ --- -title: USMT Requirements (Windows 10) +title: USMT Requirements description: While the User State Migration Tool (USMT) doesn't have many requirements, these tips and tricks can help smooth the migration process. manager: aaroncz ms.author: frankroj ms.prod: windows-client author: frankroj -ms.date: 11/01/2022 +ms.date: 01/03/2024 ms.topic: article ms.technology: itpro-deploy +appliesto: + - ✅ Windows 11 + - ✅ Windows 10 --- # USMT requirements ## Supported operating systems -The User State Migration Tool (USMT) 10.0 doesn't have any explicit RAM or CPU speed requirements for either the source or destination computers. If your computer complies with the system requirements of the operating system, it also complies with the requirements for USMT. You need an intermediate store location large enough to hold all of the migrated data and settings, and the same amount of hard disk space on the destination computer for the migrated files and settings. +The User State Migration Tool (USMT) doesn't have any explicit RAM or CPU speed requirements for either the source or destination computers. If the computer complies with the system requirements of the operating system, it also complies with the requirements for USMT. An intermediate store location large enough to hold all of the migrated data and settings is needed. The same amount of hard disk space is also needed on the destination computer for the migrated files and settings. The following table lists the operating systems supported in USMT. -|Operating Systems|ScanState (source computer)|LoadState (destination computer)| +| Operating
Systems | ScanState
(Source
Device)| LoadState
(Destination
Device)| |--- |--- |--- | -|32-bit versions of Windows 7|✔️|✔️| -|64-bit versions of Windows 7|✔️|✔️| -|32-bit versions of Windows 8|✔️|✔️| -|64-bit versions of Windows 8|✔️|✔️| -|32-bit versions of Windows 10|✔️|✔️| -|64-bit versions of Windows 10|✔️|✔️| +|Windows 7|✔️|❌| +|Windows 8|✔️|❌| +|Windows 10|✔️|✔️| +|Windows 11|✔️|✔️| > [!NOTE] -> You can migrate a 32-bit operating system to a 64-bit operating system. However, you cannot migrate a 64-bit operating system to a 32-bit operating system. +> +> - 32-bit operating system can be migrated to a 64-bit operating system. However, a 64-bit operating system can't be migrated to a 32-bit operating system. +> +> - Gathering data from a source device using **ScanState** for a version of Windows that is out of support is supported. However, restoring data to a destination device using **LoadState** to a version of Windows that is out of support isn't supported. ## Unsupported scenarios -- USMT doesn't support any of the Windows Server® operating systems. -- USMT for Windows 10 shouldn't be used for migrating between previous versions of Windows. USMT for Windows 10 is only meant to migrate to Windows 10 or between Windows 10 versions. For more information about previous releases of the USMT tools, see [User State Migration Tool (USMT) overview](/previous-versions/windows/hh825227(v=win.10)). +- USMT doesn't support any of the Windows Server operating systems. +- USMT shouldn't be used for migrating between previous versions of Windows. USMT is only meant to: + - Migrate to a currently supported version of Windows + - Migrate between currently supported versions of Windows, assuming the version of Windows being migrated to is newer or the same as the previous version of Windows being migrated from. + +For more information about previous releases of the USMT tools, see [User State Migration Tool (USMT) overview](/previous-versions/windows/hh825227(v=win.10)). ## Windows PE -- **Must use latest version of Windows PE.** For example, to migrate to Windows 10, you'll need Windows PE 5.1. For more info, see [What's New in Windows PE](/windows-hardware/manufacture/desktop/whats-new-in-windows-pe-s14). +- **Must use latest version of Windows PE.** For more info, see [What's New in Windows PE](/windows-hardware/manufacture/desktop/whats-new-in-windows-pe-s14). ## Credentials -- **Run as administrator** - When manually running the **ScanState** and **LoadState** tools on Windows 7, Windows 8, or Windows 10 you must run them from an elevated command prompt to ensure that all specified users are migrated. If you don't run USMT from an elevated prompt, only the user profile that is logged on will be included in the migration. +- **Run as administrator.** + + When the **ScanState** and **LoadState** tools are run, they must be run from an elevated command prompt to ensure that all specified users are migrated. If USMT isn't run from an elevated prompt, only the user profile that is logged on is included in the migration. To open an elevated command prompt: 1. Select **Start**. -2. Enter `cmd` in the search function. -3. Depending on the OS you're using, **cmd** or **Command Prompt** is displayed. -4. Right-click **cmd** or **Command Prompt**, and then select **Run as administrator**. -5. If the current user isn't already an administrator, you'll be prompted to enter administrator credentials. +1. Enter `cmd` in the search function. +1. **cmd** or **Command Prompt** is displayed. +1. Right-click **cmd** or **Command Prompt**, and then select **Run as administrator**. +1. If the current user isn't already an administrator, it prompts to enter administrator credentials. > [!IMPORTANT] -> You must run USMT using an account with full administrative permissions, including the following privileges: +> +> USMT must run using an account with full administrative permissions, including the following privileges: > > - SeBackupPrivilege (Back up files and directories) > - SeDebugPrivilege (Debug programs) @@ -63,9 +73,9 @@ To open an elevated command prompt: ## Config.xml -### Specify the `/c` option and <ErrorControl> settings in the `Config.xml` file +### Specify the `/c` option and \ settings in the `Config.xml` file -USMT will fail if it can't migrate a file or setting, unless you specify the `/c` option. When you specify the `/c` option, USMT logs an error each time it encounters a file that is in use that didn't migrate, but the migration won't be interrupted. In USMT, you can specify in the `Config.xml` file, which types of errors should allow the migration to continue, and which should cause the migration to fail. For more information about error reporting, and the **<ErrorControl>** element, see [Config.xml file](usmt-configxml-file.md#errorcontrol), [Log files](usmt-log-files.md), and [XML elements library](usmt-xml-elements-library.md). +USMT fails if it can't migrate a file or setting, unless the `/c` option is specified. When the `/c` option is specified, USMT logs an error each time it encounters a file that is in use that didn't migrate, but the migration isn't be interrupted. In USMT, which types of errors should allow the migration to continue and which should cause the migration to fail can be specified in the `Config.xml` file. For more information about error reporting, and the **\** element, see [Config.xml file](usmt-configxml-file.md#errorcontrol), [Log files](usmt-log-files.md), and [XML elements library](usmt-xml-elements-library.md). ## LoadState @@ -88,6 +98,6 @@ This documentation assumes that IT professionals using USMT understand command-l ## Related articles -- [Plan your migration](usmt-plan-your-migration.md) -- [Estimate migration store size](usmt-estimate-migration-store-size.md) -- [User State Migration Tool (USMT) overview topics](usmt-topics.md) +- [Plan the migration](usmt-plan-your-migration.md). +- [Estimate migration store size](usmt-estimate-migration-store-size.md). +- [User State Migration Tool (USMT) overview articles](usmt-topics.md). diff --git a/windows/deployment/usmt/usmt-reroute-files-and-settings.md b/windows/deployment/usmt/usmt-reroute-files-and-settings.md index 8edfb43a05..99851aed2d 100644 --- a/windows/deployment/usmt/usmt-reroute-files-and-settings.md +++ b/windows/deployment/usmt/usmt-reroute-files-and-settings.md @@ -1,22 +1,25 @@ --- -title: Reroute Files and Settings (Windows 10) +title: Reroute Files and Settings description: Learn how to create a custom .xml file and specify this file name on both the ScanState and LoadState command lines to reroute files and settings. manager: aaroncz ms.author: frankroj ms.prod: windows-client author: frankroj -ms.date: 11/01/2022 +ms.date: 01/03/2024 ms.topic: article ms.technology: itpro-deploy +appliesto: + - ✅ Windows 11 + - ✅ Windows 10 --- # Reroute Files and Settings -To reroute files and settings, create a custom .xml file and specify the .xml file name on both the `ScanState.exe` and `LoadState.exe` command-lines. Th custom .xml file enables you to keep your changes separate from the default .xml files, so that it's easier to track your modifications. +To reroute files and settings, create a custom **.xml** file and specify the **.xml** file name on both the `ScanState.exe` and `LoadState.exe` command-lines. The custom **.xml** file enables keeping changes separate from the default **.xml** files, so that it's easier to track modifications. ## Reroute a folder -The following custom .xml file migrates the directories and files from `C:\EngineeringDrafts` into the **My Documents** folder of every user. **%CSIDL_PERSONAL%** is the virtual folder representing the **My Documents** desktop item, which is equivalent to **CSIDL_MYDOCUMENTS**. +The following custom **.xml** file migrates the directories and files from `C:\EngineeringDrafts` into the **Documents** folder of every user. **%CSIDL_PERSONAL%** is the virtual folder representing the **\** desktop item, which is equivalent to **CSIDL_MYDOCUMENTS**. ```xml @@ -44,12 +47,12 @@ The following custom .xml file migrates the directories and files from `C:\Engin ## Reroute a specific file type -The following custom .xml file reroutes .mp3 files located in the fixed drives on the source computer into the `C:\Music` folder on the destination computer. +The following custom **.xml** file reroutes **.mp3** files located in the fixed drives on the source computer into the `C:\Music` folder on the destination computer. ```xml - All .mp3 files to My Documents + All .mp3 files to the Documents folder @@ -71,12 +74,12 @@ The following custom .xml file reroutes .mp3 files located in the fixed drives o ## Reroute a specific file -The following custom .xml file migrates the `Sample.doc` file from `C:\EngineeringDrafts` into the **My Documents** folder of every user. **%CSIDL_PERSONAL%** is the virtual folder representing the **My Documents** desktop item, which is equivalent to **CSIDL_MYDOCUMENTS**. +The following custom **.xml** file migrates the `Sample.doc` file from `C:\EngineeringDrafts` into the **Documents** folder of every user. **%CSIDL_PERSONAL%** is the virtual folder representing the **\** desktop item, which is equivalent to **CSIDL_MYDOCUMENTS**. ```xml -Sample.doc into My Documents +Sample.doc into the Documents folder @@ -97,8 +100,6 @@ The following custom .xml file migrates the `Sample.doc` file from `C:\Engineeri ## Related articles -[Customize USMT XML files](usmt-customize-xml-files.md) - -[Conflicts and precedence](usmt-conflicts-and-precedence.md) - -[USMT XML reference](usmt-xml-reference.md) +- [Customize USMT XML files](usmt-customize-xml-files.md). +- [Conflicts and precedence](usmt-conflicts-and-precedence.md). +- [USMT XML reference](usmt-xml-reference.md). diff --git a/windows/deployment/usmt/usmt-resources.md b/windows/deployment/usmt/usmt-resources.md index 63e2f70b4c..00f4302e74 100644 --- a/windows/deployment/usmt/usmt-resources.md +++ b/windows/deployment/usmt/usmt-resources.md @@ -1,35 +1,38 @@ --- -title: USMT Resources (Windows 10) +title: USMT Resources description: Learn about User State Migration Tool (USMT) online resources, including Microsoft Visual Studio and forums. manager: aaroncz ms.author: frankroj ms.prod: windows-client author: frankroj -ms.date: 11/01/2022 +ms.date: 01/03/2024 ms.topic: article ms.technology: itpro-deploy +appliesto: + - ✅ Windows 11 + - ✅ Windows 10 --- # USMT resources ## USMT online resources -- [ADK Release Notes](/windows-hardware/get-started/what-s-new-in-kits-and-tools) +- [ADK Release Notes](/windows-hardware/get-started/what-s-new-in-kits-and-tools). - Microsoft Visual Studio - - You can use the User State Migration Tool (USMT) XML schema (the `MigXML.xsd` file) to validate the migration .xml files using an XML authoring tool such as Microsoft® Visual Studio®. + - The User State Migration Tool (USMT) XML schema (the `MigXML.xsd` file) can be used to validate the migration **.xml** files using an XML authoring tool such as Microsoft Visual Studio. - For more information about how to use the schema with your XML authoring environment, see the environment's documentation. + For more information about how to use the schema with an XML authoring environment, see the environment's documentation. -- [Ask the Directory Services Team blog](https://techcommunity.microsoft.com/t5/ask-the-directory-services-team/bg-p/AskDS) +- [Ask the Directory Services Team blog](https://techcommunity.microsoft.com/t5/ask-the-directory-services-team/bg-p/AskDS). - Forums: - - [Microsoft Deployment Toolkit forum](/answers/topics/mem-mdt.html) + - [Microsoft Deployment Toolkit forum](/answers/topics/mem-mdt.html). - - [Configuration Manager Operating System Deployment forum](/answers/topics/mem-cm-osd.html) + - [Configuration Manager Operating System Deployment forum](/answers/topics/mem-cm-osd.html). ## Related articles -[User State Migration Tool (USMT) overview topics](usmt-topics.md) +[User State Migration Tool (USMT) overview articles](usmt-topics.md). diff --git a/windows/deployment/usmt/usmt-scanstate-syntax.md b/windows/deployment/usmt/usmt-scanstate-syntax.md index d8ee510c34..25a1b1d5e8 100644 --- a/windows/deployment/usmt/usmt-scanstate-syntax.md +++ b/windows/deployment/usmt/usmt-scanstate-syntax.md @@ -1,6 +1,6 @@ --- -title: ScanState Syntax (Windows 10) -description: The ScanState command is used with the User State Migration Tool (USMT) 10.0 to scan the source computer, collect the files and settings, and create a store. +title: ScanState Syntax +description: The ScanState command is used with the User State Migration Tool (USMT) to scan the source computer, collect the files and settings, and create a store. manager: aaroncz ms.author: frankroj ms.prod: windows-client @@ -8,33 +8,36 @@ author: frankroj ms.date: 11/01/2022 ms.topic: article ms.technology: itpro-deploy +appliesto: + - ✅ Windows 11 + - ✅ Windows 10 --- # ScanState syntax -The `ScanState.exe` command is used with the User State Migration Tool (USMT) 10.0 to scan the source computer, collect the files and settings, and create a store. This article discusses the `ScanState.exe` command syntax and the options available with it. +The `ScanState.exe` command is used with the User State Migration Tool (USMT) to scan the source computer, collect the files and settings, and create a store. This article discusses the `ScanState.exe` command syntax and the options available with it. -## Before you begin +## Before beginning -Before you run the `ScanState.exe` command, note the items: +Before running the `ScanState.exe` command, note the items: -- To ensure that all operating system settings migrate, in most cases you must run the `ScanState.exe` commands in administrator mode from an account with administrative credentials. +- To ensure that all operating system settings migrate, in run the `ScanState.exe` commands in administrator mode from an account with administrative credentials. -- If you encrypt the migration store, you'll be required to enter an encryption key or a path to a file containing the encryption key. Be sure to make note of the key or the key file location, because this information isn't kept anywhere in the migration store. You'll need this information when you run the `LoadState.exe` command to decrypt the migration store, or if you need to run the recovery utility. An incorrect or missing key or key file results in an error message. +- If the migration store is encrypted, an encryption key or a path to a file containing the encryption key is required. Be sure to make note of the key or the key file location, because this information isn't kept anywhere in the migration store. This information is needed when the `LoadState.exe` command is run to decrypt the migration store, or if the recovery utility needs to be used. An incorrect or missing key or key file results in an error message. - For information about software requirements for running the `ScanState.exe` command, see [USMT requirements](usmt-requirements.md). -- Unless otherwise noted, you can use each option only once when running a tool on the command line. +- Unless otherwise noted, use each option only once when running a tool on the command line. -- You can gather domain accounts without the source computer having domain controller access. This functionality is available without any extra configuration. +- Domain accounts can be gathered without the source computer having domain controller access. This functionality is available without any extra configuration. -- The [Incompatible command-line options](#incompatible-command-line-options) table lists which options you can use together and which command-line options are incompatible. +- The [Incompatible command-line options](#incompatible-command-line-options) table lists which options can be used together and which command-line options are incompatible. -- The directory location where you save the migration store will be excluded from the scan. For example, if you save the migration store to the root of the D drive, the D drive and all of its subdirectories will be excluded from the scan. +- The directory location where the migration store is saved is excluded from the scan. For example, if the migration store is saved to the root of the D drive, the D drive and all of its subdirectories is excluded from the scan. ## Syntax -This section explains the syntax and usage of the command-line options available when you use the `ScanState.exe` command. The options can be specified in any order. If the option contains a parameter, you can use either a colon or a space separator. +This section explains the syntax and usage of the command-line options available when using the `ScanState.exe` command. The options can be specified in any order. If the option contains a parameter, either a colon or a space separator can be used. The `ScanState.exe` command's syntax is: @@ -46,7 +49,7 @@ For example, to create a `Config.xml` file in the current directory, use: ScanState.exe /i:MigApp.xml /i:MigDocs.xml /genconfig:Config.xml /v:13 ``` -To create an encrypted store using the `Config.xml` file and the default migration .xml files, use: +To create an encrypted store using the `Config.xml` file and the default migration **.xml** files, use: `ScanState.exe \\server\share\migration\mystore /i:MigApp.xml /i:MigDocs.xml /o /config:Config.xml /v:13 /encrypt /key:"mykey"` @@ -54,94 +57,96 @@ To create an encrypted store using the `Config.xml` file and the default migrati | Command-Line Option | Description | |-----|-----| -| *StorePath* | Indicates a folder where files and settings will be saved. *StorePath* can't be `C:\`. You must specify the *StorePath* option in the `ScanState.exe` command, except when using the `/genconfig` option. You can't specify more than one *StorePath* location. | +| *StorePath* | Indicates a folder where files and settings are saved. *StorePath* can't be `C:\`. The *StorePath* option must be specified in the `ScanState.exe` command, except when using the `/genconfig` option. More than one *StorePath* location can't be specified. | | **/apps** | Scans the image for apps and includes them and their associated registry settings. | -| **/ppkg** [*<FileName>*] | Exports to a specific file location. | -| **/o** | Required to overwrite any existing data in the migration store or `Config.xml` file. If not specified, the `ScanState.exe` command will fail if the migration store already contains data. You can't use this option more than once on a command line. | -| **/vsc** | This option enables the volume shadow-copy service to migrate files that are locked or in use. This command-line option eliminates most file-locking errors that are typically encountered by the **<ErrorControl>** section.

This option is only used with the **ScanState** executable file and can't be combined with the `/hardlink` option. | +| **/ppkg** [*\*] | Exports to a specific file location. | +| **/o** | Required to overwrite any existing data in the migration store or `Config.xml` file. If not specified, the `ScanState.exe` command fails if the migration store already contains data. This option can't be used more than once on a command line. | +| **/vsc** | This option enables the volume shadow-copy service to migrate files that are locked or in use. This command-line option eliminates most file-locking errors that are typically encountered by the **\** section.

This option is only used with the **ScanState** executable file and can't be combined with the `/hardlink` option. | | **/hardlink** | Enables the creation of a hard-link migration store at the specified location. The `/nocompress` option must be specified with the `/hardlink` option. | -| **/encrypt** [{**/key:** *<KeyString>* | **/keyfile**:*<file>*]} | Encrypts the store with the specified key. Encryption is disabled by default. With this option, you'll need to specify the encryption key-in one of the following ways:
  • `/key`: *KeyString* specifies the encryption key. If there's a space in *KeyString*, you'll need to surround *KeyString* with quotation marks (`"`).
  • `/keyfile`: *FilePathAndName* specifies a text (`.txt`) file that contains the encryption key.

*KeyString* is recommended to be at least eight characters long, but it can't exceed 256 characters. The `/key` and `/keyfile` options can't be used on the same command line. The `/encrypt` and `/nocompress` options can't be used on the same command line.
**Important**
Use caution when using the `/key` or `keyfile` options. For example, anyone who has access to scripts that run the `ScanState.exe` command with these options will also have access to the encryption key.

The following example shows the `ScanState.exe` command and the `/key` option:
`ScanState.exe /i:MigDocs.xml /i:MigApp.xml \server\share\migration\mystore /encrypt /key:mykey` | -| **/encrypt**:*<EncryptionStrength>* | The `/encrypt` option accepts a command-line parameter to define the encryption strength to be used for encryption of the migration store. For more information about supported encryption algorithms, see [Migration Store Encryption](usmt-migration-store-encryption.md). | -| **/nocompress** | Disables compression of data and saves the files to a hidden folder named "File" at *StorePath*\USMT. Compression is enabled by default. Combining the `/nocompress` option with the `/hardlink` option generates a hard-link migration store. You can use the uncompressed store to view what USMT stored, troubleshoot a problem, or run an antivirus utility against the files. You should use this option only in testing environments, because we recommend that you use a compressed store during your actual migration, unless you're combining the `/nocompress` option with the `/hardlink` option.

The `/nocompress` and `/encrypt` options can't be used together in one statement on the command line. However, if you do choose to migrate an uncompressed store, the `LoadState.exe` command will migrate each file directly from the store to the correct location on the destination computer without a temporary location.

For example:
`ScanState.exe /i:MigDocs.xml /i:MigApp.xml \server\share\migration\mystore /nocompress` | +| **/encrypt** [{**/key:** *\* | **/keyfile**:*\*]} | Encrypts the store with the specified key. Encryption is disabled by default. With this option, the encryption key needs to be specified in one of the following ways:
  • `/key`: *KeyString* specifies the encryption key. If there's a space in *KeyString*, *KeyString* needs to be surrounded with quotation marks (`"`).
  • `/keyfile`: *FilePathAndName* specifies a text (`.txt`) file that contains the encryption key.

*KeyString* is recommended to be at least eight characters long, but it can't exceed 256 characters. The `/key` and `/keyfile` options can't be used on the same command line. The `/encrypt` and `/nocompress` options can't be used on the same command line.
**Important**
Use caution when using the `/key` or `keyfile` options. For example, anyone who has access to scripts that run the `ScanState.exe` command with these options also have access to the encryption key.

The following example shows the `ScanState.exe` command and the `/key` option:
`ScanState.exe /i:MigDocs.xml /i:MigApp.xml \server\share\migration\mystore /encrypt /key:mykey` | +| **/encrypt**:*\* | The `/encrypt` option accepts a command-line parameter to define the encryption strength to be used for encryption of the migration store. For more information about supported encryption algorithms, see [Migration Store Encryption](usmt-migration-store-encryption.md). | +| **/nocompress** | Disables compression of data and saves the files to a hidden folder named "File" at *StorePath*\USMT. Compression is enabled by default. Combining the `/nocompress` option with the `/hardlink` option generates a hard-link migration store. The uncompressed store can be used to view what USMT stored, troubleshoot a problem, or run an antivirus utility against the files. This option should only be used in testing environments. Microsoft recommends using a compressed store during production migrations, unless combining the `/nocompress` option with the `/hardlink` option.

The `/nocompress` and `/encrypt` options can't be used together in one statement on the command line. However, if an uncompressed store is migrated, the `LoadState.exe` command migrates each file directly from the store to the correct location on the destination computer without a temporary location.

For example:
`ScanState.exe /i:MigDocs.xml /i:MigApp.xml \server\share\migration\mystore /nocompress` | ## Run the ScanState command on an offline Windows system -You can run the `ScanState.exe` command in Windows Preinstallation Environment (WinPE). In addition, USMT supports migrations from previous installations of Windows contained in Windows.old directories. The offline directory can be a Windows directory when you run the `ScanState.exe` command in WinPE or a Windows.old directory when you run the `ScanState.exe` command in Windows. +The `ScanState.exe` command can be run in Windows Preinstallation Environment (WinPE). In addition, USMT supports migrations from previous installations of Windows contained in **Windows.old** directories. The offline directory can be a Windows directory when the `ScanState.exe` command is run in WinPE or a **Windows.old** directory when the `ScanState.exe` command is run in Windows. There are several benefits to running the `ScanState.exe` command on an offline Windows image, including: - **Improved performance.** - Because WinPE is a thin operating system, there are fewer running services. In this environment, the `ScanState.exe` command has more access to the local hardware resources, enabling **ScanState** to perform migration operations more quickly. + Because WinPE is a thin operating system, there are fewer running services. In this environment, the `ScanState.exe` command has more access to the local hardware resources, enabling **ScanState** to perform migration operations more quickly. - **Simplified end to end deployment process.** - Migrating data from Windows.old simplifies the end-to-end deployment process by enabling the migration process to occur after the new operating system is installed. + Migrating data from **Windows.old** simplifies the end-to-end deployment process by enabling the migration process to occur after the new operating system is installed. - **Improved success of migration.** - The migration success rate is increased because files won't be locked for editing while offline, and because WinPE provides administrator access to files in the offline Windows file system, eliminating the need for administrator-level access to the online system. + The migration success rate is increased because: + + - Files aren't locked for editing while offline. + - WinPE provides administrator access to files in the offline Windows file system, eliminating the need for administrator-level access to the online system. -- **Ability to recover an unbootable computer.** +- **Ability to recover an from a computer that doesn't boot.** - It might be possible to recover and migrate data from an unbootable computer. + It might be possible to recover and migrate data from a computer that doesn't boot. ## Offline migration options |Command-Line Option|Definition| |--- |--- | -|**/offline:** *"path to an Offline.xml file"*|This option is used to define a path to an offline .xml file that might specify other offline migration options, for example, an offline Windows directory or any domain or folder redirection required in your migration.| -|**/offlinewindir:** *"path to a Windows directory"*|This option specifies the offline Windows directory that the `ScanState.exe` command gathers user state from. The offline directory can be Windows.old when you run the `ScanState.exe` command in Windows or a Windows directory when you run the `ScanState.exe` command in WinPE.| -|**/offlinewinold:** *"Windows.old directory"*|This command-line option enables the offline migration mode and starts the migration from the location specified. It's only intended to be used in Windows.old migration scenarios, where the migration is occurring from a Windows.old directory.| +|**/offline:** *"path to an Offline.xml file"*|This option is used to define a path to an offline **.xml** file that might specify other offline migration options. For example, an offline Windows directory or any domain or folder redirection required in the migration.| +|**/offlinewindir:** *"path to a Windows directory"*|This option specifies the offline Windows directory that the `ScanState.exe` command gathers user state from. The offline directory can be **Windows.old** when the `ScanState.exe` command is run in Windows or a Windows directory when the `ScanState.exe` command is run in WinPE.| +|**/offlinewinold:** *"Windows.old directory"*|This command-line option enables the offline migration mode and starts the migration from the location specified. This option is only intended to be used in **Windows.old** migration scenarios, where the migration is occurring from a **Windows.old** directory.| ## Migration rule options -USMT provides the following options to specify what files you want to migrate. +USMT provides the following options to specify what files to migrate. | Command-Line Option | Description | |-----|-----| -| **/i:**[*Path*]*FileName* | **(include)**

Specifies an .xml file that contains rules that define what user, application, or system state to migrate. You can specify this option multiple times to include all of your .xml files (`MigApp.xml`, `MigDocs.xml`, and any custom .xml files that you create). *Path* can be either a relative or full path. If you don't specify the *Path* variable, then *FileName* must be located in the current directory. For more information about which files to specify, see the "XML Files" section of the [Frequently asked questions](usmt-faq.yml) article. | -| **/genconfig:**[*Path*]*FileName* | (Generate **Config.xml**)

Generates the optional `Config.xml` file, but doesn't create a migration store. To ensure that this file contains every component, application and setting that can be migrated, you should create this file on a source computer that contains all the components, applications, and settings that will be present on the destination computers. In addition, you should specify the other migration .xml files, using the **/i** option, when you specify this option.

After you create this file, you'll need to make use of it with the `ScanState.exe` command using the **/config** option.

The only options that you can specify with this option are the `/i`, `/v`, and `/l` options. You can't specify *StorePath*, because the `/genconfig` option doesn't create a store. *Path* can be either a relative or full path. If you don't specify the *Path* variable, then *FileName* will be created in the current directory.

Examples:
  • The following example creates a `Config.xml` file in the current directory:
    `ScanState.exe /i:MigApp.xml /i:MigDocs.xml /genconfig:Config.xml /v:13`
| -| **/config:**[*Path*]*FileName* | Specifies the `Config.xml` file that the `ScanState.exe` command should use to create the store. You can't use this option more than once on the command line. *Path* can be either a relative or full path. If you don't specify the *Path* variable, then *FileName* must be located in the current directory.

The following example creates a store using the `Config.xml` file, `MigDocs.xml`, and `MigApp.xml` files:
`ScanState.exe \server\share\migration\mystore /config:Config.xml /i:MigDocs.xml /i:MigApp.xml /v:13 /l:ScanState.log`

The following example migrates the files and settings to the destination computer using the `Config.xml`, `MigDocs.xml`, and `MigApp.xml` files:
`LoadState.exe \server\share\migration\mystore /config:Config.xml /i:MigDocs.xml /i:MigApp.xml /v:13 /l:LoadState.log` | -| **/auto:** *path to script files* | This option enables you to specify the location of the default .xml files and then begin the migration. If no path is specified, USMT will reference the directory where the USMT binaries are located. The `/auto` option has the same effect as using the following options: `/i: MigDocs.xml /i:MigApp.xml /v:5`. | -| **/genmigxml:** *path to a file* | This option specifies that the `ScanState.exe` command should use the document finder to create and export an .xml file that defines how to migrate all of the files on the computer on which the `ScanState.exe` command is running. | -| **/targetwindows8** | Optimizes `ScanState.exe` when using USMT 10.0 to migrate a user state to Windows 8 or Windows 8.1 instead of Windows 10. You should use this command-line option in the following scenarios:
  • **To create a `Config.xml` file by using the `/genconfig` option.** Using the `/targetwindows8` option optimizes the `Config.xml` file so that it only contains components that relate to Windows 8 or Windows 8.1.
  • **To create a migration store.** Using the `/targetwindows8` option ensures that the **ScanState** tool gathers the correct set of operating system settings. Without the `/targetwindows8` command-line option, some settings can be lost during the migration.
| -| **/targetwindows7** | Optimizes `ScanState.exe` when using USMT 10.0 to migrate a user state to Windows 7 instead of Windows 10. You should use this command-line option in the following scenarios:
  • **To create a `Config.xml` file by using the `/genconfig` option.** Using the **/targetwindows7** option optimizes the `Config.xml` file so that it only contains components that relate to Windows 7.
  • **To create a migration store.** Using the `/targetwindows7` option ensures that the **ScanState** tool gathers the correct set of operating system settings. Without the `/targetwindows7` command-line option, some settings can be lost during the migration.
| -| **/localonly** | Migrates only files that are stored on the local computer, regardless of the rules in the .xml files that you specify on the command line. You should use this option when you want to exclude the data from removable drives on the source computer, such as USB flash drives (UFDs), some external hard drives, and so on, and when there are network drives mapped on the source computer. If the `/localonly` option isn't specified, then the `ScanState.exe` command will copy files from these removable or network drives into the store.

Anything that isn't considered a fixed drive by the OS will be excluded by `/localonly`. In some cases, large external hard drives are considered fixed drives. These drives can be explicitly excluded from migration by using a custom .xml file. For more information about how to exclude all files on a specific drive, see [Exclude files and settings](usmt-exclude-files-and-settings.md).

The `/localonly` command-line option includes or excludes data in the migration as identified in the following storage locations:
  • **Removable drives such as a USB flash drive** - Excluded
  • **Network drives** - Excluded
  • **Fixed drives** - Included
| +| **/i:**[*Path*]*FileName* | **(include)**

Specifies an **.xml** file that contains rules that define what user, application, or system state to migrate. This option can be specified multiple times to include all of the **.xml** files (`MigApp.xml`, `MigDocs.xml`, and any custom **.xml** files that are created). *Path* can be either a relative or full path. If the *Path* variable isn't specified, then *FileName* must be located in the current directory. For more information about which files to specify, see the "XML Files" section of the [Frequently asked questions](usmt-faq.yml) article. | +| **/genconfig:**[*Path*]*FileName* | (Generate **Config.xml**)

Generates the optional `Config.xml` file, but doesn't create a migration store. To ensure that this file contains everything that needs to be migrated, create this file on a source computer that contains all of the:
  • components
  • applications
  • settings
present on the destination computers. In addition, the other migration **.xml** files should be specified, using the **/i** option, when this option is specified.

After this file is created, it can be used with the `ScanState.exe` command using the **/config** option.

The only options that can be specified with this option are the `/i`, `/v`, and `/l` options. *StorePath* can't be specified, because the `/genconfig` option doesn't create a store. *Path* can be either a relative or full path. If the *Path* variable isn't specified, then *FileName* is created in the current directory.

Examples:
  • The following example creates a `Config.xml` file in the current directory:
    `ScanState.exe /i:MigApp.xml /i:MigDocs.xml /genconfig:Config.xml /v:13`
| +| **/config:**[*Path*]*FileName* | Specifies the `Config.xml` file that the `ScanState.exe` command should use to create the store. This option can't be used more than once on the command line. *Path* can be either a relative or full path. If the *Path* variable isn't specified, then *FileName* must be located in the current directory.

The following example creates a store using the `Config.xml` file, `MigDocs.xml`, and `MigApp.xml` files:
`ScanState.exe \server\share\migration\mystore /config:Config.xml /i:MigDocs.xml /i:MigApp.xml /v:13 /l:ScanState.log`

The following example migrates the files and settings to the destination computer using the `Config.xml`, `MigDocs.xml`, and `MigApp.xml` files:
`LoadState.exe \server\share\migration\mystore /config:Config.xml /i:MigDocs.xml /i:MigApp.xml /v:13 /l:LoadState.log` | +| **/auto:** *path to script files* | This option enables specifying the location of the default **.xml** files. If no path is specified, USMT references the directory where the USMT binaries are located. The `/auto` option has the same effect as using the following options: `/i: MigDocs.xml /i:MigApp.xml /v:5`. | +| **/genmigxml:** *path to a file* | This option specifies that the `ScanState.exe` command should use the document finder to create and export an **.xml** file that defines how to migrate all of the files on the computer on which the `ScanState.exe` command is running. | +| **/localonly** | Migrates only files that are stored on the local computer, regardless of the rules in the **.xml** files that are specified on the command line. This option should be used to exclude the data from removable drives on the source computer and when there are network drives mapped on the source computer. Examples of removable drives include USB flash drives (UFDs) and some external hard drives. If the `/localonly` option isn't specified, then the `ScanState.exe` command copies files from these removable or network drives into the store.

`/localonly` excludes anything that isn't considered a fixed drive by the OS. In some cases, large external hard drives are considered fixed drives. These drives can be explicitly excluded from migration by using a custom **.xml** file. For more information about how to exclude all files on a specific drive, see [Exclude files and settings](usmt-exclude-files-and-settings.md).

The `/localonly` command-line option includes or excludes data in the migration as identified in the following storage locations:
  • **Removable drives such as a USB flash drive** - Excluded
  • **Network drives** - Excluded
  • **Fixed drives** - Included
| ## Monitoring options -USMT provides several options that you can use to analyze problems that occur during migration. +USMT provides several options that can be used to analyze problems that occur during migration. > [!NOTE] -> The **ScanState** log is created by default, but you can specify the name and location of the log with the **/l** option. +> +> The **ScanState** log is created by default, but the name and location of the log can be specified with the **/l** option. | Command-Line Option | Description | |-----|-----| -| **/listfiles**:<FileName> | You can use the `/listfiles` command-line option with the `ScanState.exe` command to generate a text file that lists all of the files included in the migration. | -| **/l:**[*Path*]*FileName* | Specifies the location and name of the **ScanState** log.

You can't store any of the log files in *StorePath*. *Path* can be either a relative or full path. If you don't specify the *Path* variable, then the log will be created in the current directory. You can use the `/v` option to adjust the amount of output.

If you run the `ScanState.exe` command from a shared network resource, you must specify the `/l` option, or USMT will fail with the following error:

***USMT was unable to create the log file(s)***

To fix this issue, make sure to specify the `/l` option when running `ScanState.exe` from a shared network resource. | -| **/v:***<VerbosityLevel>* | **(Verbosity)**

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

You can set the *VerbosityLevel* to one of the following levels:
  • **0** - Only the default errors and warnings are enabled.
  • **1** - Enables verbose output.
  • **4** - Enables error and status output.
  • **5** - Enables verbose and status output.
  • **8** - Enables error output to a debugger.
  • **9** - Enables verbose output to a debugger.
  • **12** - Enables error and status output to a debugger.
  • **13** - Enables verbose, status, and debugger output.

For example:
`ScanState.exe \server\share\migration\mystore /v:13 /i:MigDocs.xml /i:MigApp.xml`| -| **/progress**:[*Path*]*FileName* | Creates the optional progress log. You can't store any of the log files in *StorePath*. *Path* can be either a relative or full path. If you don't specify the *Path* variable, then *FileName* will be created in the current directory.

For example:
`ScanState.exe /i:MigApp.xml /i:MigDocs.xml \server\share\migration\mystore /progress:Progress.log /l:scanlog.log` | -| **/c** | When this option is specified, the `ScanState.exe` command will continue to run, even if non-fatal errors occur. Any files or settings that cause an error are logged in the progress log. For example, if there's a large file that won't fit in the store, the `ScanState.exe` command will log an error and continue with the migration. In addition, if a file is open or in use by an application, USMT may not be able to migrate the file and will log an error. Without the `/c` option, the `ScanState.exe` command will exit on the first error.

You can use the new <**ErrorControl**> section in the `Config.xml` file to specify which file or registry read/write errors can be safely ignored and which might cause the migration to fail. This advantage in the `Config.xml` file enables the `/c` command-line option to safely skip all input/output (I/O) errors in your environment. In addition, the /`genconfig` option now generates a sample <**ErrorControl**> section that is enabled by specifying error messages and desired behaviors in the `Config.xml` file. | -| **/r:***<TimesToRetry>* | **(Retry)**

Specifies the number of times to retry when an error occurs while saving the user state to a server. The default is three times. This option is useful in environments where network connectivity isn't reliable.

While storing the user state, the `/r` option won't be able to recover data that is lost due to a network-hardware failure, such as a faulty or disconnected network cable, or when a virtual private network (VPN) connection fails. The retry option is intended for large, busy networks where connectivity is satisfactory, but communication latency is a problem. | -| **/w:***<SecondsBeforeRetry>* | **(Wait)**

Specifies the time to wait, in seconds, before retrying a network file operation. The default is 1 second. | -| **/p:***<pathToFile>* | When the `ScanState.exe` command runs, it will create an .xml file in the path specified. This .xml file includes improved space estimations for the migration store. The following example shows how to create this .xml file:
`ScanState.exe C:\MigrationLocation [additional parameters]`
`/p:"C:\MigrationStoreSize.xml"`

For more information, see [Estimate Migration Store Size](usmt-estimate-migration-store-size.md).

To preserve the functionality of existing applications or scripts that require the previous behavior of USMT, you can use the `/p` option, without specifying *"pathtoafile"*, in USMT. If you specify only the `/p` option, the storage space estimations are created in the same manner as with USMT3.x releases. | +| **/listfiles**:\ | The `/listfiles` command-line option can be used with the `ScanState.exe` command to generate a text file that lists all of the files included in the migration. | +| **/l:**[*Path*]*FileName* | Specifies the location and name of the **ScanState** log.

The log files can't be stored in *StorePath*. *Path* can be either a relative or full path. If the *Path* variable isn't specified, then the log is created in the current directory. The `/v` option can be used to adjust the amount of output.

If the `ScanState.exe` command is run from a shared network resource, the `/l` option must be specified, or USMT fails with the following error:

***USMT was unable to create the log file(s)***

To fix this issue, make sure to specify the `/l` option when running `ScanState.exe` from a shared network resource. | +| **/v:***\* | **(Verbosity)**

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

The *VerbosityLevel* can be set to one of the following levels:
  • **0** - Only the default errors and warnings are enabled.
  • **1** - Enables verbose output.
  • **4** - Enables error and status output.
  • **5** - Enables verbose and status output.
  • **8** - Enables error output to a debugger.
  • **9** - Enables verbose output to a debugger.
  • **12** - Enables error and status output to a debugger.
  • **13** - Enables verbose, status, and debugger output.

For example:
`ScanState.exe \server\share\migration\mystore /v:13 /i:MigDocs.xml /i:MigApp.xml`| +| **/progress**:[*Path*]*FileName* | Creates the optional progress log. The log files can't be stored in *StorePath*. *Path* can be either a relative or full path. If the *Path* variable isn't specified, then *FileName* is created in the current directory.

For example:
`ScanState.exe /i:MigApp.xml /i:MigDocs.xml \server\share\migration\mystore /progress:Progress.log /l:scanlog.log` | +| **/c** | When this option is specified, the `ScanState.exe` command continues to run, even if non-fatal errors occur. Any files or settings that cause an error are logged in the progress log. For example, if there's a large file that doesn't fit in the store, the `ScanState.exe` command logs an error and continue with the migration. In addition, if a file is open or in use by an application, USMT might not be able to migrate the file and logs an error. Without the `/c` option, the `ScanState.exe` command exits on the first error.

The \<**ErrorControl**\> section in the `Config.xml` file can be used to specify which file or registry read/write errors can be safely ignored and which might cause the migration to fail. This advantage in the `Config.xml` file enables the `/c` command-line option to safely skip all input/output (I/O) errors in the environment. In addition, the /`genconfig` option now generates a sample \<**ErrorControl**\> section that is enabled by specifying error messages and desired behaviors in the `Config.xml` file. | +| **/r:***\* | **(Retry)**

Specifies the number of times to retry when an error occurs while saving the user state to a server. The default is three times. This option is useful in environments where network connectivity isn't reliable.

When the user state is stored, the `/r` option can't recover data that is lost due to a network-hardware failure, such as a faulty or disconnected network cable, or when a virtual private network (VPN) connection fails. The retry option is intended for large, busy networks where connectivity is satisfactory, but communication latency is a problem. | +| **/w:***\* | **(Wait)**

Specifies the time to wait, in seconds, before retrying a network file operation. The default is 1 second. | +| **/p:***\* | When the `ScanState.exe` command runs, it creates an **.xml** file in the path specified. This **.xml** file includes improved space estimations for the migration store. The following example shows how to create this **.xml** file:
`ScanState.exe C:\MigrationLocation [additional parameters]`
`/p:"C:\MigrationStoreSize.xml"`

For more information, see [Estimate Migration Store Size](usmt-estimate-migration-store-size.md).

To preserve the functionality of existing applications or scripts that require the previous behavior of USMT, the `/p` option can be used, without specifying *"pathtoafile"*, in USMT. If only the `/p` option is specified, the storage space estimations are created in the same manner as with USMT 3.x releases. | | **/?** or **/help** | Displays Help at the command line. | ## User options -By default, all users are migrated. The only way to specify which users to include and exclude is by using the following options. You can't exclude users in the migration .xml files or using the `Config.xml` file. For more information, see [Identify users](usmt-identify-users.md) and [Migrate user accounts](usmt-migrate-user-accounts.md). +By default, all users are migrated. The only way to specify which users to include and exclude is by using the following options. Users can't be excluded in the migration **.xml** files or using the `Config.xml` file. For more information, see [Identify users](usmt-identify-users.md) and [Migrate user accounts](usmt-migrate-user-accounts.md). | Command-Line Option | Description | |-----|-----| -| **/all** | Migrates all of the users on the computer.

USMT migrates all user accounts on the computer, unless you specifically exclude an account with either the `/ue` or `/uel` options. For this reason, you don't need to specify this option on the command line. However, if you choose to specify the `/all` option, you can't also use the `/ui`, `/ue` or `/uel` options. | -| **/ui**:*<DomainName>*\*<UserName>*
or
**/ui**:*<ComputerName>*\*<LocalUserName>* | **(User include)**

Migrates the specified users. By default, all users are included in the migration. Therefore, this option is helpful only when used with the `/ue` or `/uel` options. You can specify multiple `/ui` options, but you can't use the `/ui` option with the `/all` option. *DomainName* and *UserName* can contain the asterisk (`*`) wildcard character. When you specify a user name that contains spaces, you'll need to surround it with quotation marks (`"`).
**Note**
If a user is specified for inclusion with the `/ui` option and also specified to be excluded with either the `/ue` or `/uel` options, the user will be included in the migration.

For example:
  • To include only **User2** from the Fabrikam domain, enter:

    `/ue:*\* /ui:fabrikam\user2`

  • To migrate all users from the Fabrikam domain, and only the user accounts from other domains that have been active or otherwise modified in the last 30 days, enter:

    `/uel:30 /ui:fabrikam\*`

    In this example, a user account from the Contoso domain that was last modified two months ago won't be migrated.

For more examples, see the descriptions of the `/ue` and `/ui` options in this table. | -| **/uel**:*<NumberOfDays>*
or
**/uel**:*<YYYY/MM/DD>*
or
**/uel:0** | **(User exclude based on last logon)**

Migrates the users that logged on to the source computer within the specified time period, based on the **Last Modified** date of the Ntuser.dat file on the source computer. The `/uel` option acts as an include rule. For example, the `/uel:30` option migrates users who logged on, or whose account was modified, within the last 30 days from the date when the `ScanState.exe` command is run.

You can specify the number of days or you can specify a date. You can't use this option with the `/all` option. USMT retrieves the last sign-in information from the local computer, so the computer doesn't need to be connected to the network when you run this option. In addition, if a domain user has signed in to another computer, that sign-in instance isn't considered by USMT.
**Note**
The `/uel` option isn't valid in offline migrations.
  • `/uel:0` migrates any users who are currently logged on.
  • `/uel:90` migrates users who have logged on, or whose accounts have been otherwise modified, within the last 90 days.
  • `/uel:1` migrates users whose account has been modified within the last 24 hours.
  • `/uel:2020/2/15` migrates users who have logged on or been modified February 15, 2020 or afterwards.

For example:
`ScanState.exe /i:MigApp.xml /i:MigDocs.xml \\server\share\migration\mystore /uel:0` | -| **/ue**:*<DomainName>*\*<UserName>*
-or-

**/ue**:*<ComputerName>*\*<LocalUserName>* | **(User exclude)**

Excludes the specified users from the migration. You can specify multiple `/ue` options. You can't use this option with the `/all` option. *<DomainName>* and *<UserName>* can contain the asterisk (`*`) wildcard character. When you specify a user name that contains spaces, you need to surround it with quotation marks (`"`).

For example:
`ScanState.exe /i:MigDocs.xml /i:MigApp.xml \\server\share\migration\mystore /ue:contoso\user1` | +| **/all** | Migrates all of the users on the computer.

USMT migrates all user accounts on the computer, unless an account is specifically excluded with either the `/ue` or `/uel` options. For this reason, this option doesn't need to be specified on the command line. However, if the `/all` option is specified, the `/ui`, `/ue` or `/uel` options can't also be specified. | +| **/ui**:*\*\*\*
or
**/ui**:*\*\*\* | **(User include)**

Migrates the specified users. By default, all users are included in the migration. Therefore, this option is helpful only when used with the `/ue` or `/uel` options. Multiple `/ui` options can be specified, but the `/ui` option can't be used with the `/all` option. *DomainName* and *UserName* can contain the asterisk (`*`) wildcard character. When a user name that contains spaces is specified, it needs to be surrounded with quotation marks (`"`).
**Note**
If a user is specified for inclusion with the `/ui` option and also specified to be excluded with either the `/ue` or `/uel` options, the user is included in the migration.

For example:
  • To include only **User2** from the Fabrikam domain, enter:

    `/ue:*\* /ui:fabrikam\user2`

  • To migrate all users from the Fabrikam domain, and only the user accounts from other domains that are active or otherwise modified in the last 30 days, enter:

    `/uel:30 /ui:fabrikam\*`

    In this example, a user account from the Contoso domain that was last modified two months ago isn't migrated.

For more examples, see the descriptions of the `/ue` and `/ui` options in this table. | +| **/uel**:*\*
or
**/uel**:*\*
or
**/uel:0** | **(User exclude based on last logon)**

Migrates the users that logged on to the source computer within the specified time period, based on the **Last Modified** date of the Ntuser.dat file on the source computer. The `/uel` option acts as an include rule. For example, the `/uel:30` option migrates users who logged on, or whose account was modified, within the last 30 days from the date when the `ScanState.exe` command is run.

The number of days or the date can be specified. This option can't be used with the `/all` option. USMT retrieves the last sign-in information from the local computer, so the computer doesn't need to be connected to the network when running this option. In addition, if a domain user signs in to another computer, USMT doesn't consider that sign-in instance.
**Note**
The `/uel` option isn't valid in offline migrations.
  • `/uel:0` migrates any users who are currently logged on.
  • `/uel:90` migrates users who logged on, or whose accounts were otherwise modified, within the last 90 days.
  • `/uel:1` migrates users whose account were modified within the last 24 hours.
  • `/uel:2020/2/15` migrates users who logged on or been modified February 15, 2020 or afterwards.

For example:
`ScanState.exe /i:MigApp.xml /i:MigDocs.xml \\server\share\migration\mystore /uel:0` | +| **/ue**:*\*\*\*
-or-

**/ue**:*\*\*\* | **(User exclude)**

Excludes the specified users from the migration. Multiple `/ue` options can be specified. This option can't be used with the `/all` option. *\* and *\* can contain the asterisk (`*`) wildcard character. When a user name that contains spaces is specified, it needs to be surrounded with quotation marks (`"`).

For example:
`ScanState.exe /i:MigDocs.xml /i:MigApp.xml \\server\share\migration\mystore /ue:contoso\user1` | ## How to use /ui and /ue -The following examples apply to both the `/ui` and `/ue` options. You can replace the `/ue` option with the `/ui` option to include, rather than exclude, the specified users. +The following examples apply to both the `/ui` and `/ue` options. The `/ue` option can be replaced with the `/ui` option to include, rather than exclude, the specified users. |Behavior|Command| |--- |--- | @@ -154,72 +159,75 @@ The following examples apply to both the `/ui` and `/ue` options. You can replac ## Using the options together -You can use the `/uel`, `/ue` and `/ui` options together to migrate only the users that you want migrated. +The `/uel`, `/ue` and `/ui` options can be used together to migrate only the users that need to be migrated. -The `/ui` option has precedence over the `/ue` and `/uel` options. If a user is specified for inclusion with the `/ui` option and also specified to be excluded with either the `/ue` or `/uel` options, the user will be included in the migration. For example, if you specify `/ui:contoso\* /ue:contoso\user1`, then **User1** will be migrated, because the `/ui` option takes precedence over the `/ue` option. +The `/ui` option has precedence over the `/ue` and `/uel` options. If a user is specified for inclusion with the `/ui` option and also specified to be excluded with either the `/ue` or `/uel` options, the user is included in the migration. For example, if `/ui:contoso\* /ue:contoso\user1` is specified, then **User1** is migrated, because the `/ui` option takes precedence over the `/ue` option. -The `/uel` option takes precedence over the `/ue` option. If a user has logged on within the specified time period set by the `/uel` option, that user's profile will be migrated even if they're excluded by using the `/ue` option. For example, if you specify `/ue:fixed\user1 /uel:14`, the User1 will be migrated if they've logged on to the computer within the last 14 days. +The `/uel` option takes precedence over the `/ue` option. If a user logged on within the specified time period set by the `/uel` option, that user's profile is migrated even if they're excluded by using the `/ue` option. For example, if `/ue:fixed\user1 /uel:14` is specified, then User1 is migrated if they logged on to the computer within the last 14 days. |Behavior|Command| |--- |--- | |Include only User2 from the Fabrikam domain and exclude all other users.|`/ue:*\* /ui:fabrikam\user2`| |Include only the local user named User1 and exclude all other users.|`/ue:*\* /ui:user1`| -|Include only the domain users from Contoso, except Contoso\User1.|This behavior can't be completed using a single command. Instead, to migrate this set of users, you'll need to specify the following commands:
  • On the `ScanState.exe` command line, enter:
    `/ue:*\* /ui:contoso\*`
  • On the `LoadState.exe` command line, enter:
    `/ue:contoso\user1`
| +|Include only the domain users from Contoso, except Contoso\User1.|This behavior can't be completed using a single command. Instead, to migrate this set of users, specify the following commands:
  • On the `ScanState.exe` command line, enter:
    `/ue:*\* /ui:contoso\*`
  • On the `LoadState.exe` command line, enter:
    `/ue:contoso\user1`
| |Include only local (non-domain) users.|`/ue:*\* /ui:%computername%\*`| ## Encrypted file options -You can use the following options to migrate encrypted files. In all cases, by default, USMT fails if an encrypted file is found unless you specify an `/efs` option. To migrate encrypted files, you must change the default behavior. +The following options can be used to migrate encrypted files. In all cases, by default, USMT fails if an encrypted file is found unless the `/efs` option is specified. To migrate encrypted files, the default behavior must be changed. For more information, see [Migrate EFS Files and Certificates](usmt-migrate-efs-files-and-certificates.md). > [!NOTE] -> EFS certificates will be migrated automatically when migrating to Windows 7, Windows 8 or Windows 10. Therefore, you should specify the `/efs:copyraw` option with the `ScanState.exe` command to migrate the encrypted files +> +> EFS certificates are migrated automatically during the migration. Therefore, the `/efs:copyraw` option should be specified with the `ScanState.exe` command to migrate the encrypted files. > [!CAUTION] -> Take caution when migrating encrypted files. If you migrate an encrypted file without also migrating the certificate, end users will not be able to access the file after the migration. +> +> Take caution when migrating encrypted files. If an encrypted file is migrated without also migrating the certificate, end users won't be able to access the file after the migration. | Command-Line Option | Explanation | |----|----| | **/efs:hardlink** | Creates a hard link to the EFS file instead of copying it. Use only with the `/hardlink` and the `/nocompress` options. | | **/efs:abort** | Causes the `ScanState.exe` command to fail with an error code, if an Encrypting File System (EFS) file is found on the source computer. Enabled by default. | | **/efs:skip** | Causes the `ScanState.exe` command to ignore EFS files. | -| **/efs:decryptcopy** | Causes the `ScanState.exe` command to decrypt the file, if possible, before saving it to the migration store, and to fail if the file can't be decrypted. If the `ScanState.exe` command succeeds, the file will be unencrypted in the migration store, and once you run the `LoadState.exe` command, the file will be copied to the destination computer. | -| **/efs:copyraw** | Causes the `ScanState.exe` command to copy the files in the encrypted format. The files will be inaccessible on the destination computer until the EFS certificates are migrated. EFS certificates will be automatically migrated; however, by default USMT fails if an encrypted file is found, unless you specify an `/efs` option. Therefore you should specify the `/efs:copyraw` option with the `ScanState.exe` command to migrate the encrypted file. Then, when you run the `LoadState.exe` command, the encrypted file and the EFS certificate will be automatically migrated.

For example:
`ScanState.exe /i:MigDocs.xml /i:MigApp.xml \server\share\migration\mystore /efs:copyraw`
**Important**
All files must be encrypted if the parent folder is encrypted. If the encryption attribute on a file inside an encrypted folder has been removed, the file will be encrypted during the migration using the credentials of the account used to run the **LoadState** tool. For more information, see [Migrate EFS files and certificates](usmt-migrate-efs-files-and-certificates.md).
| +| **/efs:decryptcopy** | Causes the `ScanState.exe` command to decrypt the file, if possible, before saving it to the migration store, and to fail if the file can't be decrypted. If the `ScanState.exe` command succeeds, the file is unencrypted in the migration store, and once the `LoadState.exe` command is run, the file is copied to the destination computer. | +| **/efs:copyraw** | Causes the `ScanState.exe` command to copy the files in the encrypted format. The files are inaccessible on the destination computer until the EFS certificates are migrated. EFS certificates are automatically migrated; however, by default USMT fails if an encrypted file is found, unless the `/efs` option is specified. Therefore the `/efs:copyraw` option should be specified with the `ScanState.exe` command to migrate the encrypted file. When the `LoadState.exe` command is run, the encrypted file and the EFS certificate are automatically migrated.

For example:
`ScanState.exe /i:MigDocs.xml /i:MigApp.xml \server\share\migration\mystore /efs:copyraw`
**Important**
All files must be encrypted if the parent folder is encrypted. If the encryption attribute on a file inside an encrypted folder is removed, the file is encrypted during the migration using the credentials of the account used to run the **LoadState** tool. For more information, see [Migrate EFS files and certificates](usmt-migrate-efs-files-and-certificates.md).
| ## Incompatible command-line options -The following table indicates which command-line options aren't compatible with the `ScanState.exe` command. If the table entry for a particular combination is blank, the options are compatible and you can use them together. The X symbol means that the options aren't compatible. For example, you can't use the `/nocompress` option with the `/encrypt` option. +The following table indicates which command-line options aren't compatible with the `ScanState.exe` command. If the table entry for a particular combination has a ✔️, the options are compatible and they can be used together. The ❌ symbol means that the options aren't compatible. For example, the `/nocompress` option can't be used with the `/encrypt` option. |Command-Line Option|/keyfile|/nocompress|/genconfig|/all| |--- |--- |--- |--- |--- | -|**/i**||||| -|**/o**||||| -|**/v**||||| -|**/nocompress**||||N/A| -|**/localonly**|||X|| -|**/key**|X||X|| -|**/encrypt**|Required*|X|X|| -|**/keyfile**|N/A||X|| -|**/l**||||| -|**/listfiles**|||X|| -|**/progress**|||X|| -|**/r**|||X|| -|**/w**|||X|| -|**/c**|||X|| -|**/p**|||X|N/A| -|**/all**|||X|| -|**/ui**|||X|X| -|**/ue**|||X|X| -|**/uel**|||X|X| -|**/efs**:*<option>*|||X|| -|**/genconfig**|||N/A|| -|**/config**|||X|| -|*<StorePath>*|||X|| +|**/i**| ✔️ | ✔️ | ✔️ | ✔️ | +|**/o**| ✔️ | ✔️ | ✔️ | ✔️ | +|**/v**| ✔️ | ✔️ | ✔️ | ✔️ | +|**/nocompress**| ✔️ | ✔️ | ✔️ |N/A| +|**/localonly**| ✔️ | ✔️ | ❌ | ✔️ | +|**/key**| ❌ | ✔️ | ❌ | ✔️ | +|**/encrypt**|Required*| ❌ | ❌ | ✔️ | +|**/keyfile**|N/A| ✔️ | ❌ | ✔️ | +|**/l**| ✔️ | ✔️ | ✔️ | ✔️ | +|**/listfiles**| ✔️ | ✔️ | ❌ | ✔️ | +|**/progress**| ✔️ | ✔️ | ❌ | ✔️ | +|**/r**| ✔️ | ✔️ | ❌ | ✔️ | +|**/w**| ✔️ | ✔️ | ❌ | ✔️ | +|**/c**| ✔️ | ✔️ | ❌ | ✔️ | +|**/p**| ✔️ | ✔️ | ❌ |N/A| +|**/all**| ✔️ | ✔️ | ❌ | ✔️ | +|**/ui**| ✔️ | ✔️ | ❌ | ❌ | +|**/ue**| ✔️ | ✔️ | ❌ | ❌ | +|**/uel**| ✔️ | ✔️ | ❌ | ❌ | +|**/efs**:*\*| ✔️ | ✔️ | ❌ | ✔️ | +|**/genconfig**| ✔️ | ✔️ |N/A| ✔️ | +|**/config**| ✔️ | ✔️ | ❌ | ✔️ | +|*\*| ✔️ | ✔️ | ❌ | ✔️ | > [!NOTE] -> You must specify either the `/key` or `/keyfile` option with the `/encrypt` option. +> +> Either the `/key` or `/keyfile` option must be specified with the `/encrypt` option. ## Related articles -[XML Elements Library](usmt-xml-elements-library.md) +- [XML Elements Library](usmt-xml-elements-library.md). diff --git a/windows/deployment/usmt/usmt-technical-reference.md b/windows/deployment/usmt/usmt-technical-reference.md index b60e82e749..0d34114c83 100644 --- a/windows/deployment/usmt/usmt-technical-reference.md +++ b/windows/deployment/usmt/usmt-technical-reference.md @@ -1,26 +1,23 @@ --- -title: User State Migration Tool (USMT) Technical Reference (Windows 10) +title: User State Migration Tool (USMT) Technical Reference description: The User State Migration Tool (USMT) provides a highly customizable user-profile migration experience for IT professionals. manager: aaroncz ms.author: frankroj ms.prod: windows-client author: frankroj -ms.date: 11/01/2022 +ms.date: 01/03/2024 ms.topic: article ms.technology: itpro-deploy +appliesto: + - ✅ Windows 11 + - ✅ Windows 10 --- # User State Migration Tool (USMT) technical reference -The User State Migration Tool (USMT) is included with the Windows Assessment and Deployment Kit (Windows ADK) for Windows 10. USMT provides a highly customizable user-profile migration experience for IT professionals. +The User State Migration Tool (USMT) is included with the Windows Assessment and Deployment Kit (Windows ADK). USMT provides a highly customizable user-profile migration experience for IT professionals. -Download the Windows ADK [from this website](/windows-hardware/get-started/adk-install). - -## USMT support for Microsoft Office - -- USMT in the Windows ADK for Windows 10, version 1511 (10.1.10586.0) supports migration of user settings for installations of Microsoft Office 2003, 2007, 2010, and 2013. - -- USMT in the Windows ADK for Windows 10, version 1607 (10.1.14393.0) adds support for migration of user settings for installations of Microsoft Office 2016. +The Windows ADK can be downloaded from the [Download and install the Windows ADK](/windows-hardware/get-started/adk-install) website. USMT includes three command-line tools: @@ -28,25 +25,25 @@ USMT includes three command-line tools: - LoadState.exe - UsmtUtils.exe -USMT also includes a set of three modifiable .xml files: +USMT also includes a set of three modifiable **.xml** files: - MigApp.xml - MigDocs.xml - MigUser.xml -Additionally, you can create custom .xml files to support your migration needs. You can also create a `Config.xml` file to specify files or settings to exclude from the migration. +Additionally, custom **.xml** files can be created to support the organization's migration needs. A `Config.xml` file can also be created to specify files or settings to exclude from the migration. -USMT tools can be used on several versions of Windows operating systems, for more information, see [USMT requirements](usmt-requirements.md). For more information about previous releases of the USMT tools, see [User State Migration Tool (USMT) overview](/previous-versions/windows/hh825227(v=win.10)). +USMT tools can be used on several versions of Windows operating systems. For more information, see [USMT requirements](usmt-requirements.md). For more information about previous releases of the USMT tools, see [User State Migration Tool (USMT) overview](/previous-versions/windows/hh825227(v=win.10)). + +## USMT support for Microsoft Office + +USMT in the currently supported versions of the Windows ADK supports migration of user settings for installations of Microsoft Office 2013 and 2016. ## In this section | Link | Description | |------ |----------- | -|[User State Migration Tool (USMT) overview topics](usmt-topics.md)|Describes what's new in USMT, how to get started with USMT, and the benefits and limitations of using USMT.| -|[User State Migration Tool (USMT) how-to topics](usmt-how-to.md)|Includes step-by-step instructions for using USMT and how-to topics for conducting tasks in USMT.| +|[User State Migration Tool (USMT) overview articles](usmt-topics.md)|Describes what's new in USMT, how to get started with USMT, and the benefits and limitations of using USMT.| +|[User State Migration Tool (USMT) how-to articles](usmt-how-to.md)|Includes step-by-step instructions for using USMT and how-to articles for conducting tasks in USMT.| |[User State Migration Tool (USMT) troubleshooting](usmt-troubleshooting.md)|Provides answers to frequently asked questions and common issues in USMT and a reference for return codes used in USMT.| |[User State Migration Toolkit (USMT) reference](usmt-reference.md)|Includes reference information for migration planning, migration best practices, command-line syntax, using XML, and requirements for using USMT.| - -## Related articles - -- [Windows Assessment and Deployment Kit](/previous-versions/windows/it-pro/windows-8.1-and-8/dn247001(v=win.10)) diff --git a/windows/deployment/usmt/usmt-test-your-migration.md b/windows/deployment/usmt/usmt-test-your-migration.md index 9b0981998d..b21e91a311 100644 --- a/windows/deployment/usmt/usmt-test-your-migration.md +++ b/windows/deployment/usmt/usmt-test-your-migration.md @@ -1,35 +1,48 @@ --- -title: Test Your Migration (Windows 10) -description: Learn about testing your migration plan in a controlled laboratory setting before you deploy it to your entire organization. +title: Test The Migration +description: Learn about testing the migration plan in a controlled laboratory setting before deploying it to the entire organization. manager: aaroncz ms.author: frankroj ms.prod: windows-client author: frankroj -ms.date: 11/01/2022 +ms.date: 01/03/2024 ms.topic: article ms.technology: itpro-deploy +appliesto: + - ✅ Windows 11 + - ✅ Windows 10 --- -# Test your migration +# Test the migration -Always test your migration plan in a controlled laboratory setting before you deploy it to your entire organization. In your test environment, you need at least one computer for each type of operating system from which you're migrating data. +Always test the migration plan in a controlled laboratory setting before deploying it to the entire organization. In the test environment, at least one computer is needed for each type of operating system from which data is being migrated. -After you've thoroughly tested the entire migration process on a single computer running each of your source operating systems, conduct a pilot migration with a small group of users. After migrating a few typical user states to the intermediate store, note the space required and adjust your initial calculations accordingly. For details about estimating the space needed for your migration, see [Estimate migration store size](usmt-estimate-migration-store-size.md). You might also need to adjust the registry-setting and file-location information in your migration-rule files. If you make changes, test the migration again. Then verify that all data and settings have migrated as expected. A pilot migration also gives you an opportunity to test your space estimates for the intermediate store. +Once the entire migration process is tested on a single computer running each of the organization source operating systems, conduct a pilot migration with a small group of users. After migrating a few typical user states to the intermediate store, note the space required and adjust the initial calculations accordingly. For details about estimating the space needed for the migration, see [Estimate migration store size](usmt-estimate-migration-store-size.md). Registry-setting and file-location information might need to be adjusted in the migration-rule files. If changes are made, test the migration again and verify that all data and settings migrated as expected. A pilot migration also gives the opportunity to test the space estimates for the intermediate store. -If your test migration encounters any errors, examine the **ScanState** and **LoadState** logs to obtain the exact User State Migration Tool (USMT) 10.0 return code and associated error messages or Windows application programming interface (API) error message. For more information about USMT return codes and error messages, see [Return codes](/troubleshoot/windows-client/deployment/usmt-return-codes). You can obtain more information about any listed **Windows** system error codes by typing in a command prompt window `net.exe helpmsg ` where ** is the error code number generated by the error message. For more information about System Error Codes, see [System Error Codes (0-499)](/windows/win32/debug/system-error-codes--0-499-). +If the test migration encounters any errors, examine the **ScanState** and **LoadState** logs to obtain the exact User State Migration Tool (USMT) return code and associated error messages or Windows application programming interface (API) error message. For more information about USMT return codes and error messages, see [Return codes](/troubleshoot/windows-client/deployment/usmt-return-codes). More information can be obtained about any listed **Windows** system error codes by typing in the following at a command prompt window: -In most cases, the **ScanState** and **LoadState** logs indicate why a USMT migration is failing. We recommend that you use the `/v:5` option when testing your migration. This verbosity level can be adjusted in a production migration. Reducing the verbosity level might make it more difficult to diagnose failures that are encountered during production migrations. You can use a higher verbosity level if you want the log files output to go to a debugger. +```cmd +net.exe helpmsg +``` + +where ** is the error code number generated by the error message. For more information about System Error Codes, see [System Error Codes (0-499)](/windows/win32/debug/system-error-codes--0-499-). + +In most cases, the **ScanState** and **LoadState** logs indicate why a USMT migration is failing. Microsoft recommends using the `/v:5` option when testing the migration. This verbosity level can be adjusted in a production migration. Reducing the verbosity level might make it more difficult to diagnose failures that are encountered during production migrations. Higher verbosity levels can be used if the log files need to output to go to a debugger. > [!NOTE] -> Running the **ScanState** and **LoadState** tools with the `/v:5` option creates a detailed log file. Although this option makes the log file large, it is helpful in determining where migration errors occurred. +> +> Running the **ScanState** and **LoadState** tools with the `/v:5` option creates a detailed log file. Although this option makes the log file large, it's helpful in determining where migration errors occurred. -After you've determined that the pilot migration successfully migrated the specified files and settings, you're ready to add USMT to the server that is running Microsoft Configuration Manager, or a non-Microsoft management technology. For more information, see [Manage user state in Configuration Manager](/configmgr/osd/get-started/manage-user-state). +After the pilot migration is verified that it successfully migrated the specified files and settings, USMT is ready to be used in the environment to migrate data. For example, using USMT with Microsoft Configuration Manager. For more information, see [Manage user state in Configuration Manager]/(mem/configmgr/osd/get-started/manage-user-state). > [!NOTE] -> For testing purposes, you can create an uncompressed store using the `/hardlink /nocompress` option. When compression is disabled, the **ScanState** tool saves the files and settings to a hidden folder named **File** at `\USMT`. You can use the uncompressed store to view what USMT has stored or to troubleshoot a problem, or you can run an antivirus utility against the files. Additionally, you can also use the `/listfiles` command-line option and the diagnostic log to list the files that were gathered and to troubleshoot problems with your migration. +> +> For testing purposes, an uncompressed store using the `/hardlink /nocompress` option can be created. When compression is disabled, the **ScanState** tool saves the files and settings to a hidden folder named **File** at `\USMT`. The uncompressed store can be used to view what USMT stored or to troubleshoot a problem. An antivirus utility can also be run against the files. Additionally, the following items can be used to troubleshoot problems with the migration: +> +> - The `/listfiles` command-line option. +> - The diagnostic log that lists the files that were gathered. ## Related articles -[Plan your migration](usmt-plan-your-migration.md) - -[Log files](usmt-log-files.md) +- [Plan the migration](usmt-plan-your-migration.md). +- [Log files](usmt-log-files.md). diff --git a/windows/deployment/usmt/usmt-topics.md b/windows/deployment/usmt/usmt-topics.md index a1a2c43ef3..21d5a39253 100644 --- a/windows/deployment/usmt/usmt-topics.md +++ b/windows/deployment/usmt/usmt-topics.md @@ -1,18 +1,21 @@ --- -title: User State Migration Tool (USMT) Overview Topics (Windows 10) +title: User State Migration Tool (USMT) Overview Articles description: Learn about User State Migration Tool (USMT) overview articles that describe USMT as a highly customizable user-profile migration experience for IT professionals. manager: aaroncz ms.author: frankroj ms.prod: windows-client author: frankroj -ms.date: 11/01/2022 +ms.date: 01/03/2024 ms.topic: article ms.technology: itpro-deploy +appliesto: + - ✅ Windows 11 + - ✅ Windows 10 --- -# User State Migration Tool (USMT) overview topics +# User State Migration Tool (USMT) overview articles -The User State Migration Tool (USMT) 10.0 provides a highly customizable user-profile migration experience for IT professionals. USMT includes three command-line tools: `ScanState.exe`, `LoadState.exe`, and `UsmtUtils.exe`. USMT also includes a set of three modifiable .xml files: `MigApp.xml`, `MigDocs.xml`, and `MigUser.xml`. Additionally, you can create custom .xml files to support your migration needs. You can also create a `Config.xml` file to specify files or settings to exclude from the migration. +The User State Migration Tool (USMT) provides a highly customizable user-profile migration experience for IT professionals. USMT includes three command-line tools: `ScanState.exe`, `LoadState.exe`, and `UsmtUtils.exe`. USMT also includes a set of three modifiable .xml files: `MigApp.xml`, `MigDocs.xml`, and `MigUser.xml`. Additionally, custom **.xml** files can be created to support the organization's migration needs. A `Config.xml` file can also be created to specify files or settings to exclude from the migration. ## In this section @@ -20,10 +23,10 @@ The User State Migration Tool (USMT) 10.0 provides a highly customizable user-pr |------ |----------- | |[User State Migration Tool (USMT) overview](usmt-overview.md)|Describes the benefits and limitations of using USMT.| |[Getting started with the User State Migration Tool (USMT)](getting-started-with-the-user-state-migration-tool.md)|Describes the general process to follow to migrate files and settings, and provides links to more information.| -|[Windows upgrade and migration considerations](../upgrade/windows-upgrade-and-migration-considerations.md)|Discusses the Microsoft® tools you can use to move files and settings between installations and special considerations for performing an upgrade or migration.| +|[Windows upgrade and migration considerations](../upgrade/windows-upgrade-and-migration-considerations.md)|Discusses the Microsoft tools that can be used to move files and settings between installations and special considerations for performing an upgrade or migration.| ## Related articles -- [User State Migration Tool (USMT) how-to topics](usmt-how-to.md) -- [User State Migration Tool (USMT) troubleshooting](usmt-troubleshooting.md) -- [User State Migration Toolkit (USMT) reference](usmt-reference.md) +- [User State Migration Tool (USMT) how-to articles](usmt-how-to.md). +- [User State Migration Tool (USMT) troubleshooting](usmt-troubleshooting.md). +- [User State Migration Toolkit (USMT) reference](usmt-reference.md). diff --git a/windows/deployment/usmt/usmt-troubleshooting.md b/windows/deployment/usmt/usmt-troubleshooting.md index 05971e5afd..bb59960a58 100644 --- a/windows/deployment/usmt/usmt-troubleshooting.md +++ b/windows/deployment/usmt/usmt-troubleshooting.md @@ -1,18 +1,21 @@ --- -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: 01/03/2024 ms.topic: article ms.technology: itpro-deploy +appliesto: + - ✅ Windows 11 + - ✅ Windows 10 --- # 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 can be used to troubleshoot issues that arise during the migration. ## In this section @@ -20,16 +23,13 @@ The following table describes articles that address common User State Migration |--- |--- | |[Common Issues](/troubleshoot/windows-client/deployment/usmt-common-issues)|Find troubleshooting solutions for common problems in USMT.| |[Frequently Asked Questions](usmt-faq.yml)|Find answers to questions about how to use USMT.| -|[Log Files](usmt-log-files.md)|Learn how to enable logging to help you troubleshoot issues in USMT.| +|[Log Files](usmt-log-files.md)|Learn how to enable logging to help troubleshoot issues in USMT.| |[Return Codes](/troubleshoot/windows-client/deployment/usmt-return-codes)|Learn how to use return codes to identify problems in USMT.| |[USMT Resources](usmt-resources.md)|Find more information and support for using USMT.| ## 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..59ba8b8b14 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 @@ -8,19 +8,22 @@ author: frankroj ms.date: 11/01/2022 ms.topic: article ms.technology: itpro-deploy +appliesto: + - ✅ Windows 11 + - ✅ Windows 10 --- # 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 @@ -28,30 +31,30 @@ The following table lists command-line options for `UsmtUtils.exe`. The sections The syntax for `UsmtUtils.exe` is: -> UsmtUtils.exe \[/ec | /rd *<storeDir>* | /verify *<filepath>* \[options\] | /extract *<filepath>* *<destinationPath>* \[options\]\] +> UsmtUtils.exe \[/ec | /rd *\* | /verify *\* \[options\] | /extract *\* *\* \[options\]\] |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.| -|**/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`.| +|**/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** *\* |Removes the directory path specified by the *\* 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: -> UsmtUtils.exe /verify\[:*<reportType>*\] *<filePath>* \[/l:*<logfile>*\] \[/v:*VerbosityLevel*\] \[/decrypt \[:*<AlgID>*\] {/key:*<keystring>* | /keyfile:*<filename>*}\] +> UsmtUtils.exe /verify\[:*\*\] *\* \[/l:*\*\] \[/v:*VerbosityLevel*\] \[/decrypt \[:*\*\] {/key:*\* | /keyfile:*\*}\] | Command-line Option | Description | |-----|--------| -| *<reportType>* | Specifies whether to report on all files, corrupted files only, or the status of the catalog.
  • **Summary**. Returns both the number of files that are intact and the number of files that are corrupted in the migration store. If no algorithm is specified, the summary report is displayed as a default.
  • **all**. Returns a tab-delimited list of all of the files in the compressed migration store and the status for each file. Each line contains the file name followed by a tab spacing, and either **CORRUPTED** or **OK** depending on the status of the file. The last entry reports the corruption status of the **CATALOG** of the store. A catalog file contains metadata for all files in a migration store. The **LoadState** tool requires a valid catalog file in order to open the migration store. Returns "OK" if the catalog file is intact and **LoadState** can open the migration store and "CORRUPTED" if the migration store is corrupted.
  • **failureonly**. Returns a tab-delimited list of only the files that are corrupted in the compressed migration store.
  • **Catalog**. Returns only the status of the catalog file.
| -| **/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:
  • **0** - Only the default errors and warnings are enabled.
  • **1** - Enables verbose output.
  • **4** - Enables error and status output.
  • **5** - Enables verbose and status output.
  • **8** - Enables error output to a debugger.
  • **9** - Enables verbose output to a debugger.
  • **12** - Enables error and status output to a debugger.
  • **13** - Enables verbose, status, and debugger output.
| -| **/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:
  • *<AlgID>* specifies the cryptographic algorithm that was used to create the migration store on the `ScanState.exe` command line. If no algorithm is specified, **ScanState** and **UsmtUtils** use the 3DES algorithm as a default.
    *<AlgID>* valid values include: `AES_128`, `AES_192`, `AES_256`, `3DES`, or `3DES_112`.
  • `/key:` *<KeyString>* specifies the encryption key. If there's a space in *<KeyString>*, you must surround the argument with quotation marks.
  • `/keyfile`: *<FileName>* specifies the location and name of a text (.txt) file that contains the encryption key.

For more information about supported encryption algorithms, see [Migration Store Encryption](usmt-migration-store-encryption.md) | +| *\* | Specifies whether to report on all files, corrupted files only, or the status of the catalog.
  • **Summary**. Returns both the number of files that are intact and the number of files that are corrupted in the migration store. If no algorithm is specified, the summary report is displayed as a default.
  • **all**. Returns a tab-delimited list of all of the files in the compressed migration store and the status for each file. Each line contains the file name followed by a tab spacing, and either **CORRUPTED** or **OK** depending on the status of the file. The last entry reports the corruption status of the **CATALOG** of the store. A catalog file contains metadata for all files in a migration store. The **LoadState** tool requires a valid catalog file in order to open the migration store. Returns "OK" if the catalog file is intact and **LoadState** can open the migration store and "CORRUPTED" if the migration store is corrupted.
  • **failureonly**. Returns a tab-delimited list of only the files that are corrupted in the compressed migration store.
  • **Catalog**. Returns only the status of the catalog file.
| +| **/l:**
*\* | Specifies the location and name of the log file. | +| **/v:** *\* | **(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:
  • **0** - Only the default errors and warnings are enabled.
  • **1** - Enables verbose output.
  • **4** - Enables error and status output.
  • **5** - Enables verbose and status output.
  • **8** - Enables error output to a debugger.
  • **9** - Enables verbose output to a debugger.
  • **12** - Enables error and status output to a debugger.
  • **13** - Enables verbose, status, and debugger output.
| +| **/decrypt** *\* **/**:*\*
or
**/decrypt** *\* **/**:*\<"Key String"\>*
or
**/decrypt:** *\* **/keyfile**:*\* | 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:
  • *\* specifies the cryptographic algorithm that was used to create the migration store on the `ScanState.exe` command line. If no algorithm is specified, **ScanState** and **UsmtUtils** use the 3DES algorithm as a default.
    *\* valid values include: `AES_128`, `AES_192`, `AES_256`, `3DES`, or `3DES_112`.
  • `/key:` *\* specifies the encryption key. If there's a space in *\*, the argument must be surrounded with quotation marks.
  • `/keyfile`: *\* specifies the location and name of a text (.txt) file that contains the encryption key.

For more information about supported encryption algorithms, see [Migration Store Encryption](usmt-migration-store-encryption.md). | Some examples of `/verify` commands: @@ -65,21 +68,21 @@ 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: -> /extract *<filePath>* *<destinationPath>* \[/i:*<includePattern>*\] \[/e: *<excludePattern>*\] \[/l: *<logfile>*\] \[/v: *VerbosityLevel>*\] \[/decrypt\[:*<AlgID>*\] {key: *<keystring>* | /keyfile: *<filename>*}\] \[/o\] +> /extract *\* *\* \[/i:*\*\] \[/e: *\*\] \[/l: *\*\] \[/v: *VerbosityLevel\>*\] \[/decrypt\[:*\*\] {key: *\* | /keyfile: *\*}\] \[/o\] | Command-line Option | Description | |-------|-----| -| *<filePath>* | Path to the USMT migration store.

For example:
`D:\MyMigrationStore\USMT\store.mig` | -| *<destinationPath>* | Path to the folder where the tool puts the individual files. | -| **/i**:*<includePattern>* | Specifies a pattern for files to include in the extraction. You can specify more than one pattern. Separate patterns with a comma or a semicolon. You can use `/i`: *<includePattern>* and `/e`: *<excludePattern>* options in the same command. When both include and exclude patterns are used on the command line, include patterns take precedence over exclude patterns. | -| **/e**:*<excludePattern>* | Specifies a pattern for files to omit from the extraction. You can specify more than one pattern. Separate patterns with a comma or a semicolon. You can use `/i`: *<includePattern>* and `/e`: *<excludePattern>* options in the same command. When both include and exclude patterns are used on the command line, include patterns take precedence over exclude patterns. | -| **/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:
  • **0** - Only the default errors and warnings are enabled.
  • **1** - Enables verbose output.
  • **4** - Enables error and status output.
  • **5** - Enables verbose and status output.
  • **8** - Enables error output to a debugger.
  • **9** - Enables verbose output to a debugger.
  • **12** - Enables error and status output to a debugger.
  • **13** - Enables verbose, status, and debugger output.
| -| **/decrypt***<AlgID>***/key**:*<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, you must also specify the `/key` or `/keyfile` option as follows:
  • *<AlgID>* specifies the cryptographic algorithm that was used to create the migration store on the `ScanState.exe` command line. If no algorithm is specified, **ScanState** and **UsmtUtils** use the 3DES algorithm as a default.
    *<AlgID>* valid values include: `AES_128`, `AES_192`, `AES_256`, `3DES`, or `3DES_112`.
  • `/key`: *<KeyString>* specifies the encryption key. If there's a space in *<KeyString>*, you must surround the argument with quotation marks.
  • `/keyfile`:*<FileName>* specifies a text (.txt) file that contains the encryption key

For more information about supported encryption algorithms, see [Migration store encryption](usmt-migration-store-encryption.md). | +| *\* | Path to the USMT migration store.

For example:
`D:\MyMigrationStore\USMT\store.mig` | +| *\* | Path to the folder where the tool puts the individual files. | +| **/i**:*\* | Specifies a pattern for files to include in the extraction. More than one pattern can be specified. Separate patterns with a comma or a semicolon. The `/i`: *\* and `/e`: *\* options can be used in the same command. When both include and exclude patterns are used on the command line, include patterns take precedence over exclude patterns. | +| **/e**:*\* | Specifies a pattern for files to omit from the extraction. More than one pattern can be specified. Separate patterns with a comma or a semicolon. The `/i`: *\* and `/e`: *\* options can be used in the same command. When both include and exclude patterns are used on the command line, include patterns take precedence over exclude patterns. | +| **/l**:*\* | Specifies the location and name of the log file. | +| **/v:***\* | **(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:
  • **0** - Only the default errors and warnings are enabled.
  • **1** - Enables verbose output.
  • **4** - Enables error and status output.
  • **5** - Enables verbose and status output.
  • **8** - Enables error output to a debugger.
  • **9** - Enables verbose output to a debugger.
  • **12** - Enables error and status output to a debugger.
  • **13** - Enables verbose, status, and debugger output.
| +| **/decrypt***\***/key**:*\*
or
**/decrypt***\***/**:*\<"Key String"\>*
or
**/decrypt:***\***/keyfile**:*\* | Specifies that the `/encrypt` option was used to create the migration store with the **ScanState** tool. To decrypt the migration store, the `/key` or `/keyfile` option must also be specified as follows:
  • *\* specifies the cryptographic algorithm that was used to create the migration store on the `ScanState.exe` command line. If no algorithm is specified, **ScanState** and **UsmtUtils** use the 3DES algorithm as a default.
    *\* valid values include: `AES_128`, `AES_192`, `AES_256`, `3DES`, or `3DES_112`.
  • `/key`: *\* specifies the encryption key. If there's a space in *\*, the argument must be surrounded with quotation marks.
  • `/keyfile`:*\* specifies a text (.txt) file that contains the encryption key

For more information about supported encryption algorithms, see [Migration store encryption](usmt-migration-store-encryption.md). | | **/o** | Overwrites existing output files. | Some examples of `/extract` commands: @@ -94,6 +97,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..0ae37eaea0 100644 --- a/windows/deployment/usmt/usmt-what-does-usmt-migrate.md +++ b/windows/deployment/usmt/usmt-what-does-usmt-migrate.md @@ -1,28 +1,31 @@ --- -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: 01/03/2024 ms.topic: article ms.technology: itpro-deploy +appliesto: + - ✅ Windows 11 + - ✅ Windows 10 --- # What does USMT migrate? ## 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. -- **MigDocs.XML** - Rules that use the **MigXmlHelper.GenerateDocPatterns** helper function, which can be used to automatically find user documents on a computer without the need to author extensive custom migration .xml files. +- **MigDocs.XML** - Rules that use the **MigXmlHelper.GenerateDocPatterns** helper function, which can be used to automatically find user documents on a computer without the need to author extensive custom migration **.xml** files. - **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 +36,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 folder items: - - My Documents + - Documents. - - My Video + - Videos. - - My Music + - Music. - - My Pictures + - 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,161 +74,120 @@ 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 -USMT migrates operating-system components to a destination computer from computers running Windows 7 and Windows 8 +USMT migrates operating-system components to a destination computer. The following components are migrated by default using the manifest files: -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. To view what groups a user belongs to: -- 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. + 1. Right-clicking on the Start menu and then selecting **Computer Management**. + 1. In the **Computer Management** console, expand **System tools** > **Local Users and Groups** > **Groups**. + 1. Inspect the individual groups in the results pane to see what users belong to what groups. + + The use of a **\** section in the `Config.xml` file is required when running an offline migration. -- 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 +195,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 the **ScanState** and **LoadState** tools are run, 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 +217,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..b47b672f77 100644 --- a/windows/deployment/usmt/usmt-xml-elements-library.md +++ b/windows/deployment/usmt/usmt-xml-elements-library.md @@ -1,40 +1,47 @@ --- -title: XML Elements Library (Windows 10) -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). +title: XML Elements Library +description: Learn about the XML elements and helper functions that can be employed to author migration .xml files to use with User State Migration Tool (USMT). manager: aaroncz ms.author: frankroj ms.prod: windows-client author: frankroj -ms.date: 11/01/2022 +ms.date: 01/03/2024 ms.topic: article ms.technology: itpro-deploy +appliesto: + - ✅ Windows 11 + - ✅ Windows 10 --- # 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 can be employed to author migration **.xml** files to use with User State Migration Tool (USMT). This article assumes a basic knowledge of XML. -In addition to XML elements and helper functions, this article describes how to specify encoded locations and locations patterns, functions that are for internal USMT use only, 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 can be used with helper functions. ## Elements and helper functions -The following table describes the XML elements and helper functions you can use with USMT. +The following table describes the XML elements and helper functions can be used with USMT. | Elements A-K | Elements L-Z | Helper functions | |-----|----|-----| -| [<addObjects>](#addobjects)
[<attributes>](#attributes)
[<bytes>](#bytes)
[<commandLine>](#commandline)
[<component>](#component)
[<condition>](#condition)
[<conditions>](#conditions)
[<content>](#content)
[<contentModify>](#contentmodify)
[<description>](#description)
[<destinationCleanup>](#destinationcleanup)
[<detect>](#detect)
[<detects>](#detects)
[<detection>](#detection)
[<displayName>](#displayname)
[<environment>](#environment)
[<exclude>](#exclude)
[<excludeAttributes>](#excludeattributes)
[<extensions>](#extensions)
[<extension>](#extension)
[<externalProcess>](#externalprocess)
[<icon>](#icon)
[<include>](#include)
[<includeAttribute>](#includeattributes) | [<library>](#library)
[<location>](#location)
[<locationModify>](#locationmodify)
[<_locDefinition>](#_locdefinition)
[<manufacturer>](#manufacturer)
[<merge>](#merge)
[<migration>](#migration)
[<namedElements>](#namedelements)
[<object>](#object)
[<objectSet>](#objectset)
[<path>](#path)
[<paths>](#paths)
[<pattern>](#pattern)
[<processing>](#processing)
[<plugin>](#plugin)
[<role>](#role)
[<rules>](#rules)
[<script>](#script)
[<text>](#text)
[<unconditionalExclude>](#unconditionalexclude)
[<variable>](#variable)
[<version>](#version)
[<windowsObjects>](#windowsobjects) | [<condition> functions](#condition-functions)
[<content> functions](#content-functions)
[<contentModify> functions](#contentmodify-functions)
[<include> and <exclude> filter functions](#include-and-exclude-filter-functions)
[<locationModify> functions](#locationmodify-functions)
[<merge> functions](#merge-functions)
[<script> functions](#script-functions)
[Internal USMT functions](#internal-usmt-functions) | +| [\](#addobjects)
[\](#attributes)
[\](#bytes)
[\](#commandline)
[\](#component)
[\](#condition)
[\](#conditions)
[\](#content)
[\](#contentmodify)
[\](#description)
[\](#destinationcleanup)
[\](#detect)
[\](#detects)
[\](#detection)
[\](#displayname)
[\](#environment)
[\](#exclude)
[\](#excludeattributes)
[\](#extensions)
[\](#extension)
[\](#externalprocess)
[\](#icon)
[\](#include)
[\](#includeattributes) | [\](#library)
[\](#location)
[\](#locationmodify)
[\<_locDefinition\>](#_locdefinition)
[\](#manufacturer)
[\](#merge)
[\](#migration)
[\](#namedelements)
[\](#object)
[\](#objectset)
[\](#path)
[\](#paths)
[\](#pattern)
[\](#processing)
[\](#plugin)
[\](#role)
[\](#rules)
[\](#script)
[\](#text)
[\](#unconditionalexclude)
[\](#variable)
[\](#version)
[\](#windowsobjects) | [\ functions](#condition-functions)
[\ functions](#content-functions)
[\ functions](#contentmodify-functions)
[\ and \ filter functions](#include-and-exclude-filter-functions)
[\ functions](#locationmodify-functions)
[\ functions](#merge-functions)
[\ functions](#script-functions)
[Internal USMT functions](#internal-usmt-functions) | -## <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 **\** element emulates the existence of one or more objects on the source computer. The child **\** elements provide the details of the emulated objects. If the content is a **\** element, the result of the invocation is an array of objects. - **Number of occurrences:** unlimited -- **Parent elements:** [<rules>](#rules) +- **Parent elements:** [\](#rules) -- **Required child elements:** [<object>](#object) In addition, you must specify [<location>](#location) and [<attribute>](#attributes) as child elements of this **<object>** element. +- **Required child elements:** [\](#object) In addition, [\](#location) and [\](#attributes) must be specified as child elements of this **\** element. -- **Optional child elements:** [<conditions>](#conditions), [<condition>](#condition), [<script>](#script) +- **Optional child elements:** [\](#conditions), [\](#condition), [\](#script) Syntax: @@ -48,25 +55,25 @@ The following example is from the `MigApp.xml` file: ```xml - %HklmWowSoftware%\Microsoft\Office\12.0\Common\Migration\Office [UpgradeVersion] + %HklmWowSoftware%\Microsoft\Office\16.0\Common\Migration\Office [UpgradeVersion] DWORD 0B000000 - %HklmWowSoftware%\Microsoft\Office\12.0\Common\Migration\Office [Lang] + %HklmWowSoftware%\Microsoft\Office\16.0\Common\Migration\Office [Lang] DWORD 00000000 ``` -## <attributes> +## \ -The **<attributes>** element defines the attributes for a registry key or file. +The **\** element defines the attributes for a registry key or file. -- **Number of occurrences:** once for each [<object>](#object) +- **Number of occurrences:** once for each [\](#object) -- **Parent elements:** [<object>](#object) +- **Parent elements:** [\](#object) - **Child elements:** none @@ -78,25 +85,25 @@ Syntax: | Setting | Required? | Value | |------|-----|----| -| *Content* | Yes | The content depends on the type of object specified.
  • For files, the content can be a string containing any of the following attributes separated by commas:
    • Archive
    • Read-only
    • System
    • Hidden
  • For registry keys, the content can be one of the following types:
    • None
    • String
    • ExpandString
    • Binary
    • Dword
    • REG_SZ
| +| *Content* | Yes | The content depends on the type of object specified.
  • For files, the content can be a string containing any of the following attributes separated by commas:
    • Archive
    • Read-only
    • System
    • Hidden
  • For registry keys, the content can be one of the following types:
    • None
    • String
    • ExpandString
    • Binary
    • Dword
    • REG_SZ
| The following example is from the `MigApp.xml` file: ```xml - %HklmWowSoftware%\Microsoft\Office\12.0\Common\Migration\Office [Lang] + %HklmWowSoftware%\Microsoft\Office\16.0\Common\Migration\Office [Lang] DWORD 00000000 ``` -## <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. +The **\** element can only be specified for files because, if **\** corresponds to a registry key or a directory, then **\** is ignored. - **Number of occurrences:** zero or one -- **Parent elements:** [<object>](#object) +- **Parent elements:** [\](#object) - **Child elements:** none @@ -109,26 +116,26 @@ Syntax: |Setting|Required?|Value| |--- |--- |--- | |string|No, default is No|Determines whether *Content* should be interpreted as a string or as bytes.| -|expand|No (default = Yes|When the expand parameter is **Yes**, the content of the **<bytes>** element is first expanded in the context of the source computer and then interpreted.| -|*Content*|Yes|Depends on the value of the string.
  • When the string is **Yes**: the content of the **<bytes>** element is interpreted as a string.
  • When the string is **No**: the content of the **<bytes>** element is interpreted as bytes. Each two characters represent the hexadecimal value of a byte. For example, `616263` is the representation for the `abc` ANSI string. A complete representation of the UNICODE string `abc` including the string terminator would be: `6100620063000000`.
| +|expand|No (default = Yes|When the expand parameter is **Yes**, the content of the **\** element is first expanded in the context of the source computer and then interpreted.| +|*Content*|Yes|Depends on the value of the string.
  • When the string is **Yes**: the content of the **\** element is interpreted as a string.
  • When the string is **No**: the content of the **\** element is interpreted as bytes. Every two characters represent the hexadecimal value of a byte. For example, `616263` is the representation for the `abc` ANSI string. A complete representation of the UNICODE string `abc` including the string terminator would be: `6100620063000000`.
| The following example is from the `MigApp.xml` file: ```xml - %HklmWowSoftware%\Microsoft\Office\12.0\Common\Migration\Office [Lang] + %HklmWowSoftware%\Microsoft\Office\16.0\Common\Migration\Office [Lang] DWORD 00000000 ``` -## <commandLine> +## \ -You might want to use the **<commandLine>** element if you want to start or stop a service or application before or after you run the **ScanState** and **LoadState** tools. +The **\** element might be used to start or stop a service or application before or after running the **ScanState** and **LoadState** tools. - **Number of occurrences:** unlimited -- **Parent elements:** [<externalProcess>](#externalprocess) +- **Parent elements:** [\](#externalprocess) - **Child elements:** none @@ -142,22 +149,22 @@ Syntax: |--- |--- |--- | |*CommandLineString*|Yes|A valid command line.| -## <component> +## \ -The **<component>** element is required in a custom .xml file. This element defines the most basic construct of a migration .xml file. For example, in the `MigApp.xml` file, "Microsoft Office 2003" is a component that contains another component, "Microsoft Office Access 2003". You can use the child elements to define the component. +The **\** element is required in a custom **.xml** file. This element defines the most basic construct of a migration **.xml** file. For example, in the `MigApp.xml` file, **Microsoft Office 2016** is a component that contains another component, **Microsoft Office Access 2016**. The child elements can be used to define the component. -A component can be nested inside another component; that is, the **<component>** element can be a child of the **<role>** element within the **<component>** element in two cases: +A component can be nested inside another component; that is, the **\** element can be a child of the **\** element within the **\** element in two cases: -1. When the parent **<component>** element is a container -2. If the child **<component>** element has the same role as the parent **<component>** element. +1. When the parent **\** element is a container +1. If the child **\** element has the same role as the parent **\** element. - **Number of occurrences:** Unlimited -- **Parent elements:** [<migration>](#migration), [<role>](#role) +- **Parent elements:** [\](#migration), [\](#role) -- **Required child elements:** [<role>](#role), [<displayName>](#displayname) +- **Required child elements:** [\](#role), [\](#displayname) -- **Optional child elements:** [<manufacturer>](#manufacturer), [<version>](#version), [<description>](#description), [<paths>](#paths), [<icon>](#icon), [<environment>](#environment), [<extensions>](#extensions) +- **Optional child elements:** [\](#manufacturer), [\](#version), [\](#description), [\](#paths), [\](#icon), [\](#environment), [\](#extensions) Syntax: @@ -169,26 +176,26 @@ hidden="Yes|No"> |Setting|Required?|Value| |--- |--- |--- | -| type | Yes | You can use the following to group settings, and define the type of the component.
  • **System:** Operating system settings. All Windows components are defined by this type.
    When **type="System"** and **defaultSupported="FALSE"** the settings will not migrate unless there is an equivalent component in the .xml files that is specified on the `LoadState.exe` command line. For example, the default `MigSys.xml` file contains components with **type="System"** and **defaultSupported="FALSE"**. If you specify this file on the `ScanState.exe` command line, you must also specify the file on the `LoadState.exe` command line for the settings to migrate. This is because the `LoadState.exe` tool must detect an equivalent component. That is, the component must have the same migration urlid of the .xml file and an identical display name. Otherwise, the **LoadState** tool 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.
  • **Application:** Settings for an application.
  • **Device:** Settings for a device.
  • **Documents:** Specifies files.
| -| context | No
Default = UserAndSystem | Defines the scope of this parameter; that is, whether to process this component in the context of the specific user, across the entire operating system, or both.
The largest possible scope is set by the **<component>** element. For example, if a **<component>** element has a context of **User** and a **<rules>** element had a context of **UserAndSystem**, then the **<rules>** element would act as though it has a context of **User**. If a **<rules>** element has a context of **System**, it would act as though the **<rules>** element is not there.
  • **User**: Evaluates the component for each user.
  • **System**: Evaluates the component only once for the system.
  • **UserAndSystem**: Evaluates the component for the entire operating system and each user.
| -| defaultSupported | No
(default = TRUE) | Can be any of **TRUE**, **FALSE**, **YES**, or **NO**. If this parameter is **FALSE** (or **NO**), the component 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 | The following items can be used to group settings, and define the type of the component.
  • **System:** Operating system settings. All Windows components are defined by this type.
    When **type="System"** and **defaultSupported="FALSE"**, the settings don't migrate unless there's an equivalent component in the **.xml** files that is specified on the `LoadState.exe` command line. For example, the default `MigSys.xml` file contains components with **type="System"** and **defaultSupported="FALSE"**. If this file is specified on the `ScanState.exe` command line, the file must also be specified on the `LoadState.exe` command line for the settings to migrate. The file must be specified because the `LoadState.exe` tool must detect an equivalent component. That is, the component must have the same migration urlid of the **.xml** file and an identical display name. Otherwise, the **LoadState** tool doesn't migrate those settings from the store. This setting is helpful because a store can be used for destination computers that are the same or different version of Windows as the source computer.
  • **Application:** Settings for an application.
  • **Device:** Settings for a device.
  • **Documents:** Specifies files.
| +| context | No
Default = UserAndSystem | Defines the scope of this parameter; that is, whether to process this component in the context of the specific user, across the entire operating system, or both.
The largest possible scope is set by the **\** element. For example, if a **\** element has a context of **User** and a **\** element had a context of **UserAndSystem**, then the **\** element would act as though it has a context of **User**. If a **\** element has a context of **System**, it would act as though the **\** element isn't there.
  • **User**: Evaluates the component for each user.
  • **System**: Evaluates the component only once for the system.
  • **UserAndSystem**: Evaluates the component for the entire operating system and each user.
| +| defaultSupported | No
(default = TRUE) | Can be any of **TRUE**, **FALSE**, **YES**, or **NO**. If this parameter is **FALSE** (or **NO**), the component isn't migrated unless there's an equivalent component on the destination computer.
When **type="System"** and **defaultSupported="FALSE"**, the settings aren't migrated unless there's an equivalent component in the **.xml** files that are specified on the `LoadState.exe` command line. For example, the default `MigSys.xml` file contains components with **type="System"** and **defaultSupported="FALSE"**. If this file is specified on the `ScanState.exe` command line, the file must also be specified on the `LoadState.exe` command line for the settings to migrate. The file has to be specified in both command lines because the **LoadState** tool must detect an equivalent component. That is, the component must have the same migration urlid of the **.xml** file and an identical display name or the **LoadState** tool doesn't migrate those settings from the store. This setting is helpful because a store can be used for destination computers that are the same or different version of Windows as the source computer. | | hidden | | This parameter is for internal USMT use only. | -For an example, see any of the default migration .xml files. +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 **\** element under the **\**, **\**, and **\** elements is still supported, Microsoft recommends to no longer use the **\** element because it might be deprecated in future versions of USMT. If the **\** element is deprecated, it would require a rewrite of any scripts that use the **\** element. Instead, if a condition needs to be used within the **\** and **\** elements, Microsoft recommends using the more powerful **[\](#conditions)** element. The **\** element allows for formulation of complex Boolean statements. -The **<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 **\** element has a Boolean result. This element can be used to specify the conditions in which the parent element is evaluated. If any of the present conditions return **FALSE**, the parent element isn't be evaluated. - **Number of occurrences:** unlimited. -- **Parent elements:** [<conditions>](#conditions), [<detect>](#detect), [<objectSet>](#objectset), [<addObjects>](#addobjects) +- **Parent elements:** [\](#conditions), [\](#detect), [\](#objectset), [\](#addobjects) - **Child elements:** none -- **Helper functions:** You can use the following [<condition> functions](#condition-functions) with this element: `DoesOSMatch`, `IsNative64Bit()`, `IsOSLaterThan`, `IsOSEarlierThan`, `DoesObjectExist`, `DoesFileVersionMatch`, `IsFileVersionAbove`, `IsFileVersionBelow`, `IsSystemContext`, `DoesStringContentEqual`, `DoesStringContentContain`, `IsSameObject`, `IsSameContent`, and `IsSameStringContent`. +- **Helper functions:** The following [\ functions](#condition-functions) can be used with this element: `DoesOSMatch`, `IsNative64Bit()`, `IsOSLaterThan`, `IsOSEarlierThan`, `DoesObjectExist`, `DoesFileVersionMatch`, `IsFileVersionAbove`, `IsFileVersionBelow`, `IsSystemContext`, `DoesStringContentEqual`, `DoesStringContentContain`, `IsSameObject`, `IsSameContent`, and `IsSameStringContent`. Syntax: @@ -198,10 +205,10 @@ 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.| +|negation|No
Default = No|**"Yes"** reverses the True/False value of the condition.| +|*ScriptName*|Yes|A script that is defined within this migration section.| -For example, in the 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 **\** elements, **A** and **B**, are joined together by the **AND** operator because they are in separate **\** sections: ```xml @@ -214,7 +221,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 **\** elements, **A** and **B**, are joined together by the **OR** operator because they are in the same **\** section. ```xml @@ -225,9 +232,9 @@ However, in the code sample below, the **<condition>** elements, **A** and ``` -### <condition> functions +### \ functions -The **<condition>** functions return a Boolean value. You can use these elements in **<addObjects>** conditions. +The **\** functions return a Boolean value. These elements can be used in **\** conditions. - [Operating system version functions](#operating-system-version-functions) @@ -243,8 +250,8 @@ The **<condition>** functions return a Boolean value. You can use these el |Setting|Required?|Value| |--- |--- |--- | - |*OSType*|Yes|The only valid value for this setting is **NT**. Note, however, that you must set this setting for the **<condition>** functions to work correctly.| - |*OSVersion*|Yes|The major version, minor version, build number and corrected service diskette version separated by periods. For example, `5.0.2600.Service Pack 1`. You can also specify partial specification of the version with a pattern such as `5.0.*`.| + |*OSType*|Yes|The only valid value for this setting is **NT**. However, this setting must be set for the **\** functions to work correctly.| + |*OSVersion*|Yes|The major version, minor version, build number and corrected service diskette version separated by periods. For example, `5.0.2600.Service Pack 1`. Partial specification of the version can also be specified with a pattern such as `5.0.*`.| For example: @@ -264,8 +271,8 @@ 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**.| - |*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*.| + |*OSType*|Yes|Can be **9x** or **NT**. If *OSType* doesn't match the type of the current operating system, then it returns **FALSE**. For example, if the current operating system is Windows NT-based and *OSType* is **"9x"**, the result is **FALSE**.| + |*OSVersion*|Yes|The major version, minor version, build number, and corrected service diskette version separated by periods. For example, `5.0.2600.Service Pack 1`. Partial specification of the version can also be specified but no pattern is allowed such as `5.0`.

The **IsOSLaterThan** function returns **TRUE** if the current operating system is later than or equal to *OSVersion*.| For example: @@ -281,8 +288,8 @@ 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**.| - |*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*.| + |*OSType*|Yes|Can be **9x** or **NT**. If *OSType* doesn't match the type of the current operating system, then it returns **FALSE**. For example, if the current operating system is Windows NT-based and *OSType* is **"9x"** the result is **FALSE**.| + |*OSVersion*|Yes|The major version, minor version, build number, and corrected service diskette version separated by periods. For example, `5.0.2600.Service Pack 1`. Partial specification of the version can also be specified but no pattern is allowed such as `5.0`.

The **IsOSEarlierThan** function returns **TRUE** if the current operating system is earlier than *OSVersion*.| ### Object content functions @@ -307,8 +314,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 +332,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. A pattern can't be specified.| - **IsFileVersionBelow** @@ -335,9 +342,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. A pattern can't be specified.| - **IsSystemContext** @@ -354,8 +361,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. Environment variables can be specified.| + |StringContent|Yes|The string that is checked against.| For example: @@ -372,8 +379,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. Environment variables can be specified.| + |*StrToFind*|Yes|A string that is searched inside the content of the given object.| - **IsSameObject** @@ -384,8 +391,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.| - |*EncodedLocation1*|Yes|The **[encoded location](#specifying-locations)** for the first object. You can specify environment variables.| - |*EncodedLocation2*|Yes|The **[encoded location](#specifying-locations)** for the second object. You can specify environment variables.| + |*EncodedLocation1*|Yes|The **[encoded location](#specifying-locations)** for the first object. Environment variables can be specified.| + |*EncodedLocation2*|Yes|The **[encoded location](#specifying-locations)** for the second object. Environment variables can be specified.| For example: @@ -398,39 +405,39 @@ 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")` |Setting|Required?|Value| |--- |--- |--- | |*ObjectType1*|Yes|Defines the type of the first object. Can be File or Registry.| - |*EncodedLocation1*|Yes|The **[encoded location](#specifying-locations)** for the first object. You can specify environment variables.| + |*EncodedLocation1*|Yes|The **[encoded location](#specifying-locations)** for the first object. Environment variables can be specified.| |*ObjectType2*|Yes|Defines the type of the second object. Can be File or Registry.| - |*EncodedLocation2*|Yes|The **[encoded location](#specifying-locations)** for the second object. You can specify environment variables.| + |*EncodedLocation2*|Yes|The **[encoded location](#specifying-locations)** for the second object. Environment variables can be specified.| - **IsSameStringContent** - The **IsSameStringContent** function returns **TRUE** if the given objects have the same content. Otherwise, it returns **FALSE**. The content 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")` |Setting|Required?|Value| |--- |--- |--- | |*ObjectType1*|Yes|Defines the type of the first object. Can be File or Registry.| - |*EncodedLocation1*|Yes|The **[encoded location](#specifying-locations)** for the first object. You can specify environment variables.| + |*EncodedLocation1*|Yes|The **[encoded location](#specifying-locations)** for the first object. Environment variables can be specified.| |*ObjectType2*|Yes|Defines the type of the second object. Can be File or Registry.| - |*EncodedLocation2*|Yes|The **[encoded location](#specifying-locations)** for the second object. You can specify environment variables.| + |*EncodedLocation2*|Yes|The **[encoded location](#specifying-locations)** for the second object. Environment variables can be specified.| -## <conditions> +## \ -The **<conditions>** element returns a Boolean result that is used to specify the conditions in which the parent element is evaluated. USMT evaluates the child elements, and then joins their results using the operators **AND** or **OR** according to the operation parameter. +The **\** element returns a Boolean result that is used to specify the conditions in which the parent element is evaluated. USMT evaluates the child elements, and then joins their results using the operators **AND** or **OR** according to the operation parameter. -- **Number of occurrences:** Unlimited inside another **<conditions>** element. Limited to one occurrence in [<detection>](#detection), [<rules>](#rules), [<addObjects>](#addobjects), and [<objectSet>](#objectset) +- **Number of occurrences:** Unlimited inside another **\** element. Limited to one occurrence in [\](#detection), [\](#rules), [\](#addobjects), and [\](#objectset) -- **Parent elements:** [<conditions>](#conditions), [<detection>](#detection), [<environment>](#environment), [<rules>](#rules), [<addObjects>](#addobjects), and [<objectSet>](#objectset) +- **Parent elements:** [\](#conditions), [\](#detection), [\](#environment), [\](#rules), [\](#addobjects), and [\](#objectset) -- **Child elements:** [<conditions>](#conditions), [<condition>](#condition) +- **Child elements:** [\](#conditions), [\](#condition) Syntax: @@ -456,17 +463,17 @@ The following example is from the `MigApp.xml` file: ``` -## <content> +## \ -You can use the **<content>** element to specify a list of object patterns to obtain an object set from the source computer. Each **<objectSet>** within a **<content>** element is evaluated. For each resulting object pattern list, the objects that match it are enumerated and their content is filtered by the filter parameter. The resulting string array is the output for the **<content>** element. The filter script returns an array of locations. The parent **<objectSet>** element can contain multiple child **<content>** elements. +The **\** element can be used to specify a list of object patterns to obtain an object set from the source computer. Each **\** within a **\** element is evaluated. For each resulting object pattern list, the objects that match it are enumerated and their content is filtered by the filter parameter. The resulting string array is the output for the **\** element. The filter script returns an array of locations. The parent **\** element can contain multiple child **\** elements. - **Number of occurrences:** unlimited -- **Parent elements:** [<objectSet>](#objectset) +- **Parent elements:** [\](#objectset) -- **Child elements:** [<objectSet>](#objectset) +- **Child elements:** [\](#objectset) -- **Helper functions:** You can use the following [<content> functions](#content-functions) with this element: `ExtractSingleFile`, `ExtractMultipleFiles`, and `ExtractDirectory`. +- **Helper functions:** The following [\ functions](#content-functions) can be used with this element: `ExtractSingleFile`, `ExtractMultipleFiles`, and `ExtractDirectory`. Syntax: @@ -477,22 +484,22 @@ 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 **\** rule. The filter script returns a Boolean value. If the return value is **TRUE**, the object is migrated. If it's **FALSE**, it isn't migrated.| -### <content> functions +### \ functions -The following functions generate patterns out of the content of an object. These functions are called for every object that the parent **<ObjectSet>** element is enumerating. +The following functions generate patterns out of the content of an object. These functions are called for every object that the parent **\** element is enumerating. - **ExtractSingleFile** - 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**.| + |*Separators*|Yes|A list of possible separators that might follow the file specification in this registry value name. For example, if the content is **"C:\Windows\Notepad.exe,-2"**, the separator is a comma. **NULL** can be specified.| + |*PathHints*|Yes|A list of extra paths, separated by colons (`;`), where the function looks for a file matching the current content. For example, if the content is **"Notepad.exe"** and the path is the **%Path%** environment variable, the function finds **Notepad.exe** in `%windir%` and returns **"c:\Windows [Notepad.exe]"**. **NULL** can be specified.| For example: @@ -508,27 +515,27 @@ The following functions generate patterns out of the content of an object. These - **ExtractMultipleFiles** - The **ExtractMultipleFiles** function returns multiple patterns, one for each file that is found in the content of the given registry value. If the registry value is a **MULTI-SZ**, the **MULTI-SZ** separator is considered a separator by default. therefore, for **MULTI-SZ**, the **<Separators>** argument must be **NULL**. + The **ExtractMultipleFiles** function returns multiple patterns, one for each file that is found in the content of the given registry value. If the registry value is a **MULTI-SZ**, the **MULTI-SZ** separator is considered a separator by default. therefore, for **MULTI-SZ**, the **\** argument must be **NULL**. - The returned patterns are the encoded locations for files that must exist on the source computer. If the specification is correct in the registry value but the file 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]"**. **NULL** can be specified.| - **ExtractDirectory** - The **ExtractDirectory** function returns a pattern that is the encoded location for a directory that must exist on the source computer. If the specification is correct in the registry value, but the directory 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)` |Setting|Required?|Value| |--- |--- |--- | - |*Separators*|No|A list of possible separators that might follow the file specification in this registry value name. For example, if the content is **"C:\Windows\Notepad.exe,-2"**, the separator is a comma. You must specify **NULL** when processing **MULTI-SZ** registry values.| - |*LevelsToTrim*|Yes|The number of levels to delete from the end of the directory specification. Use this function to extract a root directory when you have a registry value that points inside that root directory in a known location.| + |*Separators*|No|A list of possible separators that might follow the file specification in this registry value name. For example, if the content is **"C:\Windows\Notepad.exe,-2"**, the separator is a comma. **NULL** must be specified when processing **MULTI-SZ** registry values.| + |*LevelsToTrim*|Yes|The number of levels to delete from the end of the directory specification. Use this function to extract a root directory when there's a registry value that points inside that root directory in a known location.| |*PatternSuffix*|Yes|The pattern to add to the directory specification. For example, `* [*]`.| For example: @@ -543,17 +550,17 @@ The following functions generate patterns out of the content of an object. These ``` -## <contentModify> +## \ -The **<contentModify>** element modifies the content of an object before 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 **\** element modifies the content of an object before the object is written to the destination computer. For each **\** element, there can be multiple **\** elements. This element returns the new content of the object that is being processed. - **Number of occurrences:** Unlimited -- **Parent elements:** [<rules>](#rules) +- **Parent elements:** [\](#rules) -- **Required child elements:** [<objectSet>](#objectset) +- **Required child elements:** [\](#objectset) -- **Helper functions**: You can use the following [<contentModify> functions](#contentmodify-functions) with this element: **ConvertToDWORD**, **ConvertToString**, **ConvertToBinary**, **KeepExisting**, **OffsetValue**, **SetValueByTable**, **MergeMultiSzContent**, and **MergeDelimitedContent**. +- **Helper functions**: The following [\ functions](#contentmodify-functions) can be used with this element: **ConvertToDWORD**, **ConvertToString**, **ConvertToBinary**, **KeepExisting**, **OffsetValue**, **SetValueByTable**, **MergeMultiSzContent**, and **MergeDelimitedContent**. Syntax: @@ -564,31 +571,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 +### \ 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 **\** 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 **\** 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. **NULL** can be specified, and `0` is written if the conversion fails.| - **ConvertToString** - The **ConvertToString** function converts the content of registry values that match the parent **<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 **\** 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. **NULL** can be specified, and `0` is written if the conversion fails.| For example: @@ -602,7 +609,7 @@ The following functions change the content of objects as they are migrated. Thes - **ConvertToBinary** - The **ConvertToBinary** function converts the content of registry values that match the parent **<ObjectSet>** element to a binary type. + The **ConvertToBinary** function converts the content of registry values that match the parent **\** element to a binary type. Syntax: `ConvertToBinary ()` @@ -618,7 +625,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,48 +633,48 @@ 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. + The **KeepExisting** function can be used when there are conflicts on the destination computer. This function keeps (not overwrites) the specified attributes for the object that is on the destination computer. Syntax: `KeepExisting("OptionString","OptionString","OptionString",…)` |Setting|Required?|Value| |--- |--- |--- | - | *OptionString* | Yes | *OptionString* can be **Security**, **TimeFields**, or **FileAttrib**:*Letter*. 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.
  • **Security**: Keeps the destination object's security descriptor if it exists.
  • **TimeFields**: Keeps the destination object's time stamps. This parameter is for files only.
  • **FileAttrib:<Letter>**: Keeps the destination object's attribute value, either **ON** or **OFF**, for the specified set of file attributes. This parameter is for files only. The following are case-insensitive, but USMT will ignore any values that are invalid, repeated, or if there is a space after **FileAttrib:**. You can specify any combination of the following attributes:
    • **A** = Archive
    • **C** = Compressed
    • **E** = Encrypted
    • **H** = Hidden
    • **I** = Not Content Indexed
    • **O** = Offline
    • **R** = Read-Only
    • **S** = System
    • **T** = Temporary
| + | *OptionString* | Yes | *OptionString* can be **Security**, **TimeFields**, or **FileAttrib**:*Letter*. One of each type of *OptionStrings* can be specified. Don't specify multiple *OptionStrings* with the same value. If multiple *OptionStrings* with the same value are specified, the right-most option of that type is kept. For example, don't specify **("FileAttrib:H", "FileAttrib:R")** because only Read-only is evaluated. Instead specify **("FileAttrib:HR")** and both Hidden and Read-only attributes are kept on the destination computer.
  • **Security**: Keeps the destination object's security descriptor if it exists.
  • **TimeFields**: Keeps the destination object's time stamps. This parameter is for files only.
  • **FileAttrib:\**: Keeps the destination object's attribute value, either **ON** or **OFF**, for the specified set of file attributes. This parameter is for files only. The following are case-insensitive, but USMT will ignore any values that are invalid, repeated, or if there's a space after **FileAttrib:**. Any combination of the following attributes can be specified:
    • **A** = Archive
    • **C** = Compressed
    • **E** = Encrypted
    • **H** = Hidden
    • **I** = Not Content Indexed
    • **O** = Offline
    • **R** = Read-Only
    • **S** = System
    • **T** = Temporary
| - **MergeMultiSzContent** - The **MergeMultiSzContent** function merges the **MULTI-SZ** content of the registry values that are enumerated by the parent **<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 **\** 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:
  • **Add**. Adds the corresponding String to the resulting MULTI-SZ if it is not already there.
  • **Remove**. Removes the corresponding String from the resulting MULTI-SZ.
| + | *Instruction* | Yes | Can be one of the following values:
  • **Add**. Adds the corresponding String to the resulting MULTI-SZ if it isn't already there.
  • **Remove**. Removes the corresponding String from the resulting MULTI-SZ.
| | *String* | Yes | The string to be added or removed. | - **MergeDelimitedContent** - The **MergeDelimitedContent** function merges the content of the registry values that are enumerated by the parent **<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 **\** 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:
  • **Add**: Adds *String* to the resulting MULTI-SZ if it is not already there.
  • **Remove**: Removes *String* from the resulting MULTI-SZ.
| + | *Delimiters* | Yes | A single character that is used to separate the content of the object that is being processed. The content is considered as a list of elements that is separated by the *Delimiters*.
For example, `"."` separates the string based on a period. | + | *Instruction* | Yes | Can be one of the following values:
  • **Add**: Adds *String* to the resulting MULTI-SZ if it isn't already there.
  • **Remove**: Removes *String* from the resulting MULTI-SZ.
| | *String* | Yes | The string to be added or removed. | -## <description> +## \ -The **<description>** element defines a description for the component but does not affect the migration. +The **\** element defines a description for the component but doesn't affect the migration. - **Number of occurrences:** zero or one -- **Parent elements:** [<component>](#component) +- **Parent elements:** [\](#component) - **Child elements:** none @@ -681,26 +688,26 @@ Syntax: |--- |--- |--- | |*ComponentDescription*|Yes|The description of the component.| -The following code sample shows how the <description> element defines the "My custom component" description.: +The following code sample shows how the \ element defines the "My custom component" description: ```xml My custom component ``` -## <destinationCleanup> +## \ -The **<destinationCleanup>** element deletes objects, such as files and registry keys, from the destination computer before applying the objects from the source computer. This element is evaluated only when the **LoadState** tool is run on the destination computer. That is, this element is ignored by the **ScanState** tool. +The **\** element deletes objects, such as files and registry keys, from the destination computer before applying the objects from the source computer. This element is evaluated only when the **LoadState** tool is run on the destination computer. That is, this element is ignored by the **ScanState** tool. > [!IMPORTANT] > Use this option with extreme caution because it will delete objects from the destination computer. -For each **<destinationCleanup>** element there can be multiple **<objectSet>** elements. A common use for this element is if there 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 **\** element, there can be multiple **\** elements. A common use for this element is if there's a missing registry key on the source computer but the component still needs to be migrated. In this case, all of the component's registry keys can be deleted before migrating the source registry keys. Deleting all of the component's registry keys ensures that if there's a missing key on the source computer, it will also be missing on the destination computer. - **Number of occurrences:** Unlimited -- **Parent elements:** [<rules>](#rules) +- **Parent elements:** [\](#rules) -- **Child elements:** [<objectSet>](#objectset) (Note that the destination computer will delete all child elements.) +- **Child elements:** [\](#objectset) (The destination computer deletes all child elements.) Syntax: @@ -711,7 +718,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: @@ -724,21 +731,21 @@ 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 **\** element is still supported, Microsoft recommends no longer using the **\** element because it might be deprecated in future versions of USMT. If the **\** element is deprecated, it would require a rewrite of any scripts that use the **\** element. Instead, Microsoft recommends using the **[\](#detection)** element. The **\** element allows for more clearly formulated complex Boolean statements -The **<detect>** element can be used to determine if the component is present on a system. If all child **<detect>** elements within a **<detect>** element resolve to **TRUE**, then the **<detect>** element resolves to **TRUE**. If any child **<detect>** elements resolve to **FALSE**, then their parent **<detect>** element resolves to **FALSE**. If there is no **<detect>** element section, then USMT will assume that the component is present. +The **\** element can be used to determine if the component is present on a system. If all child **\** elements within a **\** element resolve to **TRUE**, then the **\** element resolves to **TRUE**. If any child **\** elements resolve to **FALSE**, then their parent **\** element resolves to **FALSE**. If there's no **\** element section, then USMT assumes that the component is present. -For each **<detect>** element there can be multiple child **<condition>** or **<objectSet>** elements, which 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 **\** element there can be multiple children **\** or **\** elements, which are logically joined by an **OR** operator. If at least one **\** or **\** element evaluates to **TRUE**, then the **\** element evaluates to **TRUE**. - **Number of occurrences:** unlimited -- **Parent elements:** [<detects>](#detects), [<namedElements>](#namedelements) +- **Parent elements:** [\](#detects), [\](#namedelements) -- **Required child elements:** [<condition>](#condition) +- **Required child elements:** [\](#condition) -- **Optional child elements:** [<objectSet>](#objectset) +- **Optional child elements:** [\](#objectset) Syntax: @@ -749,16 +756,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 **\** is a child to **\**
No, when **\** is a child to \ | When *ID* is specified, any child elements aren't processed. Instead, any other **\** elements with the same name that are declared within the **\** element are processed. | +| context | No
(default = UserAndSystem) | Defines the scope of this parameter, which is whether to process this component in the context of the specific user, across the entire operating system, or both.
The largest possible scope is set by the component element. For example, if a **\** element has a context of **User**, and a **\** element had a context of **UserAndSystem**, then the **\** element would act as though it had a context of **User**. If the **\** element had a context of **System**, it would act as though the **\** element weren't there.
  • **User**: Evaluates the variables for each user.
  • **System**: Evaluates the variables only once for the system.
  • **UserAndSystem**: Evaluates the variables for the entire operating system and each user.
| -For examples, see the examples for [<detection>](#detection). +For examples, see the examples for [\](#detection). -## <detects> +## \ -Although the **<detects>** element is still supported, 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 **\** element is still supported, Microsoft recommends no longer using the **\** element because it might be deprecated in future versions of USMT. If the **\** element is deprecated, it would require a rewrite of any scripts that use the **\** element. Instead, Microsoft recommends using the **[\](#detection)** element if the parent element is **\** or **\**, or use the **[\](#conditions)** element if the parent element is **\**. The **\** element allows for more clearly formulated complex Boolean statements and the **\** element allows for formulation of complex Boolean statements. -The **<detects>** element is a container for one or more **<detect>** elements. If all of the child **<detect>** elements within a **<detects>** element resolve to **TRUE**, then **<detects>** resolves to **TRUE**. If any of the child **<detect>** elements resolve to **FALSE**, then **<detects>** resolves to **FALSE**. If you 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 **\** element is a container for one or more **\** elements. If all of the child **\** elements within a **\** element resolve to **TRUE**, then **\** resolves to **TRUE**. If any of the child **\** elements resolve to **FALSE**, then **\** resolves to **FALSE**. To prevent the **\** element to be written within a component, create the **\** element under the **\** element, and then refer to it. If there's no **\** element section, then USMT assumes that the component is present. The results from each **\** element are joined together by the **OR** operator to form the rule used to detect the parent element. Syntax: @@ -769,14 +776,14 @@ Syntax: - **Number of occurrences:** Unlimited. -- **Parent elements:** [<role>](#role), [<rules>](#rules), [<namedElements>](#namedelements) +- **Parent elements:** [\](#role), [\](#rules), [\](#namedelements) -- **Required child elements:** [<detect>](#detect) +- **Required child elements:** [\](#detect) |Setting|Required?|Value| |--- |--- |--- | -| name | Yes, when <detects> is a child to **<namedElements>**
No, when <detects> is a child to **<role>** or **<rules>** | When *ID* is specified, no child **<detect>** elements are processed. Instead, any other **<detects>** elements with the same name that are declared within the **<namedElements>** element are processed. | -| context | No
(default = UserAndSystem) | Defines the scope of this parameter: whether to process this component in the context of the specific user, across the entire operating system, or both.
The largest possible scope is set by the **<component element>**. For example, if a **<component>** element has a context of **User** and a **<rules>** element had a context of **UserAndSystem**, then the **<rules>** element would act as though it had a context of **User**. If the **<rules>** element had a context of **System**, it would act as though the **<rules>** element 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. | +| name | Yes, when \ is a child to **\**
No, when \ is a child to **\** or **\** | When *ID* is specified, no child **\** elements are processed. Instead, any other **\** elements with the same name that are declared within the **\** element are processed. | +| context | No
(default = UserAndSystem) | Defines the scope of this parameter: whether to process this component in the context of the specific user, across the entire operating system, or both.
The largest possible scope is set by the **\**. For example, if a **\** element has a context of **User** and a **\** element had a context of **UserAndSystem**, then the **\** element would act as though it had a context of **User**. If the **\** element had a context of **System**, it would act as though the **\** element weren't there.
  • **User**: Evaluates the variables for each user.
  • **System**: Evaluates the variables only once for the system.
  • **UserAndSystem**: Evaluates the variables for the entire operating system and each user.

The context parameter is ignored for **\** elements that are inside **\** elements. | The following example is from the `MigApp.xml` file. @@ -791,19 +798,19 @@ The following example is from the `MigApp.xml` file. ``` -## <detection> +## \ -The **<detection>** element is a container for one **<conditions>** element. The result of the child **<condition>** elements, located underneath the **<conditions>** element, determines the result of this element. For example, if all of the child **<conditions>** elements within the **<detection>** element resolve to **TRUE**, then the **<detection>** element resolves to **TRUE**. If any of the child **<conditions>** elements resolve to **FALSE**, then the **<detection>** element resolves to **FALSE**. +The **\** element is a container for one **\** element. The result of the child **\** elements, located underneath the **\** element, determines the result of this element. For example, if all of the child **\** elements within the **\** element resolve to **TRUE**, then the **\** element resolves to **TRUE**. If any of the child **\** elements resolve to **FALSE**, then the **\** element resolves to **FALSE**. -In addition, the results from each **<detection>** section within the **<role>** element are joined together by the **OR** operator to form the detection rule of the parent element. That is, if one of the **<detection>** sections resolves to **TRUE**, then the **<role>** element will be processed. Otherwise, the **<role>** element will not be processed. +In addition, the results from each **\** section within the **\** element are joined together by the **OR** operator to form the detection rule of the parent element. That is, if one of the **\** sections resolve to **TRUE**, then the **\** element is processed. Otherwise, the **\** 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 **\** element under the **\** element to not write within a component. Then include a matching **\** section under the **\** element to control whether the component is migrated. If there isn't a **\** section for a component, then USMT assumes that the component is present. - **Number of occurrences:** Unlimited. -- **Parent elements:** [<role>](#role), [<namedElements>](#namedelements) +- **Parent elements:** [\](#role), [\](#namedelements) -- **Child elements:** [<conditions>](#conditions) +- **Child elements:** [\](#conditions) Syntax: @@ -814,7 +821,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 **\** is declared under **\**
  • Optional, when declared under **\**
| If declared, the content of the **\** element is ignored and the content of the **\** element with the same name that is declared in the **\** element is evaluated. | | context | No, default = UserAndSystem | Defines the scope of this parameter: whether to process this component in the context of the specific user, across the entire operating system, or both.
  • **User**: Evaluates the component for each user.
  • **System**: Evaluates the component only once for the system.
  • **UserAndSystem**: Evaluates the component for the entire operating system and each user.
| For example: @@ -840,13 +847,13 @@ and ``` -## <displayName> +## \ -The **<displayName>** element is a required field within each **<component>** element. +The **\** element is a required field within each **\** element. - **Number of occurrences:** once for each component -- **Parent elements:** [<component>](#component) +- **Parent elements:** [\](#component) - **Child elements:** none @@ -858,7 +865,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: @@ -867,17 +874,17 @@ For example: Command Prompt settings ``` -## <environment> +## \ -The **<environment>** element is a container for **<variable>** elements in which you can define variables to use in your .xml file. All environment variables defined this way 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 **\** element is a container for **\** elements in which variables can be defined for use in an **.xml** file. All environment variables defined this way are private. That is, they're available only for their child components and the component in which they were defined. For two example scenarios, see [Examples](#examples). - **Number of occurrences:** unlimited -- **Parent elements:** [<role>](#role), [<component>](#component), [<namedElements>](#namedelements) +- **Parent elements:** [\](#role), [\](#component), [\](#namedelements) -- **Required child elements:** [<variable>](#variable) +- **Required child elements:** [\](#variable) -- **Optional child elements:** [<conditions>](#conditions) +- **Optional child elements:** [\](#conditions) Syntax: @@ -888,14 +895,14 @@ 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.
| +| name | Yes, when **\** is a child of **\**
No, when **\** is a child of **\** or **\** | When declared as a child of the **\** or **\** elements, if *ID* is declared, USMT ignores the content of the **\** element and the content of the **\** element with the same name declared in the **\** element is processed. | +| context | No
(default = UserAndSystem) | Defines the scope of this parameter: whether to process this component in the context of the specific user, across the entire operating system, or both.
The largest possible scope is set by the **\** element. For example, if a **\** element has a context of **User** and a **\** element had a context of **UserAndSystem**, then the **\** element would act as though it had a context of **User**. If the **\** element had a context of **System**, it would act as though **\** weren't there.
  • **User**: Evaluates the variables for each user.
  • **System**: Evaluates the variables only once for the system.
  • **UserAndSystem**: Evaluates the variables for the entire operating system and each user.
| ## Examples ### Example scenario 1 -In this scenario, 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, generate the location of objects at run time depending on the configuration of the destination computer. For example, if an application writes data in the directory where the application is installed, and users can install the application anywhere on the computer. If the application writes a registry value `hklm\software\companyname\install [path\]` and then updates this value with the location where the application is installed, then the only way to migrate the required data correctly is to define an environment variable. For example: ```xml @@ -905,7 +912,7 @@ In this scenario, you want to generate the location of objects at run time depen ``` -Then you can use an include rule as follows. You can use any of the [<script> functions](#script-functions) to perform similar tasks. +Then an include rule can be used as follows. Any of the [\ functions](#script-functions) can be used to perform similar tasks. ```xml @@ -915,7 +922,7 @@ Then you can use an include rule as follows. You can use any of the [<script& ``` -Second, you can also filter registry values that contain data that you need. The following example extracts the first string (before the separator "`,`") in the value of the registry `Hklm\software\companyname\application\ [Path\]`. +Second, registry values can be filtered to contain the data that is needed. The following example extracts the first string (before the separator "`,`") in the value of the registry `Hklm\software\companyname\application\ [Path\]`. ```xml @@ -933,7 +940,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, five files named `File1.txt`, `File2.txt`, and so on, need to be migrated from `%SYSTEMDRIVE%\data\userdata\dir1\dir2\`. To migrate these files, the following **\** rule must be in an **.xml** file: ```xml @@ -947,7 +954,7 @@ In this scenario, you want to migrate five files named `File1.txt`, `File2.txt`, ``` -Instead of typing the path five times, you can create a variable for the location as follows: +Instead of typing the path five times, create a variable for the location as follows: ```xml @@ -957,7 +964,7 @@ Instead of typing the path five times, you can create a variable for the locatio ``` -Then, you can specify the variable in an **<include>** rule as follows: +Then, specify the variable in an **\** rule as follows: ```xml @@ -971,17 +978,17 @@ 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 **\** element determines what objects aren't migrated, unless there's a more specific **\** element that migrates an object. If there's an **\** and **\** element for the same object, the object is included. For each **\** element, there can be multiple child **\** elements. - **Number of occurrences:** Unlimited -- **Parent elements:** [<rules>](#rules) +- **Parent elements:** [\](#rules) -- **Child elements:** [<objectSet>](#objectset) +- **Child elements:** [\](#objectset) -- **Helper functions:** You can use the following [<exclude> filter functions](#include-and-exclude-filter-functions) with this element: `CompareStringContent`, `IgnoreIrrelevantLinks`, `AnswerNo`, `NeverRestore`, and `SameRegContent`. +- **Helper functions:** The following [\ filter functions](#include-and-exclude-filter-functions) can be used with this element: `CompareStringContent`, `IgnoreIrrelevantLinks`, `AnswerNo`, `NeverRestore`, and `SameRegContent`. Syntax: @@ -992,7 +999,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: @@ -1006,15 +1013,15 @@ 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. +The **\** element can be used to determine which parameters associated with an object aren't migrated. If there are conflicts between the **\** and **\** elements, the most specific pattern determines the patterns that aren't migrated. If an object doesn't have an **\** or **\** element, then all of its parameters are migrated. - **Number of occurrences:** Unlimited -- **Parent elements:** [<rules>](#rules) +- **Parent elements:** [\](#rules) -- **Child elements:** [<objectSet>](#objectset) +- **Child elements:** [\](#objectset) Syntax: @@ -1025,13 +1032,13 @@ Syntax: |Setting|Required?|Value| |--- |--- |--- | -| attributes | Yes | Specifies the attributes to be excluded. You can specify one of the following, or both separated by quotes; for example, `"Security","TimeFields"`:
  • Security can be one of Owner, Group, DACL, or SACL.
  • TimeFields can be one of CreationTime, LastAccessTime and LastWrittenTime
| +| attributes | Yes | Specifies the attributes to be excluded. Either one of the following or both can be specified. If specifying both, they need to be separated by quotes. For example, `"Security","TimeFields"`:
  • Security can be one of Owner, Group, DACL, or SACL.
  • TimeFields can be one of CreationTime, LastAccessTime and LastWrittenTime
| Example: ```xml - + System Data @@ -1078,15 +1085,15 @@ Example: ``` -## <extensions> +## \ -The <extensions> element is a container for one or more <extension> elements. +The \ element is a container for one or more \ elements. - **Number of occurrences:** zero or one -- **Parent elements:** [<component>](#component) +- **Parent elements:** [\](#component) -- **Required child elements:** [<extension>](#extension) +- **Required child elements:** [\](#extension) Syntax: @@ -1095,13 +1102,13 @@ Syntax: ``` -## <extension> +## \ -You can use the <extension> element to specify documents of a specific extension. +The \ element can be used to specify documents of a specific extension. - **Number of occurrences:** unlimited -- **Parent elements:** [<extensions>](#extensions) +- **Parent elements:** [\](#extensions) - **Child elements:** none @@ -1115,7 +1122,7 @@ Syntax: |--- |--- |--- | |*FilenameExtension*|Yes|A file name extension.| -For example, if you want to migrate all \*.doc files from the source computer, specifying the following code under the **<component>** element: +For example, to migrate all \*.doc files from the source computer, specifying the following code under the **\** element: ```xml @@ -1123,7 +1130,7 @@ For example, if you want to migrate all \*.doc files from the source computer, s ``` -is the same as specifying the following code below the **<rules>** element: +is the same as specifying the following code below the **\** element: ```xml @@ -1133,17 +1140,17 @@ is the same as specifying the following code below the **<rules>** element ``` -For another example of how to use the <extension> element, see the example for [<excludeAttributes>](#excludeattributes). +For another example of how to use the \ element, see the example for [\](#excludeattributes). -## <externalProcess> +## \ -You can use the <externalProcess> element to run a command line during the migration process. For example, you may want to run a command after the **LoadState** process completes. +The \ element can be used to run a command line during the migration process. For example, a run a command might need to run after the **LoadState** process completes. - **Number of occurrences:** Unlimited -- **Parent elements:** [<rules>](#rules) +- **Parent elements:** [\](#rules) -- **Required child elements:** [<commandLine>](#commandline) +- **Required child elements:** [\](#commandline) Syntax: @@ -1154,25 +1161,25 @@ 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). +For an example of how to use the \ element, see the example for [\](#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 **\** element determines what to migrate, unless there's a more specific [\](#exclude) rule. A script can be specified to be more specific to extend the definition of what want needs to be collected. For each **\** element, there can be multiple **\** elements. - **Number of occurrences:** Unlimited -- **Parent elements:** [<rules>](#rules) +- **Parent elements:** [\](#rules) -- **Required child element:** [<objectSet>](#objectset) +- **Required child element:** [\](#objectset) -- **Helper functions:** You can use the following [<include> filter functions](#include-and-exclude-filter-functions) with this element: `CompareStringContent`, `IgnoreIrrelevantLinks`, `AnswerNo`, and `NeverRestore`. +- **Helper functions:** The following [\ filter functions](#include-and-exclude-filter-functions) can be used with this element: `CompareStringContent`, `IgnoreIrrelevantLinks`, `AnswerNo`, and `NeverRestore`. Syntax: @@ -1183,9 +1190,9 @@ 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 **\** element are processed. | A script followed by any number of string arguments that are separated by a comma and enclosed in parenthesis. For example, `MyScripts.AScript ("Arg1","Arg2")`.
The script is called for each object that is enumerated by the object sets in the **\** rule. The filter script returns a Boolean value. If the return value is **TRUE**, the object is migrated. If it's **FALSE**, it isn't migrated. | -The following example is from the MigUser.xml file: +The following example is from the `MigUser.xml` file: ```xml @@ -1215,9 +1222,9 @@ The following example is from the MigUser.xml file: ``` -### <include> and **<exclude>** filter functions +### \ and **\** filter functions -The following functions return a Boolean value. You can use them to migrate certain objects based on when certain conditions are met. +The following functions return a Boolean value. They can be used to migrate certain objects based on when certain conditions are met. - **AnswerNo** @@ -1232,11 +1239,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 the **LoadState** tool runs. Syntax: `IgnoreIrrelevantLinks ()` @@ -1252,11 +1259,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. + This function can be used to collect the specified objects from the source computer but then not migrate the objects to the destination computer. When run with the **ScanState** tool, this function evaluates to **TRUE**. When run with the **LoadState** tool, this function evaluates to **FALSE**. This function might be used to check an object's value on the destination computer but there's no intention to migrate the object to the destination. Syntax: `NeverRestore()` - In the following example, HKCU\\Control Panel\\International \[Locale\] 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 @@ -1266,15 +1273,15 @@ The following functions return a Boolean value. You can use them to migrate cert ``` -## <includeAttributes> +## \ -You can use the **<includeAttributes>** element to determine whether certain parameters associated with an object 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. +The **\** element can be used to determine whether certain parameters associated with an object are migrated along with the object itself. If there are conflicts between the **\** and **\** elements, the most specific pattern determines which parameters are migrated. If an object doesn't have an **\** or **\** element, then all of its parameters are migrated. - **Number of occurrences:** unlimited -- **Parent elements:** [<rules>](#rules) +- **Parent elements:** [\](#rules) -- **Child elements:** [<objectSet>](#objectset) +- **Child elements:** [\](#objectset) Syntax: @@ -1285,23 +1292,23 @@ 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. Either one of the following or both can be specified. If specifying both, they need to be separated by quotes. For example, `"Security","TimeFields"`:
  • Security can be one of the following values:
    • **Owner**: The owner of the object (SID).
    • **Group**: The primary group for the object (SID).
    • **DACL** (discretionary access control list): An access control list that is controlled by the owner of an object and that specifies the access particular users or groups can have to the object.
    • **SACL** (system access control list): An ACL that controls the generation of audit messages for attempts to access a securable object. The ability to get or set an object's SACL is controlled by a privilege typically held only by system administrators.
  • TimeFields can be one of the following values:
    • **CreationTime**: Specifies when the file or directory was created.
    • **LastAccessTime**: Specifies when the file is last read from, written to, or for executable files, run.
    • **LastWrittenTime**: Specifies when the file is last written to, truncated, or overwritten.
| -For an example of how to use the **<includeAttributes>** element, see the example for [<excludeAttributes>](#excludeattributes). +For an example of how to use the **\** element, see the example for [\](#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> +## \ -The **<location>** element defines the location of the **<object>** element. +The **\** element defines the location of the **\** element. -- **Number of occurrences:** once for each **<object>** +- **Number of occurrences:** once for each **\** -- **Parent elements:** [<object>](#object) +- **Parent elements:** [\](#object) -- **Child elements:** [<script>](#script) +- **Child elements:** [\](#script) Syntax: @@ -1319,29 +1326,29 @@ The following example is from the `MigApp.xml` file: ```xml - %HklmWowSoftware%\Microsoft\Office\12.0\Common\Migration\Office [UpgradeVersion] + %HklmWowSoftware%\Microsoft\Office\16.0\Common\Migration\Office [UpgradeVersion] DWORD 0B000000 - %HklmWowSoftware%\Microsoft\Office\12.0\Common\Migration\Office [Lang] + %HklmWowSoftware%\Microsoft\Office\16.0\Common\Migration\Office [Lang] DWORD 00000000 ``` -## <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. +The **\** element can be used to change the location and name of an object before the object is migrated to the destination computer. The **\** element is processed only when the **LoadState** tool is run on the destination computer. In other words, this element is ignored by the **ScanState** tool. The **\** element creates the appropriate folder on the destination computer if it doesn't already exist. **Number of occurrences:** Unlimited -- **Parent elements:** [<rules>](#rules) +- **Parent elements:** [\](#rules) -- **Required child element:** [<objectSet>](#objectset) +- **Required child element:** [\](#objectset) -- **Helper functions:** You can use the following [<locationModify> functions](#locationmodify-functions) with this element: `ExactMove`, `RelativeMove`, and `Move`. +- **Helper functions:** The following [\ functions](#locationmodify-functions) can be used with this element: `ExactMove`, `RelativeMove`, and `Move`. Syntax: @@ -1352,7 +1359,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: @@ -1364,13 +1371,13 @@ The following example is from the `MigApp.xml` file: ``` -### <locationModify> functions +### \ 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 **\** element. These functions are called for every object that the parent **\** element is enumerating. The **\** element creates the appropriate folder on the destination computer if it doesn't already exist. - **ExactMove** - The ExactMove function moves all of the objects that are matched by the parent **<objectSet>** element into the given *ObjectEncodedLocation*. You can use this function when you want to move a single file to a different location on the destination computer. If the destination location is a node, all of the matching source objects 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 **\** element into the given *ObjectEncodedLocation*. This function can be used to move a single file to a different location on the destination computer. If the destination location is a node, all of the matching source objects are written to the node without any subdirectories. If the destination location is a leaf, the migration engine migrates all of the matching source objects to the same location. If a collision occurs, the normal collision algorithms apply. Syntax: `ExactMove(ObjectEncodedLocation)` @@ -1396,18 +1403,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. + The RelativeMove function can be used to collect and move data. Environment variables can be used in source and destination roots, but they might be defined differently on the source and destination computers. Syntax: `RelativeMove(SourceRoot,DestinationRoot)` |Setting|Required?|Value| |--- |--- |--- | - |*SourceRoot*|Yes|The location 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 where the objects are moved from. Any source objects that are enumerated by the parent **\** element that aren't in this location aren't moved.| + |*DestinationRoot*|Yes|The location where the source objects are moved to on the destination computer. If needed, this function creates any subdirectories that were above *SourceRoot*.| For example: @@ -1424,17 +1431,17 @@ For example: ``` -## <\_locDefinition> +## \<\_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 **\** element defines the manufacturer for the component, but doesn't affect the migration. - **Number of occurrences:** zero or one -- **Parent elements:** [<component>](#component) +- **Parent elements:** [\](#component) - **Child elements:** none @@ -1448,19 +1455,19 @@ Syntax: |--- |--- |--- | |*Name*|Yes|The name of the manufacturer for the component.| -## <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 **\** element determines what happens when a collision occurs. A collision is when an object that is migrated is already present on the destination computer. If this element isn't specified, the default behavior for the registry is for the source object to overwrite the destination object. The default behavior for files is for the source file to be renamed to `OriginalFileName(1).OriginalExtension`. This element specifies only what should be done when a collision occurs. It doesn't include objects. Therefore, for the objects to migrate, **\** rules must be specified along with the **\** element. When an object is processed and a collision is detected, USMT selects the most specific merge rule. It then applies the rule to resolve the conflict. For example, if a **\** rule `C:\* [*]` is set to **\** and a **\** rule `C:\subfolder\* [*]` is set to **\**, then USMT would use the **\** rule because it's the more specific. For an example of this element, see [Conflicts and precedence](usmt-conflicts-and-precedence.md). - **Number of occurrences:** Unlimited -- **Parent elements:** [<rules>](#rules) +- **Parent elements:** [\](#rules) -- **Required child element:** [<objectSet>](#objectset) +- **Required child element:** [\](#objectset) -- **Helper functions:** You can use the following [<merge> functions](#merge-functions) with this element: `SourcePriority`, `DestinationPriority`, `FindFilePlaceByPattern`, `LeafPattern`, `NewestVersion`, `HigherValue()`, and `LowerValue()`. +- **Helper functions:** The following [\ functions](#merge-functions) can be used with this element: `SourcePriority`, `DestinationPriority`, `FindFilePlaceByPattern`, `LeafPattern`, `NewestVersion`, `HigherValue()`, and `LowerValue()`. Syntax: @@ -1471,9 +1478,9 @@ 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 **\** 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: +The following example is from the `MigUser.xml` file: ```xml @@ -1490,7 +1497,7 @@ The following example is from the MigUser.xml file: ``` -### <merge> functions +### \ functions These functions control how collisions are resolved. @@ -1503,40 +1510,40 @@ These functions control how collisions are resolved. ```xml - HKCU\Software\Microsoft\Office\9.0\PhotoDraw\ [MyPictures] - HKCU\Software\Microsoft\Office\9.0\PhotoDraw\Settings\ [PicturesPath] - HKCU\Software\Microsoft\Office\9.0\PhotoDraw\Settings\ [AdditionalPlugInPath] + HKCU\Software\Microsoft\Office\16.0\PhotoDraw\ [MyPictures] + HKCU\Software\Microsoft\Office\16.0\PhotoDraw\Settings\ [PicturesPath] + HKCU\Software\Microsoft\Office\16.0\PhotoDraw\Settings\ [AdditionalPlugInPath] ``` - **FindFilePlaceByPattern** - The FindFilePlaceByPattern function saves files with an incrementing counter when a collision occurs. It 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: **\**, **\**, **\** 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 |
  • **\** is replaced by the original file name.
  • **\** is replaced by an incrementing counter until there's no collision with the objects on the destination computer.
  • **\** is replaced by the original file name extension.

For example, ` ().` changes the source file `MyDocument.doc` into `MyDocument (1).doc` on the destination computer. | - **NewestVersion** - The NewestVersion function 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. + This function can be used for merging registry values. The registry values are evaluated as numeric values, and the one with the higher value determines which registry values are merged. - **LowerValue()** - 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. + This function can be used for merging registry values. The registry values are evaluated as numeric values and the one with the lower value determines which registry values are merged. - **SourcePriority** @@ -1547,24 +1554,24 @@ These functions control how collisions are resolved. ```xml - %HklmWowSoftware%\Microsoft\Office\12.0\Common\Migration\Publisher [UpgradeVersion] - %HklmWowSoftware%\Microsoft\Office\11.0\Common\Migration\Publisher [UpgradeVersion] - %HklmWowSoftware%\Microsoft\Office\10.0\Common\Migration\Publisher [UpgradeVersion] + %HklmWowSoftware%\Microsoft\Office\14.0\Common\Migration\Publisher [UpgradeVersion] + %HklmWowSoftware%\Microsoft\Office\15.0\Common\Migration\Publisher [UpgradeVersion] + %HklmWowSoftware%\Microsoft\Office\16.0\Common\Migration\Publisher [UpgradeVersion] ``` -## <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 **\** element is the single root element of a migration **.xml** file and is required. Each **.xml** file must have a unique migration urlid. The urlid of each file that is specified on the command line must be unique. The urlids must be unique because USMT uses the urlid to define the components within the file. - **Number of occurrences:** one - **Parent elements:** none -- **Required child elements:** [<component>](#component) +- **Required child elements:** [\](#component) -- **Optional child elements:** [<library>](#library), [<namedElements>](#namedelements) +- **Optional child elements:** [\](#library), [\](#namedelements) Syntax: @@ -1575,8 +1582,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 +1600,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: "2023/05/15-2020/05/17", "2023/05/15"
Size: A numeral with B, KB, MB, or GB at the end. "5GB", "1KB-1MB"| ```xml @@ -1601,7 +1608,7 @@ This filter helper function can be used to filter the migration of files based o - + %SYSTEMDRIVE%\DOCS\* [*] @@ -1611,9 +1618,9 @@ This filter helper function can be used to filter the migration of files based o ``` -## <namedElements> +## \ -You can use the **<namedElements>** element to define named elements. You can use these elements in any component throughout your .xml file. For an example of how to use this element, see the `MigApp.xml` file. +The **\** element can be used to define named elements. These elements can be used in any component throughout the **.xml** file. For an example of how to use this element, see the `MigApp.xml` file. Syntax: @@ -1624,23 +1631,23 @@ Syntax: - **Number of occurrences:** Unlimited -- **Parent elements:** [<migration>](#migration) +- **Parent elements:** [\](#migration) -- **Child elements:** [<environment>](#environment), [<rules>](#rules), [<conditions>](#conditions), [<detection>](#detection), [<detects>](#detects), [<detect>](#detect) +- **Child elements:** [\](#environment), [\](#rules), [\](#conditions), [\](#detection), [\](#detects), [\](#detect) For an example of this element, see the `MigApp.xml` file. -## <object> +## \ -The **<object>** element represents a file or registry key. +The **\** element represents a file or registry key. - **Number of occurrences:** Unlimited -- **Parent elements:** [<addObjects>](#addobjects) +- **Parent elements:** [\](#addobjects) -- **Required child elements:** [<location>](#location), [<attributes>](#attributes) +- **Required child elements:** [\](#location), [\](#attributes) -- **Optional child elements:** [<bytes>](#bytes) +- **Optional child elements:** [\](#bytes) Syntax: @@ -1654,29 +1661,29 @@ The following example is from the `MigApp.xml` file: ```xml - %HklmWowSoftware%\Microsoft\Office\12.0\Common\Migration\Office [UpgradeVersion] + %HklmWowSoftware%\Microsoft\Office\16.0\Common\Migration\Office [UpgradeVersion] DWORD 0B000000 - %HklmWowSoftware%\Microsoft\Office\12.0\Common\Migration\Office [Lang] + %HklmWowSoftware%\Microsoft\Office\16.0\Common\Migration\Office [Lang] DWORD 00000000 ``` -## <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 **\** element contains a list of object patterns; for example, file paths, registry locations, and so on. Any child **\** elements are evaluated first. If all child **\** elements return **FALSE**, the **\** element evaluates to an empty set. For each parent element, there can be only multiple **\** elements. - **Number of occurrences:** Unlimited -- **Parent elements:** [<variable>](#variable), [<content>](#content), [<include>](#include), [<exclude>](#exclude), [<merge>](#merge), [<contentModify>](#contentmodify), [<locationModify>](#locationmodify), [<destinationCleanup>](#destinationcleanup), [<includeAttributes>](#includeattributes), [<excludeAttributes>](#excludeattributes), [<unconditionalExclude>](#unconditionalexclude), [<detect>](#detect) +- **Parent elements:** [\](#variable), [\](#content), [\](#include), [\](#exclude), [\](#merge), [\](#contentmodify), [\](#locationmodify), [\](#destinationcleanup), [\](#includeattributes), [\](#excludeattributes), [\](#unconditionalexclude), [\](#detect) -- **Required child elements:** either [<script>](#script) or [<pattern>](#pattern) +- **Required child elements:** either [\](#script) or [\](#pattern) -- **Optional child elements:** [<content>](#content), [<conditions>](#conditions), [<condition>](#condition) +- **Optional child elements:** [\](#content), [\](#conditions), [\](#condition) Syntax: @@ -1685,7 +1692,7 @@ Syntax: ``` -The following example is from the MigUser.xml file: +The following example is from the `MigUser.xml` file: ```xml @@ -1715,17 +1722,17 @@ 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: +This element can be used to specify multiple objects. Multiple **\** elements can be used for each **\** element and they're combined. If specifying files, Microsoft recommends using `GenerateDrivePatterns` with **\** instead. `GenerateDrivePatterns` is basically the same as a **\** rule, without the drive letter specification. For example, the following two lines of code are similar: ```xml C:\Folder\* [Sample.doc] @@ -1734,7 +1741,7 @@ You can use this element to specify multiple objects. You can specify multiple * - **Number of occurrences:** Unlimited -- **Parent elements:** [<objectSet>](#objectset) +- **Parent elements:** [\](#objectset) - **Child elements:** none but *Path* \[*object*\] must be valid. @@ -1746,8 +1753,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 a space between *Path* and *object* isn't allowed. For example, the following format is correct when type="Ini":
**\%WinAmp5InstPath%\Winamp.ini|WinAmp[keeponscreen]\** | +| *Path* [*object*] | Yes | A valid registry or file path pattern, followed by at least one space, followed by brackets [] that contain the object to be migrated.
  • *Path* can contain the asterisk (`*`) wildcard character or can be an [Recognized environment variables](usmt-recognized-environment-variables.md). The question mark can't be used as a wildcard character. `HKCU` and `HKLM` can be used to refer to `HKEY_CURRENT_USER` and `HKEY_LOCAL_MACHINE` respectively.
  • *Object* can contain the asterisk (`*`) wildcard character. However, the question mark can't be used as a wildcard character. For example:
    **`C:\Folder\ [*]`** enumerates all files in `C:\Folder` but no subfolders of `C:\Folder`.
    **`C:\Folder* [*]`** enumerates all files and subfolders of `C:\Folder`.
    **`C:\Folder\ [*.mp3]`** enumerates all `.mp3` files in `C:\Folder`.
    **`C:\Folder\ [Sample.doc]`** enumerates only the `Sample.doc` file located in C:\Folder.
    **Note**
    If migrating a file that has a square bracket character ([ or ]) in the file name, a carrot (^) character must be inserted directly before the bracket for it to be valid. For example, if there's a file named "file].txt", `c:\documents\mydocs [file^].txt]` must be specified instead of `c:\documents\mydocs [file].txt]`.
| For example: @@ -1773,7 +1780,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] @@ -1781,15 +1788,15 @@ For example: - For more examples of how to use this element, see [Exclude files and settings](usmt-exclude-files-and-settings.md), [Reroute files and settings](usmt-reroute-files-and-settings.md), [Include files and settings](usmt-include-files-and-settings.md), and [Custom XML examples](usmt-custom-xml-examples.md). -## <processing> +## \ -You can use this element to run a script during a specific point within the migration process. Return values are not expected from the scripts that you specify, and if there are return values, they will be ignored. +This element can be used to run a script during a specific point within the migration process. Return values aren't expected from the scripts that are specified. If there are return values, they're ignored. - **Number of occurrences:** unlimited -- **Parent elements:** [<rules>](#rules) +- **Parent elements:** [\](#rules) -- **Required child element:** [<script>](#script) +- **Required child element:** [\](#script) Syntax: @@ -1800,23 +1807,23 @@ 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 **\** element is required in a custom **.xml** file. When the **\** element is specified, a concrete component can be created. The component is defined by the parameters specified at the **\** level, and with the role that is specified here. -- **Number of occurrences:** Each **<component>** can have one, two or three child **<role>** elements. +- **Number of occurrences:** Each **\** can have one, two or three child **\** elements. -- **Parent elements:** [<component>](#component), [<role>](#role) +- **Parent elements:** [\](#component), [\](#role) -- **Required child elements:** [<rules>](#rules) +- **Required child elements:** [\](#rules) -- **Optional child elements:** [<environment>](#environment), [<detection>](#detection), [<component>](#component), [<role>](#role), [<detects>](#detects), [<plugin>](#plugin) +- **Optional child elements:** [\](#environment), [\](#detection), [\](#component), [\](#role), [\](#detects), [\](#plugin) Syntax: @@ -1827,9 +1834,9 @@ 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**
One of the following items can be specified:
  1. Up to three **\** elements within a **\** - one "Binaries" role element, one "Settings" role element and one "Data" role element. These parameters don't change the migration behavior - their only purpose is to help categorize the settings that are migrating. These **\** elements can be nested, but each nested element must be of the same role parameter.
  2. One "Container" **\** element within a **\** element. In this case, any child **\** elements can't be specified, only other **\** elements. And each child **\** element must have the same type as that of parent **\** element. For example:
\
  \Microsoft Office 2016\
  \
  \
    \
    \
    \ | [Windows Mixed Reality](/windows/mixed-reality/enthusiast-guide/before-you-start) is deprecated and will be removed in a future release of Windows. This deprecation includes the [Mixed Reality Portal](/windows/mixed-reality/enthusiast-guide/install-windows-mixed-reality) app, and [Windows Mixed Reality for SteamVR](/windows/mixed-reality/enthusiast-guide/using-steamvr-with-windows-mixed-reality) and Steam VR Beta. | December 2023 |
+| Windows Mixed Reality  | [Windows Mixed Reality](/windows/mixed-reality/enthusiast-guide/before-you-start) is deprecated and will be removed in a future release of Windows. This deprecation includes the [Mixed Reality Portal](/windows/mixed-reality/enthusiast-guide/install-windows-mixed-reality) app, and [Windows Mixed Reality for SteamVR](/windows/mixed-reality/enthusiast-guide/using-steamvr-with-windows-mixed-reality) and Steam VR Beta. 

 As of November 1, 2026, for consumer editions of Windows and November 1, 2027 for commercial editions of Windows, Windows Mixed Reality will no longer be available for download via the Mixed Reality Portal app, Windows Mixed Reality for SteamVR, and Steam VR beta, and we'll discontinue support. At that time, Windows Mixed Reality will no longer receive security updates, nonsecurity updates, bug fixes, technical support, or online technical content updates. Existing Windows Mixed Reality devices will continue to work with Steam until users upgrade to a version of Windows that doesn't include Windows Mixed Reality. 
 
 This deprecation doesn't impact HoloLens. We remain committed to HoloLens and our enterprise customers.  | December 2023 |
 | Microsoft Defender Application Guard for Edge | [Microsoft Defender Application Guard](/windows/security/application-security/application-isolation/microsoft-defender-application-guard/md-app-guard-overview), including the [Windows Isolated App Launcher APIs](/windows/win32/api/isolatedapplauncher/), is being deprecated for Microsoft Edge for Business and [will no longer be updated](feature-lifecycle.md). Please download the [Microsoft Edge For Business Security Whitepaper](https://edgestatic.azureedge.net/shared/cms/pdfs/Microsoft_Edge_Security_Whitepaper_v2.pdf) to learn more about Edge for Business security capabilities. | December 2023 |
 | Legacy console mode | The [legacy console mode](/windows/console/legacymode) is deprecated and no longer being updated. In future Windows releases, it will be available as an optional [Feature on Demand](/windows-hardware/manufacture/desktop/features-on-demand-v2--capabilities). This feature won't be installed by default. | December 2023 |
 | Windows speech recognition | [Windows speech recognition](https://support.microsoft.com/windows/83ff75bd-63eb-0b6c-18d4-6fae94050571) is  deprecated and is no longer being developed. This feature is being replaced with [voice access](https://support.microsoft.com/topic/4dcd23ee-f1b9-4fd1-bacc-862ab611f55d). Voice access is available for Windows 11, version 22H2, or later devices. Currently, voice access supports five English locales: English - US, English - UK, English - India, English - New Zealand, English - Canada, and English - Australia. For more information, see [Setup voice access](https://support.microsoft.com/topic/set-up-voice-access-9fc44e29-12bf-4d86-bc4e-e9bb69df9a0e). | December 2023 |