From db6fcb013947a235db2cdd988fcb7a149e7e7c14 Mon Sep 17 00:00:00 2001 From: Frank Rojas <115200257+RojasNet@users.noreply.github.com> Date: Wed, 2 Nov 2022 00:53:32 -0400 Subject: [PATCH] Metadata update deployment/usmt 5 --- ...rted-with-the-user-state-migration-tool.md | 53 ++--- .../usmt/migrate-application-settings.md | 70 ++++--- .../usmt/migration-store-types-overview.md | 10 +- .../usmt/offline-migration-reference.md | 48 ++--- .../usmt/understanding-migration-xml-files.md | 184 +++++++++--------- .../deployment/usmt/usmt-best-practices.md | 52 ++--- .../usmt/usmt-choose-migration-store-type.md | 2 +- windows/deployment/usmt/usmt-common-issues.md | 73 +++---- .../usmt/usmt-common-migration-scenarios.md | 21 +- .../deployment/usmt/usmt-configxml-file.md | 78 ++++---- .../usmt/usmt-conflicts-and-precedence.md | 78 ++++---- .../usmt/usmt-custom-xml-examples.md | 12 +- .../usmt/usmt-customize-xml-files.md | 45 +++-- 13 files changed, 363 insertions(+), 363 deletions(-) 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 21d4d8c1a0..8eced69283 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 @@ -11,79 +11,80 @@ ms.technology: itpro-deploy ms.date: 11/01/2022 --- -# Getting Started with the User State Migration Tool (USMT) +# Getting started with the User State Migration Tool (USMT) + This article outlines the general process that you should follow to migrate files and settings. ## In this topic -- [Step 1: Plan Your Migration](#step-1-plan-your-migration) +- [Step 1: Plan Your Migration](#step-1-plan-your-migration) -- [Step 2: Collect files and settings from the source computer](#step-2-collect-files-and-settings-from-the-source-computer) +- [Step 2: Collect files and settings from the source computer](#step-2-collect-files-and-settings-from-the-source-computer) -- [Step 3: Prepare the destination computer and restore files and settings](#step-3-prepare-the-destination-computer-and-restore-files-and-settings) +- [Step 3: Prepare the destination computer and restore files and settings](#step-3-prepare-the-destination-computer-and-restore-files-and-settings) ## Step 1: Plan your 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 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). -2. [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. +2. [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. -3. 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). +3. 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). -4. 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) +4. 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) -5. 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. +5. 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. - > [!Important] + > [!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. 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). -6. Create a [Config.xml File](usmt-configxml-file.md) if you want to exclude any components from the migration. To create this file, use the [ScanState Syntax](usmt-scanstate-syntax.md) option together with the other .xml files when you use the `ScanState.exe` command. For example, the following command creates a `Config.xml` file by using the `MigDocs.xml` and `MigApp.xml` files: +6. Create a [Config.xml File](usmt-configxml-file.md) if you want to exclude any components from the migration. To create this file, use the [ScanState Syntax](usmt-scanstate-syntax.md) option together with the other .xml files when you use the `ScanState.exe` command. For example, the following command creates a `Config.xml` file by using the `MigDocs.xml` and `MigApp.xml` files: `scanstate.exe /genconfig:config.xml /i:migdocs.xml /i:migapp.xml /v:13 /l:scanstate.log` -7. Review the migration state of the components listed in the `Config.xml` file, and specify `migrate=no` for any components that you don't want to migrate. +7. Review the migration state of the components listed in the `Config.xml` file, and specify `migrate=no` for any components that you don't want to migrate. ## Step 2: Collect files and settings from the source computer -1. Back up the source computer. +1. Back up the source computer. -2. 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. +2. 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. - > [!Note] + > [!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. -3. 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, +3. 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, `scanstate.exe \\server\migration\mystore /config:config.xml /i:migdocs.xml /i:migapp.xml /v:13 /l:scan.log` - > [!Note] + > [!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). -4. Run the `USMTUtils.exe` command with the `/Verify` option to ensure that the store you created isn't corrupted. +4. Run the `USMTUtils.exe` command with the `/Verify` option to ensure that the store you created 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 the operating system on the destination computer. -2. 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. +2. 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. - > [!Note] + > [!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. -3. 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. +3. 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. - > [!Note] + > [!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. -4. 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). +4. 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). For example, the following command migrates the files and settings: `loadstate.exe \\server\migration\mystore /config:config.xml /i:migdocs.xml /i:migapp.xml /v:13 /l:load.log` - > [!Note] + > [!NOTE] > Run the `Loadstate.exe` command in administrator mode. To do this, right-click **Command Prompt**, and then click **Run As Administrator**. -5. Sign out after you run the `Loadstate.exe` command. Some settings (for example, fonts, wallpaper, and screen saver settings) won't take effect until the next time that the user logs on. +5. Sign out after you run the `Loadstate.exe` command. Some settings (for example, 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 96de07fa10..fe13dd7b36 100644 --- a/windows/deployment/usmt/migrate-application-settings.md +++ b/windows/deployment/usmt/migrate-application-settings.md @@ -21,29 +21,29 @@ This article doesn't contain information about how to migrate applications that ## In this topic -- [Before You Begin](#bkmk-beforebegin) +- [Before You Begin](#bkmk-beforebegin) -- [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](#bkmk-step1). +- [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](#bkmk-step1). -- [Step 2: Identify settings to collect and determine where each setting is stored on the computer](#bkmk-step2). +- [Step 2: Identify settings to collect and determine where each setting is stored on the computer](#bkmk-step2). -- [Step 3: Identify how to apply the gathered settings](#bkmk-step3). +- [Step 3: Identify how to apply the gathered settings](#bkmk-step3). -- [Step 4: Create the migration XML component for the application](#bkmk-step4). +- [Step 4: Create the migration XML component for the application](#bkmk-step4). -- [Step 5: Test the application settings migration](#bkmk-step5). +- [Step 5: Test the application settings migration](#bkmk-step5). -## Before You Begin +## Before You Begin 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. -## 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. +## 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. 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. -### Check the registry for an application uninstall key. +### 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: @@ -61,47 +61,45 @@ Usually, you can find this key by searching under 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. -### Check the file system for the application executable file. +### 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. -## Step 2: Identify settings to collect and determine where each setting is stored on the computer. +## 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. -### +### How to determine where each setting is stored -**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 the Regmon and Filemon tools, from the [Windows Sysinternals Web site](/sysinternals/). +2. Shut down as many applications as possible to limit the registry and file system activity on the computer. -2. 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. -3. Filter the output of the tools so it only displays changes being made by the application. - - > [!Note] + > [!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. -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**. +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**. -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. +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. - > [!Note] + > [!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. +## 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: -### Case 1: The version of the application on the destination computer is newer than the one on the source computer. +### 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: -- **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 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. - 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](#bkmkdetermine). 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 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. -- [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.](#bkmkdetermine) 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](#bkmkdetermine). 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. +- **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. ### Case 2: The destination computer already contains settings for the application. @@ -115,29 +113,29 @@ We recommend that you migrate the settings after you install the application, bu 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. - > [!Note] + > [!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. -> [!Important] +> [!IMPORTANT] > Some applications store information in the user profile that should not be migrated (for example, application installation paths, the computer name, and so on). You should make sure to exclude these files and registry keys from the migration. Your script should do the following actions: -1. Check whether the application and correct version is installed by: +1. Check whether the application and correct version is installed by: - - Searching for the installation uninstall key under `HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall` using the `DoesObjectExist` helper function. + - Searching 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. + - Checking 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. +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. - - 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 **<include>** and **<exclude>** 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: + - 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 you must install the application before migrating the settings, delete any settings that are already on the destination computer using the **<destinationCleanup>** element. + - If you must install the application before migrating the settings, delete any settings that are already on the destination computer using the **<destinationCleanup>** element. For information about the .xml elements and helper functions, see [XML Elements Library](usmt-xml-elements-library.md). @@ -155,4 +153,4 @@ To speed up the time it takes to collect and migrate the data, you can migrate o [XML Elements Library](usmt-xml-elements-library.md) -[Log Files](usmt-log-files.md) \ No newline at end of file +[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 408d785e78..2f6c6b1b79 100644 --- a/windows/deployment/usmt/migration-store-types-overview.md +++ b/windows/deployment/usmt/migration-store-types-overview.md @@ -23,7 +23,7 @@ When planning your migration, you should determine which migration store type be [The /localonly Command-Line Option](#bkmk-localonly) -## Migration Store Types +## Migration Store Types This section describes the three migration store types available in USMT. @@ -45,19 +45,19 @@ The following flowchart illustrates the procedural differences between a local m ![migration store comparison.](images/dep-win8-l-usmt-migrationcomparemigstores.gif) -## Local Store vs. Remote Store +## 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 isn't enough local disk space, or if you're moving the user state to another computer, then you must store the data remotely. For example, you can store it in on a shared folder, on removable media such as a UFD drive, or you can store it directly on the destination computer. For example, create and share `C:\store` on the destination computer. Then run the `ScanState.exe` command on the source computer and save the files and settings to `\\\store`. Then, run the `Loadstate.exe` command on the destination computer and specify `C:\Store` as the store location. By doing this process, you don't need to save the files to a server. -> [!Important] +> [!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. -### The /localonly Command-Line Option +### 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). ## Related articles -[Plan Your Migration](usmt-plan-your-migration.md) \ No newline at end of file +[Plan Your 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 e0ec4d4ad1..a32631093a 100644 --- a/windows/deployment/usmt/offline-migration-reference.md +++ b/windows/deployment/usmt/offline-migration-reference.md @@ -15,51 +15,51 @@ ms.technology: itpro-deploy 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 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. When you use User State Migration Tool (USMT) 10.0 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 may 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. ## In this topic -- [What Will Migrate Offline?](#bkmk-whatwillmigrate) +- [What Will Migrate Offline?](#bkmk-whatwillmigrate) -- [What Offline Environments are Supported?](#bkmk-offlineenvironments) +- [What Offline Environments are Supported?](#bkmk-offlineenvironments) -- [User-Group Membership and Profile Control](#bkmk-usergroupmembership) +- [User-Group Membership and Profile Control](#bkmk-usergroupmembership) -- [Command-Line Options](#bkmk-commandlineoptions) +- [Command-Line Options](#bkmk-commandlineoptions) -- [Environment Variables](#bkmk-environmentvariables) +- [Environment Variables](#bkmk-environmentvariables) -- [Offline.xml Elements](#bkmk-offlinexml) +- [Offline.xml Elements](#bkmk-offlinexml) -## What Will Migrate Offline? +## What Will Migrate 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 +- Internet Explorer® Favorites For exceptions to what you can migrate offline, see [What Does USMT Migrate?](usmt-what-does-usmt-migrate.md) -## What Offline Environments are Supported? +## What Offline Environments are Supported? The following table defines the supported combination of online and offline operating systems in USMT. @@ -68,10 +68,10 @@ The following table defines the supported combination of online and offline oper |WinPE 5.0 or greater, with the MSXML library|Windows 7, Windows 8, Windows 10| |Windows 7, Windows 8, Windows 10|Windows.old directory| -> [!Note] +> [!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)). -## User-Group Membership and Profile Control +## 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: @@ -93,7 +93,7 @@ User-group membership isn't preserved during offline migrations. You must config For information about the format of a `Config.xml` file, see [Config.xml File](usmt-configxml-file.md). -## Command-Line Options +## Command-Line Options An offline migration can either be enabled by using a configuration file on the command line, or by using one of the following command line options: @@ -105,7 +105,7 @@ An offline migration can either be enabled by using a configuration file on the 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. -## Environment Variables +## Environment Variables The following system environment variables are necessary in the scenarios outlined below. @@ -173,4 +173,4 @@ The following XML example illustrates some of the elements discussed earlier in ## Related articles -[Plan Your Migration](usmt-plan-your-migration.md) \ No newline at end of file +[Plan Your 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 9d0c7dd33b..18fed52688 100644 --- a/windows/deployment/usmt/understanding-migration-xml-files.md +++ b/windows/deployment/usmt/understanding-migration-xml-files.md @@ -43,7 +43,7 @@ This article provides an overview of the default and custom migration XML files [Next Steps](#bkmk-next) -## Overview of the Config.xml file +## 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: @@ -54,133 +54,133 @@ When used this way, the `Config.xml` file tightly controls aspects of the migrat > [!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. -## Overview of the MigApp.xml file +## 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). -> [!Important] +> [!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 the [Sample migration rules for customized versions of XML files](#bkmk-samples). -## Overview of the MigDocs.xml file +## 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 default `MigDocs.xml` file migrates the following data: -- All files on the root of the drive except %WINDIR%, %PROGRAMFILES%, %PROGRAMDATA%, or %USERS%. +- 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: +- Standard shared folders: - - CSIDL\_COMMON\_DESKTOPDIRECTORY + - CSIDL\_COMMON\_DESKTOPDIRECTORY - - CSIDL\_COMMON\_FAVORITES + - CSIDL\_COMMON\_FAVORITES - - CSIDL\_COMMON\_DOCUMENTS + - CSIDL\_COMMON\_DOCUMENTS - - CSIDL\_COMMON\_MUSIC + - CSIDL\_COMMON\_MUSIC - - CSIDL\_COMMON\_PICTURES + - CSIDL\_COMMON\_PICTURES - - CSIDL\_COMMON\_VIDEO + - CSIDL\_COMMON\_VIDEO - - FOLDERID\_PublicDownloads + - FOLDERID\_PublicDownloads -- Standard user-profile folders for each user: +- Standard user-profile folders for each user: - - CSIDL\_MYDOCUMENTS + - CSIDL\_MYDOCUMENTS - - CSIDL\_MYPICTURES + - CSIDL\_MYPICTURES - - FOLDERID\_OriginalImages + - FOLDERID\_OriginalImages - - CSIDL\_MYMUSIC + - CSIDL\_MYMUSIC - - CSIDL\_MYVIDEO + - CSIDL\_MYVIDEO - - CSIDL\_FAVORITES + - CSIDL\_FAVORITES - - CSIDL\_DESKTOP + - CSIDL\_DESKTOP - - CSIDL\_QUICKLAUNCH + - CSIDL\_QUICKLAUNCH - - FOLDERID\_Contacts + - FOLDERID\_Contacts - - FOLDERID\_Libraries + - FOLDERID\_Libraries - - FOLDERID\_Downloads + - FOLDERID\_Downloads - - FOLDERID\_SavedGames + - FOLDERID\_SavedGames - - FOLDERID\_RecordedTV + - FOLDERID\_RecordedTV The default `MigDocs.xml` file won't migrate the following data: -- Files tagged with both the **hidden** and **system** attributes. +- 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%, %PROGRAMDATA%, and %PROGRAMFILES% folders. +- Data from the %WINDIR%, %PROGRAMDATA%, and %PROGRAMFILES% folders. -- Folders that contain installed applications. +- 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. -## Overview of the MigUser.xml file +## 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 default `MigUser.xml` file migrates the following data: -- All files from the standard user-profile folders, which are described as: +- All files from the standard user-profile folders, which are described as: - - CSIDL\_MYVIDEO + - CSIDL\_MYVIDEO - - CSIDL\_MYMUSIC + - CSIDL\_MYMUSIC - - CSIDL\_DESKTOP + - CSIDL\_DESKTOP - - CSIDL\_STARTMENU + - CSIDL\_STARTMENU - - CSIDL\_PERSONAL + - CSIDL\_PERSONAL - - CSIDL\_MYPICTURES + - CSIDL\_MYPICTURES - - CSIDL\_FAVORITES + - CSIDL\_FAVORITES - - CSIDL\_QUICK LAUNCH + - CSIDL\_QUICK LAUNCH -- Files with the following extensions: +- Files with the following extensions: `.qdf`, `.qsd`, `.qel`, `.qph`, `.doc*`, `.dot*`, `.rtf`, `.mcw`, `.wps`, `.scd`, `.wri`, `.wpd`, `.xl*`, `.csv`, `.iqy`, `.dqy`, `.oqy`, `.rqy`, `.wk*`, `.wq1`, `.slk`, `.dif`, `.ppt*`, `.pps*`, `.pot*`, `.sh3`, `.ch3`, `.pre`, `.ppa`, `.txt`, `.pst`, `.one*`, `.vl*`, `.vsd`, `.mpp`, `.or6`, `.accdb`, `.mdb`, `.pub` The default `MigUser.xml` file doesn't migrate the following data: -- Files tagged with both the **hidden** and **system** attributes. +- 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. +- Data from the %WINDIR%, %PROGRAMFILES%, %PROGRAMDATA% folders. -- ACLS for files in folders outside the user profile. +- 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. > [!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](#bkmk-multiple) section of this document. -## Using multiple XML files +## 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. |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).| +|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.| @@ -191,7 +191,7 @@ For example, you can use all of the XML migration file types for a single migrat Scanstate.exe /config:c:\myFolder\config.xml /i:migapps.xml /i:migdocs.xml /i:customrules.xml ``` -### XML rules for migrating user files +### 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. @@ -200,7 +200,7 @@ If your data set is unknown or if many files are stored outside of the standard If you want more control over the migration, you can create custom XML files. See the [Creating and editing a custom ,xml file](#bkmk-createxml) section of this document. -## 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. @@ -209,13 +209,13 @@ You can use the `/genmigxml` command-line option to determine which files will b 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. Select **Start** > **All Programs** > **Accessories** -3. Select an account with administrator privileges, supply a password, and then select **OK**. +2. Right-click **Command Prompt**, and then select **Run as**. -4. At the command prompt, type: +3. Select an account with administrator privileges, supply a password, and then select **OK**. + +4. At the command prompt, type: ```console cd /d @@ -229,7 +229,7 @@ To generate the XML migration rules file for a source computer: scanstate.exe /genmigxml:"C:\Documents and Settings\USMT Tester\Desktop\genMig.xml" ``` -### The GenerateDocPatterns function +### 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. @@ -287,67 +287,67 @@ To create exclude data patterns: ``` -### Understanding the system and user context +### 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. -**System context** +#### System context The system context includes rules for data outside of the User Profiles directory. For example, when called in a system context in the `MigDocs.xml` file, the `GenerateDocPatterns` function creates patterns for all common shell folders, files in the root directory of hard drives, and folders located at the root of hard drives. The following folders are included: -- CSIDL\_COMMON\_DESKTOPDIRECTORY +- CSIDL\_COMMON\_DESKTOPDIRECTORY -- CSIDL\_COMMON\_FAVORITES +- CSIDL\_COMMON\_FAVORITES -- CSIDL\_COMMON\_DOCUMENTS +- CSIDL\_COMMON\_DOCUMENTS -- CSIDL\_COMMON\_MUSIC +- CSIDL\_COMMON\_MUSIC -- CSIDL\_COMMON\_PICTURES +- CSIDL\_COMMON\_PICTURES -- CSIDL\_COMMON\_VIDEO +- CSIDL\_COMMON\_VIDEO -- FOLDERID\_PublicDownloads +- FOLDERID\_PublicDownloads -**User context** +#### User context The user context includes rules for data in the User Profiles directory. When called in a user context in the `MigDocs.xml` file, the `GenerateDocPatterns` function creates patterns for all user shell folders, files located at the root of the profile, and folders located at the root of the profile. The following folders are included: -- CSIDL\_MYDOCUMENTS +- CSIDL\_MYDOCUMENTS -- CSIDL\_MYPICTURES +- CSIDL\_MYPICTURES -- FOLDERID\_OriginalImages +- FOLDERID\_OriginalImages -- CSIDL\_MYMUSIC +- CSIDL\_MYMUSIC -- CSIDL\_MYVIDEO +- CSIDL\_MYVIDEO -- CSIDL\_FAVORITES +- CSIDL\_FAVORITES -- CSIDL\_DESKTOP +- CSIDL\_DESKTOP -- CSIDL\_QUICKLAUNCH +- CSIDL\_QUICKLAUNCH -- FOLDERID\_Contacts +- FOLDERID\_Contacts -- FOLDERID\_Libraries +- FOLDERID\_Libraries -- FOLDERID\_Downloads +- FOLDERID\_Downloads -- FOLDERID\_SavedGames +- FOLDERID\_SavedGames -- FOLDERID\_RecordedTV +- 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. - ### Sample migration rules for customized versions of XML files +### Sample migration rules for customized versions of XML files > [!NOTE] > 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 +### 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: @@ -358,7 +358,7 @@ In the examples below, the source computer has a .txt file called "new text docu To exclude the new text document.txt file and any .txt files in "new folder", you can do the following modification: -**Example 1: Exclude all .txt files in a folder** +#### 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. @@ -371,7 +371,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** +#### 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). @@ -383,9 +383,9 @@ 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** +#### 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. +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. ``` xml @@ -404,11 +404,11 @@ If you want the <UnconditionalExclude> element to apply to both the system 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). -### Include rules usage examples +### 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: -**Example 1: Include a file name extension in a known user folder** +#### 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. @@ -420,7 +420,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** +#### 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. @@ -437,7 +437,7 @@ For more examples of include rules that you can use in custom migration XML file > [!NOTE] > For more information about the order of precedence for XML migration rules, see [Conflicts and Precedence](usmt-conflicts-and-precedence.md). -## Next steps +## 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. diff --git a/windows/deployment/usmt/usmt-best-practices.md b/windows/deployment/usmt/usmt-best-practices.md index 059df90121..2f6e9b3c0d 100644 --- a/windows/deployment/usmt/usmt-best-practices.md +++ b/windows/deployment/usmt/usmt-best-practices.md @@ -18,35 +18,35 @@ This article discusses general and security-related best practices when using Us ## 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. -- **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). -- **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. -- **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. -- **Log off after you run the LoadState** +- **Log off after you run 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. -- **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. -- **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)). -- **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. @@ -54,40 +54,40 @@ This article discusses general and security-related best practices when using Us 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: -- **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). - > [!Note] + > [!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. -- **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. -- **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. -- **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://go.microsoft.com/fwlink/p/?LinkId=215657). -- **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. -- **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. ## 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. -- **The <CustomFileName> in the migration urlid should match the name of the file** +- **The <CustomFileName> 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: @@ -96,15 +96,15 @@ As the authorized administrator, it is your responsibility to protect the privac ``` -- **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. -- **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. -- **Consider the impact on performance when using the <context> parameter** +- **Consider the impact on performance when using the <context> 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. @@ -114,24 +114,24 @@ As the authorized administrator, it is your responsibility to protect the privac In the **UserAndSystem** context, a rule is processed one time for each user on the system and one time for the system. - > [!Note] + > [!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. -- **We recommend that you create a separate .xml file instead of adding your .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, if you have code that migrates the settings for an application, you shouldn't just add the code to the `MigApp.xml` file. -- **You should not create custom .xml files 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** 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. -- **You can use the asterisk (\*) wildcard character in any migration XML file that you create** +- **You can use the asterisk (\*) wildcard character in any migration XML file that you create** - > [!Note] + > [!NOTE] > The question mark is not 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) \ No newline at end of file +[Plan Your 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 702d5a9783..5c2fee2a99 100644 --- a/windows/deployment/usmt/usmt-choose-migration-store-type.md +++ b/windows/deployment/usmt/usmt-choose-migration-store-type.md @@ -28,4 +28,4 @@ One of the main considerations for planning your migration is to determine which [Plan Your Migration](usmt-plan-your-migration.md) -[User State Migration Tool (USMT) How-to topics](usmt-how-to.md) \ No newline at end of file +[User State Migration Tool (USMT) How-to topics](usmt-how-to.md) diff --git a/windows/deployment/usmt/usmt-common-issues.md b/windows/deployment/usmt/usmt-common-issues.md index 65c77a5059..fd31f45b47 100644 --- a/windows/deployment/usmt/usmt-common-issues.md +++ b/windows/deployment/usmt/usmt-common-issues.md @@ -29,7 +29,7 @@ The following sections discuss common issues that you might see when you run the [Hard Link Migration Problems](#bkmk-hardlink) -[USMT doesn't migrate the Start layout](#usmt-does-not-migrate-the-start-layout) +[USMT doesn't migrate the Start layout](#usmt-doesnt-migrate-the-start-layout) ## General Guidelines for Identifying Migration Problems @@ -39,7 +39,7 @@ When you encounter a problem or error message during migration, you can use the 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; however, reducing the verbosity level might make it more difficult to diagnose failures that are encountered during production migrations. You can use a verbosity level higher than 5 if you want the log files output to go to a debugger. - > [!Note] + > [!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, the extra detail can help you determine where migration errors occurred. - Use the `/Verify` option with the UsmtUtils tool to determine whether any files in a compressed migration store are corrupted. For more information, see [Verify the Condition of a Compressed Migration Store](verify-the-condition-of-a-compressed-migration-store.md). @@ -54,18 +54,18 @@ When you encounter a problem or error message during migration, you can use the - Close all applications before running ScanState or LoadState tools. If some applications are running during the ScanState or LoadState process, USMT might not migrate some data. For example, if Microsoft Outlook® is open, USMT might not migrate PST files. - > [!Note] + > [!NOTE] > 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 ignores errors. However, it logs an error when it encounters a file that is in use that didn't migrate. -## User Account Problems +## User Account Problems The following sections describe common user account problems. Expand the section to see recommended solutions. -### I'm having problems creating local accounts on the destination computer. +### I'm having problems creating local accounts on the destination computer **Resolution:** For more information about creating accounts and migrating local accounts, see [Migrate User Accounts](usmt-migrate-user-accounts.md). -### Not all of the user accounts were migrated to the destination computer. +### Not all of the user accounts were migrated to the destination computer **Causes/Resolutions** There are two possible causes for this problem: @@ -76,40 +76,40 @@ When running the ScanState and LoadState tools on Windows 7, Windows 8, or Windo 2. Right-click **Command Prompt**. 3. Select **Run as administrator**. - + 4. Specify the `LoadState.exe` or `ScanState.exe` command. If you don't run USMT in Administrator mode, only the user profile that is logged on will be included in the migration. Any user accounts on the computer that haven't been used won't be migrated. For example, if you add User1 to the computer, but User1 never logs on, then USMT won't migrate the User1 account. -### User accounts that I excluded were migrated to the destination computer. +### User accounts that I excluded were migrated to the destination computer **Cause:** The command that you specified might have had conflicting `ui` and `/ue` options. If a user is specified with the `/ui` option and with either the `/ue` or `/uel` options at the same time, the user will be included in the migration. For example, if you specify `/ui:domain1\* /ue:domain1\user1`, then User1 will be migrated because the `/ui` option takes precedence. **Resolution:** For more information about how to use the `/ui` and `/ue` options together, see the examples in the [ScanState Syntax](usmt-scanstate-syntax.md) article. -### I'm using the /uel option, but many accounts are still being included in the migration. +### I'm using the /uel option, but many accounts are still being included in the migration **Cause:** The `/uel` option depends on the last modified date of the users' NTUser.dat file. There are scenarios in which this last modified date might not match the users' last sign-in date. **Resolution:** This is a limitation of the `/uel` option. You might need to exclude these users manually with the `/ue` option. -### The LoadState tool reports an error as return code 71 and fails to restore a user profile during a migration test. +### The LoadState tool reports an error as return code 71 and fails to restore a user profile during a migration test **Cause:** During a migration test, if you run the ScanState tool on your test computer and then delete user profiles in order to test the LoadState tool on the same computer, you may have a conflicting key present in the registry. Using the **net use** command to remove a user profile will delete folders and files associated with that profile, but won't remove the registry key. **Resolution:** To delete a user profile, use the **User Accounts** item in Control Panel. To correct an incomplete deletion of a user profile: -1. Open the registry editor by typing `regedit` at an elevated command prompt. +1. Open the registry editor by typing `regedit` at an elevated command prompt. -2. Navigate to `HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\ProfileList`. +2. Navigate to `HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\ProfileList`. Each user profile is stored in a System Identifier key under `ProfileList`. -3. Delete the key for the user profile you're trying to remove. +3. Delete the key for the user profile you're trying to remove. -### Files that weren't encrypted before the migration are now encrypted with the account used to run the LoadState tool. +### Files that weren't encrypted before the migration are now encrypted with the account used to run the LoadState tool **Cause:** The ScanState tool was run using the `/EFS:copyraw` option to migrate encrypted files and Encrypting File System (EFS) certificates. The encryption attribute was set on a folder that was migrated, but the attribute was removed from file contents of that folder prior to migration. @@ -117,7 +117,7 @@ Any user accounts on the computer that haven't been used won't be migrated. For To remove encryption from files that have already been migrated incorrectly, you must sign into the computer with the account that you used to run the LoadState tool and then remove the encryption from the affected files. -### The LoadState tool reports an error as return code 71 and a Windows Error 2202 in the log file. +### The LoadState tool reports an error as return code 71 and a Windows Error 2202 in the log file **Cause:** The computer name was changed during an offline migration of a local user profile. @@ -128,7 +128,7 @@ loadstate.exe /i:migapp.xml /i:migdocs.xml \\server\share\migration\mystore /progress:prog.log /l:load.log /mu:fareast\user1:farwest\user1 ``` -## Command-line Problems +## Command-line Problems The following sections describe common command-line problems. Expand the section to see recommended solutions. @@ -144,8 +144,7 @@ The following sections describe common command-line problems. Expand the section **Resolution:** To fix this issue in this scenario, specify the `/l:scan.log` or `/l:load.log` option. -## XML File Problems - +## XML File Problems The following sections describe common XML file problems. Expand the section to see recommended solutions. @@ -157,27 +156,27 @@ The following sections describe common XML file problems. Expand the section to `scanstate.exe /genconfig:config.xml /i:migdocs.xml /i:migapp.xml /v:5 /l:scanstate.log` -### I'm having problems with a custom .xml file that I authored, and I can't verify that the syntax is correct. +### I'm having problems with a custom .xml file that I authored, and I can't verify that the syntax is correct **Resolution:** You can load the XML schema file `MigXML.xsd` into your XML authoring tool. `MigXML.xsd` is included with USMT. For examples, see the [Visual Studio Development Center](https://go.microsoft.com/fwlink/p/?LinkId=74513). Then, load your .xml file in the authoring tool to see if there's a syntax error. For more information about using the XML elements, see [USMT XML Reference](usmt-xml-reference.md). -### I'm using a MigXML helper function, but the migration isn't working the way I expected it to. How do I troubleshoot this issue? +### I'm using a MigXML helper function, but the migration isn't working the way I expected it to. How do I troubleshoot this issue? **Cause:** Typically, this issue is caused by incorrect syntax used in a helper function. You receive a Success return code, but the files you wanted to migrate didn't get collected or applied, or weren't collected or applied in the way you expected. **Resolution:** You should search the ScanState or LoadState log for either the component name that contains the MigXML helper function, or the MigXML helper function title, so that you can locate the related warning in the log file. -## Migration Problems +## Migration Problems The following sections describe common migration problems. Expand the section to see recommended solutions. -### Files that I specified to exclude are still being migrated. +### Files that I specified to exclude are still being migrated **Cause:** There might be another rule that is including the files. If there's a more specific rule or a conflicting rule, the files will be included in the migration. **Resolution:** For more information, see [Conflicts and Precedence](usmt-conflicts-and-precedence.md) and the Diagnostic Log section in [Log Files](usmt-log-files.md). -### I specified rules to move a folder to a specific location on the destination computer, but it hasn't migrated correctly. +### I specified rules to move a folder to a specific location on the destination computer, but it hasn't migrated correctly **Cause:** There might be an error in the XML syntax. @@ -193,7 +192,7 @@ The following sections describe common migration problems. Expand the section to [Custom XML Examples](usmt-custom-xml-examples.md) -### After LoadState completes, the new desktop background doesn't appear on the destination computer. +### After LoadState completes, the new desktop background doesn't appear on the destination computer There are three typical causes for this issue. @@ -211,7 +210,7 @@ There are three typical causes for this issue. **Resolution:** Run the ScanState and LoadState tools from within an account with administrative credentials. ---> -### I included MigApp.xml in the migration, but some PST files aren't migrating. +### I included MigApp.xml in the migration, but some PST files aren't migrating **Cause:** The `MigApp.xml` file migrates only the PST files that are linked to Outlook profiles. @@ -227,35 +226,37 @@ There are three typical causes for this issue. 1. With the user signed in, back up the Start layout using the following Windows PowerShell command. You can specify a different path if desired: - ``` + ```powershell Export-StartLayout -Path "C:\Layout\user1.xml" ``` + 2. Migrate the user's profile with USMT. + 3. Before the user signs in on the new device, import the Start layout using the following Windows PowerShell command: - ``` + ```powershell Import-StartLayout -LayoutPath "C:\Layout\user1.xml" -MountPath %systemdrive% ``` This workaround changes the Default user's Start layout. The workaround doesn't scale to a mass migrations or multiuser devices, but it can potentially unblock some scenarios. If other users will sign on to the device, you should delete layoutmodification.xml from the Default user profile. Otherwise, all users who sign on to that device will use the imported Start layout. -## Offline Migration Problems +## Offline Migration Problems The following sections describe common offline migration problems. Expand the section to see recommended solutions. -### Some of my system settings don't migrate in an offline migration. +### Some of my system settings don't migrate in an offline migration **Cause:** Some system settings, such as desktop backgrounds and network printers, aren't supported in an offline migration. For more information, see [What Does USMT Migrate?](usmt-what-does-usmt-migrate.md) **Resolution:** In an offline migration, these system settings must be restored manually. -### The ScanState tool fails with return code 26. +### The ScanState tool fails with return code 26 **Cause:** A common cause of return code 26 is that a temp profile is active on the source computer. This profile maps to c:\\users\\temp. The ScanState log shows a MigStartupOfflineCaught exception that includes the message "User profile duplicate SID error". **Resolution:** You can reboot the computer to get rid of the temp profile or you can set MIG\_FAIL\_ON\_PROFILE\_ERROR=0 to skip the error and exclude the temp profile. -### Include and Exclude rules for migrating user profiles don't work the same offline as they do online. +### Include and Exclude rules for migrating user profiles don't work the same offline as they do online **Cause:** When offline, the DNS server can't be queried to resolve the user name and SID mapping. @@ -269,7 +270,7 @@ The wild card (\*) at the end of the SID will migrate the *SID*\_Classes key as You can also use patterns for SIDs that identify generic users or groups. For example, you can use the `/ue:*-500` option to exclude the local administrator accounts. For more information about Windows SIDs, see [this Microsoft Web site](/troubleshoot/windows-server/identity/security-identifiers-in-windows). -### My script to wipe the disk fails after running the ScanState tool on a 64-bit system. +### My script to wipe the disk fails after running the ScanState tool on a 64-bit system **Cause:** The HKLM registry hive isn't unloaded after the ScanState tool has finished running. @@ -279,17 +280,17 @@ You can also use patterns for SIDs that identify generic users or groups. For ex reg.exe unload hklm\$dest$software ``` -## Hard-Link Migration Problems +## Hard-Link Migration Problems The following sections describe common hard-link migration problems. Expand the section to see recommended solutions. -### EFS files aren't restored to the new partition. +### EFS files aren't restored to the new partition **Cause:** EFS files can't be moved to a new partition with a hard link. The `/efs:hardlink` command-line option is only applicable to files migrated on the same partition. **Resolution:** Use the `/efs:copyraw` command-line option to copy EFS files during the migration instead of creating hard links, or manually copy the EFS files from the hard-link store. -### The ScanState tool can't delete a previous hard-link migration store. +### The ScanState tool can't delete a previous hard-link migration store **Cause:** The migration store contains hard links to locked files. @@ -309,4 +310,4 @@ You should also reboot the machine. [Return Codes](usmt-return-codes.md) -[UsmtUtils Syntax](usmt-utilities.md) \ No newline at end of file +[UsmtUtils Syntax](usmt-utilities.md) diff --git a/windows/deployment/usmt/usmt-common-migration-scenarios.md b/windows/deployment/usmt/usmt-common-migration-scenarios.md index 5853303709..cdb081b177 100644 --- a/windows/deployment/usmt/usmt-common-migration-scenarios.md +++ b/windows/deployment/usmt/usmt-common-migration-scenarios.md @@ -37,13 +37,13 @@ One common scenario is when the operating system is upgraded on existing hardwar [Scenario Three: Managed network migration](#bkmk-threepcreplace) -## PC-Refresh +## 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. ![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 +### 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. @@ -53,7 +53,7 @@ A company has received funds to update the operating system on all of its comput 3. 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 +### 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. @@ -63,7 +63,7 @@ A company has received funds to update the operating system on all of its comput 3. 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 +### 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. @@ -73,7 +73,7 @@ A company has received funds to update the operating system on all of its comput 3. 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 +### 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. @@ -83,14 +83,13 @@ A company has decided to update the operating system on all of its computers to 3. The administrator runs the ScanState and LoadState command-line tools successively on each computer while specifying the `/hardlink /nocompress` command-line options. -## PC-Replacement - +## 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. ![usmt pc replace scenario.](images/dep-win8-l-usmt-pcreplace.jpg) -### Scenario One: Offline migration using WinPE and an external migration store +### Scenario One: Offline migration using WinPE 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. @@ -100,7 +99,7 @@ A company is allocating 20 new computers to users in the accounting department. 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. -### Scenario Two: Manual network migration +### 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. @@ -112,7 +111,7 @@ A company receives 50 new laptops for their managers and needs to reallocate 50 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. -### Scenario Three: Managed network migration +### 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. @@ -128,4 +127,4 @@ A company is allocating 20 new computers to users in the accounting department. [Choose a Migration Store Type](usmt-choose-migration-store-type.md) -[Offline Migration Reference](offline-migration-reference.md) \ No newline at end of file +[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 6b6606f31d..8143e98216 100644 --- a/windows/deployment/usmt/usmt-configxml-file.md +++ b/windows/deployment/usmt/usmt-configxml-file.md @@ -13,8 +13,6 @@ ms.technology: itpro-deploy # Config.xml File -## 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. 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. @@ -23,7 +21,7 @@ The `Config.xml` file has a different format than the other migration .xml files 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] +> [!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. ## In this topic @@ -64,21 +62,21 @@ In USMT there are new migration policies that can be configured in the `Config.x [Sample Config.xml File](#bkmk-sampleconfigxjmlfile) -## <Policies> +## <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>**. Syntax: `` `` -## <ErrorControl> +## <ErrorControl> 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. -- **Number of occurrences**: Once for each component +- **Number of occurrences**: Once for each component -- **Parent elements**: The **<Policies>** element +- **Parent elements**: The **<Policies>** element -- **Child elements**: The **<fileError>** and **<registryError>** element +- **Child elements**: The **<fileError>** and **<registryError>** element Syntax: `` `` @@ -101,15 +99,15 @@ 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. -### <fatal> +### <fatal> The **<fatal>** element isn't required. -- **Number of occurrences**: Once for each component +- **Number of occurrences**: Once for each component -- **Parent elements**: **<fileError>** and **<registryError>** +- **Parent elements**: **<fileError>** and **<registryError>** -- **Child elements**: None. +- **Child elements**: None. Syntax: `` *<pattern>* `` @@ -119,29 +117,29 @@ Syntax: `` *<pattern>* `` You use the **<fatal>** element to specify that errors matching a specific pattern should cause USMT to halt the migration. -## <fileError> +## <fileError> The **<fileError>** element isn't required. -- **Number of occurrences**: Once for each component +- **Number of occurrences**: Once for each component -- **Parent elements**: **<ErrorControl>** +- **Parent elements**: **<ErrorControl>** -- **Child elements**: **<nonFatal>** and **<fatal>** +- **Child elements**: **<nonFatal>** and **<fatal>** Syntax: `` `` You use the **<fileError>** element to represent the behavior associated with file errors. -## <nonFatal> +## <nonFatal> The **<nonFatal>** element isn't required. -- **Number of occurrences**: Once for each component +- **Number of occurrences**: Once for each component -- **Parent elements**: The **<fileError>** and **<registryError>** elements. +- **Parent elements**: The **<fileError>** and **<registryError>** elements. -- **Child elements**: None. +- **Child elements**: None. Syntax: `` *<pattern>* `` @@ -151,15 +149,15 @@ Syntax: `` *<pattern>* `` You use the **<nonFatal>** element to specify that errors matching a specific pattern shouldn't cause USMT to halt the migration. -## <registryError> +## <registryError> -The <registryError> element isn't required. +The **<registryError>** element isn't required. -- **Number of occurrences**: Once for each component +- **Number of occurrences**: Once for each component -- **Parent elements**: **<ErrorControl>** +- **Parent elements**: **<ErrorControl>** -- **Child elements**: **<nonfatal>** and **<fatal>** +- **Child elements**: **<nonfatal>** and **<fatal>** Syntax: `` `` @@ -169,17 +167,17 @@ Syntax: `` `` You use the **<registryError>** element to specify that errors matching a specific pattern shouldn't cause USMT to halt the migration. -## <HardLinkStoreControl> +## <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>**. Syntax: `` `` -- **Number of occurrences**: Once for each component +- **Number of occurrences**: Once for each component -- **Parent elements**: **<Policies>** +- **Parent elements**: **<Policies>** -- **Child elements**: **<fileLocked>** +- **Child elements**: **<fileLocked>** Syntax: `` `` @@ -202,43 +200,43 @@ The **<HardLinkStoreControl>** sample code below specifies that hard links ``` -## <fileLocked> +## <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. Syntax: `` `` -## <createHardLink> +## <createHardLink> 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>* `` -## <errorHardLink> +## <errorHardLink> 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. Syntax: `` *<pattern>* `` -## <ProfileControl> +## <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. **<ProfileMigration>** is a child of **<Configuration>**. Syntax: <`ProfileControl>` `` -## <localGroups> +## <localGroups> This element is used to contain other elements that establish rules for how to migrate local groups. **<localGroups>** is a child of **<ProfileControl>**. Syntax: `` `` -## <mappings> +## <mappings> This element is used to contain other elements that establish mappings between groups. Syntax: `` `` -## <changeGroup> +## <changeGroup> 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: @@ -252,19 +250,19 @@ The valid and required children of **<changeGroup>** are **<include> Syntax: `` `` -## <include> +## <include> This element specifies that its required child, *<pattern>*, should be included in the migration. Syntax: `` `` -## <exclude> +## <exclude> This element specifies that its required child, *<pattern>*, should be excluded from the migration. Syntax: `` `` -## Sample Config.xml File +## 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.
@@ -467,4 +465,4 @@ Refer to the following sample `Config.xml` file for more details about items you ## Related articles -[USMT XML Reference](usmt-xml-reference.md) \ No newline at end of file +[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 8e0dec0e09..47383f7df6 100644 --- a/windows/deployment/usmt/usmt-conflicts-and-precedence.md +++ b/windows/deployment/usmt/usmt-conflicts-and-precedence.md @@ -15,47 +15,47 @@ ms.technology: itpro-deploy 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. -- **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?](#bkmk1) and the first example in [Include and exclude precedence examples](#precexamples) later in this article. +- **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?](#bkmk1) and the first example in [Include and exclude precedence examples](#precexamples) 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 **<unconditionalExclude>** 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, <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. -- **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 <include> and <exclude> 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**. +- **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**. ## In this topic **General** -- [What is the relationship between rules that are located within different components?](#bkmk2) +- [What is the relationship between rules that are located within different components?](#bkmk2) -- [How does precedence work with the Config.xml file?](#bkmk3) +- [How does precedence work with the Config.xml file?](#bkmk3) -- [How does USMT process each component in an .xml file with multiple components?](#bkmk4) +- [How does USMT process each component in an .xml file with multiple components?](#bkmk4) -- [How are rules processed?](#bkmk5) +- [How are rules processed?](#bkmk5) -- [How does USMT combine all of the .xml files that I specify on the command line?](#bkmk6) +- [How does USMT combine all of the .xml files that I specify on the command line?](#bkmk6) **The <include> and <exclude> rules** -- [What happens when there are conflicting include and exclude rules?](#bkmk1) +- [What happens when there are conflicting include and exclude rules?](#bkmk1) -- [<include> and <exclude> precedence examples](#precexamples) +- [<include> and <exclude> precedence examples](#precexamples) **File collisions** -- [What is the default behavior when there are file collisions?](#collisions) +- [What is the default behavior when there are file collisions?](#collisions) -- [How does the <merge> rule work when there are file collisions?](#bkmk11) +- [How does the <merge> rule work when there are file collisions?](#bkmk11) ## General -### What is the relationship between rules that are located within different components? +### 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. @@ -93,7 +93,7 @@ The following .xml file migrates all files from C:\\Userdocs, including .mp3 fil ``` -### How does precedence work with the Config.xml file? +### 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. @@ -105,25 +105,25 @@ 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? +### 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. -### How are rules processed? +### 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 **<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 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 **<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. -### How does USMT combine all of the .xml files that I specify on the command line? +### 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. -## The <include> and <exclude> rules +## The <include> and <exclude> rules -### What happens when there are conflicting <include> and <exclude> rules? +### What happens when there are conflicting <include> and <exclude> 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. @@ -142,15 +142,15 @@ In the following example, mp3 files won't be excluded from the migration. The mp ``` -### <include> and **<exclude>** rules precedence examples +### <include> and **<exclude>** 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. -- [Including and excluding files](#filesex) +- [Including and excluding files](#filesex) -- [Including and excluding registry objects](#regex) +- [Including and excluding registry objects](#regex) -### Including and excluding files +### Including and excluding files | If you have the following code in the same component | Resulting behavior | Explanation | |-----|-----|-----| @@ -167,7 +167,7 @@ These examples explain how USMT deals with **<include>** and **<exclude | 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. | -### Including and excluding registry objects +### Including and excluding registry objects | If you have the following code in the same component | Resulting behavior | Explanation | |-----|-----|-----| @@ -181,11 +181,11 @@ These examples explain how USMT deals with **<include>** and **<exclude ## File collisions -### What is the default behavior when there are 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. -### How does the <merge> rule work when there are file collisions? +### How does the <merge> 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. @@ -193,17 +193,17 @@ When a collision is detected, USMT will select the most specific **<merge> The source computer contains the following files: -- C:\\Data\\SampleA.txt +- `C:\Data\SampleA.txt` -- C:\\Data\\SampleB.txt +- `C:\Data\SampleB.txt` -- C:\\Data\\Folder\\SampleB.txt +- `C:\Data\Folder\SampleB.txt` The destination computer contains the following files: -- C:\\Data\\SampleB.txt +- `C:\Data\SampleB.txt` -- C:\\Data\\Folder\\SampleB.txt +- `C:\Data\SampleB.txt` You have a custom .xml file that contains the following code: @@ -217,7 +217,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. -**Example 1** +#### Example 1 ```xml @@ -229,7 +229,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. -**Example 2** +#### Example 2 ```xml @@ -242,7 +242,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, all the files will be restored, overwriting the existing files on the destination computer. -**Example 3** +#### Example 3 ```xml diff --git a/windows/deployment/usmt/usmt-custom-xml-examples.md b/windows/deployment/usmt/usmt-custom-xml-examples.md index fe1f25909d..4e749bc6c1 100644 --- a/windows/deployment/usmt/usmt-custom-xml-examples.md +++ b/windows/deployment/usmt/usmt-custom-xml-examples.md @@ -13,7 +13,7 @@ ms.date: 11/01/2022 # Custom XML Examples -## Example 1: Migrating an Unsupported Application +## 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. @@ -85,9 +85,10 @@ The following template is a template for the sections that you need to migrate y ``` + -## Example 2: Migrating the My Videos Folder +## 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. @@ -132,9 +133,10 @@ The following sample is a custom .xml file named `CustomFile.xml` that migrates ``` + -## Example 3: Migrating Files and Registry Keys +## Example 3: Migrating Files and Registry Keys The sample patterns describe the behavior in the following example .xml file. @@ -189,9 +191,10 @@ The sample patterns describe the behavior in the following example .xml file. ``` + -## Example 4: Migrating Specific Folders from Various Locations +## Example 4: Migrating Specific Folders from Various Locations The behavior for this custom .xml file is described within the `` tags in the code. @@ -268,6 +271,7 @@ The behavior for this custom .xml file is described within the `` t ``` + ## Related articles diff --git a/windows/deployment/usmt/usmt-customize-xml-files.md b/windows/deployment/usmt/usmt-customize-xml-files.md index 497fe8f067..45d046b40c 100644 --- a/windows/deployment/usmt/usmt-customize-xml-files.md +++ b/windows/deployment/usmt/usmt-customize-xml-files.md @@ -27,7 +27,7 @@ ms.technology: itpro-deploy [Additional Information](#bkmk-addlinfo) -## Overview +## 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. @@ -47,27 +47,27 @@ To modify the migration, do one or more of the following. For more information about excluding data, see the [Exclude Files and Settings](usmt-exclude-files-and-settings.md) article. -## Migration .xml Files +## 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. -> [!Note] +> [!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 MigApp.xml file.** Specify this file with both the `ScanState.exe` and `LoadState.exe` commands to migrate application settings. +- **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. You can modify the `MigDocs.xml` file. -- **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. 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. -> [!Note] +> [!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 +## 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. -## The Config.xml File +## 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. @@ -79,40 +79,39 @@ After you create this file, you need to specify it only with the `ScanState.exe` 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 will automatically be 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 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. -- 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, you can configure additional **<ErrorControl>**, **<ProfileControl>**, and **<HardLinkStoreControl>** options. For more information, see the [Config.xml File](usmt-configxml-file.md) article. -> [!Note] +> [!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. -### Examples +### Examples -- The following command creates a `Config.xml` file in the current directory, but it doesn't create a store: +- The following command creates a `Config.xml` file in the current directory, but it doesn't create a store: `scanstate /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 \\server\share\migration\mystore /i:migapp.xml /i:migdocs.xml /o /config:config.xml /v:5 /encrypt /key:"mykey"` -- The following command decrypts the store and migrates the files and settings: +- The following command decrypts the store and migrates the files and settings: `loadstate \\server\share\migration\mystore /i:migapp.xml /i:migdocs.xml /v:5 /decrypt /key:"mykey"` -## Additional Information +## 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 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 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. +- 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) \ No newline at end of file +[USMT Resources](usmt-resources.md)