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

USMT Refresh 11

Browse Source
This commit is contained in:
Frank Rojas
2024-01-02 12:27:24 -05:00
parent e185f43bf3
commit f741c889e9
33 changed files with 482 additions and 485 deletions
Download Patch File Download Diff File Expand all files Collapse all files

46
windows/deployment/usmt/getting-started-with-the-user-state-migration-tool.md
View File

@ -1,6 +1,6 @@
---
title: User State Migration Tool (USMT) - Getting Started
description: Plan, collect, and prepare your source computer for migration using the User State Migration Tool (USMT).
description: Plan, collect, and prepare the source computer for migration using the User State Migration Tool (USMT).
manager: aaroncz
ms.author: frankroj
ms.prod: windows-client
@ -12,15 +12,15 @@ ms.date: 12/06/2023
# Getting started with the User State Migration Tool (USMT)
This article outlines the general process that you should follow to migrate files and settings.
This article outlines the general process to follow to migrate files and settings.
## Step 1: Plan your migration
## Step 1: Plan the migration
1. [Plan Your Migration](usmt-plan-your-migration.md). Depending on whether your migration scenario is refreshing or replacing computers, you can choose an online migration or an offline migration using Windows Preinstallation Environment (WinPE) or the files in the Windows.old directory. For more information, see [Common Migration Scenarios](usmt-common-migration-scenarios.md).
1. [Plan The Migration](usmt-plan-your-migration.md). Depending on whether the migration scenario is refreshing or replacing computers, an online migration or an offline migration can be chosen. Offline migrations can use either Windows Preinstallation Environment (WinPE) or the files in the Windows.old directory. For more information, see [Common Migration Scenarios](usmt-common-migration-scenarios.md).
1. [Determine What to Migrate](usmt-determine-what-to-migrate.md). Data you might consider migrating includes end-user information, applications settings, operating-system settings, files, folders, and registry keys.
1. [Determine What to Migrate](usmt-determine-what-to-migrate.md). Data to consider migrating includes end-user information, applications settings, operating-system settings, files, folders, and registry keys.
1. Determine where to store data. Depending on the size of your migration store, you can store the data in one of the following locations:
1. Determine where to store data. Depending on the size of the migration store, data can be stored in one of the following locations:
- Remotely.
- Locally in a hard-link migration store or on a local external storage device.
@ -28,20 +28,20 @@ This article outlines the general process that you should follow to migrate file
For more information, see [Choose a Migration Store Type](usmt-choose-migration-store-type.md).
1. Use the `/GenMigXML` command-line option to determine which files are included in your migration, and to determine whether any modifications are necessary. For more information, see [ScanState Syntax](usmt-scanstate-syntax.md)
1. Use the `/GenMigXML` command-line option to determine which files are included in the migration, and to determine whether any modifications are necessary. For more information, see [ScanState Syntax](usmt-scanstate-syntax.md)
1. If necessary, modify copies of the `Migration.xml` and `MigDocs.xml` files and create custom **.xml** files. To modify the migration behavior, such as migrating the **Documents** folder but not the **Music** folder, 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.
1. If necessary, modify copies of the `Migration.xml` and `MigDocs.xml` files and create custom **.xml** files. To modify the migration behavior, such as migrating the **Documents** folder but not the **Music** folder, custom **.xml** file can be created or modify the rules in the existing migration **.xml** files. The document finder, or `MigXmlHelper.GenerateDocPatterns` helper function, can be used to automatically find user documents on a computer without creating extensive custom migration **.xml** files.
> [!IMPORTANT]
>
> We recommend that you always make and modify copies of the **.xml** files included in User State Migration Tool (USMT). Never modify the original **.xml** files.
> Microsoft recommends to always make copies of the **.xml** files included in User State Migration Tool (USMT) and then modify the copies. Never modify the original **.xml** files.
You can use the `MigXML.xsd` file to help you write and validate the **.xml** files. For more information about how to modify these files, see [USMT XML Reference](usmt-xml-reference.md).
The `MigXML.xsd` file can be used to help write and validate the **.xml** files. For more information about how to modify these files, see [USMT XML Reference](usmt-xml-reference.md).
1. Create a [Config.xml File](usmt-configxml-file.md) if you want to exclude any components from the migration. To create this file, run the `ScanState.exe` command with the following options:
1. Create a [Config.xml File](usmt-configxml-file.md) if to exclude any components from the migration. To create this file, run the `ScanState.exe` command with the following options:
- [/genconfig](usmt-scanstate-syntax.md#migration-rule-options).
- [/i](usmt-scanstate-syntax.md#migration-rule-options) - as arguments specify the **.xml** files that you plan to use with `ScanState.exe`.
- [/i](usmt-scanstate-syntax.md#migration-rule-options) - as arguments specify the **.xml** files that are being used with `ScanState.exe`.
For example, the following command creates a `Config.xml` file by using the `MigDocs.xml` and `MigApp.xml` files:
@ -49,19 +49,19 @@ This article outlines the general process that you should follow to migrate file
ScanState.exe /genconfig:Config.xml /i:MigDocs.xml /i:MigApp.xml /v:13 /l:ScanState.log
```
1. Open the `Config.xml` that was generated in the previous step. Review the migration state of each of the components listed in the `Config.xml` file. If necessary, edit the `Config.xml` file and specify `migrate=no` for any components that you don't want to migrate.
1. Open the `Config.xml` that was generated in the previous step. Review the migration state of each of the components listed in the `Config.xml` file. If necessary, edit the `Config.xml` file and specify `migrate=no` for any components that don't need to be migrated.
## Step 2: Collect files and settings from the source computer
1. Back up the source computer.
1. Close all applications. If some applications are running when you run the `ScanState.exe` command, USMT might not migrate all of the specified data. For example, if Microsoft Office Outlook is open, USMT might not migrate PST files.
1. Close all applications. If some applications are running when the `ScanState.exe` command is run, USMT might not migrate all of the specified data. For example, if Microsoft Office Outlook is open, USMT might not migrate PST files.
> [!NOTE]
>
> USMT fails if it can't migrate a file or setting unless you specify the `/c` option. When you specify the `/c` option, USMT ignores the errors, and log an error every time that it encounters a file that is being used that USMT didn't migrate. You can use the `<ErrorControl>` section in the `Config.xml` file to specify which errors should be ignored, and which should cause the migration to fail.
> USMT fails if it can't migrate a file or setting unless the `/c` option is specified. When the `/c` option is specified, USMT ignores the errors, and logs an error every time that it encounters a file that is being used that USMT didn't migrate. The `<ErrorControl>` section in the `Config.xml` file can be used to specify which errors should be ignored, and which should cause the migration to fail.
1. Run the `ScanState.exe` command on the source computer to collect files and settings. You should specify all of the **.xml** files that you want the `ScanState.exe` command to use. For example,
1. Run the `ScanState.exe` command on the source computer to collect files and settings. All of the **.xml** files that the `ScanState.exe` command needs to use should be specified. For example,
```cmd
ScanState.exe \\server\migration\mystore /config:Config.xml /i:MigDocs.xml /i:MigApp.xml /v:13 /l:ScanState.log
@ -69,27 +69,27 @@ This article outlines the general process that you should follow to migrate file
> [!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 how the `ScanState.exe` command processes and stores the data, see [How USMT Works](usmt-how-it-works.md).
> The `ScanState.exe` command must be run in **Administrator** mode on the source computer. To run in **Administrator** mode, right-click **Command Prompt**, and then select **Run As Administrator**. For more information about how the `ScanState.exe` command processes and stores the data, see [How USMT Works](usmt-how-it-works.md).
1. Run the `UsmtUtils.exe` command with the `/Verify` option to ensure that the store you created isn't corrupted.
1. Run the `UsmtUtils.exe` command with the `/Verify` option to ensure that the created store isn't corrupted.
## Step 3: Prepare the destination computer and restore files and settings
1. Install the operating system on the destination computer.
1. Install all applications that were on the source computer. Although it isn't always required, we recommend installing all applications on the destination computer before you restore the user state. Installing all applications before restoring user state makes sure that migrated settings are preserved.
1. Install all applications that were on the source computer. Although it isn't always required, Microsoft recommends installing all applications on the destination computer before restoring the user state. Installing all applications before restoring user state makes sure that migrated settings are preserved.
> [!NOTE]
>
> The application version that is installed on the destination computer should be the same version as the one on the source computer. USMT doesn't support migrating the settings for an older version of an application to a newer version. The exception for this rule is Microsoft Office. USMT can migrate from an older version of Microsoft Office to a newer version of Microsoft Office.
1. Close all applications. If some applications are running when you run the `LoadState.exe` command, USMT might not migrate all of the specified data. For example, if Microsoft Office Outlook is open, USMT might not migrate PST files.
1. Close all applications. If some applications are running when the `LoadState.exe` command runs, USMT might not migrate all of the specified data. For example, if Microsoft Office Outlook is open, USMT might not migrate PST files.
> [!NOTE]
>
> Use `/c` to continue your migration if errors are encountered, and use the `<ErrorControl>` section in the `Config.xml` file to specify which errors should be ignored, and which errors should cause the migration to fail.
> Use `/c` to continue the migration if errors are encountered. Use the `<ErrorControl>` section in the `Config.xml` file to specify which errors should be ignored, and which errors should cause the migration to fail.
1. Run the `LoadState.exe` command on the destination computer. Specify the same set of **.xml** files that you specified when you used the `ScanState.exe` command. However, the `Config.xml` file doesn't always need to be specified. The `Config.xml` file only needs to be specified when you wanted 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. For example, modify the `Config.xml` file and specify the updated file by using the `LoadState.exe` command. Then, the `LoadState.exe` command migrates only the files and settings that you want to migrate. For more information about how the `LoadState.exe` command processes and migrates data, see [How USMT Works](usmt-how-it-works.md).
1. Run the `LoadState.exe` command on the destination computer. Specify the same set of **.xml** files that were specified when the `ScanState.exe` command was used. However, the `Config.xml` file doesn't always need to be specified. The `Config.xml` file only needs to be specified to exclude some of the files and settings that were migrated to the store. For example, the **Documents** folder was migrated to the store, but doesn't need to be migrated to the destination computer. For example, modify the `Config.xml` file and specify the updated file by using the `LoadState.exe` command. Then, the `LoadState.exe` command migrates only the files and settings that need to be migrated. For more information about how the `LoadState.exe` command processes and migrates data, see [How USMT Works](usmt-how-it-works.md).
For example, the following command migrates the files and settings:
@ -101,4 +101,4 @@ This article outlines the general process that you should follow to migrate file
>
> Run the `LoadState.exe` command in administrator mode. To do this, right-click **Command Prompt**, and then select **Run As Administrator**.
1. Sign out after you run the `LoadState.exe` command. Some settings, such as fonts, wallpaper, and screen saver settings, won't take effect until the next time that the user logs on.
1. Sign out after running the `LoadState.exe` command. Some settings, such as fonts, wallpaper, and screen saver settings, won't take effect until the next time that the user logs on.

66
windows/deployment/usmt/migrate-application-settings.md
View File

@ -12,21 +12,21 @@ ms.technology: itpro-deploy
# Migrate Application Settings
You can create a custom **.xml** file to migrate specific line-of-business application settings or to change the default migration behavior of the User State Migration Tool (USMT). For ScanState and LoadState to use this file, you must specify the custom **.xml** file on both command lines.
A custom **.xml** file can be created to migrate specific line-of-business application settings or to change the default migration behavior of the User State Migration Tool (USMT). For ScanState and LoadState to use this file, the custom **.xml** file must be specified on both command lines.
This article defines how to author a custom migration **.xml** file that migrates the settings of an application that isn't migrated by default using `MigApp.xml`. You should migrate the settings after you install the application, but before the user runs the application for the first time.
This article defines how to author a custom migration **.xml** file that migrates the settings of an application that isn't migrated by default using `MigApp.xml`. The settings should be migrated after the application is installed, but before the user runs the application for the first time.
This article doesn't contain information about how to migrate applications that store settings in an application-specific store, only the applications that store the information in files or in the registry. It also doesn't contain information about how to migrate the data that users create using the application. For example, if the application creates .doc files using a specific template, this article doesn't discuss how to migrate the .doc files and templates themselves.
## Before you begin
## Before beginning
You should identify a test computer that contains the operating system of your source computers, and the application whose settings you want to migrate. For example, if you're planning on migrating from Windows 10 to Windows 11, install Windows 10 on your test computer and then install the application.
A test computer that contains the operating system of the source computers should be identified. The test computer should also have the applications whose settings need to be migrated. For example, if migrating from Windows 10 to Windows 11, install Windows 10 on the test computer and then install the applications.
## Step 1: Verify that the application is installed on the source computer, and that it's the same version as the version to be installed on the destination computer
Before USMT migrates the settings, you need it to check whether the application is installed on the source computer, and that it's the correct version. If the application isn't installed on the source computer, you probably don't want USMT to spend time searching for the application's settings. More importantly, if USMT collects settings for an application that isn't installed, it could migrate settings that 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 could store the settings in a different location. Mismatched application versions could lead to unexpected results on the destination computer.
Before USMT migrates the settings, check whether the application is installed on the source computer, and that it's the correct version. If the application isn't installed on the source computer, USMT still spends time searching for the application's settings. More importantly, if USMT collects settings for an application that isn't installed, it could migrate settings that cause the destination computer to function incorrectly. Also determine whether there's more than one version of the application because the new version could store the settings in a different location. Mismatched application versions could lead to unexpected results on the destination computer.
There are many ways to detect if an application is installed. The best practice is to check for an application uninstall key in the registry, and then search the computer for the executable file that installed the application. It's important that you check for both of these items, because sometimes different versions of the same application share the same uninstall key. Even if the key is there, it could correspond to a different version of the application that you want.
There are many ways to detect if an application is installed. The best practice is to check for an application uninstall key in the registry, and then search the computer for the executable file that installed the application. It's important to check for both of these items, because sometimes different versions of the same application share the same uninstall key. Even if the key is there, it could correspond to a different version of the application that is wanted.
### Check the registry for an application uninstall key
@ -38,27 +38,27 @@ For example, when Adobe Acrobat Reader 7 is installed, it creates a key named:
`HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall \{AC76BA86-7AD7-1033-7B44-A70000000000}`
Therefore, if a computer contains this key, then Adobe Acrobat Reader 7 is installed on the computer. You can check for the existence of a registry key using the `DoesObjectExist` helper function.
Therefore, if a computer contains this key, then Adobe Acrobat Reader 7 is installed on the computer. The existence of a registry key can be checked using the `DoesObjectExist` helper function.
Usually, you can find this key by searching under
Usually, this key can be found by searching under:
`HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall`
for the name of the application, the name of the application executable file, or for the name of the company that makes the application. You can use the Registry Editor, `Regedit.exe` located in the `%SystemRoot%`, to search the registry.
for the name of the application, the name of the application executable file, or for the name of the company that makes the application. The Registry Editor, `Regedit.exe` located in the `%SystemRoot%`, can be used to search the registry.
### Check the file system for the application executable file
You should also check the application binaries for the executable that installed the application. To check for application binaries, 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 on one of the following items until you find the registry value that contains the installation path:
The application binaries for the executable that installed the application should also be checked. To check for application binaries, determine where the application is installed and what the name of the executable is. Most applications store the installation location of the application binaries in the registry. The registry should be searched on one of the following items until the registry value that contains the installation path is found:
- The name of the application.
- The name of the application executable.
- The name of the company that makes the application.
Once the path to the application executable is determined, 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.
Once the path to the application executable is determined, the `DoesFileVersionMatch` helper function can be used to check for the correct version of the application executable. For an example of how to use the `DoesFileVersionMatch` helper function, see the Windows Live™ Messenger section of the `MigApp.xml` file.
## Step 2: Identify settings to collect and determine where each setting is stored on the computer
Next, you should go through the user interface and make a list of all of the available settings. You can reduce the list if there are settings that you don't want to migrate. To determine where each setting is stored, change the setting. As the setting is changed, monitor the activity on the registry and the file system. You don't need to migrate the binary files and registry settings that are created when the application is installed. When the application is reinstalled onto the destination computer, it recreates those settings. You only need to migrate the settings that are customized.
Next, go through the user interface and make a list of all of the available settings. The list can be reduced if there are settings that don't need to be migrated. To determine where each setting is stored, change the setting. As the setting is changed, monitor the activity on the registry and the file system through a tool such as [Process Monitor](/sysinternals/downloads/procmon). The binary files and registry settings that are created when the application is installed don't need to be migrated. When the application is reinstalled onto the destination computer, it recreates those settings. Only the customized settings need to be migrated.
### How to determine where each setting is stored
@ -70,11 +70,11 @@ Next, you should go through the user interface and make a list of all of the ava
> [!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 filtering considerably reduces the amount of output that needs to be examined.
> Most applications store their settings under the user profile. That is, the settings stored in the file system are under the `%UserProfile%` directory, and the settings stored in the registry are under the `HKEY_CURRENT_USER` hive. For these applications, the output of the file and registry monitoring tools can be filtered to show activity only under these locations. This filtering considerably reduces the amount of output that needs to be examined.
1. 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 doesn't take effect until you close the dialog box by selecting **OK**.
1. Start the monitoring tool(s), change a setting, and look for registry and file system writes that occurred when the setting was changed. Make sure the changes made actually take effect. For example, if changing a setting in Microsoft Word by selecting a check box in the **Options** dialog box, the change typically doesn't take effect until the dialog box is closed by selecting **OK**.
1. When the setting is changed, note the changes to the file system and registry. There could be more than one file or registry values for each setting. 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 need to migrate in order to migrate the setting.
1. When the setting is changed, note the changes to the file system and registry. There could be more than one file or registry values for each setting. The minimal set of file and registry changes that are required to change this setting should be identified. This set of files and registry keys is what needs to be migrated in order to migrate the setting.
> [!NOTE]
>
@ -82,34 +82,34 @@ Next, you should go through the user interface and make a list of all of the ava
## 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 automatically migrates the file to `D:\Users\User1\My Documents`. However, you may need to modify the location of some settings in the following three cases:
If the version of the application on the source computer is the same as the one on the destination computer, then the collected files and registry keys don't need to be modified. By default, USMT migrates the files and registry keys from the source location to the corresponding location on the destination computer. For example, if a file was collected from the `C:\Documents and Settings\User1\My Documents` folder and the profile directory on the destination computer is located at `D:\Users\User1`, then USMT automatically migrates the file to `D:\Users\User1\My Documents`. However, the location of some settings might need to be modified in the following three cases:
### Case 1: The version of the application on the destination computer is newer than the one on the source computer
In this case, the newer version of the application may be able to read the settings from the source computer without modification. That is, the data collected from an older version of the application is sometimes compatible with the newer version of the application. However, you may need to modify the setting location if either of the following conditions is true:
In this case, the newer version of the application might be able to read the settings from the source computer without modification. That is, the data collected from an older version of the application is sometimes compatible with the newer version of the application. However, the setting location might need to be modified if either of the following conditions is true:
- **The newer version of the application has the ability to import settings from an older version.** This mapping usually happens the first time a user runs the newer version after the settings are migrated. Some applications import settings automatically after settings are migrated. However, other applications only import settings if the application was upgraded from the older version. When the application is upgraded, a set of files and/or registry keys is installed that indicates the older version of the application was previously installed. If you perform a clean installation of the newer version, the computer doesn't contain these files and registry keys. If the files and registry keys aren't present, the mapping doesn't occur. In order to trick the newer version of the application into initiating this import process, your migration script may need to create these files and/or registry keys on the destination computer.
- **The newer version of the application has the ability to import settings from an older version.** This mapping usually happens the first time a user runs the newer version after the settings are migrated. Some applications import settings automatically after settings are migrated. However, other applications only import settings if the application was upgraded from the older version. When the application is upgraded, a set of files and/or registry keys is installed that indicates the older version of the application was previously installed. If a clean installation of the newer version is performed, the computer doesn't contain these files and registry keys. If the files and registry keys aren't present, the mapping doesn't occur. In order to trick the newer version of the application into initiating this import process, the migration script might need to create these files and/or registry keys on the destination computer.
To identify which files and/or registry keys/values need to be created so that the import works:
1. Upgrade the older version of the application to the newer one.
1. Monitor the changes made to the file system and registry by using the same process described in [How to determine where each setting is stored](#how-to-determine-where-each-setting-is-stored).
Once you know the set of files that the computer needs, you can use the **&lt;addObjects&gt;** element to add them to the destination computer.
Once the set of files that the computer needs is known, the **\<addObjects\>** element can be used to add them to the destination computer.
- **The newer version of the application can't read settings from the source computer and it's also unable to import the settings into the new format.** In this case, create a mapping for each setting from the old locations to the new locations. To create the mapping, determine where the newer version stores each setting using the process described in [How to determine where each setting is stored](#how-to-determine-where-each-setting-is-stored). After creating the mapping, apply the settings to the new location on the destination computer using the **&lt;locationModify&gt;** 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, create a mapping for each setting from the old locations to the new locations. To create the mapping, determine where the newer version stores each setting using the process described in [How to determine where each setting is stored](#how-to-determine-where-each-setting-is-stored). After creating the mapping, apply the settings to the new location on the destination computer using the **\<locationModify\>** element, and the `RelativeMove` and `ExactMove` helper functions.
### Case 2: The destination computer already contains settings for the application
We recommend that you migrate the settings after you install the application, but before the user runs the application for the first time. We recommend this process because this process ensures that there are no settings on the destination computer when you migrate the settings. If you must install the application before the migration, you should delete any existing settings using the **&lt;destinationCleanup&gt;** element. If for any reason you want to preserve the settings that are on the destination computer, you can use the **&lt;merge&gt;** element and `DestinationPriority` helper function.
Microsoft recommends migrating the settings after the application is installed, but before the user runs the application for the first time. Microsoft recommends this process because this process ensures that there are no settings on the destination computer when the settings are migrated. If the application must be installed before the migration, any existing settings should be deleted using the **\<destinationCleanup\>** element. If for any reason the settings need to be preserved that are on the destination computer, the **\<merge\>** element and `DestinationPriority` helper function can be used.
### Case 3: The application overwrites settings when installed
We recommend that you migrate the settings after you install the application, but before the user runs the application for the first time. We recommend this process because this process ensures that there are no settings on the destination computer when you migrate the settings. Also, when some applications are installed, they overwrite any existing settings that are on the computer. In this scenario, if you migrated the data before you installed the application, your customized settings would be overwritten. This scenario is common for applications that store settings in locations that are outside of the user profile (typically these settings are settings that apply to all users). These universal settings are sometimes overwritten when an application is installed, and they're replaced by default values. To avoid this problem, you must install these applications before migrating the files and settings to the destination computer. By default with USMT, data from the source computer overwrites data that already exists in the same location on the destination computer.
Microsoft recommends migrating the settings after the application is installed, but before the user runs the application for the first time. Microsoft recommends this process because this process ensures that there are no settings on the destination computer when the settings are migrated. Also, when some applications are installed, they overwrite any existing settings that are on the computer. In this scenario, if the data was migrated before the application was installed, the customized settings would be overwritten. This scenario is common for applications that store settings in locations that are outside of the user profile (typically these settings are settings that apply to all users). These universal settings are sometimes overwritten when an application is installed, and they're replaced by default values. To avoid this problem, these applications must be installed before migrating the files and settings to the destination computer. By default with USMT, data from the source computer overwrites data that already exists in the same location on the destination computer.
## Step 4: Create the migration XML component for the application
After completing steps 1 through 3, create a custom migration **.xml** file that migrates the application based on the information that you now have. You can use the `MigApp.xml` file as a model because it contains examples of many of the concepts discussed in this article. You can also see [Custom XML Examples](usmt-custom-xml-examples.md) for another sample **.xml** file.
After completing steps 1 through 3, create a custom migration **.xml** file that migrates the application based on the updated information. The `MigApp.xml` file can be used as a model because it contains examples of many of the concepts discussed in this article. Also see [Custom XML Examples](usmt-custom-xml-examples.md) for another sample **.xml** file.
> [!NOTE]
>
@ -117,9 +117,9 @@ After completing steps 1 through 3, create a custom migration **.xml** file that
> [!IMPORTANT]
>
> Some applications store information in the user profile, such as application installation paths, the computer name, etc., shouldn't be migrated. You should make sure to exclude these files and registry keys from the migration.
> Some applications store information in the user profile, such as application installation paths, the computer name, etc. Application information stored in the user profile shouldn't be migrated and should be excluded from the migration.
Your script should do the following actions:
The script should do the following actions:
1. Check if the correct version of the application is installed:
@ -127,24 +127,24 @@ Your script should do the following actions:
- Check for the correct version of the application executable file using the `DoesFileVersionMatch` helper function.
2. If the correct version of the application is installed, then ensure that each setting is migrated to the appropriate location on the destination computer.
1. If the correct version of the application is installed, then ensure that each setting is migrated to the appropriate location on the destination computer.
- If the versions of the applications are the same on both the source and destination computers, migrate each setting using the **&lt;include&gt;** and **&lt;exclude&gt;** 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, the script should either:
1. Add the set of files that trigger the import using the **&lt;addObjects&gt;** element.
2. Create a mapping that applies the old settings to the correct location on the destination computer using the **&lt;locationModify&gt;** element, and the `RelativeMove` and `ExactMove` helper functions.
1. Add the set of files that trigger the import using the **\<addObjects\>** element.
1. 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 **&lt;destinationCleanup&gt;** element.
- If the application must be installed 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).
## Step 5: Test the application settings migration
On a test computer, install the operating system that will be installed on the destination computers. For example, if you're planning on migrating from Windows 10 to Windows 11, install Windows 11, and then install the application in Windows 11. Next, run LoadState on the test computer and verify that all settings migrate. Make corrections if necessary and repeat the process until all the necessary settings are migrated correctly.
On a test computer, install the operating system that will be installed on the destination computers. For example, if planning on migrating from Windows 10 to Windows 11, install Windows 11, and then install the application in Windows 11. Next, run **LoadState** on the test computer and verify that all settings migrate. Make corrections if necessary and repeat the process until all the necessary settings are migrated correctly.
To speed up the time it takes to collect and migrate the data, you can migrate only one user at a time. You can also exclude all other components from the migration except the application that you're testing. To specify only **User1** in the migration, enter:
To speed up the time it takes to collect and migrate the data, only one user can be migrated at a time. All other components can be excluded from the migration except the application that is being tested. To specify only **User1** in the migration, enter:
```cmd
/ue:*\* /ui:user1

30
windows/deployment/usmt/offline-migration-reference.md
View File

@ -53,7 +53,7 @@ The following table defines the supported combination of online and offline oper
|Running Operating System|Offline Operating System|
|---|---|
|Currently supported version of WinPE, with the MSXML library|Windows 7, Windows 8, Windows 10, Windows 11|
|Windows 7, Windows 8, Windows 10, Windows 11|Windows.old directory|
|Windows 10, Windows 11|Windows.old directory|
> [!NOTE]
>
@ -61,7 +61,7 @@ The following table defines the supported combination of online and offline oper
## User-group membership and profile control
User-group membership isn't preserved during offline migrations. You must configure a **&lt;ProfileControl&gt;** section in the `Config.xml` file to specify the groups that the migrated users should be made members of. The following example places all migrated users into the Users group:
User-group membership isn't preserved during offline migrations. 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:
```xml
<Configuration>
@ -87,9 +87,9 @@ An offline migration can either be enabled by using a configuration file on the
|Component|Option|Description|
|--- |--- |--- |
|*ScanState.exe*|**/offline:***&lt;path to Offline.xml&gt;*|This command-line option enables the offline-migration mode and requires a path to an Offline.xml configuration file.|
|*ScanState.exe*|**/offlineWinDir:***&lt;Windows directory&gt;*|This command-line option enables the offline-migration mode and starts the migration from the location specified. It's only for use in WinPE offline scenarios where the migration is occurring from a Windows directory.|
|*ScanState.exe*|**/OfflineWinOld:***&lt;Windows.old directory&gt;*|This command-line option enables the offline migration mode and starts the migration from the location specified. Only use in Windows.old migration scenarios, where the migration is occurring from a Windows.old directory.|
|*ScanState.exe*|**/offline:***\<path to Offline.xml\>*|This command-line option enables the offline-migration mode and requires a path to an Offline.xml configuration file.|
|*ScanState.exe*|**/offlineWinDir:***\<Windows directory\>*|This command-line option enables the offline-migration mode and starts the migration from the location specified. It's only for use in WinPE offline scenarios where the migration is occurring from a Windows directory.|
|*ScanState.exe*|**/OfflineWinOld:***\<Windows.old directory\>*|This command-line option enables the offline migration mode and starts the migration from the location specified. Only use in Windows.old migration scenarios, where the migration is occurring from a Windows.old directory.|
You can use only one of the `/offline`, `/offlineWinDir`, or `/OfflineWinOld` command-line options at a time. USMT doesn't support using more than one together.
@ -106,7 +106,7 @@ System environment variables are necessary in the scenarios outlined in the foll
Use an `Offline.xml` file when running the ScanState tool on a computer that has multiple Windows directories. The `Offline.xml` file specifies which directories to scan for windows files. An `Offline.xml` file can be used with the `/offline` option as an alternative to specifying a single Windows directory path with the `/offlineDir` option.
### &lt;offline&gt;
### \<offline\>
This element contains other elements that define how an offline migration is to be performed.
@ -116,9 +116,9 @@ Syntax:
<offline> </offline>
```
### &lt;winDir&gt;
### \<winDir\>
This element is a required child of **&lt;offline&gt;** and contains information about how the offline volume can be selected. The migration is performed from the first element of **&lt;winDir&gt;** that contains a valid Windows system volume.
This element is a required child of **\<offline\>** and contains information about how the offline volume can be selected. The migration is performed from the first element of **\<winDir\>** that contains a valid Windows system volume.
Syntax:
@ -126,9 +126,9 @@ Syntax:
<winDir> </winDir>
```
### &lt;path&gt;
### \<path\>
This element is a required child of **&lt;winDir&gt;** and contains a file path pointing to a valid Windows directory. Relative paths are interpreted from the ScanState tool's working directory.
This element is a required child of **\<winDir\>** and contains a file path pointing to a valid Windows directory. Relative paths are interpreted from the ScanState tool's working directory.
Syntax:
@ -136,7 +136,7 @@ Syntax:
<path> C:\Windows </path>
```
or when used with the **&lt;mappings&gt;** element:
or when used with the **\<mappings\>** element:
Syntax:
@ -144,9 +144,9 @@ Syntax:
<path> C:\, D:\ </path>
```
### &lt;mappings&gt;
### \<mappings\>
This element is an optional child of **&lt;offline&gt;**. When specified, the **&lt;mappings&gt;** element overrides the automatically detected WinPE drive mappings. Each child **&lt;path&gt;** element provides a mapping from one system volume to another. Additionally, mappings between folders can be provided, since an entire volume can be mounted to a specific folder.
This element is an optional child of **\<offline\>**. When specified, the **\<mappings\>** element overrides the automatically detected WinPE drive mappings. Each child **\<path\>** element provides a mapping from one system volume to another. Additionally, mappings between folders can be provided, since an entire volume can be mounted to a specific folder.
Syntax:
@ -154,9 +154,9 @@ Syntax:
<mappings> </mappings>
```
### &lt;failOnMultipleWinDir&gt;
### \<failOnMultipleWinDir\>
This element is an optional child of **&lt;offline&gt;**. The **&lt;failOnMultipleWinDir&gt;** element allows the user to specify that the migration should fail when USMT detects that there are multiple instances of Windows installed on the source machine. When the **&lt;failOnMultipleWinDir&gt;** element isn't present, the default behavior is that the migration doesn't fail.
This element is an optional child of **\<offline\>**. The **\<failOnMultipleWinDir\>** element allows the user to specify that the migration should fail when USMT detects that there are multiple instances of Windows installed on the source machine. When the **\<failOnMultipleWinDir\>** element isn't present, the default behavior is that the migration doesn't fail.
Syntax:

12
windows/deployment/usmt/understanding-migration-xml-files.md
View File

@ -164,7 +164,7 @@ You can use multiple XML files with the ScanState and LoadState tools. Each of t
|XML migration file|Modifies the following components:|
|--- |--- |
|**Config.xml file**|Operating-system components such as desktop wallpaper and background theme.<br/> 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.<br> 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.|
@ -210,8 +210,8 @@ To generate the XML migration rules file for a source computer:
where:
- **&lt;USMTpath&gt;** - location on your source computer of the saved USMT files and tools.
- **&lt;filepath.xml&gt;** - full path to a file where you can save the report.
- **\<USMTpath\>** - location on your source computer of the saved USMT files and tools.
- **\<filepath.xml\>** - full path to a file where you can save the report.
For example, enter:
@ -280,7 +280,7 @@ To create exclude data patterns:
### Understanding the system and user context
The migration XML files contain two &lt;component&gt; elements with different **context** settings:
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.
- The user context applies to files that are particular to an individual user.
@ -369,7 +369,7 @@ To exclude Rule 1, there needs to be an exact match of the file name. However, f
#### Example 2: Use the UnconditionalExclude element to give a rule precedence over include rules
If you don't know the file name or location of the file, but you do know the file name extension, you can use the `GenerateDrivePatterns` function. However, the rule is less specific than the default include rule generated by the `MigDocs.xml` file, so it doesn't have precedence. You must use the &lt;UnconditionalExclude&gt; element to give this rule precedence over the default include rule. For more information about the order of precedence for XML migration rules, see [Conflicts and Precedence](usmt-conflicts-and-precedence.md).
If 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 is less specific than the default include rule generated by the `MigDocs.xml` file, so it doesn't 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).
```xml
<unconditionalExclude>
@ -381,7 +381,7 @@ If you don't know the file name or location of the file, but you do know the fil
#### Example 3: Use a UserandSystem context component to run rules in both contexts
If you want the **&lt;UnconditionalExclude&gt;** element to apply to both the system and user context, you can create a third component using the **UserandSystem** context. Rules in this component 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 run in both contexts.
```xml
<component type="Documents" context="UserandSystem">

8
windows/deployment/usmt/usmt-best-practices.md
View File

@ -86,9 +86,9 @@ As the authorized administrator, it is your responsibility to protect the privac
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 &lt;CustomFileName&gt; 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 **&lt;CustomFileName&gt;** to match the name of the file. For example, the following example is from the `MigApp.xml` file:
Although it isn't a requirement, it's good practice for **\<CustomFileName\>** to match the name of the file. For example, the following example is from the `MigApp.xml` file:
```xml
<?xml version="1.0" encoding="UTF-8"?>
@ -103,9 +103,9 @@ As the authorized administrator, it is your responsibility to protect the privac
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 &lt;context&gt; parameter**
- **Consider the impact on performance when using the \<context\> parameter**
Your migration performance can be affected when you use the **&lt;context&gt;** element with the **&lt;component&gt;** element; for example, as in when you want to encapsulate logical units of file- or path-based **&lt;include&gt;** and **&lt;exclude&gt;** rules.
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.
In the **User** context, a rule is processed one time for each user on the system.

20
windows/deployment/usmt/usmt-common-migration-scenarios.md
View File

@ -34,9 +34,9 @@ A company receives funds to update the operating system on all of its computers
1. On each computer, the administrator boots the machine into WinPE and runs the **ScanState** command-line tool, specifying the `/hardlink /nocompress` command-line options. **ScanState** saves the user state to a hard-link migration store on each computer, improving performance by minimizing network traffic and minimizing migration failures on computers with limited space available on the hard drive.
2. On each computer, the administrator installs the company's standard operating environment (SOE) which includes the latest supported version of Windows and other company applications.
1. On each computer, the administrator installs the company's standard operating environment (SOE) which includes the latest supported version of Windows and other company applications.
3. The administrator runs the **LoadState** command-line tool on each computer. **LoadState** restores each user state back to each computer.
1. The administrator runs the **LoadState** command-line tool on each computer. **LoadState** restores each user state back to each computer.
### Scenario Two: PC-refresh using a compressed migration store
@ -44,9 +44,9 @@ A company receives funds to update the operating system on all of its computers
1. The administrator runs the **ScanState** command-line tool on each computer. **ScanState** saves each user state to a server.
2. On each computer, the administrator installs the company's standard SOE that includes the latest supported version of Windows and other company applications.
1. On each computer, the administrator installs the company's standard SOE that includes the latest supported version of Windows and other company applications.
3. The administrator runs the **LoadState** command-line tool on each source computer, and **LoadState** restores each user state back to the computer.
1. The administrator runs the **LoadState** command-line tool on each source computer, and **LoadState** restores each user state back to the computer.
### Scenario Three: PC-refresh using a hard-link migration store
@ -54,9 +54,9 @@ A company receives funds to update the operating system on all of its computers
1. The administrator runs the **ScanState** command-line tool on each computer, specifying the `/hardlink /nocompress` command-line options. **ScanState** saves the user state to a hard-link migration store on each computer, improving performance by minimizing network traffic and minimizing migration failures on computers with limited space available on the hard drive.
2. On each computer, the administrator installs the company's SOE that includes the latest supported version of Windows and other company applications.
1. On each computer, the administrator installs the company's SOE that includes the latest supported version of Windows and other company applications.
3. The administrator runs the **LoadState** command-line tool on each computer. **LoadState** restores each user state back on each computer.
1. The administrator runs the **LoadState** command-line tool on each computer. **LoadState** restores each user state back on each computer.
### Scenario Four: PC-refresh using Windows.old folder and a hard-link migration store
@ -67,9 +67,9 @@ A company decides to update the operating system on all of its computers to the
- Performing the install without formatting or repartitioning the disk.
- Selecting a partition that contains the previous version of Windows.
2. On each computer, the administrator installs the company's SOE that includes company applications.
1. On each computer, the administrator installs the company's SOE that includes company applications.
3. The administrator runs the **ScanState** and **LoadState** command-line tools successively on each computer while specifying the `/hardlink /nocompress` command-line options.
1. The administrator runs the **ScanState** and **LoadState** command-line tools successively on each computer while specifying the `/hardlink /nocompress` command-line options.
## PC-replacement
@ -83,9 +83,9 @@ A company is allocating 20 new computers to users in the accounting department.
1. On each source computer, an administrator boots the machine into WinPE and runs **ScanState** to collect the user state to either a server or an external hard disk.
2. On each new computer, the administrator installs the company's SOE that includes the latest supported version of Windows and other company applications.
1. On each new computer, the administrator installs the company's SOE that includes the latest supported version of Windows and other company applications.
3. On each of the new computers, the administrator runs the **LoadState** tool, restoring each user state from the migration store to one of the new computers.
1. On each of the new computers, the administrator runs the **LoadState** tool, restoring each user state from the migration store to one of the new computers.
### Scenario Two: Manual network migration

108
windows/deployment/usmt/usmt-configxml-file.md
View File

@ -26,11 +26,11 @@ For more information about using the `Config.xml` file with other migration file
## Migration Policies
In USMT, there are migration policies that can be configured in the `Config.xml` file. For example, you can configure **&lt;ErrorControl&gt;**, **&lt;ProfileControl&gt;**, and **&lt;HardLinkStoreControl&gt;** options. The following elements and parameters are for use in the `Config.xml` file only.
In USMT, there are migration policies that can be configured in the `Config.xml` file. For example, you can configure **\<ErrorControl\>**, **\<ProfileControl\>**, and **\<HardLinkStoreControl\>** options. The following elements and parameters are for use in the `Config.xml` file only.
### &lt;Policies&gt;
### \<Policies\>
The **&lt;Policies&gt;** element contains elements that describe the policies that USMT follows while creating a migration store. Valid children of the **&lt;Policies&gt;** element are **&lt;ErrorControl&gt;** and **&lt;HardLinkStoreControl&gt;**. The **&lt;Policies&gt;** element is a child of **&lt;Configuration&gt;**.
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:
@ -38,15 +38,15 @@ Syntax:
<Policies> </Policies>
```
### &lt;ErrorControl&gt;
### \<ErrorControl\>
The **&lt;ErrorControl&gt;** element is an optional element you can configure in the `Config.xml` file. The configurable **&lt;ErrorControl&gt;** rules support only the environment variables for the operating system that is running and the currently logged-on user. As a workaround, you can specify a path using the (\*) wildcard character.
The **\<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
- **Parent elements**: The **&lt;Policies&gt;** element
- **Parent elements**: The **\<Policies\>** element
- **Child elements**: The **&lt;fileError&gt;** and **&lt;registryError&gt;** element
- **Child elements**: The **\<fileError\>** and **\<registryError\>** element
Syntax:
@ -54,9 +54,9 @@ Syntax:
<ErrorControl> </ErrorControl>
```
The following example specifies that all locked files, regardless of their location (including files in C:\\Users), should be ignored. However, the migration fails if any file in C:\\Users can't be accessed because of any other reason. In the following example, the **&lt;ErrorControl&gt;** element ignores any problems in migrating registry keys that match the supplied pattern, and it resolves them to an **Access denied** error.
The following example specifies that all locked files, regardless of their location (including files in C:\\Users), should be ignored. However, the migration fails if any file in C:\\Users can't be accessed because of any other reason. In the following example, the **\<ErrorControl\>** element ignores any problems in migrating registry keys that match the supplied pattern, and it resolves them to an **Access denied** error.
Additionally, the order in the **&lt;ErrorControl&gt;** section implies priority. In this example, the first **&lt;nonFatal&gt;** tag takes precedence over the second **&lt;fatal&gt;** tag. This precedence is applied, regardless of how many tags are listed.
Additionally, the order in the **\<ErrorControl\>** section implies priority. In this example, the first **\<nonFatal\>** tag takes precedence over the second **\<fatal\>** tag. This precedence is applied, regardless of how many tags are listed.
```xml
<ErrorControl>
@ -72,15 +72,15 @@ Additionally, the order in the **&lt;ErrorControl&gt;** section implies priority
> [!IMPORTANT]
>
> The configurable **&lt;ErrorControl&gt;** rules support only the environment variables for the operating system that is running and the currently logged-on user. As a workaround, you can specify a path using the (\*) wildcard character.
> The configurable **\<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.
### &lt;fatal&gt;
### \<fatal\>
The **&lt;fatal&gt;** element isn't required.
The **\<fatal\>** element isn't required.
- **Number of occurrences**: Once for each component
- **Parent elements**: **&lt;fileError&gt;** and **&lt;registryError&gt;**
- **Parent elements**: **\<fileError\>** and **\<registryError\>**
- **Child elements**: None.
@ -94,17 +94,17 @@ Syntax:
|--- |--- |--- |
|errorCode|No|"any" or "*specify system error message here*"|
You use the **&lt;fatal&gt;** element to specify that errors matching a specific pattern should cause USMT to halt the migration.
You use the **\<fatal\>** element to specify that errors matching a specific pattern should cause USMT to halt the migration.
### &lt;fileError&gt;
### \<fileError\>
The **&lt;fileError&gt;** element isn't required.
The **\<fileError\>** element isn't required.
- **Number of occurrences**: Once for each component
- **Parent elements**: **&lt;ErrorControl&gt;**
- **Parent elements**: **\<ErrorControl\>**
- **Child elements**: **&lt;nonFatal&gt;** and **&lt;fatal&gt;**
- **Child elements**: **\<nonFatal\>** and **\<fatal\>**
Syntax:
@ -112,15 +112,15 @@ Syntax:
<fileError> </fileError>
```
You use the **&lt;fileError&gt;** element to represent the behavior associated with file errors.
You use the **\<fileError\>** element to represent the behavior associated with file errors.
### &lt;nonFatal&gt;
### \<nonFatal\>
The **&lt;nonFatal&gt;** element isn't required.
The **\<nonFatal\>** element isn't required.
- **Number of occurrences**: Once for each component
- **Parent elements**: The **&lt;fileError&gt;** and **&lt;registryError&gt;** elements.
- **Parent elements**: The **\<fileError\>** and **\<registryError\>** elements.
- **Child elements**: None.
@ -132,19 +132,19 @@ Syntax:
|Parameter|Required|Value|
|--- |--- |--- |
|**&lt;errorCode&gt;**|No|"any" or "*specify system error message*". If system error messages aren't specified, the default behavior applies the parameter to all system error messages.|
|**\<errorCode\>**|No|"any" or "*specify system error message*". If system error messages aren't specified, the default behavior applies the parameter to all system error messages.|
You use the **&lt;nonFatal&gt;** element to specify that errors matching a specific pattern shouldn't cause USMT to halt the migration.
You use the **\<nonFatal\>** element to specify that errors matching a specific pattern shouldn't cause USMT to halt the migration.
### &lt;registryError&gt;
### \<registryError\>
The **&lt;registryError&gt;** element isn't required.
The **\<registryError\>** element isn't required.
- **Number of occurrences**: Once for each component
- **Parent elements**: **&lt;ErrorControl&gt;**
- **Parent elements**: **\<ErrorControl\>**
- **Child elements**: **&lt;nonfatal&gt;** and **&lt;fatal&gt;**
- **Child elements**: **\<nonfatal\>** and **\<fatal\>**
Syntax:
@ -154,13 +154,13 @@ Syntax:
|Parameter|Required|Value|
|--- |--- |--- |
|**&lt;errorCode&gt;**|No|"any" or "*specify system error message here*". If system error messages aren't specified, the default behavior applies the parameter to all system error messages.|
|**\<errorCode\>**|No|"any" or "*specify system error message here*". If system error messages aren't specified, the default behavior applies the parameter to all system error messages.|
You use the **&lt;registryError&gt;** element to specify that errors matching a specific pattern shouldn't cause USMT to halt the migration.
You use the **\<registryError\>** element to specify that errors matching a specific pattern shouldn't cause USMT to halt the migration.
### &lt;HardLinkStoreControl&gt;
### \<HardLinkStoreControl\>
The **&lt;HardLinkStoreControl&gt;** element contains elements that describe how to handle files during the creation of a hard-link migration store. Its only valid child is **&lt;fileLocked&gt;**.
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:
@ -170,9 +170,9 @@ Syntax:
- **Number of occurrences**: Once for each component
- **Parent elements**: **&lt;Policies&gt;**
- **Parent elements**: **\<Policies\>**
- **Child elements**: **&lt;fileLocked&gt;**
- **Child elements**: **\<fileLocked\>**
Syntax:
@ -180,11 +180,11 @@ Syntax:
<HardLinkStoreControl> </HardLinkStoreControl>
```
The following **&lt;HardLinkStoreControl&gt;** sample code specifies that hard links can be created to locked files only if the locked file resides somewhere under C:\\Users\\. Otherwise, a file-access error occurs when a locked file is encountered that can't be copied, even though is technically possible for the link to be created.
The following **\<HardLinkStoreControl\>** sample code specifies that hard links can be created to locked files only if the locked file resides somewhere under C:\\Users\\. Otherwise, a file-access error occurs when a locked file is encountered that can't be copied, even though is technically possible for the link to be created.
> [!IMPORTANT]
>
> The **&lt;ErrorControl&gt;** section can be configured to conditionally ignore file access errors, based on the file's location.
> The **\<ErrorControl\>** section can be configured to conditionally ignore file access errors, based on the file's location.
```xml
<Policy>
@ -200,9 +200,9 @@ The following **&lt;HardLinkStoreControl&gt;** sample code specifies that hard l
</Policy>
```
### &lt;fileLocked&gt;
### \<fileLocked\>
The **&lt;fileLocked&gt;** element contains elements that describe how to handle files that are locked for editing. The rules defined by the **&lt;fileLocked&gt;** element are processed in the order in which they appear in the XML file.
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:
@ -210,9 +210,9 @@ Syntax:
<fileLocked> </fileLocked>
```
### &lt;createHardLink&gt;
### \<createHardLink\>
The **&lt;createHardLink&gt;** 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.
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:
@ -220,9 +220,9 @@ Syntax:
<createHardLink> <specify pattern here> </createHardLink>
```
### &lt;errorHardLink&gt;
### \<errorHardLink\>
The **&lt;errorHardLink&gt;** element defines a standard MigXML pattern that describes file paths where hard links shouldn't be created if the file is locked for editing by another application. USMT attempts to copy files under these paths into the migration store. However, if that isn't possible, **Error\_Locked** is thrown. This error is a standard Windows application programming interface (API) error that can be captured by the **&lt;ErrorControl&gt;** section to either cause USMT to skip the file or abort the migration.
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 attempts to copy files under these paths into the migration store. However, if that isn't possible, **Error\_Locked** is thrown. This error is a standard Windows application programming interface (API) error that can be captured by the **\<ErrorControl\>** section to either cause USMT to skip the file or abort the migration.
Syntax:
@ -230,9 +230,9 @@ Syntax:
<errorHardLink> <specify pattern here> </errorHardLink>
```
### &lt;ProfileControl&gt;
### \<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. **&lt;ProfileMigration&gt;** is a child of **&lt;Configuration&gt;**.
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:
@ -240,9 +240,9 @@ Syntax:
<ProfileControl> </ProfileControl>
```
### &lt;localGroups&gt;
### \<localGroups\>
This element is used to contain other elements that establish rules for how to migrate local groups. **&lt;localGroups&gt;** is a child of **&lt;ProfileControl&gt;**.
This element is used to contain other elements that establish rules for how to migrate local groups. **\<localGroups\>** is a child of **\<ProfileControl\>**.
Syntax:
@ -250,7 +250,7 @@ Syntax:
<localGroups> </localGroups>
```
### &lt;mappings&gt;
### \<mappings\>
This element is used to contain other elements that establish mappings between groups.
@ -260,9 +260,9 @@ Syntax:
<mappings> </mappings>
```
### &lt;changeGroup&gt;
### \<changeGroup\>
This element describes the source and destination groups for a local group membership change during the migration. It's a child of **&lt;localGroups&gt;**. The following parameters are defined:
This element describes the source and destination groups for a local group membership change during the migration. It's a child of **\<localGroups\>**. The following parameters are defined:
|Parameter|Required|Value|
|--- |--- |--- |
@ -270,7 +270,7 @@ This element describes the source and destination groups for a local group membe
|To|Yes|A local group that the users are to be moved to during the migration.|
|appliesTo|Yes|nonmigratedUsers, migratedUsers, AllUsers. This value defines which users the change group operation should apply to.|
The valid and required children of **&lt;changeGroup&gt;** are **&lt;include&gt;** and **&lt;exclude&gt;**. Although both can be children at the same time, only one is required.
The valid and required children of **\<changeGroup\>** are **\<include\>** and **\<exclude\>**. Although both can be children at the same time, only one is required.
Syntax:
@ -278,9 +278,9 @@ Syntax:
<changeGroup From="Group1" To= "Group2"> </changeGroup>
```
### &lt;include&gt;
### \<include\>
This element specifies that its required child, *&lt;pattern&gt;*, should be included in the migration.
This element specifies that its required child, *\<pattern\>*, should be included in the migration.
Syntax:
@ -288,9 +288,9 @@ Syntax:
<include> </include>
```
### &lt;exclude&gt;
### \<exclude\>
This element specifies that its required child, *&lt;pattern&gt;*, should be excluded from the migration.
This element specifies that its required child, *\<pattern\>*, should be excluded from the migration.
Syntax:

62
windows/deployment/usmt/usmt-conflicts-and-precedence.md
View File

@ -14,27 +14,27 @@ ms.technology: itpro-deploy
When you include, exclude, and reroute files and settings, it's important to know how User State Migration Tool (USMT) 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 **&lt;unconditionalExclude&gt;** 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 &lt;include&gt; and &lt;exclude&gt; rules?](#what-happens-when-there-are-conflicting-include-and-exclude-rules) and the first example in [&lt;include&gt; and &lt;exclude&gt; rules precedence examples](#include-and-exclude-rules-precedence-examples) later in this article.
- **If there are conflicting rules within a component, the most specific rule is applied.** However, the **\<unconditionalExclude\>** rule is an exception because it takes precedence over all others. Directory names take precedence over file extensions. For examples, see [What happens when there are conflicting \<include\> and \<exclude\> rules?](#what-happens-when-there-are-conflicting-include-and-exclude-rules) and the first example in [\<include\> and \<exclude\> rules precedence examples](#include-and-exclude-rules-precedence-examples) later in this article.
- **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 **&lt;unconditionalExclude&gt;** 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, &lt;exclude&gt; takes precedence over &lt;include&gt;.** For example, if you use the **&lt;exclude&gt;** rule to exclude a file and use the **&lt;include&gt;** 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 the &lt;include&gt; and &lt;exclude&gt; 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 &lt;unconditionalExclude&gt; element to globally exclude data.** This element excludes objects, regardless of any other **&lt;include&gt;** rules that are in the **.xml** files. For example, you can use the **&lt;unconditionalExclude&gt;** 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`.
## General
### What is the relationship between rules that are located within different components?
Only rules inside the same component can affect each other, depending on specificity, except for the **&lt;unconditionalExclude&gt;** rule. Rules that are in different components don't affect each other. If there's an **&lt;include&gt;** rule in one component and an identical **&lt;exclude&gt;** rule in another component, the data will be migrated because the two rules are independent of each other.
Only rules inside the same component can affect each other, depending on specificity, except for the **\<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.
If you have an **&lt;include&gt;** rule in one component and a **&lt;locationModify&gt;** 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 **&lt;include&gt;** rule, and it will be migrated based on the **&lt;locationModify&gt;** rule.
If you have an **\<include\>** rule in one component and a **\<locationModify\>** rule in another component for the same file, the file will be migrated in both places. That is, it will be included based on the **\<include\>** rule, and it will be migrated based on the **\<locationModify\>** rule.
The following **.xml** file migrates all files from C:\\Userdocs, including .mp3 files, because the **&lt;exclude&gt;** rule is specified in a separate component.
The following **.xml** file migrates all files from C:\\Userdocs, including .mp3 files, because the **\<exclude\>** rule is specified in a separate component.
```xml
<migration urlid="http://www.microsoft.com/migration/1.0/migxmlext/UserDocs">
@ -80,25 +80,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?
The ordering of components doesn't matter. Each component is processed independently of other components. For example, if you have an **&lt;include&gt;** rule in one component and a **&lt;locationModify&gt;** 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 **&lt;include&gt;** rule, and it will be migrated based on the **&lt;locationModify&gt;** rule.
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?
There are two broad categories of rules.
- **Rules that affect the behavior of both the ScanState and LoadState tools**. For example, the **&lt;include&gt;**, **&lt;exclude&gt;**, and **&lt;unconditionalExclude&gt;** 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 **&lt;include&gt;** 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 **&lt;locationModify&gt;**, **&lt;contentModify&gt;**, and **&lt;destinationCleanup&gt;** 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 **&lt;locationModify&gt;** and **&lt;contentModify&gt;** rules. Then, LoadState processes all of the **&lt;destinationCleanup&gt;** 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?
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 &lt;include&gt; and &lt;exclude&gt; rules
## The \<include\> and \<exclude\> rules
### What happens when there are conflicting &lt;include&gt; and &lt;exclude&gt; 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 **&lt;unconditionalExclude&gt;** rule, which takes precedence over all other rules. If the rules are equally specific, then the data won't be migrated. For example if you exclude a file, and include the same file, the file won't be migrated. If there are conflicting rules within different components, the rules don't affect each other because each component is processed independently.
If there are conflicting rules within a component, the most specific rule is applied, except with the **\<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.
In the following example, mp3 files won't be excluded from the migration. The mp3 files won't be excluded because directory names take precedence over the file extensions.
@ -115,9 +115,9 @@ In the following example, mp3 files won't be excluded from the migration. The mp
</exclude>
```
### &lt;include&gt; and &lt;exclude&gt; rules precedence examples
### \<include\> and \<exclude\> rules precedence examples
These examples explain how USMT deals with **&lt;include&gt;** and **&lt;exclude&gt;** rules. When the rules are in different components, the resulting behavior will be the same regardless of whether the components are in the same or in different migration **.xml** files.
These examples explain how USMT deals with **\<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](#including-and-excluding-files)
@ -127,40 +127,40 @@ These examples explain how USMT deals with **&lt;include&gt;** and **&lt;exclude
| If you have the following code in the same component | Resulting behavior | Explanation |
|-----|-----|-----|
| <ul><li>Include rule: &lt;pattern type=&quot;File&quot;&gt;C:\Dir1* []&lt;/pattern&gt;</li><li>Exclude rule: &lt;pattern type=&quot;File&quot;&gt;C:* [.txt]&lt;/pattern&gt;</li></ul> | Migrates all files and subfolders in Dir1 (including all .txt files in C:). | The **&lt;exclude&gt;** rule doesn't affect the migration because the **&lt;include&gt;** rule is more specific. |
| <ul><li>Include rule: &lt;pattern type=&quot;File&quot;&gt;C:\Dir1* []&lt;/pattern&gt;</li><li>Exclude rule: &lt;pattern type=&quot;File&quot;&gt;C:\Dir1\Dir2* [.txt]&lt;/pattern&gt;</li></ul> | Migrates all files and subfolders in C:\Dir1, except the .txt files in C:\Dir1\Dir2 and its subfolders. | Both rules are processed as intended. |
| <ul><li>Include rule: &lt;pattern type=&quot;File&quot;&gt;C:\Dir1* []&lt;/pattern&gt;</li><li>Exclude rule: &lt;pattern type=&quot;File&quot;&gt;C:\Dir1\ * [.txt]&lt;/pattern&gt;</li></ul> | Migrates all files and subfolders in C:\Dir1, except the .txt files in C:\Dir1 and its subfolders. | Both rules are processed as intended. |
| <ul><li>Include rule: &lt;pattern type=&quot;File&quot;&gt;C:\Dir1\Dir2* [.txt]&lt;/pattern&gt;</li><li>Exclude rule: &lt;pattern type=&quot;File&quot;&gt;C:\Dir1\Dir2* [.txt]&lt;/pattern&gt;</li></ul> | Nothing will be migrated. | The rules are equally specific, so the **&lt;exclude&gt;** rule takes precedence over the **&lt;include&gt;** rule. |
| <ul><li>Include rule: C:\Dir1* [.txt]</li><li>Exclude rule: C:\Dir1\Dir2* []</li></ul> | Migrates the .txt files in Dir1 and the .txt files from subfolders other than Dir2. <br/>No files are migrated from Dir2 or its subfolders. | Both rules are processed as intended. |
| <ul><li>Include rule: \<pattern type=&quot;File&quot;\>C:\Dir1* []\</pattern\></li><li>Exclude rule: \<pattern type=&quot;File&quot;\>C:* [.txt]\</pattern\></li></ul> | Migrates all files and subfolders in Dir1 (including all .txt files in C:). | The **\<exclude\>** rule doesn't affect the migration because the **\<include\>** rule is more specific. |
| <ul><li>Include rule: \<pattern type=&quot;File&quot;\>C:\Dir1* []\</pattern\></li><li>Exclude rule: \<pattern type=&quot;File&quot;\>C:\Dir1\Dir2* [.txt]\</pattern\></li></ul> | Migrates all files and subfolders in C:\Dir1, except the .txt files in C:\Dir1\Dir2 and its subfolders. | Both rules are processed as intended. |
| <ul><li>Include rule: \<pattern type=&quot;File&quot;\>C:\Dir1* []\</pattern\></li><li>Exclude rule: \<pattern type=&quot;File&quot;\>C:\Dir1\ * [.txt]\</pattern\></li></ul> | Migrates all files and subfolders in C:\Dir1, except the .txt files in C:\Dir1 and its subfolders. | Both rules are processed as intended. |
| <ul><li>Include rule: \<pattern type=&quot;File&quot;\>C:\Dir1\Dir2* [.txt]\</pattern\></li><li>Exclude rule: \<pattern type=&quot;File&quot;\>C:\Dir1\Dir2* [.txt]\</pattern\></li></ul> | Nothing will be migrated. | The rules are equally specific, so the **\<exclude\>** rule takes precedence over the **\<include\>** rule. |
| <ul><li>Include rule: C:\Dir1* [.txt]</li><li>Exclude rule: C:\Dir1\Dir2* []</li></ul> | Migrates the .txt files in Dir1 and the .txt files from subfolders other than Dir2. <br>No files are migrated from Dir2 or its subfolders. | Both rules are processed as intended. |
| <ul><li>Include rule: C:\Dir1\Dir2* []</li><li>Exclude rule: C:\Dir1* [.txt]</li></ul> | Migrates all files and subfolders of Dir2, except the .txt files from Dir1 and any subfolders of Dir1 (including Dir2). | Both rules are processed as intended. |
| If you have the following code in different components | Resulting behavior | Explanation |
|-----|----|----|
| Component 1:<ul><li>Include rule: &lt;pattern type=&quot;File&quot;&gt;C:\Dir1* []&lt;/pattern&gt;</li><li>Exclude rule: &lt;pattern type=&quot;File&quot;&gt;C:\Dir1\Dir2* [.txt]&lt;/pattern&gt;</li></ul> <br/>Component 2:<ul><li>Include rule: &lt;pattern type=&quot;File&quot;&gt;C:\Dir1\Dir2* [.txt]&lt;/pattern&gt;</li><li>Exclude rule: &lt;pattern type=&quot;File&quot;&gt;C:\Dir1* []&lt;/pattern&gt;</li></ul> | Migrates all files and subfolders of C:\Dir1\ (including C:\Dir1\Dir2). | Rules that are in different components don't affect each other, except for the **&lt;unconditionalExclude&gt;** rule. Therefore, in this example, although some .txt files were excluded when Component 1 was processed, they were included when Component 2 was processed. |
| Component 1:<ul><li>Include rule: C:\Dir1\Dir2* []</li></ul> <br/>Component 2:<ul><li>Exclude rule: C:\Dir1* [.txt]</li></ul> | 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:<ul><li>Exclude rule: C:\Dir1\Dir2* []</li></ul> <br/>Component 2:<ul><li>Include rule: C:\Dir1* [.txt]</li></ul> | Migrates all .txt files in Dir1 and any subfolders. | Component 1 doesn't contain an **&lt;include&gt;** rule, so the **&lt;exclude&gt;** rule isn't processed. |
| Component 1:<ul><li>Include rule: \<pattern type=&quot;File&quot;\>C:\Dir1* []\</pattern\></li><li>Exclude rule: \<pattern type=&quot;File&quot;\>C:\Dir1\Dir2* [.txt]\</pattern\></li></ul> <br>Component 2:<ul><li>Include rule: \<pattern type=&quot;File&quot;\>C:\Dir1\Dir2* [.txt]\</pattern\></li><li>Exclude rule: \<pattern type=&quot;File&quot;\>C:\Dir1* []\</pattern\></li></ul> | Migrates all files and subfolders of C:\Dir1\ (including C:\Dir1\Dir2). | Rules that are in different components don't affect each other, except for the **\<unconditionalExclude\>** rule. Therefore, in this example, although some .txt files were excluded when Component 1 was processed, they were included when Component 2 was processed. |
| Component 1:<ul><li>Include rule: C:\Dir1\Dir2* []</li></ul> <br>Component 2:<ul><li>Exclude rule: C:\Dir1* [.txt]</li></ul> | 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:<ul><li>Exclude rule: C:\Dir1\Dir2* []</li></ul> <br>Component 2:<ul><li>Include rule: C:\Dir1* [.txt]</li></ul> | 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
| If you have the following code in the same component | Resulting behavior | Explanation |
|-----|-----|-----|
| <ul><li>Include rule: <br/>HKLM\Software\Microsoft\Command Processor* []</li><li>Exclude Rule: <br/>HKLM\Software\Microsoft\Command Processor [DefaultColor]</li></ul> | Migrates all keys in HKLM\Software\Microsoft\Command Processor except DefaultColor. | Both rules are processed as intended. |
| <ul><li>Include rule: <br/>HKLM\Software\Microsoft\Command Processor [DefaultColor]</li><li>Exclude Rule: <br/>HKLM\Software\Microsoft\Command Processor* []</li></ul> | Migrates only DefaultColor in HKLM\Software\Microsoft\Command Processor. | DefaultColor is migrated because the **&lt;include&gt;** rule is more specific than the **&lt;exclude&gt;** rule. |
| <ul><li>Include rule: <br/>HKLM\Software\Microsoft\Command Processor [DefaultColor]</li><li>Exclude rule: <br/>HKLM\Software\Microsoft\Command Processor [DefaultColor]</li></ul> | Doesn't migrate DefaultColor. | The rules are equally specific, so the **&lt;exclude&gt;** rule takes precedence over the &lt;include&gt; rule. |
| <ul><li>Include rule: <br>HKLM\Software\Microsoft\Command Processor* []</li><li>Exclude Rule: <br>HKLM\Software\Microsoft\Command Processor [DefaultColor]</li></ul> | Migrates all keys in HKLM\Software\Microsoft\Command Processor except DefaultColor. | Both rules are processed as intended. |
| <ul><li>Include rule: <br>HKLM\Software\Microsoft\Command Processor [DefaultColor]</li><li>Exclude Rule: <br>HKLM\Software\Microsoft\Command Processor* []</li></ul> | Migrates only DefaultColor in HKLM\Software\Microsoft\Command Processor. | DefaultColor is migrated because the **\<include\>** rule is more specific than the **\<exclude\>** rule. |
| <ul><li>Include rule: <br>HKLM\Software\Microsoft\Command Processor [DefaultColor]</li><li>Exclude rule: <br>HKLM\Software\Microsoft\Command Processor [DefaultColor]</li></ul> | Doesn't migrate DefaultColor. | The rules are equally specific, so the **\<exclude\>** rule takes precedence over the \<include\> rule. |
| If you have the following code in different components | Resulting behavior | Explanation |
|-----|-----|-----|
| Component 1:<ul><li>Include rule: <br/>HKLM\Software\Microsoft\Command Processor [DefaultColor]</li><li>Exclude rule: <br/>HKLM\Software\Microsoft\Command Processor* []</li></ul> <br/>Component 2:<ul><li>Include rule: <br/>HKLM\Software\Microsoft\Command Processor* []</li><li>Exclude rule: <br/>HKLM\Software\Microsoft\Command Processor [DefaultColor]</li></ul> | Migrates all the keys/values under HKLM\Software\Microsoft\Command Processor. | Rules that are in different components don't affect each other, except for the **&lt;unconditionalExclude&gt;** rule. Therefore, in this example, the objects that were excluded when Component 1 was processed were included when Component 2 was processed. |
| Component 1:<ul><li>Include rule: <br>HKLM\Software\Microsoft\Command Processor [DefaultColor]</li><li>Exclude rule: <br>HKLM\Software\Microsoft\Command Processor* []</li></ul> <br>Component 2:<ul><li>Include rule: <br>HKLM\Software\Microsoft\Command Processor* []</li><li>Exclude rule: <br>HKLM\Software\Microsoft\Command Processor [DefaultColor]</li></ul> | Migrates all the keys/values under HKLM\Software\Microsoft\Command Processor. | Rules that are in different components don't affect each other, except for the **\<unconditionalExclude\>** rule. Therefore, in this example, the objects that were excluded when Component 1 was processed were included when Component 2 was processed. |
## File collisions
### What is the default behavior when there are file collisions?
If there isn't a **&lt;merge&gt;** rule, the default behavior for the registry is for the source to overwrite the destination. The default behavior for files is for the source to be renamed incrementally: for example, OriginalFileName(1).OriginalExtension, OriginalFileName(2).OriginalExtension, and so on.
If there isn't a **\<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 &lt;merge&gt; 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 **&lt;merge&gt;** rule and apply it to resolve the conflict. For example, if you have a **&lt;merge&gt;** rule for **C:\\\* \[\*\]** set to **sourcePriority()** and another **&lt;merge&gt;** rule for **C:\\subfolder\\\* \[\*\]** set to **destinationPriority()** , then USMT uses the **destinationPriority()** rule because it's the most specific.
When a collision is detected, USMT 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.
### Example scenario

8
windows/deployment/usmt/usmt-custom-xml-examples.md
View File

@ -14,7 +14,7 @@ ms.date: 12/20/2023
## Example 1: Migrating an unsupported application
The following template is a template for the sections that you need to migrate your application. The template isn't functional on its own, but you can use it to write your own .xml file.
The following template is a template for the sections that 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.
**Template**
<br>
@ -89,7 +89,7 @@ The following template is a template for the sections that you need to migrate y
## Example 2: Migrating the My Videos folder
The following sample is a custom .xml file named `CustomFile.xml` that migrates **My Videos** for all users, if the folder exists on the source computer.
The following sample is a custom **.xml** file named `CustomFile.xml` that migrates **My Videos** for all users, if the folder exists on the source computer.
- **Sample condition**: Verifies that **My Videos** exists on the source computer:
@ -137,7 +137,7 @@ The following sample is a custom .xml file named `CustomFile.xml` that migrates
## Example 3: Migrating files and registry keys
The sample patterns describe the behavior in the following example .xml file.
The sample patterns describe the behavior in the following example **.xml** file.
- **Sample pattern**: Migrates all instances of the file `Usmttestfile.txt` from all subdirectories under `%ProgramFiles%\USMTTestFolder`:
@ -195,7 +195,7 @@ The sample patterns describe the behavior in the following example .xml file.
## Example 4: Migrating specific folders from various locations
The behavior for this custom .xml file is described within the `<displayName>` tags in the code.
The behavior for this custom **.xml** file is described within the `<displayName>` tags in the code.
**XML file**
<br>

4
windows/deployment/usmt/usmt-customize-xml-files.md
View File

@ -60,7 +60,7 @@ The `Config.xml` file is an optional file that you create using the `/genconfig`
If you want to include all of the default components, you don't need to create the `Config.xml` file. Alternatively, if you're satisfied with the default migration behavior defined in the `MigApp.xml`, `MigDocs.xml`, and `MigUser.xml` files, and you want to exclude only some components, you can create and modify a `Config.xml` file and leave the other **.xml** files in their original state.
When you run the `ScanState.exe` command with the `/genconfig` option, `ScanState.exe` reads the other **.xml** files that you specify using the `/i` option to create a custom list of components that can be migrated from the computer. This file contains only operating system components, applications, and the user document sections that are in both of the **.xml** files and that are installed on the computer when you run the `ScanState.exe` command with the `/genconfig` option. Therefore, you should create this file on a source computer that contains all of the components, applications, and settings that are present on the destination computers. Creating the file on the source computer ensures that this file contains every component that can be migrated. The components are organized into sections: &lt;Applications&gt;, &lt;WindowsComponents&gt;, and &lt;Documents&gt;. To choose not to migrate a component, change its entry to `migrate="no"`.
When you run the `ScanState.exe` command with the `/genconfig` option, `ScanState.exe` reads the other **.xml** files that you specify using the `/i` option to create a custom list of components that can be migrated from the computer. This file contains only operating system components, applications, and the user document sections that are in both of the **.xml** files and that are installed on the computer when you run the `ScanState.exe` command with the `/genconfig` option. Therefore, you should create this file on a source computer that contains all of the components, applications, and settings that are present on the destination computers. Creating the file on the source computer ensures that this file contains every component that can be migrated. The components are organized into sections: \<Applications\>, \<WindowsComponents\>, and \<Documents\>. To choose not to migrate a component, change its entry to `migrate="no"`.
After you create this file, you need to specify it only with the `ScanState.exe` command using the `/Config` option for it to affect the migration. However, if additional data that was migrated to the store needs to be excluded, modify the `Config.xml` file and specify the updated file with the `LoadState.exe` command. For example, if you collected the My Documents folder in the store, but you decide that you don't want to migrate the My Documents folder to a destination computer, you can modify the `Config.xml` file to indicate `migrate="no"` before you run the `LoadState.exe` command, and the file aren't be migrated. For more information about the precedence that takes place when excluding data, see the [Exclude files and settings](usmt-exclude-files-and-settings.md) article.
@ -70,7 +70,7 @@ In addition, note the following functionality with the `Config.xml` file:
- 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 is migrated.
- In USMT, there are several migration policies that can be configured in the `Config.xml` file. For example, you can configure additional **&lt;ErrorControl&gt;**, **&lt;ProfileControl&gt;**, and **&lt;HardLinkStoreControl&gt;** 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]
>

10
windows/deployment/usmt/usmt-estimate-migration-store-size.md
View File

@ -50,7 +50,7 @@ To run the ScanState tool on the source computer with USMT installed:
cd /d "C:\Program Files (x86)\Windows Kits\10.0\Assessment and Deployment Kit\User State Migration Tool\<architecture>"
```
where *&lt;architecture&gt;* is x86 or amd64.
where *\<architecture\>* is x86 or amd64.
1. Run the **ScanState** tool to generate an XML report of the space requirements. At the command prompt, enter:
@ -60,8 +60,8 @@ To run the ScanState tool on the source computer with USMT installed:
Where:
- *&lt;StorePath&gt;* is a path to a directory where the migration store is saved.
- *&lt;path to a file&gt;* is the path and filename where the XML report for space requirements is saved.
- *\<StorePath\>* is a path to a directory where the migration store is saved.
- *\<path to a file\>* is the path and filename where the XML report for space requirements is saved.
For example:
@ -69,7 +69,7 @@ To run the ScanState tool on the source computer with USMT installed:
ScanState.exe c:\store /p:c:\spaceRequirements.xml
```
Although a migration store isn't created by running this command, the *&lt;StorePath&gt;* is still a required parameter.
Although a migration store isn't created by running this command, the *\<StorePath\>* is still a required parameter.
The ScanState tool also allows you to estimate disk space requirements based on a customized migration. For example, you might not want to migrate the My Documents folder to the destination computer. You can specify this condition in a configuration file when you run the ScanState tool. For more information, see [Customize USMT XML files](usmt-customize-xml-files.md).
@ -77,7 +77,7 @@ The ScanState tool also allows you to estimate disk space requirements based on
>
> To preserve the functionality of existing applications or scripts that require the previous behavior of USMT, the `/p` option is still available in USMT without having to specify the path to a file. For more information, see [Monitoring Options](usmt-scanstate-syntax.md#monitoring-options).
The space requirements report provides two elements, &lt;**storeSize**&gt; and &lt;**temporarySpace**&gt;. The &lt;**temporarySpace**&gt; value shows the disk space, in bytes, that USMT uses to operate during the migration but it doesn't include the minimum 250 MB needed to support USMT. The &lt;**storeSize**&gt; value shows the disk space, in bytes, required to host the migration store contents on both the source and destination computers. The following example shows a report generated using `/p:`*&lt;path to a file&gt;*.
The space requirements report provides two elements, \<**storeSize**\> and \<**temporarySpace**\>. The \<**temporarySpace**\> value shows the disk space, in bytes, that USMT uses to operate during the migration but it doesn't include the minimum 250 MB needed to support USMT. The \<**storeSize**\> value shows the disk space, in bytes, required to host the migration store contents on both the source and destination computers. The following example shows a report generated using `/p:`*\<path to a file\>*.
```xml
<?xml version="1.0" encoding="UTF-8"?>

24
windows/deployment/usmt/usmt-exclude-files-and-settings.md
View File

@ -18,9 +18,9 @@ Methods to customize the migration and include and exclude files and settings in
- [Create a custom .xml file](#create-a-custom-xml-file). You can use the following elements to specify what to exclude:
- [Include and exclude](#include-and-exclude): You can use the **&lt;include&gt;** and **&lt;exclude&gt;** elements to exclude objects with conditions. For example, you can migrate all files located in the `C:\` drive, except any `.mp3` files. It's important to remember that [Conflicts and precedence](usmt-conflicts-and-precedence.md) apply to these elements.
- [Include and exclude](#include-and-exclude): You can use the **\<include\>** and **\<exclude\>** elements to exclude objects with conditions. For example, you can migrate all files located in the `C:\` drive, except any `.mp3` files. It's important to remember that [Conflicts and precedence](usmt-conflicts-and-precedence.md) apply to these elements.
- [unconditionalExclude](#example-1-how-to-migrate-all-files-from-c-except-mp3-files): You can use the **&lt;unconditionalExclude&gt;** element to globally exclude data. This element takes precedence over all other include and exclude rules in the **.xml** files. Therefore, this element excludes objects regardless of any other **&lt;include&gt;** rules that are in the **.xml** files. For example, you can exclude all .mp3 files on the computer, or you can exclude all files from C:\\UserData.
- [unconditionalExclude](#example-1-how-to-migrate-all-files-from-c-except-mp3-files): You can use the **\<unconditionalExclude\>** element to globally exclude data. This element takes precedence over all other include and exclude rules in the **.xml** files. Therefore, this element excludes objects regardless of any other **\<include\>** rules that are in the **.xml** files. For example, you can exclude all .mp3 files on the computer, or you can exclude all files from C:\\UserData.
- [Create a Config.xml file](#create-a-config-xml-file): You can create and modify a `Config.xml` file to exclude an entire component from the migration. For example, you can use this file to exclude the settings for one of the default applications. In addition, creating and modifying a `Config.xml` file is the only way to exclude the operating-system settings that are migrated to computers running Windows. Excluding components using this file is easier than modifying the migration **.xml** files because you don't need to be familiar with the migration rules and syntax.
@ -28,13 +28,13 @@ Methods to customize the migration and include and exclude files and settings in
We recommend that you create a custom **.xml** file instead of modifying the default migration **.xml** files. When you use a custom **.xml** file, you can keep your changes separate from the default **.xml** file, which makes it easier to track your modifications.
### &lt;include&gt; and &lt;exclude&gt;
### \<include\> and \<exclude\>
The migration **.xml** files, `MigApp.xml`, `MigDocs.xml`, and `MigUser.xml`, contain the **&lt;component&gt;** element, which typically represents a self-contained component or an application such as Microsoft® Office Outlook® and Word. To exclude the files and registry settings that are associated with these components, use the **&lt;include&gt;** and **&lt;exclude&gt;** elements. For example, you can use these elements to migrate all files and settings with pattern X except files and settings with pattern Y, where Y is more specific than X. For the syntax of these elements, see [USMT XML Reference](usmt-xml-reference.md).
The migration **.xml** files, `MigApp.xml`, `MigDocs.xml`, and `MigUser.xml`, contain the **\<component\>** element, which typically represents a self-contained component or an application such as Microsoft® Office Outlook® and Word. To exclude the files and registry settings that are associated with these components, use the **\<include\>** and **\<exclude\>** elements. For example, you can use these elements to migrate all files and settings with pattern X except files and settings with pattern Y, where Y is more specific than X. For the syntax of these elements, see [USMT XML Reference](usmt-xml-reference.md).
> [!NOTE]
>
> If you specify an **&lt;exclude&gt;** rule, always specify a corresponding **&lt;include&gt;** rule. Otherwise, if you don't specify an **&lt;include&gt;** rule, the specific files or settings aren't included. They're already excluded from the migration. Thus, an unaccompanied **&lt;exclude&gt;** rule is unnecessary.
> If you specify an **\<exclude\>** rule, always specify a corresponding **\<include\>** rule. Otherwise, if you don't specify an **\<include\>** rule, the specific files or settings aren't included. They're already excluded from the migration. Thus, an unaccompanied **\<exclude\>** rule is unnecessary.
- [Example 1: How to migrate all files from C:\\ except .mp3 files](#example-1-how-to-migrate-all-files-from-c-except-mp3-files)
@ -101,7 +101,7 @@ The following **.xml** file migrates all files and subfolders in `C:\Data`, exce
### Example 3: How to exclude the files in a folder but include all subfolders
The following .xml file migrates any subfolders in `C:\EngineeringDrafts`, but excludes all files that are in `C:\EngineeringDrafts`.
The following **.xml** file migrates any subfolders in `C:\EngineeringDrafts`, but excludes all files that are in `C:\EngineeringDrafts`.
```xml
<migration urlid="http://www.microsoft.com/migration/1.0/migxmlext/test">
@ -153,13 +153,13 @@ The following **.xml** file migrates all files and subfolders in `C:\Engineering
### Example 5: How to exclude a file from any location
To exclude a Sample.doc file from any location on the C: drive, use the **&lt;pattern&gt;** element. If multiple files exist with the same name on the C: drive, all of these files are excluded.
To exclude a Sample.doc file from any location on the C: drive, use the **\<pattern\>** element. If multiple files exist with the same name on the C: drive, all of these files are excluded.
```xml
<pattern type="File"> C:\* [Sample.doc] </pattern>
```
To exclude a Sample.doc file from any drive on the computer, use the **&lt;script&gt;** element. If multiple files exist with the same name, all of these files are excluded.
To exclude a Sample.doc file from any drive on the computer, use the **\<script\>** element. If multiple files exist with the same name, all of these files are excluded.
```xml
<script>MigXmlHelper.GenerateDrivePatterns("* [sample.doc]", "Fixed")</script>
@ -240,7 +240,7 @@ The following **.xml** file unconditionally excludes the `HKEY_CURRENT_USER` reg
##### Example 4: How to Exclude `C:\Windows` and `C:\Program Files`
The following **.xml** file unconditionally excludes the system folders of `C:\Windows` and `C:\Program Files`. All `*.docx`, `*.xls` and `*.ppt` files aren't migrated because the **&lt;unconditionalExclude&gt;** element takes precedence over the **&lt;include&gt;** element.
The following **.xml** file unconditionally excludes the system folders of `C:\Windows` and `C:\Program Files`. All `*.docx`, `*.xls` and `*.ppt` files aren't migrated because the **\<unconditionalExclude\>** element takes precedence over the **\<include\>** element.
```xml
<?xml version="1.0" encoding="UTF-8"?>
@ -272,11 +272,11 @@ The following **.xml** file unconditionally excludes the system folders of `C:\W
You can create and modify a `Config.xml` file if you want to exclude components from the migration. Excluding components using this file is easier than modifying the migration **.xml** files because you don't need to be familiar with the migration rules and syntax. `Config.xml` is an optional file that you can create using the `/genconfig` command-line option with the ScanState tool. For example, you can use the `Config.xml` file to exclude the settings for one of the default applications. In addition, creating and modifying this file is the only way to exclude the operating-system settings that are migrated to computers running Windows.
- **To exclude the settings for a default application:** Specify `migrate="no"` for the application under the **&lt;Applications&gt;** section of the `Config.xml` file.
- **To exclude the settings for a default application:** Specify `migrate="no"` for the application under the **\<Applications\>** section of the `Config.xml` file.
- **To exclude an operating system setting:** Specify `migrate="no"` for the setting under the **&lt;WindowsComponents&gt;** section.
- **To exclude an operating system setting:** Specify `migrate="no"` for the setting under the **\<WindowsComponents\>** section.
- **To exclude My Documents:** Specify `migrate="no"` for **My Documents** under the **&lt;Documents&gt;** section. Any **&lt;include&gt;** rules in the **.xml** files are still applied. For example, if you have a rule that includes all the .docx files in My Documents, then .docx files are still migrated. However, any additional files that aren't .docx aren't migrated.
- **To exclude My Documents:** Specify `migrate="no"` for **My Documents** under the **\<Documents\>** section. Any **\<include\>** rules in the **.xml** files are still applied. For example, if you have a rule that includes all the .docx files in My Documents, then .docx files are still migrated. However, any additional files that aren't .docx aren't migrated.
For more information, see [Config.xml File](usmt-configxml-file.md).

18
windows/deployment/usmt/usmt-extract-files-from-a-compressed-migration-store.md
View File

@ -34,23 +34,23 @@ UsmtUtils.exe /extract <filePath> <destinationPath> [/i:<includePattern>] [/e:<e
Where the placeholders have the following values:
- **&lt;USMTpath&gt;** is the location where the USMT files and tools are saved.
- **\<USMTpath\>** is the location where the USMT files and tools are saved.
- **&lt;filePath&gt;** is the location of the migration store.
- **\<filePath\>** is the location of the migration store.
- **&lt;destination path&gt;** is the location of the file where you want the **/extract** option to put the extracted migration store contents.
- **\<destination path\>** is the location of the file where you want the **/extract** option to put the extracted migration store contents.
- **&lt;includePattern&gt;** specifies the pattern for the files to include in the extraction.
- **\<includePattern\>** specifies the pattern for the files to include in the extraction.
- **&lt;excludePattern&gt;** specifies the pattern for the files to omit from the extraction.
- **\<excludePattern\>** specifies the pattern for the files to omit from the extraction.
- **&lt;AlgID&gt;** is the cryptographic algorithm that was used to create the migration store on the `ScanState.exe` command line.
- **\<AlgID\>** is the cryptographic algorithm that was used to create the migration store on the `ScanState.exe` command line.
- **&lt;logfile&gt;** is the location and name of the log file.
- **\<logfile\>** is the location and name of the log file.
- **&lt;keystring&gt;** is the encryption key that was used to encrypt the migration store.
- **\<keystring\>** is the encryption key that was used to encrypt the migration store.
- **&lt;filename&gt;** is the location and name of the text file that contains the encryption key.
- **\<filename\>** is the location and name of the text file that contains the encryption key.
### To extract all files from a compressed migration store

4
windows/deployment/usmt/usmt-faq.yml
View File

@ -74,7 +74,7 @@ sections:
- question: |
How can I exclude a folder or a certain type of file from the migration?
answer: |
You can use the **&lt;unconditionalExclude&gt;** element to globally exclude data from the migration. For example, you can use this element to exclude all MP3 files on the computer or to exclude all files from `C:\UserData`. This element excludes objects regardless of any other **&lt;include&gt;** rules that are in the **.xml** files. For an example, see **&lt;unconditionalExclude&gt;** in the [Exclude files and settings](usmt-exclude-files-and-settings.md) article. For the syntax of this element, see [XML elements library](usmt-xml-elements-library.md).
You can use the **\<unconditionalExclude\>** element to globally exclude data from the migration. For example, you can use this element to exclude all MP3 files on the computer or to exclude all files from `C:\UserData`. This element excludes objects regardless of any other **\<include\>** rules that are in the **.xml** files. For an example, see **\<unconditionalExclude\>** in the [Exclude files and settings](usmt-exclude-files-and-settings.md) article. For the syntax of this element, see [XML elements library](usmt-xml-elements-library.md).
- question: |
What happens to files that were located on a drive that don't exist on the destination computer?
@ -85,7 +85,7 @@ sections:
- Destination computer doesn't have an E:\\ drive.
- C:\\ is the system drive on the destination computer.
the file is migrated to `C:\data\File.pst`. This behavior holds true even when **&lt;locationModify&gt;** rules attempt to move data to a drive that doesn't exist on the destination computer.
the file is migrated to `C:\data\File.pst`. This behavior holds true even when **\<locationModify\>** rules attempt to move data to a drive that doesn't exist on the destination computer.
- name: USMT .xml Files
questions:

4
windows/deployment/usmt/usmt-general-conventions.md
View File

@ -28,13 +28,13 @@ Before you modify the **.xml** files, become familiar with the following guideli
- **Required elements**.
The required elements for a migration **.xml** file are **&lt;migration&gt;**, **&lt;component&gt;**, **&lt;role&gt;**, and **&lt;rules&gt;**.
The required elements for a migration **.xml** file are **\<migration\>**, **\<component\>**, **\<role\>**, and **\<rules\>**.
- **Required child elements**.
- USMT doesn't fail with an error if you don't specify the required child elements. However, you must specify the required child elements for the parent element to affect the migration.
- The required child elements apply only to the first definition of the element. If these elements are defined and then referred to using their name, the required child elements don't apply. For example, if you define `<detects name="Example">` in **&lt;namedElements&gt;**, and you specify `<detects name="Example"/>` in **&lt;component&gt;** to refer to this element, the definition inside **&lt;namedElements&gt;** must have the required child elements, but the **&lt;component&gt;** element doesn't need to have the required child elements.
- The required child elements apply only to the first definition of the element. If these elements are defined and then referred to using their name, the required child elements don't apply. For example, if you define `<detects name="Example">` in **\<namedElements\>**, and you specify `<detects name="Example"/>` in **\<component\>** to refer to this element, the definition inside **\<namedElements\>** must have the required child elements, but the **\<component\>** element doesn't need to have the required child elements.
- **File names with brackets**.

14
windows/deployment/usmt/usmt-hard-link-migration-store.md
View File

@ -130,11 +130,11 @@ When an application or the operating system has a lock on a file, the file is ha
Operating system locked files can't remain in place and must be copied into the hard-link migration store. As a result, selecting many operating-system files for migration significantly reduces performance during a hard-link migration. As a best practice, we recommend that you don't migrate any files out of the `\Windows` directory, which minimizes performance-related issues.
Application locked files are treated the same in hard-link migrations as in other scenarios when the volume shadow-copy service isn't being utilized. The volume shadow-copy service can't be used with hard-link migrations. However, by modifying the new **&lt;HardLinkStoreControl&gt;** section in the `Config.xml` file, it's possible to enable the migration of files locked by an application.
Application locked files are treated the same in hard-link migrations as in other scenarios when the volume shadow-copy service isn't being utilized. The volume shadow-copy service can't be used with hard-link migrations. However, by modifying the new **\<HardLinkStoreControl\>** section in the `Config.xml` file, it's possible to enable the migration of files locked by an application.
> [!IMPORTANT]
>
> There are some scenarios in which modifying the **&lt;HardLinkStoreControl&gt;** section in the `Config.xml` file makes it more difficult to delete a hard-link migration store. In these scenarios, you must use `UsmtUtils.exe` to schedule the migration store for deletion on the next restart.
> There are some scenarios in which modifying the **\<HardLinkStoreControl\>** section in the `Config.xml` file makes it more difficult to delete a hard-link migration store. In these scenarios, you must use `UsmtUtils.exe` to schedule the migration store for deletion on the next restart.
## XML elements in the Config.xml file
@ -142,11 +142,11 @@ A new section in the `Config.xml` file allows optional configuration of some of
| Element | Description |
|--- |--- |
| **&lt;Policies&gt;** | This element contains elements that describe the policies that USMT follows while creating a migration store. |
| **&lt;HardLinkStoreControl&gt;** | This element contains elements that describe how to handle files during the creation of a hard link migration store. |
| **&lt;fileLocked&gt;** | This element contains elements that describe how to handle files that are locked for editing. |
| **&lt;createHardLink&gt;** | This element defines a standard MigXML pattern that describes file paths where hard links should be created, even if the file is locked for editing by another application. <br/><br/>Syntax: `<createHardLink>` [pattern] `</createHardLink>` |
| **&lt;errorHardLink&gt;** | This element defines a standard MigXML pattern that describes file paths where hard links shouldn't be created, if the file is locked for editing by another application. <br/><br/>`<errorHardLink>` [pattern] `</errorHardLink>` |
| **\<Policies\>** | This element contains elements that describe the policies that USMT follows while creating a migration store. |
| **\<HardLinkStoreControl\>** | This element contains elements that describe how to handle files during the creation of a hard link migration store. |
| **\<fileLocked\>** | This element contains elements that describe how to handle files that are locked for editing. |
| **\<createHardLink\>** | This element defines a standard MigXML pattern that describes file paths where hard links should be created, even if the file is locked for editing by another application. <br><br>Syntax: `<createHardLink>` [pattern] `</createHardLink>` |
| **\<errorHardLink\>** | This element defines a standard MigXML pattern that describes file paths where hard links shouldn't be created, if the file is locked for editing by another application. <br><br>`<errorHardLink>` [pattern] `</errorHardLink>` |
> [!IMPORTANT]
>

22
windows/deployment/usmt/usmt-how-it-works.md
View File

@ -50,17 +50,17 @@ When you run the **ScanState** tool on the source computer, it goes through the
1. Each component that is selected in the previous step is processed further. Any profile-specific variables (such as **CSIDL_PERSONAL**) are evaluated in the context of the current profile. For example, if the profile that is being processed belongs to **User1**, then **CSIDL_PERSONAL** would expand to `C:\Users\User1\Documents`, assuming that the user profiles are stored in the `C:\Users` directory.
1. For each selected component, **ScanState** evaluates the **&lt;detects&gt;** section. If the condition in the **&lt;detects&gt;** section evaluates to false, the component isn't processed any further. Otherwise, the processing of this component continues.
1. For each selected component, **ScanState** evaluates the **\<detects\>** section. If the condition in the **\<detects\>** section evaluates to false, the component isn't processed any further. Otherwise, the processing of this component continues.
1. For each selected component, **ScanState** evaluates the **&lt;rules&gt;** sections. For each **&lt;rules&gt;** section, if the current user profile is the system profile and the context of the **&lt;rules&gt;** section is **System** or **UserAndSystem**, the rule is processed further. Otherwise, this rule is ignored. Alternatively, if the current user profile isn't the system profile and the context of the **&lt;rules&gt;** section is **User** or **UserAndSystem**, the rule is processed further. Otherwise, this rule is ignored.
1. For each selected component, **ScanState** evaluates the **\<rules\>** sections. For each **\<rules\>** section, if the current user profile is the system profile and the context of the **\<rules\>** section is **System** or **UserAndSystem**, the rule is processed further. Otherwise, this rule is ignored. Alternatively, if the current user profile isn't the system profile and the context of the **\<rules\>** section is **User** or **UserAndSystem**, the rule is processed further. Otherwise, this rule is ignored.
1. **ScanState** creates a list of migration units that need to be migrated by processing the various subsections under this **&lt;rules&gt;** section. Each unit is collected if the unit is mentioned in an **&lt;include&gt;** subsection, as long as there isn't a more specific rule for it in an **&lt;exclude&gt;** subsection in the same **&lt;rules&gt;** section. For more information about precedence in the **.xml** files, see [Conflicts and precedence](usmt-conflicts-and-precedence.md).
1. **ScanState** creates a list of migration units that need to be migrated by processing the various subsections under this **\<rules\>** section. Each unit is collected if the unit is mentioned in an **\<include\>** subsection, as long as there isn't a more specific rule for it in an **\<exclude\>** subsection in the same **\<rules\>** section. For more information about precedence in the **.xml** files, see [Conflicts and precedence](usmt-conflicts-and-precedence.md).
In addition, any migration unit (such as a file, registry key, or set of registry values) that is in an &lt;UnconditionalExclude&gt; section isn't migrated.
In addition, any migration unit (such as a file, registry key, or set of registry values) that is in an \<UnconditionalExclude\> section isn't migrated.
> [!NOTE]
>
> **ScanState** ignores some subsections such as &lt;destinationCleanup&gt; and &lt;locationModify&gt;. These sections are evaluated only on the destination computer.
> **ScanState** ignores some subsections such as \<destinationCleanup\> and \<locationModify\>. These sections are evaluated only on the destination computer.
1. In the **Collecting** phase, **ScanState** creates a central list of the migration units by combining the lists that were created for each selected user profile.
@ -102,21 +102,21 @@ The **LoadState** process is similar to the **ScanState** process. The **ScanSta
> [!NOTE]
>
> **LoadState** ignores the **&lt;detects&gt;** section specified in a component. At this point, all specified components are considered to be detected and are selected for migration.
> **LoadState** ignores the **\<detects\>** section specified in a component. At this point, all specified components are considered to be detected and are selected for migration.
1. For each selected component, **LoadState** evaluates the **&lt;rules&gt;** sections. For each **&lt;rules&gt;** section, if the current user profile is the system profile and the context of the **&lt;rules&gt;** section is **System** or **UserAndSystem**, the rule is processed further. Otherwise, this rule is ignored. Alternatively, if the current user profile isn't the system profile and the context of the **&lt;rules&gt;** section is **User** or **UserAndSystem**, the rule is processed further. Otherwise, this rule is ignored.
1. For each selected component, **LoadState** evaluates the **\<rules\>** sections. For each **\<rules\>** section, if the current user profile is the system profile and the context of the **\<rules\>** section is **System** or **UserAndSystem**, the rule is processed further. Otherwise, this rule is ignored. Alternatively, if the current user profile isn't the system profile and the context of the **\<rules\>** section is **User** or **UserAndSystem**, the rule is processed further. Otherwise, this rule is ignored.
1. **LoadState** creates a central list of migration units by processing the various subsections under the **&lt;rules&gt;** section. Each migration unit that is in an **&lt;include&gt;** subsection is migrated as long, as there isn't a more specific rule for it in an **&lt;exclude&gt;** subsection in the same **&lt;rules&gt;** section. For more information about precedence, see [Conflicts and precedence](usmt-conflicts-and-precedence.md).
1. **LoadState** creates a central list of migration units by processing the various subsections under the **\<rules\>** section. Each migration unit that is in an **\<include\>** subsection is migrated as long, as there isn't a more specific rule for it in an **\<exclude\>** subsection in the same **\<rules\>** section. For more information about precedence, see [Conflicts and precedence](usmt-conflicts-and-precedence.md).
1. **LoadState** evaluates the destination computer-specific subsections, for example, the **&lt;destinationCleanup&gt;** and **&lt;locationModify&gt;** subsections.
1. **LoadState** evaluates the destination computer-specific subsections, for example, the **\<destinationCleanup\>** and **\<locationModify\>** subsections.
1. If the destination computer is running a currently supported version of Windows, then the migunits that were collected by **ScanState** using downlevel manifest files are processed by **LoadState** using the corresponding Component Manifest from the downlevel Windows version. The downlevel manifest files aren't used during **LoadState**.
> [!IMPORTANT]
>
> It's important to specify the **.xml** files with the `LoadState.exe` command if you want **LoadState** to use them. Otherwise, any destination-specific rules, such as **&lt;locationModify&gt;**, in these **.xml** files are ignored, even if the same **.xml** files were provided when the `ScanState.exe` command ran.
> It's important to specify the **.xml** files with the `LoadState.exe` command if you want **LoadState** to use them. Otherwise, any destination-specific rules, such as **\<locationModify\>**, in these **.xml** files are ignored, even if the same **.xml** files were provided when the `ScanState.exe` command ran.
1. In the **Apply** phase, **LoadState** writes the migration units that were collected to the various locations on the destination computer. If there are conflicts and there isn't a **&lt;merge&gt;** rule for the object, the default behavior for the registry is for the source to overwrite the destination. The default behavior for files is for the source to be renamed incrementally, for example, OriginalFileName(1).OriginalExtension. Some settings, such as fonts, wallpaper, and screen-saver settings, don't take effect until the next time the user logs on. For this reason, you should sign out when the `LoadState.exe` command actions are finished.
1. In the **Apply** phase, **LoadState** writes the migration units that were collected to the various locations on the destination computer. If there are conflicts and there isn't a **\<merge\>** rule for the object, the default behavior for the registry is for the source to overwrite the destination. The default behavior for files is for the source to be renamed incrementally, for example, OriginalFileName(1).OriginalExtension. Some settings, such as fonts, wallpaper, and screen-saver settings, don't take effect until the next time the user logs on. For this reason, you should sign out when the `LoadState.exe` command actions are finished.
## Related articles

6
windows/deployment/usmt/usmt-how-to.md
View File

@ -18,13 +18,13 @@ The following table lists articles that describe how to use User State Migration
| Link | Description |
|------ |----------- |
|[Exclude files and settings](usmt-exclude-files-and-settings.md)|Create a custom .xml file to exclude files, file types, folders, or registry settings from your migration.|
|[Exclude files and settings](usmt-exclude-files-and-settings.md)|Create a custom **.xml** file to exclude files, file types, folders, or registry settings from your migration.|
|[Extract files from a compressed USMT migration store](usmt-extract-files-from-a-compressed-migration-store.md)|Recover files from a compressed migration store after installing the operating system.|
|[Include files and settings](usmt-include-files-and-settings.md)|Create a custom .xml file to include files, file types, folders, or registry settings in your migration.|
|[Include files and settings](usmt-include-files-and-settings.md)|Create a custom **.xml** file to include files, file types, folders, or registry settings in your migration.|
|[Migrate application settings](migrate-application-settings.md)|Migrate the settings of an application that the MigApp.xml file doesn't include by default.|
|[Migrate EFS files and certificates](usmt-migrate-efs-files-and-certificates.md)|Migrate Encrypting File System (EFS) certificates by using USMT.|
|[Migrate user accounts](usmt-migrate-user-accounts.md)|Specify the users to include and exclude in your migration.|
|[Reroute files and settings](usmt-reroute-files-and-settings.md)|Create a custom .xml file to reroute files and settings during a migration.|
|[Reroute files and settings](usmt-reroute-files-and-settings.md)|Create a custom **.xml** file to reroute files and settings during a migration.|
|[Verify the condition of a compressed migration store](verify-the-condition-of-a-compressed-migration-store.md)|Determine whether a compressed migration store is intact, or whether it contains corrupt files or a corrupt catalog.|
## Related articles

4
windows/deployment/usmt/usmt-include-files-and-settings.md
View File

@ -171,13 +171,13 @@ The following examples show how to migrate a file from a specific folder, and ho
</migration>
```
- **To migrate a file from any location.** To migrate the `Sample.doc` file from any location on the `C:\` drive, use the **&lt;pattern&gt;** element, as the following example shows. If multiple files exist with the same name on the `C:\` drive, all of files with this name are migrated.
- **To migrate a file from any location.** To migrate the `Sample.doc` file from any location on the `C:\` drive, use the **\<pattern\>** element, as the following example shows. If multiple files exist with the same name on the `C:\` drive, all of files with this name are migrated.
```xml
<pattern type="File"> C:\* [Sample.doc] </pattern>
```
To migrate the Sample.doc file from any drive on the computer, use &lt;script&gt; as the following example shows. If multiple files exist with the same name, all files with this name are migrated.
To migrate the Sample.doc file from any drive on the computer, use \<script\> as the following example shows. If multiple files exist with the same name, all files with this name are migrated.
```xml
<script>MigXmlHelper.GenerateDrivePatterns("* [sample.doc]", "Fixed")</script>

36
windows/deployment/usmt/usmt-loadstate-syntax.md
View File

@ -53,10 +53,10 @@ USMT provides the following options that you can use to specify how and where th
| Command-Line Option | Description |
|--- |--- |
| **StorePath** | Indicates the folder where the files and settings data are stored. You must specify *StorePath* when using the `LoadState.exe` command. You can't specify more than one *StorePath*. |
| **/decrypt /key**:*KeyString* <br/>or <br/>**/decrypt /key**:"*Key String*" <br/>or <br/>**/decrypt /keyfile**:[*Path*]*FileName* | Decrypts the store with the specified key. With this option, the encryption key needs to be specified in one of the following ways:<ul><li>`/key`:*KeyString* specifies the encryption key. If there's a space in *KeyString*, you must surround the argument with quotation marks (`"`).</li><li>`/keyfile`:*FilePathAndName* specifies a text (`.txt`) file that contains the encryption key</li></ul> <br/>*KeyString* can't exceed 256 characters. <br/>The `/key` and `/keyfile` options can't be used on the same command line. <br/>The `/decrypt` and `/nocompress` options can't be used on the same command line. <br/><div class="alert">**Important** <br/> Use caution when using the `/key` or `keyfile` options. For example, anyone who has access to scripts that run the `LoadState.exe` command with these options also have access to the encryption key.</div> <br/>For example: <br/>`LoadState.exe /i:MigApp.xml /i:MigDocs.xml \server\share\migration\mystore /decrypt /key:mykey` |
| **/decrypt /key**:*KeyString* <br>or <br>**/decrypt /key**:"*Key String*" <br>or <br>**/decrypt /keyfile**:[*Path*]*FileName* | Decrypts the store with the specified key. With this option, the encryption key needs to be specified in one of the following ways:<ul><li>`/key`:*KeyString* specifies the encryption key. If there's a space in *KeyString*, you must surround the argument with quotation marks (`"`).</li><li>`/keyfile`:*FilePathAndName* specifies a text (`.txt`) file that contains the encryption key</li></ul> <br>*KeyString* can't exceed 256 characters. <br>The `/key` and `/keyfile` options can't be used on the same command line. <br>The `/decrypt` and `/nocompress` options can't be used on the same command line. <br><div class="alert">**Important** <br> Use caution when using the `/key` or `keyfile` options. For example, anyone who has access to scripts that run the `LoadState.exe` command with these options also have access to the encryption key.</div> <br>For example: <br>`LoadState.exe /i:MigApp.xml /i:MigDocs.xml \server\share\migration\mystore /decrypt /key:mykey` |
| **/decrypt**:*"encryption strength"* | The `/decrypt` option accepts a command-line parameter to define the encryption strength specified for the migration store encryption. For more information about supported encryption algorithms, see [Migration Store Encryption](usmt-migration-store-encryption.md). |
| **/hardlink** | Enables user-state data to be restored from a hard-link migration store. The `/nocompress` parameter must be specified with `/hardlink` option. |
| **/nocompress** | Specifies that the store isn't compressed. You should only use this option in testing environments. We recommend that you use a compressed store during your actual migration. This option can't be used with the `/decrypt` option. <br/>For example: <br/>`LoadState.exe /i:MigApp.xml /i:MigDocs.xml \server\share\migration\mystore /nocompress` |
| **/nocompress** | Specifies that the store isn't compressed. You should only use this option in testing environments. We recommend that you use a compressed store during your actual migration. This option can't be used with the `/decrypt` option. <br>For example: <br>`LoadState.exe /i:MigApp.xml /i:MigDocs.xml \server\share\migration\mystore /nocompress` |
## Migration rule options
@ -64,8 +64,8 @@ USMT provides the following options to specify what files you want to migrate.
| Command-Line Option | Description |
|--- |--- |
| **/i**:[*Path*]*FileName* | **(include)** <br/>Specifies an **.xml** file that contains rules that define what state to migrate. You can specify this option multiple times to include all of your **.xml** files (`MigApp.xml`, `MigSys.xml`, `MigDocs.xml` and any custom **.xml** files that you create). *Path* can be either a relative or full path. If you don't specify the *Path* variable, then *FileName* must be located in the current directory. <br/><br/>For more information about which files to specify, see the &quot;XML files&quot; section of the [Frequently Asked Questions](usmt-faq.yml) article. |
| **/config**:[*Path*]*FileName* | Specifies the `Config.xml` file that the `LoadState.exe` command should use. You can't specify this option more than once on the command line. *Path* can be either a relative or full path. If you don't specify the *Path* variable, then the *FileName* must be located in the current directory. <br/><br/>This example migrates the files and settings based on the rules in the `Config.xml`, `MigDocs.xml`, and `MigApp.xml` files: <br/><br/>`LoadState.exe \server\share\migration\mystore /config:Config.xml /i:MigDocs.xml /i:MigApp.xml /v:5 /l:LoadState.log` |
| **/i**:[*Path*]*FileName* | **(include)** <br>Specifies an **.xml** file that contains rules that define what state to migrate. You can specify this option multiple times to include all of your **.xml** files (`MigApp.xml`, `MigSys.xml`, `MigDocs.xml` and any custom **.xml** files that you create). *Path* can be either a relative or full path. If you don't specify the *Path* variable, then *FileName* must be located in the current directory. <br><br>For more information about which files to specify, see the &quot;XML files&quot; section of the [Frequently Asked Questions](usmt-faq.yml) article. |
| **/config**:[*Path*]*FileName* | Specifies the `Config.xml` file that the `LoadState.exe` command should use. You can't specify this option more than once on the command line. *Path* can be either a relative or full path. If you don't specify the *Path* variable, then the *FileName* must be located in the current directory. <br><br>This example migrates the files and settings based on the rules in the `Config.xml`, `MigDocs.xml`, and `MigApp.xml` files: <br><br>`LoadState.exe \server\share\migration\mystore /config:Config.xml /i:MigDocs.xml /i:MigApp.xml /v:5 /l:LoadState.log` |
| **/auto**:*"path to script files"* | This option enables you to specify the location of the default **.xml** files and then launch your migration. If no path is specified, USMT uses the directory where the USMT binaries are located. The `/auto` option has the same effect as using the following options: `/i:MigDocs.xml` `/i:MigApp.xml /v:5`. |
## Monitoring options
@ -74,12 +74,12 @@ USMT provides several command-line options that you can use to analyze problems
| Command-Line Option | Description |
|--- |--- |
| **/l**:[*Path*]*FileName* | Specifies the location and name of the **LoadState** log. You can't store any of the log files in *StorePath*. *Path* can be either a relative or full path. If you don't specify the *Path* variable, then the log is created in the current directory. You can specify the `/v` option to adjust the verbosity of the log. <br/><br/>If you run the `LoadState.exe` command from a shared network resource, you must specify the `l` option, or USMT fails with the error:<br/><br/>***USMT was unable to create the log file(s)***<br/><br/> To fix this issue, make sure to specify the `/l` option when running `LoadState.exe` from a shared network resource. |
| **/v**:*`<VerbosityLevel>`* | **(Verbosity)** <br/><br/>Enables verbose output in the **LoadState** log file. The default value is 0. <br/>You can set the *VerbosityLevel* to one of the following levels:<ul><li>**0** - Only the default errors and warnings are enabled.</li><li>**1** - Enables verbose output.</li><li>**4** - Enables error and status output.</li><li>**5** - Enables verbose and status output.</li><li>**8** - Enables error output to a debugger.</li><li>**9** - Enables verbose output to a debugger.</li><li>**12** - Enables error and status output to a debugger.</li><li>**13** - Enables verbose, status, and debugger output.</li></ul><br/>For example: <br/>`LoadState.exe \server\share\migration\mystore /v:5 /i:MigDocs.xml /i:MigApp.xml` |
| **/progress**:[*Path*]*FileName* | Creates the optional progress log. You can't store any of the log files in *StorePath*. *Path* can be either a relative or full path. If you don't specify the *Path* variable, then *FileName* is created in the current directory. <br/><br/>For example: <br/>`LoadState.exe /i:MigApp.xml /i:MigDocs.xml \server\share\migration\mystore /progress:Progress.log /l:loadlog.log` |
| **/c** | When this option is specified, the `LoadState.exe` command continues to run, even if non-fatal errors occur. Any files or settings that cause an error are logged in the progress log. For example, if there's a large file that doesn't fit on the computer, the `LoadState.exe` command logs an error and continue with the migration. Without the `/c` option, the `LoadState.exe` command exits on the first error. You can use the new &lt;**ErrorControl**&gt; section in the `Config.xml` file to specify which file or registry read/write errors can be safely ignored and which might cause the migration to fail. This error control enables the `/c` command-line option to safely skip all input/output (I/O) errors in your environment. In addition, the `/genconfig` option now generates a sample &lt;**ErrorControl**&gt; section that is enabled by specifying error messages and desired behaviors in the `Config.xml` file. |
| **/r**:*`<TimesToRetry>`* | **(Retry)** <br/><br/>Specifies the number of times to retry when an error occurs while migrating the user state from a server. The default is three times. This option is useful in environments where network connectivity isn't reliable. <br/><br/>When the user state is being restored, the `/r` option doesn't recover data that is lost due to a network-hardware failure, such as a faulty or disconnected network cable, or when a virtual private network (VPN) connection fails. The retry option is intended for large, busy networks where connectivity is satisfactory, but communication latency is a problem. |
| **/w**:*`<SecondsBeforeRetry>`* | **(Wait)** <br/><br/>Specifies the time to wait, in seconds, before retrying a network file operation. The default is 1 second. |
| **/l**:[*Path*]*FileName* | Specifies the location and name of the **LoadState** log. You can't store any of the log files in *StorePath*. *Path* can be either a relative or full path. If you don't specify the *Path* variable, then the log is created in the current directory. You can specify the `/v` option to adjust the verbosity of the log. <br><br>If you run the `LoadState.exe` command from a shared network resource, you must specify the `l` option, or USMT fails with the error:<br><br>***USMT was unable to create the log file(s)***<br><br> To fix this issue, make sure to specify the `/l` option when running `LoadState.exe` from a shared network resource. |
| **/v**:*`<VerbosityLevel>`* | **(Verbosity)** <br><br>Enables verbose output in the **LoadState** log file. The default value is 0. <br>You can set the *VerbosityLevel* to one of the following levels:<ul><li>**0** - Only the default errors and warnings are enabled.</li><li>**1** - Enables verbose output.</li><li>**4** - Enables error and status output.</li><li>**5** - Enables verbose and status output.</li><li>**8** - Enables error output to a debugger.</li><li>**9** - Enables verbose output to a debugger.</li><li>**12** - Enables error and status output to a debugger.</li><li>**13** - Enables verbose, status, and debugger output.</li></ul><br>For example: <br>`LoadState.exe \server\share\migration\mystore /v:5 /i:MigDocs.xml /i:MigApp.xml` |
| **/progress**:[*Path*]*FileName* | Creates the optional progress log. You can't store any of the log files in *StorePath*. *Path* can be either a relative or full path. If you don't specify the *Path* variable, then *FileName* is created in the current directory. <br><br>For example: <br>`LoadState.exe /i:MigApp.xml /i:MigDocs.xml \server\share\migration\mystore /progress:Progress.log /l:loadlog.log` |
| **/c** | When this option is specified, the `LoadState.exe` command continues to run, even if non-fatal errors occur. Any files or settings that cause an error are logged in the progress log. For example, if there's a large file that doesn't fit on the computer, the `LoadState.exe` command logs an error and continue with the migration. Without the `/c` option, the `LoadState.exe` command exits on the first error. You can use the new \<**ErrorControl**\> section in the `Config.xml` file to specify which file or registry read/write errors can be safely ignored and which might cause the migration to fail. This error control enables the `/c` command-line option to safely skip all input/output (I/O) errors in your environment. In addition, the `/genconfig` option now generates a sample \<**ErrorControl**\> section that is enabled by specifying error messages and desired behaviors in the `Config.xml` file. |
| **/r**:*`<TimesToRetry>`* | **(Retry)** <br><br>Specifies the number of times to retry when an error occurs while migrating the user state from a server. The default is three times. This option is useful in environments where network connectivity isn't reliable. <br><br>When the user state is being restored, the `/r` option doesn't recover data that is lost due to a network-hardware failure, such as a faulty or disconnected network cable, or when a virtual private network (VPN) connection fails. The retry option is intended for large, busy networks where connectivity is satisfactory, but communication latency is a problem. |
| **/w**:*`<SecondsBeforeRetry>`* | **(Wait)** <br><br>Specifies the time to wait, in seconds, before retrying a network file operation. The default is 1 second. |
| **/?** or **/help** | Displays Help on the command line. |
## User options
@ -88,14 +88,14 @@ By default, all users are migrated. The only way to specify which users to inclu
| Command-Line Option | Description |
|--- |--- |
| **/all** | Migrates all of the users on the computer. <br/><br/>USMT migrates all user accounts on the computer, unless you specifically exclude an account with the `/ue` or `/uel` options. For this reason, you don't need to specify this option on the command line. However, if you choose to use the `/all` option, you can't also use the `/ui`, `/ue` or `/uel` options. |
| **/ui**:*DomainName UserName* <br/>or <br/>**/ui**:*"DomainName User Name"* <br/>or <br/>**/ui**:*ComputerName LocalUserName* | **(User include)** <br/><br/>Migrates the specified user. By default, all users are included in the migration. Therefore, this option is helpful only when used with the `/ue` option. You can specify multiple `/ui` options, but you can't use the `/ui` option with the `/all` option. *DomainName* and *UserName* can contain the asterisk (`*`) wildcard character. When user name that contains spaces is specified, it needs to be surrounded with quotations marks (`"`). <br/><br/>For example, to include only **User2** from the Corporate domain, enter: <br/><br/>`/ue:* /ui:corporate\user2`<br/><br/><div class="alert">**Note** <br/>If a user is specified for inclusion with the `/ui` option and also specified to be excluded with either the `/ue` or `/uel` options, the user is included in the migration.</div> <br/> For more examples, see the descriptions of the `/uel`, `/ue`, and `/ui` options in this table. |
| **/uel**:*`<NumberOfDays>`* <br/>or <br/>**/uel**:*`<YYYY/MM/DD>`* <br/>or <br/>**/uel**:0 | **(User exclude based on last logon)** <br/><br/>Migrates only the users that logged onto the source computer within the specified time period, based on the **Last Modified** date of the **Ntuser.dat** file on the source computer. The `/uel` option acts as an include rule. For example, the `/uel:30` option migrates users who logged on, or whose user account was modified, within the last 30 days from the date when the `ScanState.exe` command is run. You can specify the number of days or you can specify a date. You can't use this option with the `/all` option. USMT retrieves the last sign-in information from the local computer, so the computer doesn't need to be connected to the network when you run this option. In addition, if a domain user signs into another computer, USMT doesn't consider that sign-in instance. <div class="alert">**Note** <br/>The `/uel` option isn't valid in offline migrations.</div> <br/>Examples:<ul><li>`/uel:0` migrates accounts that were logged on to the source computer when the `ScanState.exe` command was run.</li><li>`/uel:90` migrates users who logged on, or whose accounts were otherwise modified, within the last 90 days.</li><li>`/uel:1` migrates users whose accounts were modified within the last 24 hours.</li><li>`/uel:2020/2/15` migrates users who logged on or whose accounts modified since February 15, 2020.</li></ul> <br/>For example: <br/>`LoadState.exe /i:MigApp.xml /i:MigDocs.xml \server\share\migration\mystore /uel:0` |
| **/ue**:*DomainName\UserName* <br/>or <br/>**/ue** *"DomainName\User Name"* <br/>or <br/>**/ue**:*ComputerName\LocalUserName* | **(User exclude)** <br/><br/>Excludes the specified users from the migration. You can specify multiple `/ue` options but you can't use the `/ue` option with the `/all` option. *DomainName* and *UserName* can contain the asterisk (`*`) wildcard character. When a user name that contains spaces is specified, it needs to be surround with quotation marks (`"`). <br/><br/>For example: <br/>`LoadState.exe /i:MigApp.xml /i:MigDocs.xml \server\share\migration\mystore /ue:contoso\user1` <br/>For more examples, see the descriptions of the `/uel`, `/ue`, and `/ui` options in this table. |
| **/md**:*OldDomain*:*NewDomain* <br/>or <br/>**/md**:*LocalComputerName:NewDomain* | **(Move domain)** <br/><br/>Specifies a new domain for the user. Use this option to change the domain for users on a computer or to migrate a local user to a domain account. *OldDomain* might contain the asterisk () wildcard character. <br/><br/>This option can be specified more than once. If consolidating users across multiple domains to a single domain, multiple `/md` options might need to be specified. For example, to consolidate the users from the Corporate and FarNorth domains into the Fabrikam domain, specify the following settings: `/md:corporate:fabrikam` and `/md:farnorth:fabrikam`. <br/><br/>If there are conflicts between two `/md` commands, the first rule that you specify is applied. For example, if you specify the `/md:corporate:fabrikam` and `/md:corporate:farnorth` commands, then Corporate users would be mapped to the Fabrikam domain. <div class="alert"> **Note** <br/>If you specify an *OldDomain* that didn't exist on the source computer, the `LoadState.exe` command appears to complete successfully, without an error or warning. However, in this case, users aren't moved to *NewDomain* but instead remain in their original domain. For example, if you misspell **contoso** and you instead specify **/md:contso:fabrikam**, the users remain in **contoso** on the destination computer.</div> <br/> For example: <br/>`LoadState.exe /i:MigApp.xml /i:MigDocs.xml \server\share\migration\mystore` <br/>` /progress:Progress.log /l:LoadState.log /md:contoso:fabrikam` |
| **/mu**:*OldDomain OldUserName*:[*NewDomain*]*NewUserName* <br/>or <br/>**/mu**:*OldLocalUserName*:*NewDomain NewUserName* | **(Move user)** <br/><br/>Specifies a new user name for the specified user. If the store contains more than one user, you can specify multiple `/mu` options. You can't use wildcard characters with this option. <br/><br/>For example: <br/>`LoadState.exe /i:MigApp.xml /i:MigDocs.xml \server\share\migration\mystore` <br/>`/progress:Progress.log /l:LoadState.log /mu:contoso\user1:fabrikam\user1` |
| **/lac**:[*Password*] | **(Local account create)** <br/><br/>If a user account is:<ul><li>A local (non-domain) account</li><li>An account that doesn't exist on the destination computer</li></ul>this setting specifies to create the account on the destination computer. However, the account is disabled. To enable the account, you must also use the `/lae` option. <br/><br/>If the `/lac` option isn't specified, any local user accounts that don't already exist on the destination computer aren't migrated. <br/><br/>*Password* is the password for the newly created account. An empty password is used by default. <div class="alert"> **Caution** <br/>Use the *Password* variable with caution. The *Password* variable is provided in plain text and anyone with access to the computer that is running the `LoadState.exe` command can obtain the password. <br/>Also, if the computer has multiple users, all migrated users have the same password.</div> <br/>For example: <br/>`LoadState.exe /i:MigApp.xml /i:MigDocs.xml \server\share\migration\mystore` <br/><br/>For instructions, see [Migrate user accounts](usmt-migrate-user-accounts.md). |
| `/lae` | **(Local account enable)** <br/><br/>Enables the account that was created with the `/lac` option. You must specify the `/lac` option with this option. <br/><br/>For example: <br/>`LoadState.exe /i:MigApp.xml /i:MigDocs.xml \server\share\migration\mystore` <br/>`/progress:Progress.log /l:LoadState.log /lac:password /lae` <br/><br/>For instructions, see [Migrate user accounts](usmt-migrate-user-accounts.md). |
| **/all** | Migrates all of the users on the computer. <br><br>USMT migrates all user accounts on the computer, unless you specifically exclude an account with the `/ue` or `/uel` options. For this reason, you don't need to specify this option on the command line. However, if you choose to use the `/all` option, you can't also use the `/ui`, `/ue` or `/uel` options. |
| **/ui**:*DomainName UserName* <br>or <br>**/ui**:*"DomainName User Name"* <br>or <br>**/ui**:*ComputerName LocalUserName* | **(User include)** <br><br>Migrates the specified user. By default, all users are included in the migration. Therefore, this option is helpful only when used with the `/ue` option. You can specify multiple `/ui` options, but you can't use the `/ui` option with the `/all` option. *DomainName* and *UserName* can contain the asterisk (`*`) wildcard character. When user name that contains spaces is specified, it needs to be surrounded with quotations marks (`"`). <br><br>For example, to include only **User2** from the Corporate domain, enter: <br><br>`/ue:* /ui:corporate\user2`<br><br><div class="alert">**Note** <br>If a user is specified for inclusion with the `/ui` option and also specified to be excluded with either the `/ue` or `/uel` options, the user is included in the migration.</div> <br> For more examples, see the descriptions of the `/uel`, `/ue`, and `/ui` options in this table. |
| **/uel**:*`<NumberOfDays>`* <br>or <br>**/uel**:*`<YYYY/MM/DD>`* <br>or <br>**/uel**:0 | **(User exclude based on last logon)** <br><br>Migrates only the users that logged onto the source computer within the specified time period, based on the **Last Modified** date of the **Ntuser.dat** file on the source computer. The `/uel` option acts as an include rule. For example, the `/uel:30` option migrates users who logged on, or whose user account was modified, within the last 30 days from the date when the `ScanState.exe` command is run. You can specify the number of days or you can specify a date. You can't use this option with the `/all` option. USMT retrieves the last sign-in information from the local computer, so the computer doesn't need to be connected to the network when you run this option. In addition, if a domain user signs into another computer, USMT doesn't consider that sign-in instance. <div class="alert">**Note** <br>The `/uel` option isn't valid in offline migrations.</div> <br>Examples:<ul><li>`/uel:0` migrates accounts that were logged on to the source computer when the `ScanState.exe` command was run.</li><li>`/uel:90` migrates users who logged on, or whose accounts were otherwise modified, within the last 90 days.</li><li>`/uel:1` migrates users whose accounts were modified within the last 24 hours.</li><li>`/uel:2020/2/15` migrates users who logged on or whose accounts modified since February 15, 2020.</li></ul> <br>For example: <br>`LoadState.exe /i:MigApp.xml /i:MigDocs.xml \server\share\migration\mystore /uel:0` |
| **/ue**:*DomainName\UserName* <br>or <br>**/ue** *"DomainName\User Name"* <br>or <br>**/ue**:*ComputerName\LocalUserName* | **(User exclude)** <br><br>Excludes the specified users from the migration. You can specify multiple `/ue` options but you can't use the `/ue` option with the `/all` option. *DomainName* and *UserName* can contain the asterisk (`*`) wildcard character. When a user name that contains spaces is specified, it needs to be surround with quotation marks (`"`). <br><br>For example: <br>`LoadState.exe /i:MigApp.xml /i:MigDocs.xml \server\share\migration\mystore /ue:contoso\user1` <br>For more examples, see the descriptions of the `/uel`, `/ue`, and `/ui` options in this table. |
| **/md**:*OldDomain*:*NewDomain* <br>or <br>**/md**:*LocalComputerName:NewDomain* | **(Move domain)** <br><br>Specifies a new domain for the user. Use this option to change the domain for users on a computer or to migrate a local user to a domain account. *OldDomain* might contain the asterisk () wildcard character. <br><br>This option can be specified more than once. If consolidating users across multiple domains to a single domain, multiple `/md` options might need to be specified. For example, to consolidate the users from the Corporate and FarNorth domains into the Fabrikam domain, specify the following settings: `/md:corporate:fabrikam` and `/md:farnorth:fabrikam`. <br><br>If there are conflicts between two `/md` commands, the first rule that you specify is applied. For example, if you specify the `/md:corporate:fabrikam` and `/md:corporate:farnorth` commands, then Corporate users would be mapped to the Fabrikam domain. <div class="alert"> **Note** <br>If you specify an *OldDomain* that didn't exist on the source computer, the `LoadState.exe` command appears to complete successfully, without an error or warning. However, in this case, users aren't moved to *NewDomain* but instead remain in their original domain. For example, if you misspell **contoso** and you instead specify **/md:contso:fabrikam**, the users remain in **contoso** on the destination computer.</div> <br> For example: <br>`LoadState.exe /i:MigApp.xml /i:MigDocs.xml \server\share\migration\mystore` <br>` /progress:Progress.log /l:LoadState.log /md:contoso:fabrikam` |
| **/mu**:*OldDomain OldUserName*:[*NewDomain*]*NewUserName* <br>or <br>**/mu**:*OldLocalUserName*:*NewDomain NewUserName* | **(Move user)** <br><br>Specifies a new user name for the specified user. If the store contains more than one user, you can specify multiple `/mu` options. You can't use wildcard characters with this option. <br><br>For example: <br>`LoadState.exe /i:MigApp.xml /i:MigDocs.xml \server\share\migration\mystore` <br>`/progress:Progress.log /l:LoadState.log /mu:contoso\user1:fabrikam\user1` |
| **/lac**:[*Password*] | **(Local account create)** <br><br>If a user account is:<ul><li>A local (non-domain) account</li><li>An account that doesn't exist on the destination computer</li></ul>this setting specifies to create the account on the destination computer. However, the account is disabled. To enable the account, you must also use the `/lae` option. <br><br>If the `/lac` option isn't specified, any local user accounts that don't already exist on the destination computer aren't migrated. <br><br>*Password* is the password for the newly created account. An empty password is used by default. <div class="alert"> **Caution** <br>Use the *Password* variable with caution. The *Password* variable is provided in plain text and anyone with access to the computer that is running the `LoadState.exe` command can obtain the password. <br>Also, if the computer has multiple users, all migrated users have the same password.</div> <br>For example: <br>`LoadState.exe /i:MigApp.xml /i:MigDocs.xml \server\share\migration\mystore` <br><br>For instructions, see [Migrate user accounts](usmt-migrate-user-accounts.md). |
| `/lae` | **(Local account enable)** <br><br>Enables the account that was created with the `/lac` option. You must specify the `/lac` option with this option. <br><br>For example: <br>`LoadState.exe /i:MigApp.xml /i:MigDocs.xml \server\share\migration\mystore` <br>`/progress:Progress.log /l:LoadState.log /lac:password /lae` <br><br>For instructions, see [Migrate user accounts](usmt-migrate-user-accounts.md). |
### Examples for the /ui and /ue options

22
windows/deployment/usmt/usmt-log-files.md
View File

@ -140,14 +140,14 @@ However, upon testing the migration you notice that the **New Text Document.txt*
```xml
<MigUnitList>
<MigUnit Name="&lt;System&gt;\DATA1 (CMXEAgent)" Context="System" ConfidenceLevel="100" Group="Applications" Role="UserData" Agent="CMXEAgent" Selected="true" Supported="true">
<MigUnit Name="\<System\>\DATA1 (CMXEAgent)" Context="System" ConfidenceLevel="100" Group="Applications" Role="UserData" Agent="CMXEAgent" Selected="true" Supported="true">
<Patterns Type="Include">
<Pattern Type="File" Path="C:\data [*]"/>
</Patterns>
</MigUnit>
</MigUnitList>
<Perform Name="Gather" User="System">
<MigUnit Name="&lt;System&gt;\DATA1 (CMXEAgent)">
<MigUnit Name="\<System\>\DATA1 (CMXEAgent)">
<Operation Name="Store" Type="File" Path="C:\data" SimObj="false" Success="true"/>
<Operation Name="Store" Type="File" Path="C:\data [test (1).txt]" SimObj="false" Success="true"/>
<Operation Name="Store" Type="File" Path="C:\data [test.txt]" SimObj="false" Success="true"/>
@ -155,9 +155,9 @@ However, upon testing the migration you notice that the **New Text Document.txt*
</Perform>
```
Analysis of this XML section reveals the migunit that was created when the migration rule was processed. The **&lt;Perform&gt;** section details the actual files that were scheduled for gathering and the result of the gathering operation. The **New Text Document.txt** file doesn't appear in this section, which confirms that the migration rule wasn't correctly authored.
Analysis of this XML section reveals the migunit that was created when the migration rule was processed. The **\<Perform\>** section details the actual files that were scheduled for gathering and the result of the gathering operation. The **New Text Document.txt** file doesn't appear in this section, which confirms that the migration rule wasn't correctly authored.
An analysis of the [XML elements library](usmt-xml-elements-library.md) reference article reveals that the [**&lt;pattern&gt;**](usmt-xml-elements-library.md#pattern) tag needs to be modified as follows:
An analysis of the [XML elements library](usmt-xml-elements-library.md) reference article reveals that the [**\<pattern\>**](usmt-xml-elements-library.md#pattern) tag needs to be modified as follows:
```xml
<pattern type="File">c:\data\* [*]</pattern>
@ -167,14 +167,14 @@ When the migration is performed again with the modified tag, the diagnostic log
```xml
<MigUnitList>
<MigUnit Name="&lt;System&gt;\DATA1 (CMXEAgent)" Context="System" ConfidenceLevel="100" Group="Applications" Role="UserData" Agent="CMXEAgent" Selected="true" Supported="true">
<MigUnit Name="\<System\>\DATA1 (CMXEAgent)" Context="System" ConfidenceLevel="100" Group="Applications" Role="UserData" Agent="CMXEAgent" Selected="true" Supported="true">
<Patterns Type="Include">
<Pattern Type="File" Path="C:\data\* [*]"/>
</Patterns>
</MigUnit>
</MigUnitList>
<Perform Name="Gather" User="System">
<MigUnit Name="&lt;System&gt;\DATA1 (CMXEAgent)">
<MigUnit Name="\<System\>\DATA1 (CMXEAgent)">
<Operation Name="Store" Type="File" Path="C:\data" SimObj="false" Success="true"/>
<Operation Name="Store" Type="File" Path="C:\data [test (1).txt]" SimObj="false" Success="true"/>
<Operation Name="Store" Type="File" Path="C:\data [test.txt]" SimObj="false" Success="true"/>
@ -184,7 +184,7 @@ When the migration is performed again with the modified tag, the diagnostic log
</Perform>
```
This diagnostic log confirms that the modified **&lt;pattern&gt;** value enables the migration of the file.
This diagnostic log confirms that the modified **\<pattern\>** value enables the migration of the file.
**Why is this file migrating when I authored an exclude rule excluding it?**
@ -242,7 +242,7 @@ However, upon testing the migration you notice that all the text files are still
```xml
<MigUnitList>
<MigUnit Name="&lt;System&gt;\DATA1 (CMXEAgent)" Context="System" ConfidenceLevel="100" Group="Applications" Role="UserData" Agent="CMXEAgent" Selected="true" Supported="true">
<MigUnit Name="\<System\>\DATA1 (CMXEAgent)" Context="System" ConfidenceLevel="100" Group="Applications" Role="UserData" Agent="CMXEAgent" Selected="true" Supported="true">
<Patterns Type="Include">
<Pattern Type="File" Path="C:\data\* [*]"/>
</Patterns>
@ -252,7 +252,7 @@ However, upon testing the migration you notice that all the text files are still
</MigUnit>
</MigUnitList>
<Perform Name="Gather" User="System">
<MigUnit Name="&lt;System&gt;\DATA1 (CMXEAgent)">
<MigUnit Name="\<System\>\DATA1 (CMXEAgent)">
<Operation Name="Store" Type="File" Path="C:\data" SimObj="false" Success="true"/>
<Operation Name="Store" Type="File" Path="C:\data [test (1).txt]" SimObj="false" Success="true"/>
<Operation Name="Store" Type="File" Path="C:\data [test.docx]" SimObj="false" Success="true"/>
@ -299,7 +299,7 @@ Your revised migration XML script excludes the files from migrating, as confirme
```xml
<MigUnitList>
<MigUnit Name="&lt;System&gt;\DATA1 (CMXEAgent)" Context="System" ConfidenceLevel="100" Group="Applications" Role="UserData" Agent="CMXEAgent" Selected="true" Supported="true">
<MigUnit Name="\<System\>\DATA1 (CMXEAgent)" Context="System" ConfidenceLevel="100" Group="Applications" Role="UserData" Agent="CMXEAgent" Selected="true" Supported="true">
<Patterns Type="Include">
<Pattern Type="File" Path="C:\data\* [*]"/>
</Patterns>
@ -309,7 +309,7 @@ Your revised migration XML script excludes the files from migrating, as confirme
</MigUnit>
</MigUnitList>
<Perform Name="Gather" User="System">
<MigUnit Name="&lt;System&gt;\DATA1 (CMXEAgent)">
<MigUnit Name="\<System\>\DATA1 (CMXEAgent)">
<Operation Name="Store" Type="File" Path="C:\data" SimObj="false" Success="true"/>
<Operation Name="Store" Type="File" Path="C:\data [test.docx]" SimObj="false" Success="true"/>
<Operation Name="Store" Type="File" Path="C:\data\New Folder" SimObj="false" Success="true"/>

2
windows/deployment/usmt/usmt-migrate-efs-files-and-certificates.md
View File

@ -38,7 +38,7 @@ You can run the [Cipher.exe](/windows-server/administration/windows-commands/cip
cipher.exe /D /S:<PATH>
```
where *&lt;Path&gt;* is the full path of the topmost parent directory where the encryption attribute is set.
where *\<Path\>* is the full path of the topmost parent directory where the encryption attribute is set.
## Related articles

4
windows/deployment/usmt/usmt-recognized-environment-variables.md
View File

@ -19,7 +19,7 @@ When using the XML files `MigDocs.xml`, `MigApp.xml`, and `MigUser.xml`, you can
## Variables that are processed for the operating system and in the context of each user
You can use these variables within sections in the .xml files with `context=UserAndSystem`, `context=User`, and `context=System`.
You can use these variables within sections in the **.xml** files with `context=UserAndSystem`, `context=User`, and `context=System`.
|Variable|Explanation|
|--- |--- |
@ -83,7 +83,7 @@ You can use these variables within sections in the .xml files with `context=User
## Variables that are recognized only in the user context
You can use these variables in the .xml files within sections with `context=User` and `context=UserAndSystem`.
You can use these variables in the **.xml** files within sections with `context=User` and `context=UserAndSystem`.
|Variable|Explanation|
|--- |--- |

4
windows/deployment/usmt/usmt-requirements.md
View File

@ -69,9 +69,9 @@ To open an elevated command prompt:
## Config.xml
### Specify the `/c` option and &lt;ErrorControl&gt; settings in the `Config.xml` file
### Specify the `/c` option and \<ErrorControl\> settings in the `Config.xml` file
USMT fails if it can't migrate a file or setting, unless the `/c` option is specified. When you specify the `/c` option, USMT logs an error each time it encounters a file that is in use that didn't migrate, but the migration isn't be interrupted. In USMT, you can specify in the `Config.xml` file, which types of errors should allow the migration to continue, and which should cause the migration to fail. For more information about error reporting, and the **&lt;ErrorControl&gt;** element, see [Config.xml file](usmt-configxml-file.md#errorcontrol), [Log files](usmt-log-files.md), and [XML elements library](usmt-xml-elements-library.md).
USMT fails if it can't migrate a file or setting, unless the `/c` option is specified. When you specify the `/c` option, USMT logs an error each time it encounters a file that is in use that didn't migrate, but the migration isn't be interrupted. In USMT, you can specify in the `Config.xml` file, which types of errors should allow the migration to continue, and which should cause the migration to fail. For more information about error reporting, and the **\<ErrorControl\>** element, see [Config.xml file](usmt-configxml-file.md#errorcontrol), [Log files](usmt-log-files.md), and [XML elements library](usmt-xml-elements-library.md).
## LoadState

2
windows/deployment/usmt/usmt-resources.md
View File

@ -18,7 +18,7 @@ ms.technology: itpro-deploy
- Microsoft Visual Studio
- You can use the User State Migration Tool (USMT) XML schema (the `MigXML.xsd` file) to validate the migration .xml files using an XML authoring tool such as Microsoft® Visual Studio®.
- You can use the User State Migration Tool (USMT) XML schema (the `MigXML.xsd` file) to validate the migration **.xml** files using an XML authoring tool such as Microsoft® Visual Studio®.
For more information about how to use the schema with your XML authoring environment, see the environment's documentation.

50
windows/deployment/usmt/usmt-scanstate-syntax.md
View File

@ -56,13 +56,13 @@ To create an encrypted store using the `Config.xml` file and the default migrati
|-----|-----|
| *StorePath* | Indicates a folder where files and settings are saved. *StorePath* can't be `C:\`. The *StorePath* option must be specified in the `ScanState.exe` command, except when using the `/genconfig` option. More than one *StorePath* location can't be specified. |
| **/apps** | Scans the image for apps and includes them and their associated registry settings. |
| **/ppkg** [*&lt;FileName&gt;*] | Exports to a specific file location. |
| **/ppkg** [*\<FileName\>*] | Exports to a specific file location. |
| **/o** | Required to overwrite any existing data in the migration store or `Config.xml` file. If not specified, the `ScanState.exe` command fails if the migration store already contains data. This option can't be used more than once on a command line. |
| **/vsc** | This option enables the volume shadow-copy service to migrate files that are locked or in use. This command-line option eliminates most file-locking errors that are typically encountered by the **&lt;ErrorControl&gt;** section. <br/><br/>This option is only used with the **ScanState** executable file and can't be combined with the `/hardlink` option. |
| **/vsc** | This option enables the volume shadow-copy service to migrate files that are locked or in use. This command-line option eliminates most file-locking errors that are typically encountered by the **\<ErrorControl\>** section. <br><br>This option is only used with the **ScanState** executable file and can't be combined with the `/hardlink` option. |
| **/hardlink** | Enables the creation of a hard-link migration store at the specified location. The `/nocompress` option must be specified with the `/hardlink` option. |
| **/encrypt** [{**/key:** *&lt;KeyString&gt;* &#124; **/keyfile**:*&lt;file&gt;*]} | Encrypts the store with the specified key. Encryption is disabled by default. With this option, the encryption key needs to be specified in one of the following ways: <ul><li>`/key`: *KeyString* specifies the encryption key. If there's a space in *KeyString*, *KeyString* needs to be surrounded with quotation marks (`"`).</li><li>`/keyfile`: *FilePathAndName* specifies a text (`.txt`) file that contains the encryption key.</li></ul> <br/>*KeyString* is recommended to be at least eight characters long, but it can't exceed 256 characters. The `/key` and `/keyfile` options can't be used on the same command line. The `/encrypt` and `/nocompress` options can't be used on the same command line. <div class="alert">**Important**<br/>Use caution when using the `/key` or `keyfile` options. For example, anyone who has access to scripts that run the `ScanState.exe` command with these options also have access to the encryption key.</div> <br/>The following example shows the `ScanState.exe` command and the `/key` option: <br/>`ScanState.exe /i:MigDocs.xml /i:MigApp.xml \server\share\migration\mystore /encrypt /key:mykey` |
| **/encrypt**:*&lt;EncryptionStrength&gt;* | The `/encrypt` option accepts a command-line parameter to define the encryption strength to be used for encryption of the migration store. For more information about supported encryption algorithms, see [Migration Store Encryption](usmt-migration-store-encryption.md). |
| **/nocompress** | Disables compression of data and saves the files to a hidden folder named &quot;File&quot; at *StorePath*\USMT. Compression is enabled by default. Combining the `/nocompress` option with the `/hardlink` option generates a hard-link migration store. The uncompressed store can be used to view what USMT stored, troubleshoot a problem, or run an antivirus utility against the files. This option should only be used in testing environments. Microsoft recommends using a compressed store during production migrations, unless combining the `/nocompress` option with the `/hardlink` option. <br/><br/>The `/nocompress` and `/encrypt` options can't be used together in one statement on the command line. However, if an uncompressed store is migrated, the `LoadState.exe` command migrates each file directly from the store to the correct location on the destination computer without a temporary location. <br/><br/>For example:<br/>`ScanState.exe /i:MigDocs.xml /i:MigApp.xml \server\share\migration\mystore /nocompress` |
| **/encrypt** [{**/key:** *\<KeyString\>* &#124; **/keyfile**:*\<file\>*]} | Encrypts the store with the specified key. Encryption is disabled by default. With this option, the encryption key needs to be specified in one of the following ways: <ul><li>`/key`: *KeyString* specifies the encryption key. If there's a space in *KeyString*, *KeyString* needs to be surrounded with quotation marks (`"`).</li><li>`/keyfile`: *FilePathAndName* specifies a text (`.txt`) file that contains the encryption key.</li></ul> <br>*KeyString* is recommended to be at least eight characters long, but it can't exceed 256 characters. The `/key` and `/keyfile` options can't be used on the same command line. The `/encrypt` and `/nocompress` options can't be used on the same command line. <div class="alert">**Important**<br>Use caution when using the `/key` or `keyfile` options. For example, anyone who has access to scripts that run the `ScanState.exe` command with these options also have access to the encryption key.</div> <br>The following example shows the `ScanState.exe` command and the `/key` option: <br>`ScanState.exe /i:MigDocs.xml /i:MigApp.xml \server\share\migration\mystore /encrypt /key:mykey` |
| **/encrypt**:*\<EncryptionStrength\>* | The `/encrypt` option accepts a command-line parameter to define the encryption strength to be used for encryption of the migration store. For more information about supported encryption algorithms, see [Migration Store Encryption](usmt-migration-store-encryption.md). |
| **/nocompress** | Disables compression of data and saves the files to a hidden folder named &quot;File&quot; at *StorePath*\USMT. Compression is enabled by default. Combining the `/nocompress` option with the `/hardlink` option generates a hard-link migration store. The uncompressed store can be used to view what USMT stored, troubleshoot a problem, or run an antivirus utility against the files. This option should only be used in testing environments. Microsoft recommends using a compressed store during production migrations, unless combining the `/nocompress` option with the `/hardlink` option. <br><br>The `/nocompress` and `/encrypt` options can't be used together in one statement on the command line. However, if an uncompressed store is migrated, the `LoadState.exe` command migrates each file directly from the store to the correct location on the destination computer without a temporary location. <br><br>For example:<br>`ScanState.exe /i:MigDocs.xml /i:MigApp.xml \server\share\migration\mystore /nocompress` |
## Run the ScanState command on an offline Windows system
@ -103,12 +103,12 @@ USMT provides the following options to specify what files to migrate.
| Command-Line Option | Description |
|-----|-----|
| **/i:**[*Path*]*FileName* | **(include)** <br/><br/>Specifies an **.xml** file that contains rules that define what user, application, or system state to migrate. This option can be specified multiple times to include all of the **.xml** files (`MigApp.xml`, `MigDocs.xml`, and any custom **.xml** files that are created). *Path* can be either a relative or full path. If the *Path* variable isn't specified, then *FileName* must be located in the current directory. For more information about which files to specify, see the &quot;XML Files&quot; section of the [Frequently asked questions](usmt-faq.yml) article. |
| **/genconfig:**[*Path*]*FileName* | (Generate **Config.xml**) <br/><br/>Generates the optional `Config.xml` file, but doesn't create a migration store. To ensure that this file contains everything that needs to be migrated, create this file on a source computer that contains all of the:<ul><li>components</li><li>applications</li><li>settings</li><li></ul>present on the destination computers. In addition, the other migration **.xml** files should be specified, using the **/i** option, when this option is specified.<br/><br/>After this file is created, it can be used with the `ScanState.exe` command using the **/config** option.<br/><br/>The only options that can be specified with this option are the `/i`, `/v`, and `/l` options. *StorePath* can't be specified, because the `/genconfig` option doesn't create a store. *Path* can be either a relative or full path. If the *Path* variable isn't specified, then *FileName* is created in the current directory.<br/><br/>Examples: <ul><li>The following example creates a `Config.xml` file in the current directory:<br/>`ScanState.exe /i:MigApp.xml /i:MigDocs.xml /genconfig:Config.xml /v:13`</li></ul> |
| **/config:**[*Path*]*FileName* | Specifies the `Config.xml` file that the `ScanState.exe` command should use to create the store. This option can't be used more than once on the command line. *Path* can be either a relative or full path. If the *Path* variable isn't specified, then *FileName* must be located in the current directory.<br/><br/>The following example creates a store using the `Config.xml` file, `MigDocs.xml`, and `MigApp.xml` files:<br/>`ScanState.exe \server\share\migration\mystore /config:Config.xml /i:MigDocs.xml /i:MigApp.xml /v:13 /l:ScanState.log`<br/><br/>The following example migrates the files and settings to the destination computer using the `Config.xml`, `MigDocs.xml`, and `MigApp.xml` files:<br/>`LoadState.exe \server\share\migration\mystore /config:Config.xml /i:MigDocs.xml /i:MigApp.xml /v:13 /l:LoadState.log` |
| **/i:**[*Path*]*FileName* | **(include)** <br><br>Specifies an **.xml** file that contains rules that define what user, application, or system state to migrate. This option can be specified multiple times to include all of the **.xml** files (`MigApp.xml`, `MigDocs.xml`, and any custom **.xml** files that are created). *Path* can be either a relative or full path. If the *Path* variable isn't specified, then *FileName* must be located in the current directory. For more information about which files to specify, see the &quot;XML Files&quot; section of the [Frequently asked questions](usmt-faq.yml) article. |
| **/genconfig:**[*Path*]*FileName* | (Generate **Config.xml**) <br><br>Generates the optional `Config.xml` file, but doesn't create a migration store. To ensure that this file contains everything that needs to be migrated, create this file on a source computer that contains all of the:<ul><li>components</li><li>applications</li><li>settings</li><li></ul>present on the destination computers. In addition, the other migration **.xml** files should be specified, using the **/i** option, when this option is specified.<br><br>After this file is created, it can be used with the `ScanState.exe` command using the **/config** option.<br><br>The only options that can be specified with this option are the `/i`, `/v`, and `/l` options. *StorePath* can't be specified, because the `/genconfig` option doesn't create a store. *Path* can be either a relative or full path. If the *Path* variable isn't specified, then *FileName* is created in the current directory.<br><br>Examples: <ul><li>The following example creates a `Config.xml` file in the current directory:<br>`ScanState.exe /i:MigApp.xml /i:MigDocs.xml /genconfig:Config.xml /v:13`</li></ul> |
| **/config:**[*Path*]*FileName* | Specifies the `Config.xml` file that the `ScanState.exe` command should use to create the store. This option can't be used more than once on the command line. *Path* can be either a relative or full path. If the *Path* variable isn't specified, then *FileName* must be located in the current directory.<br><br>The following example creates a store using the `Config.xml` file, `MigDocs.xml`, and `MigApp.xml` files:<br>`ScanState.exe \server\share\migration\mystore /config:Config.xml /i:MigDocs.xml /i:MigApp.xml /v:13 /l:ScanState.log`<br><br>The following example migrates the files and settings to the destination computer using the `Config.xml`, `MigDocs.xml`, and `MigApp.xml` files:<br>`LoadState.exe \server\share\migration\mystore /config:Config.xml /i:MigDocs.xml /i:MigApp.xml /v:13 /l:LoadState.log` |
| **/auto:** *path to script files* | This option enables specifying the location of the default **.xml** files and then begin the migration. If no path is specified, USMT references the directory where the USMT binaries are located. The `/auto` option has the same effect as using the following options: `/i: MigDocs.xml /i:MigApp.xml /v:5`. |
| **/genmigxml:** *path to a file* | This option specifies that the `ScanState.exe` command should use the document finder to create and export an **.xml** file that defines how to migrate all of the files on the computer on which the `ScanState.exe` command is running. |
| **/localonly** | Migrates only files that are stored on the local computer, regardless of the rules in the **.xml** files that are specified on the command line. This option should be used to exclude the data from removable drives on the source computer and when there are network drives mapped on the source computer. Examples of removable drives include USB flash drives (UFDs) and some external hard drives. If the `/localonly` option isn't specified, then the `ScanState.exe` command copies files from these removable or network drives into the store.<br><br>`/localonly` excludes anything that isn't considered a fixed drive by the OS. In some cases, large external hard drives are considered fixed drives. These drives can be explicitly excluded from migration by using a custom **.xml** file. For more information about how to exclude all files on a specific drive, see [Exclude files and settings](usmt-exclude-files-and-settings.md).<br/><br/>The `/localonly` command-line option includes or excludes data in the migration as identified in the following storage locations:<ul><li>**Removable drives such as a USB flash drive** - Excluded</li><li>**Network drives** - Excluded</li><li>**Fixed drives** - Included</li></ul>|
| **/localonly** | Migrates only files that are stored on the local computer, regardless of the rules in the **.xml** files that are specified on the command line. This option should be used to exclude the data from removable drives on the source computer and when there are network drives mapped on the source computer. Examples of removable drives include USB flash drives (UFDs) and some external hard drives. If the `/localonly` option isn't specified, then the `ScanState.exe` command copies files from these removable or network drives into the store.<br><br>`/localonly` excludes anything that isn't considered a fixed drive by the OS. In some cases, large external hard drives are considered fixed drives. These drives can be explicitly excluded from migration by using a custom **.xml** file. For more information about how to exclude all files on a specific drive, see [Exclude files and settings](usmt-exclude-files-and-settings.md).<br><br>The `/localonly` command-line option includes or excludes data in the migration as identified in the following storage locations:<ul><li>**Removable drives such as a USB flash drive** - Excluded</li><li>**Network drives** - Excluded</li><li>**Fixed drives** - Included</li></ul>|
## Monitoring options
@ -120,14 +120,14 @@ USMT provides several options that can be used to analyze problems that occur du
| Command-Line Option | Description |
|-----|-----|
| **/listfiles**:&lt;FileName&gt; | The `/listfiles` command-line option can be used with the `ScanState.exe` command to generate a text file that lists all of the files included in the migration. |
| **/l:**[*Path*]*FileName* | Specifies the location and name of the **ScanState** log. <br/><br/>The log files can't be stored in *StorePath*. *Path* can be either a relative or full path. If the *Path* variable isn't specified, then the log is created in the current directory. The `/v` option can be used to adjust the amount of output. <br/><br/>If the `ScanState.exe` command is run from a shared network resource, the `/l` option must be specified, or USMT fails with the following error:<br><br>***USMT was unable to create the log file(s)***<br><br>To fix this issue, make sure to specify the `/l` option when running `ScanState.exe` from a shared network resource. |
| **/v:***&lt;VerbosityLevel&gt;* | **(Verbosity)**<br/><br/>Enables verbose output in the **ScanState** log file. The default value is 0. <br/><br/>The *VerbosityLevel* can be set to one of the following levels: <ul><li>**0** - Only the default errors and warnings are enabled.</li><li>**1** - Enables verbose output.</li><li>**4** - Enables error and status output.</li><li>**5** - Enables verbose and status output.</li><li>**8** - Enables error output to a debugger.</li><li>**9** - Enables verbose output to a debugger.</li><li>**12** - Enables error and status output to a debugger.</li><li>**13** - Enables verbose, status, and debugger output.</li></ul> <br/>For example: <br/>`ScanState.exe \server\share\migration\mystore /v:13 /i:MigDocs.xml /i:MigApp.xml`|
| **/progress**:[*Path*]*FileName* | Creates the optional progress log. The log files can't be stored in *StorePath*. *Path* can be either a relative or full path. If the *Path* variable isn't specified, then *FileName* is created in the current directory.<br/><br/>For example: <br/>`ScanState.exe /i:MigApp.xml /i:MigDocs.xml \server\share\migration\mystore /progress:Progress.log /l:scanlog.log` |
| **/c** | When this option is specified, the `ScanState.exe` command continues to run, even if non-fatal errors occur. Any files or settings that cause an error are logged in the progress log. For example, if there's a large file that doesn't fit in the store, the `ScanState.exe` command logs an error and continue with the migration. In addition, if a file is open or in use by an application, USMT might not be able to migrate the file and logs an error. Without the `/c` option, the `ScanState.exe` command exits on the first error.<br/><br/>The &lt;**ErrorControl**&gt; section in the `Config.xml` file can be used to specify which file or registry read/write errors can be safely ignored and which might cause the migration to fail. This advantage in the `Config.xml` file enables the `/c` command-line option to safely skip all input/output (I/O) errors in the environment. In addition, the /`genconfig` option now generates a sample &lt;**ErrorControl**&gt; section that is enabled by specifying error messages and desired behaviors in the `Config.xml` file. |
| **/r:***&lt;TimesToRetry&gt;* | **(Retry)**<br/><br/>Specifies the number of times to retry when an error occurs while saving the user state to a server. The default is three times. This option is useful in environments where network connectivity isn't reliable.<br/><br/>When the user state is stored, the `/r` option can't recover data that is lost due to a network-hardware failure, such as a faulty or disconnected network cable, or when a virtual private network (VPN) connection fails. The retry option is intended for large, busy networks where connectivity is satisfactory, but communication latency is a problem. |
| **/w:***&lt;SecondsBeforeRetry&gt;* | **(Wait)**<br/><br/>Specifies the time to wait, in seconds, before retrying a network file operation. The default is 1 second. |
| **/p:***&lt;pathToFile&gt;* | When the `ScanState.exe` command runs, it creates an **.xml** file in the path specified. This **.xml** file includes improved space estimations for the migration store. The following example shows how to create this **.xml** file:<br/>`ScanState.exe C:\MigrationLocation [additional parameters]`<br/>`/p:"C:\MigrationStoreSize.xml"`<br/><br/>For more information, see [Estimate Migration Store Size](usmt-estimate-migration-store-size.md).<br/><br/>To preserve the functionality of existing applications or scripts that require the previous behavior of USMT, the `/p` option can be used, without specifying *&quot;pathtoafile&quot;*, in USMT. If only the `/p` option is specified, the storage space estimations are created in the same manner as with USMT 3.x releases. |
| **/listfiles**:\<FileName\> | The `/listfiles` command-line option can be used with the `ScanState.exe` command to generate a text file that lists all of the files included in the migration. |
| **/l:**[*Path*]*FileName* | Specifies the location and name of the **ScanState** log. <br><br>The log files can't be stored in *StorePath*. *Path* can be either a relative or full path. If the *Path* variable isn't specified, then the log is created in the current directory. The `/v` option can be used to adjust the amount of output. <br><br>If the `ScanState.exe` command is run from a shared network resource, the `/l` option must be specified, or USMT fails with the following error:<br><br>***USMT was unable to create the log file(s)***<br><br>To fix this issue, make sure to specify the `/l` option when running `ScanState.exe` from a shared network resource. |
| **/v:***\<VerbosityLevel\>* | **(Verbosity)**<br><br>Enables verbose output in the **ScanState** log file. The default value is 0. <br><br>The *VerbosityLevel* can be set to one of the following levels: <ul><li>**0** - Only the default errors and warnings are enabled.</li><li>**1** - Enables verbose output.</li><li>**4** - Enables error and status output.</li><li>**5** - Enables verbose and status output.</li><li>**8** - Enables error output to a debugger.</li><li>**9** - Enables verbose output to a debugger.</li><li>**12** - Enables error and status output to a debugger.</li><li>**13** - Enables verbose, status, and debugger output.</li></ul> <br>For example: <br>`ScanState.exe \server\share\migration\mystore /v:13 /i:MigDocs.xml /i:MigApp.xml`|
| **/progress**:[*Path*]*FileName* | Creates the optional progress log. The log files can't be stored in *StorePath*. *Path* can be either a relative or full path. If the *Path* variable isn't specified, then *FileName* is created in the current directory.<br><br>For example: <br>`ScanState.exe /i:MigApp.xml /i:MigDocs.xml \server\share\migration\mystore /progress:Progress.log /l:scanlog.log` |
| **/c** | When this option is specified, the `ScanState.exe` command continues to run, even if non-fatal errors occur. Any files or settings that cause an error are logged in the progress log. For example, if there's a large file that doesn't fit in the store, the `ScanState.exe` command logs an error and continue with the migration. In addition, if a file is open or in use by an application, USMT might not be able to migrate the file and logs an error. Without the `/c` option, the `ScanState.exe` command exits on the first error.<br><br>The \<**ErrorControl**\> section in the `Config.xml` file can be used to specify which file or registry read/write errors can be safely ignored and which might cause the migration to fail. This advantage in the `Config.xml` file enables the `/c` command-line option to safely skip all input/output (I/O) errors in the environment. In addition, the /`genconfig` option now generates a sample \<**ErrorControl**\> section that is enabled by specifying error messages and desired behaviors in the `Config.xml` file. |
| **/r:***\<TimesToRetry\>* | **(Retry)**<br><br>Specifies the number of times to retry when an error occurs while saving the user state to a server. The default is three times. This option is useful in environments where network connectivity isn't reliable.<br><br>When the user state is stored, the `/r` option can't recover data that is lost due to a network-hardware failure, such as a faulty or disconnected network cable, or when a virtual private network (VPN) connection fails. The retry option is intended for large, busy networks where connectivity is satisfactory, but communication latency is a problem. |
| **/w:***\<SecondsBeforeRetry\>* | **(Wait)**<br><br>Specifies the time to wait, in seconds, before retrying a network file operation. The default is 1 second. |
| **/p:***\<pathToFile\>* | When the `ScanState.exe` command runs, it creates an **.xml** file in the path specified. This **.xml** file includes improved space estimations for the migration store. The following example shows how to create this **.xml** file:<br>`ScanState.exe C:\MigrationLocation [additional parameters]`<br>`/p:"C:\MigrationStoreSize.xml"`<br><br>For more information, see [Estimate Migration Store Size](usmt-estimate-migration-store-size.md).<br><br>To preserve the functionality of existing applications or scripts that require the previous behavior of USMT, the `/p` option can be used, without specifying *&quot;pathtoafile&quot;*, in USMT. If only the `/p` option is specified, the storage space estimations are created in the same manner as with USMT 3.x releases. |
| **/?** or **/help** | Displays Help at the command line. |
## User options
@ -136,10 +136,10 @@ By default, all users are migrated. The only way to specify which users to inclu
| Command-Line Option | Description |
|-----|-----|
| **/all** | Migrates all of the users on the computer. <br/><br/>USMT migrates all user accounts on the computer, unless an account is specifically excluded with either the `/ue` or `/uel` options. For this reason, this option doesn't need to be specified on the command line. However, if the `/all` option is specified, the `/ui`, `/ue` or `/uel` options can't also be specified. |
| **/ui**:*&lt;DomainName&gt;*&#92;*&lt;UserName&gt;*<br/>or<br/>**/ui**:*&lt;ComputerName&gt;*&#92;*&lt;LocalUserName&gt;* | **(User include)** <br/><br/>Migrates the specified users. By default, all users are included in the migration. Therefore, this option is helpful only when used with the `/ue` or `/uel` options. Multiple `/ui` options can be specified, but the `/ui` option can't be used with the `/all` option. *DomainName* and *UserName* can contain the asterisk (`*`) wildcard character. When a user name that contains spaces is specified, it needs to be surrounded with quotation marks (`"`). <div class="alert">**Note**<br/>If a user is specified for inclusion with the `/ui` option and also specified to be excluded with either the `/ue` or `/uel` options, the user is included in the migration.</div><br/>For example:<br/><ul><li>To include only **User2** from the Fabrikam domain, enter:<br/><br/>`/ue:*\* /ui:fabrikam\user2`<br/><br/></li><li>To migrate all users from the Fabrikam domain, and only the user accounts from other domains that are active or otherwise modified in the last 30 days, enter:<br/><br/>`/uel:30 /ui:fabrikam\*`<br/><br/>In this example, a user account from the Contoso domain that was last modified two months ago isn't migrated.</li></ul><br/>For more examples, see the descriptions of the `/ue` and `/ui` options in this table. |
| **/uel**:*&lt;NumberOfDays&gt;*<br/>or<br/>**/uel**:*&lt;YYYY/MM/DD&gt;*<br/>or<br/>**/uel:0** | **(User exclude based on last logon)**<br/><br/>Migrates the users that logged on to the source computer within the specified time period, based on the **Last Modified** date of the Ntuser.dat file on the source computer. The `/uel` option acts as an include rule. For example, the `/uel:30` option migrates users who logged on, or whose account was modified, within the last 30 days from the date when the `ScanState.exe` command is run.<br/><br/>The number of days or the date can be specified. This option can't be used with the `/all` option. USMT retrieves the last sign-in information from the local computer, so the computer doesn't need to be connected to the network when running this option. In addition, if a domain user signs in to another computer, USMT doesn't consider that sign-in instance. <div class="alert">**Note**<br/>The `/uel` option isn't valid in offline migrations.</div><ul><li>`/uel:0` migrates any users who are currently logged on.</li><li>`/uel:90` migrates users who logged on, or whose accounts were otherwise modified, within the last 90 days.</li><li>`/uel:1` migrates users whose account were modified within the last 24 hours.</li><li>`/uel:2020/2/15` migrates users who logged on or been modified February 15, 2020 or afterwards.</li></ul> <br/>For example: <br/>`ScanState.exe /i:MigApp.xml /i:MigDocs.xml \\server\share\migration\mystore /uel:0` |
| **/ue**:*&lt;DomainName&gt;*&#92;*&lt;UserName&gt;*<br/>-or-<br/><br/>**/ue**:*&lt;ComputerName&gt;*&#92;*&lt;LocalUserName&gt;* | **(User exclude)**<br/><br/>Excludes the specified users from the migration. Multiple `/ue` options can be specified. This option can't be used with the `/all` option. *&lt;DomainName&gt;* and *&lt;UserName&gt;* can contain the asterisk (`*`) wildcard character. When a user name that contains spaces is specified, it needs to be surrounded with quotation marks (`"`).<br/><br/>For example:<br/>`ScanState.exe /i:MigDocs.xml /i:MigApp.xml \\server\share\migration\mystore /ue:contoso\user1` |
| **/all** | Migrates all of the users on the computer. <br><br>USMT migrates all user accounts on the computer, unless an account is specifically excluded with either the `/ue` or `/uel` options. For this reason, this option doesn't need to be specified on the command line. However, if the `/all` option is specified, the `/ui`, `/ue` or `/uel` options can't also be specified. |
| **/ui**:*\<DomainName\>*&#92;*\<UserName\>*<br>or<br>**/ui**:*\<ComputerName\>*&#92;*\<LocalUserName\>* | **(User include)** <br><br>Migrates the specified users. By default, all users are included in the migration. Therefore, this option is helpful only when used with the `/ue` or `/uel` options. Multiple `/ui` options can be specified, but the `/ui` option can't be used with the `/all` option. *DomainName* and *UserName* can contain the asterisk (`*`) wildcard character. When a user name that contains spaces is specified, it needs to be surrounded with quotation marks (`"`). <div class="alert">**Note**<br>If a user is specified for inclusion with the `/ui` option and also specified to be excluded with either the `/ue` or `/uel` options, the user is included in the migration.</div><br>For example:<br><ul><li>To include only **User2** from the Fabrikam domain, enter:<br><br>`/ue:*\* /ui:fabrikam\user2`<br><br></li><li>To migrate all users from the Fabrikam domain, and only the user accounts from other domains that are active or otherwise modified in the last 30 days, enter:<br><br>`/uel:30 /ui:fabrikam\*`<br><br>In this example, a user account from the Contoso domain that was last modified two months ago isn't migrated.</li></ul><br>For more examples, see the descriptions of the `/ue` and `/ui` options in this table. |
| **/uel**:*\<NumberOfDays\>*<br>or<br>**/uel**:*\<YYYY/MM/DD\>*<br>or<br>**/uel:0** | **(User exclude based on last logon)**<br><br>Migrates the users that logged on to the source computer within the specified time period, based on the **Last Modified** date of the Ntuser.dat file on the source computer. The `/uel` option acts as an include rule. For example, the `/uel:30` option migrates users who logged on, or whose account was modified, within the last 30 days from the date when the `ScanState.exe` command is run.<br><br>The number of days or the date can be specified. This option can't be used with the `/all` option. USMT retrieves the last sign-in information from the local computer, so the computer doesn't need to be connected to the network when running this option. In addition, if a domain user signs in to another computer, USMT doesn't consider that sign-in instance. <div class="alert">**Note**<br>The `/uel` option isn't valid in offline migrations.</div><ul><li>`/uel:0` migrates any users who are currently logged on.</li><li>`/uel:90` migrates users who logged on, or whose accounts were otherwise modified, within the last 90 days.</li><li>`/uel:1` migrates users whose account were modified within the last 24 hours.</li><li>`/uel:2020/2/15` migrates users who logged on or been modified February 15, 2020 or afterwards.</li></ul> <br>For example: <br>`ScanState.exe /i:MigApp.xml /i:MigDocs.xml \\server\share\migration\mystore /uel:0` |
| **/ue**:*\<DomainName\>*&#92;*\<UserName\>*<br>-or-<br><br>**/ue**:*\<ComputerName\>*&#92;*\<LocalUserName\>* | **(User exclude)**<br><br>Excludes the specified users from the migration. Multiple `/ue` options can be specified. This option can't be used with the `/all` option. *\<DomainName\>* and *\<UserName\>* can contain the asterisk (`*`) wildcard character. When a user name that contains spaces is specified, it needs to be surrounded with quotation marks (`"`).<br><br>For example:<br>`ScanState.exe /i:MigDocs.xml /i:MigApp.xml \\server\share\migration\mystore /ue:contoso\user1` |
## How to use /ui and /ue
@ -166,7 +166,7 @@ The `/uel` option takes precedence over the `/ue` option. If a user logged on wi
|--- |--- |
|Include only User2 from the Fabrikam domain and exclude all other users.|`/ue:*\* /ui:fabrikam\user2`|
|Include only the local user named User1 and exclude all other users.|`/ue:*\* /ui:user1`|
|Include only the domain users from Contoso, except Contoso\User1.|This behavior can't be completed using a single command. Instead, to migrate this set of users, specify the following commands: <ul><li>On the `ScanState.exe` command line, enter:<br/> `/ue:*\* /ui:contoso\*`<br/></li><li>On the `LoadState.exe` command line, enter:<br/>`/ue:contoso\user1`</li></ul>|
|Include only the domain users from Contoso, except Contoso\User1.|This behavior can't be completed using a single command. Instead, to migrate this set of users, specify the following commands: <ul><li>On the `ScanState.exe` command line, enter:<br> `/ue:*\* /ui:contoso\*`<br></li><li>On the `LoadState.exe` command line, enter:<br>`/ue:contoso\user1`</li></ul>|
|Include only local (non-domain) users.|`/ue:*\* /ui:%computername%\*`|
## Encrypted file options
@ -189,7 +189,7 @@ For more information, see [Migrate EFS Files and Certificates](usmt-migrate-efs-
| **/efs:abort** | Causes the `ScanState.exe` command to fail with an error code, if an Encrypting File System (EFS) file is found on the source computer. Enabled by default. |
| **/efs:skip** | Causes the `ScanState.exe` command to ignore EFS files. |
| **/efs:decryptcopy** | Causes the `ScanState.exe` command to decrypt the file, if possible, before saving it to the migration store, and to fail if the file can't be decrypted. If the `ScanState.exe` command succeeds, the file is unencrypted in the migration store, and once the `LoadState.exe` command is run, the file is copied to the destination computer. |
| **/efs:copyraw** | Causes the `ScanState.exe` command to copy the files in the encrypted format. The files are inaccessible on the destination computer until the EFS certificates are migrated. EFS certificates are automatically migrated; however, by default USMT fails if an encrypted file is found, unless the `/efs` option is specified. Therefore the `/efs:copyraw` option should be specified with the `ScanState.exe` command to migrate the encrypted file. When the `LoadState.exe` command is run, the encrypted file and the EFS certificate are automatically migrated.<br/><br/>For example: <br/>`ScanState.exe /i:MigDocs.xml /i:MigApp.xml \server\share\migration\mystore /efs:copyraw` <div class="alert">**Important** <br/>All files must be encrypted if the parent folder is encrypted. If the encryption attribute on a file inside an encrypted folder is removed, the file is encrypted during the migration using the credentials of the account used to run the **LoadState** tool. For more information, see [Migrate EFS files and certificates](usmt-migrate-efs-files-and-certificates.md).</div>|
| **/efs:copyraw** | Causes the `ScanState.exe` command to copy the files in the encrypted format. The files are inaccessible on the destination computer until the EFS certificates are migrated. EFS certificates are automatically migrated; however, by default USMT fails if an encrypted file is found, unless the `/efs` option is specified. Therefore the `/efs:copyraw` option should be specified with the `ScanState.exe` command to migrate the encrypted file. When the `LoadState.exe` command is run, the encrypted file and the EFS certificate are automatically migrated.<br><br>For example: <br>`ScanState.exe /i:MigDocs.xml /i:MigApp.xml \server\share\migration\mystore /efs:copyraw` <div class="alert">**Important** <br>All files must be encrypted if the parent folder is encrypted. If the encryption attribute on a file inside an encrypted folder is removed, the file is encrypted during the migration using the credentials of the account used to run the **LoadState** tool. For more information, see [Migrate EFS files and certificates](usmt-migrate-efs-files-and-certificates.md).</div>|
## Incompatible command-line options
@ -216,10 +216,10 @@ The following table indicates which command-line options aren't compatible with
|**/ui**|||❌|❌|
|**/ue**|||❌|❌|
|**/uel**|||❌|❌|
|**/efs**:*&lt;option&gt;*|||❌||
|**/efs**:*\<option\>*|||❌||
|**/genconfig**|||N/A||
|**/config**|||❌||
|*&lt;StorePath&gt;*|||❌||
|*\<StorePath\>*|||❌||
> [!NOTE]
>

2
windows/deployment/usmt/usmt-topics.md
View File

@ -12,7 +12,7 @@ ms.technology: itpro-deploy
# User State Migration Tool (USMT) overview articles
The User State Migration Tool (USMT) provides a highly customizable user-profile migration experience for IT professionals. USMT includes three command-line tools: `ScanState.exe`, `LoadState.exe`, and `UsmtUtils.exe`. USMT also includes a set of three modifiable .xml files: `MigApp.xml`, `MigDocs.xml`, and `MigUser.xml`. Additionally, you can create custom .xml files to support your migration needs. You can also create a `Config.xml` file to specify files or settings to exclude from the migration.
The User State Migration Tool (USMT) provides a highly customizable user-profile migration experience for IT professionals. USMT includes three command-line tools: `ScanState.exe`, `LoadState.exe`, and `UsmtUtils.exe`. USMT also includes a set of three modifiable .xml files: `MigApp.xml`, `MigDocs.xml`, and `MigUser.xml`. Additionally, you can create custom **.xml** files to support your migration needs. You can also create a `Config.xml` file to specify files or settings to exclude from the migration.
## In this section

34
windows/deployment/usmt/usmt-utilities.md
View File

@ -28,15 +28,15 @@ The following table lists command-line options for `UsmtUtils.exe`. The sections
The syntax for `UsmtUtils.exe` is:
> UsmtUtils.exe \[/ec | /rd *&lt;storeDir&gt;* | /verify *&lt;filepath&gt;* \[options\] | /extract *&lt;filepath&gt;* *&lt;destinationPath&gt;* \[options\]\]
> UsmtUtils.exe \[/ec | /rd *\<storeDir\>* | /verify *\<filepath\>* \[options\] | /extract *\<filepath\>* *\<destinationPath\>* \[options\]\]
|Command-line Option|Description|
|--- |--- |
|**/ec**|Returns a list of supported cryptographic algorithms (AlgIDs) on the current system. This option can be used on a destination computer to determine which algorithm to use with the `/encrypt` command before running the **ScanState** tool on the source computer.|
|**/rd** *&lt;storeDir&gt;* |Removes the directory path specified by the *&lt;storeDir&gt;* argument on the computer. This command can be used to delete hard-link migration stores that can't otherwise be deleted at a command prompt due to a sharing lock. If the migration store spans multiple volumes on a given drive, the migration store is deleted from all of these volumes. <br/><br/>For example:<br/>`UsmtUtils.exe /rd D:\MyHardLinkStore`|
|**/rd** *\<storeDir\>* |Removes the directory path specified by the *\<storeDir\>* argument on the computer. This command can be used to delete hard-link migration stores that can't otherwise be deleted at a command prompt due to a sharing lock. If the migration store spans multiple volumes on a given drive, the migration store is deleted from all of these volumes. <br><br>For example:<br>`UsmtUtils.exe /rd D:\MyHardLinkStore`|
|**/y**|Overrides the prompt to accept deletions when used with the `/rd` option. When the `/y` option is used with the `/rd` option, a prompt isn't displayed to accept the deletions before USMT deletes the directories.|
|**/verify**|Returns information on whether the compressed migration store is intact or whether it contains corrupted files or a corrupted catalog. <br/><br/>See [Verify options](#verify-options) for syntax and options to use with `/verify`.|
|**/extract**|Recovers files from a compressed USMT migration store. <br/><br/>See [Extract options](#extract-options) for syntax and options to use with `/extract`.|
|**/verify**|Returns information on whether the compressed migration store is intact or whether it contains corrupted files or a corrupted catalog. <br><br>See [Verify options](#verify-options) for syntax and options to use with `/verify`.|
|**/extract**|Recovers files from a compressed USMT migration store. <br><br>See [Extract options](#extract-options) for syntax and options to use with `/extract`.|
## Verify options
@ -44,14 +44,14 @@ Use the `/verify` option to determine whether a compressed migration store is in
The syntax for `/verify` is:
> UsmtUtils.exe /verify\[:*&lt;reportType&gt;*\] *&lt;filePath&gt;* \[/l:*&lt;logfile&gt;*\] \[/v:*VerbosityLevel*\] \[/decrypt \[:*&lt;AlgID&gt;*\] {/key:*&lt;keystring&gt;* | /keyfile:*&lt;filename&gt;*}\]
> UsmtUtils.exe /verify\[:*\<reportType\>*\] *\<filePath\>* \[/l:*\<logfile\>*\] \[/v:*VerbosityLevel*\] \[/decrypt \[:*\<AlgID\>*\] {/key:*\<keystring\>* | /keyfile:*\<filename\>*}\]
| Command-line Option | Description |
|-----|--------|
| *&lt;reportType&gt;* | Specifies whether to report on all files, corrupted files only, or the status of the catalog. <ul><li>**Summary**. Returns both the number of files that are intact and the number of files that are corrupted in the migration store. If no algorithm is specified, the summary report is displayed as a default.</li><li>**all**. Returns a tab-delimited list of all of the files in the compressed migration store and the status for each file. Each line contains the file name followed by a tab spacing, and either **CORRUPTED** or **OK** depending on the status of the file. The last entry reports the corruption status of the **CATALOG** of the store. A catalog file contains metadata for all files in a migration store. The **LoadState** tool requires a valid catalog file in order to open the migration store. Returns &quot;OK&quot; if the catalog file is intact and **LoadState** can open the migration store and &quot;CORRUPTED&quot; if the migration store is corrupted.</li><li>**failureonly**. Returns a tab-delimited list of only the files that are corrupted in the compressed migration store.</li><li>**Catalog**. Returns only the status of the catalog file.</li></ul> |
| **/l:** <br/>*&lt;logfilePath&gt;* | Specifies the location and name of the log file. |
| **/v:** *&lt;VerbosityLevel&gt;* | **(Verbosity)**<br/><br/>Enables verbose output in the **UsmtUtils** log file. The default value is 0.<br/><br/>The *VerbosityLevel* can be set to one of the following levels:<br/><ul><li>**0** - Only the default errors and warnings are enabled.</li><li>**1** - Enables verbose output.</li><li>**4** - Enables error and status output.</li><li>**5** - Enables verbose and status output.</li><li>**8** - Enables error output to a debugger.</li><li>**9** - Enables verbose output to a debugger.</li><li>**12** - Enables error and status output to a debugger.</li><li>**13** - Enables verbose, status, and debugger output.</li></ul> |
| **/decrypt** *&lt;AlgID&gt;* **/**:*&lt;KeyString&gt;*<br/>or<br/>**/decrypt** *&lt;AlgID&gt;* **/**:*&lt;"Key String"&gt;*<br/>or<br/>**/decrypt:** *&lt;AlgID&gt;* **/keyfile**:*&lt;FileName&gt;* | Specifies that the `/encrypt` option was used to create the migration store with the **ScanState** tool. To decrypt the migration store, specify a `/key` or `/keyfile` option as follows:<br/><ul><li>*&lt;AlgID&gt;* specifies the cryptographic algorithm that was used to create the migration store on the `ScanState.exe` command line. If no algorithm is specified, **ScanState** and **UsmtUtils** use the 3DES algorithm as a default.<br/>*&lt;AlgID&gt;* valid values include: `AES_128`, `AES_192`, `AES_256`, `3DES`, or `3DES_112`.</li><li> `/key:` *&lt;KeyString&gt;* specifies the encryption key. If there's a space in *&lt;KeyString&gt;*, the argument must be surrounded with quotation marks.</li><li> `/keyfile`: *&lt;FileName&gt;* specifies the location and name of a text (.txt) file that contains the encryption key.</li></ul><br/>For more information about supported encryption algorithms, see [Migration Store Encryption](usmt-migration-store-encryption.md). |
| *\<reportType\>* | Specifies whether to report on all files, corrupted files only, or the status of the catalog. <ul><li>**Summary**. Returns both the number of files that are intact and the number of files that are corrupted in the migration store. If no algorithm is specified, the summary report is displayed as a default.</li><li>**all**. Returns a tab-delimited list of all of the files in the compressed migration store and the status for each file. Each line contains the file name followed by a tab spacing, and either **CORRUPTED** or **OK** depending on the status of the file. The last entry reports the corruption status of the **CATALOG** of the store. A catalog file contains metadata for all files in a migration store. The **LoadState** tool requires a valid catalog file in order to open the migration store. Returns &quot;OK&quot; if the catalog file is intact and **LoadState** can open the migration store and &quot;CORRUPTED&quot; if the migration store is corrupted.</li><li>**failureonly**. Returns a tab-delimited list of only the files that are corrupted in the compressed migration store.</li><li>**Catalog**. Returns only the status of the catalog file.</li></ul> |
| **/l:** <br>*\<logfilePath\>* | Specifies the location and name of the log file. |
| **/v:** *\<VerbosityLevel\>* | **(Verbosity)**<br><br>Enables verbose output in the **UsmtUtils** log file. The default value is 0.<br><br>The *VerbosityLevel* can be set to one of the following levels:<br><ul><li>**0** - Only the default errors and warnings are enabled.</li><li>**1** - Enables verbose output.</li><li>**4** - Enables error and status output.</li><li>**5** - Enables verbose and status output.</li><li>**8** - Enables error output to a debugger.</li><li>**9** - Enables verbose output to a debugger.</li><li>**12** - Enables error and status output to a debugger.</li><li>**13** - Enables verbose, status, and debugger output.</li></ul> |
| **/decrypt** *\<AlgID\>* **/**:*\<KeyString\>*<br>or<br>**/decrypt** *\<AlgID\>* **/**:*\<"Key String"\>*<br>or<br>**/decrypt:** *\<AlgID\>* **/keyfile**:*\<FileName\>* | Specifies that the `/encrypt` option was used to create the migration store with the **ScanState** tool. To decrypt the migration store, specify a `/key` or `/keyfile` option as follows:<br><ul><li>*\<AlgID\>* specifies the cryptographic algorithm that was used to create the migration store on the `ScanState.exe` command line. If no algorithm is specified, **ScanState** and **UsmtUtils** use the 3DES algorithm as a default.<br>*\<AlgID\>* valid values include: `AES_128`, `AES_192`, `AES_256`, `3DES`, or `3DES_112`.</li><li> `/key:` *\<KeyString\>* specifies the encryption key. If there's a space in *\<KeyString\>*, the argument must be surrounded with quotation marks.</li><li> `/keyfile`: *\<FileName\>* specifies the location and name of a text (.txt) file that contains the encryption key.</li></ul><br>For more information about supported encryption algorithms, see [Migration Store Encryption](usmt-migration-store-encryption.md). |
Some examples of `/verify` commands:
@ -69,17 +69,17 @@ Use the `/extract` option to recover files from a compressed USMT migration stor
The syntax for `/extract` is:
> /extract *&lt;filePath&gt;* *&lt;destinationPath&gt;* \[/i:*&lt;includePattern&gt;*\] \[/e: *&lt;excludePattern&gt;*\] \[/l: *&lt;logfile&gt;*\] \[/v: *VerbosityLevel&gt;*\] \[/decrypt\[:*&lt;AlgID&gt;*\] {key: *&lt;keystring&gt;* | /keyfile: *&lt;filename&gt;*}\] \[/o\]
> /extract *\<filePath\>* *\<destinationPath\>* \[/i:*\<includePattern\>*\] \[/e: *\<excludePattern\>*\] \[/l: *\<logfile\>*\] \[/v: *VerbosityLevel\>*\] \[/decrypt\[:*\<AlgID\>*\] {key: *\<keystring\>* | /keyfile: *\<filename\>*}\] \[/o\]
| Command-line Option | Description |
|-------|-----|
| *&lt;filePath&gt;* | Path to the USMT migration store. <br/><br/>For example:<br/>`D:\MyMigrationStore\USMT\store.mig` |
| *&lt;destinationPath&gt;* | Path to the folder where the tool puts the individual files. |
| **/i**:*&lt;includePattern&gt;* | Specifies a pattern for files to include in the extraction. You can specify more than one pattern. Separate patterns with a comma or a semicolon. You can use `/i`: *&lt;includePattern&gt;* and `/e`: *&lt;excludePattern&gt;* options in the same command. When both include and exclude patterns are used on the command line, include patterns take precedence over exclude patterns. |
| **/e**:*&lt;excludePattern&gt;* | Specifies a pattern for files to omit from the extraction. You can specify more than one pattern. Separate patterns with a comma or a semicolon. You can use `/i`: *&lt;includePattern&gt;* and `/e`: *&lt;excludePattern&gt;* options in the same command. When both include and exclude patterns are used on the command line, include patterns take precedence over exclude patterns. |
| **/l**:*&lt;logfilePath&gt;* | Specifies the location and name of the log file. |
| **/v:***&lt;VerbosityLevel&gt;* | **(Verbosity)**<br/><br/>Enables verbose output in the **UsmtUtils** log file. The default value is 0.<br/><br/>You can set the *VerbosityLevel* to one of the following levels:<br/><ul><li>**0** - Only the default errors and warnings are enabled.</li><li>**1** - Enables verbose output.</li><li>**4** - Enables error and status output.</li><li>**5** - Enables verbose and status output.</li><li>**8** - Enables error output to a debugger.</li><li>**9** - Enables verbose output to a debugger.</li><li>**12** - Enables error and status output to a debugger.</li><li>**13** - Enables verbose, status, and debugger output.</li></ul> |
| **/decrypt***&lt;AlgID&gt;***/key**:*&lt;KeyString&gt;*<br/>or<br/>**/decrypt***&lt;AlgID&gt;***/**:*&lt;"Key String"&gt;*<br/>or<br/>**/decrypt:***&lt;AlgID&gt;***/keyfile**:*&lt;FileName&gt;* | Specifies that the `/encrypt` option was used to create the migration store with the **ScanState** tool. To decrypt the migration store, you must also specify the `/key` or `/keyfile` option as follows:<br/><ul><li>*&lt;AlgID&gt;* specifies the cryptographic algorithm that was used to create the migration store on the `ScanState.exe` command line. If no algorithm is specified, **ScanState** and **UsmtUtils** use the 3DES algorithm as a default.<br/>*&lt;AlgID&gt;* valid values include: `AES_128`, `AES_192`, `AES_256`, `3DES`, or `3DES_112`.</li><li>`/key`: *&lt;KeyString&gt;* specifies the encryption key. If there's a space in *&lt;KeyString&gt;*, you must surround the argument with quotation marks.</li><li>`/keyfile`:*&lt;FileName&gt;* specifies a text (.txt) file that contains the encryption key</li></ul><br/>For more information about supported encryption algorithms, see [Migration store encryption](usmt-migration-store-encryption.md). |
| *\<filePath\>* | Path to the USMT migration store. <br><br>For example:<br>`D:\MyMigrationStore\USMT\store.mig` |
| *\<destinationPath\>* | Path to the folder where the tool puts the individual files. |
| **/i**:*\<includePattern\>* | Specifies a pattern for files to include in the extraction. You can specify more than one pattern. Separate patterns with a comma or a semicolon. You can use `/i`: *\<includePattern\>* and `/e`: *\<excludePattern\>* options in the same command. When both include and exclude patterns are used on the command line, include patterns take precedence over exclude patterns. |
| **/e**:*\<excludePattern\>* | Specifies a pattern for files to omit from the extraction. You can specify more than one pattern. Separate patterns with a comma or a semicolon. You can use `/i`: *\<includePattern\>* and `/e`: *\<excludePattern\>* options in the same command. When both include and exclude patterns are used on the command line, include patterns take precedence over exclude patterns. |
| **/l**:*\<logfilePath\>* | Specifies the location and name of the log file. |
| **/v:***\<VerbosityLevel\>* | **(Verbosity)**<br><br>Enables verbose output in the **UsmtUtils** log file. The default value is 0.<br><br>You can set the *VerbosityLevel* to one of the following levels:<br><ul><li>**0** - Only the default errors and warnings are enabled.</li><li>**1** - Enables verbose output.</li><li>**4** - Enables error and status output.</li><li>**5** - Enables verbose and status output.</li><li>**8** - Enables error output to a debugger.</li><li>**9** - Enables verbose output to a debugger.</li><li>**12** - Enables error and status output to a debugger.</li><li>**13** - Enables verbose, status, and debugger output.</li></ul> |
| **/decrypt***\<AlgID\>***/key**:*\<KeyString\>*<br>or<br>**/decrypt***\<AlgID\>***/**:*\<"Key String"\>*<br>or<br>**/decrypt:***\<AlgID\>***/keyfile**:*\<FileName\>* | Specifies that the `/encrypt` option was used to create the migration store with the **ScanState** tool. To decrypt the migration store, you must also specify the `/key` or `/keyfile` option as follows:<br><ul><li>*\<AlgID\>* specifies the cryptographic algorithm that was used to create the migration store on the `ScanState.exe` command line. If no algorithm is specified, **ScanState** and **UsmtUtils** use the 3DES algorithm as a default.<br>*\<AlgID\>* valid values include: `AES_128`, `AES_192`, `AES_256`, `3DES`, or `3DES_112`.</li><li>`/key`: *\<KeyString\>* specifies the encryption key. If there's a space in *\<KeyString\>*, you must surround the argument with quotation marks.</li><li>`/keyfile`:*\<FileName\>* specifies a text (.txt) file that contains the encryption key</li></ul><br>For more information about supported encryption algorithms, see [Migration store encryption](usmt-migration-store-encryption.md). |
| **/o** | Overwrites existing output files. |
Some examples of `/extract` commands:

10
windows/deployment/usmt/usmt-what-does-usmt-migrate.md
View File

@ -14,11 +14,11 @@ ms.technology: itpro-deploy
## Default migration scripts
The User State Migration Tool (USMT) is designed so that an IT engineer can precisely define migrations using the USMT .xml scripting language. USMT provides the following sample scripts:
The User State Migration Tool (USMT) is designed so that an IT engineer can precisely define migrations using the USMT **.xml** scripting language. USMT provides the following sample scripts:
- **MigApp.XML** - Rules to migrate application settings.
- **MigDocs.XML** - Rules that use the **MigXmlHelper.GenerateDocPatterns** helper function, which can be used to automatically find user documents on a computer without the need to author extensive custom migration .xml files.
- **MigDocs.XML** - Rules that use the **MigXmlHelper.GenerateDocPatterns** helper function, which can be used to automatically find user documents on a computer without the need to author extensive custom migration **.xml** files.
- **MigUser.XML** - Rules to migrate user profiles and user data.
@ -91,9 +91,7 @@ This section describes the user data that USMT migrates by default, using the `M
## Operating-system components
USMT migrates operating-system components to a destination computer from computers running Windows 7 and Windows 8
The following components are migrated by default using the manifest files:
USMT migrates operating-system components to a destination computer. The following components are migrated by default using the manifest files:
- Accessibility settings.
@ -111,7 +109,7 @@ The following components are migrated by default using the manifest files:
- Fonts.
- Group membership. USMT migrates users' group settings. The groups to which a user belongs can be found by right-clicking **My Computer** on the Start menu and then selecting **Manage**. The use of a **&lt;ProfileControl&gt;** section in the `Config.xml` file is required when running an offline migration.
- Group membership. USMT migrates users' group settings. The groups to which a user belongs can be found by right-clicking **My Computer** on the Start menu and then selecting **Manage**. The use of a **\<ProfileControl\>** section in the `Config.xml` file is required when running an offline migration.
- Windows Internet Explorer® settings. **¹**

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

@ -1,6 +1,6 @@
---
title: XML Elements Library
description: Learn about the XML elements and helper functions that you can employ to author migration .xml files to use with User State Migration Tool (USMT).
description: Learn about the XML elements and helper functions that can be employed to author migration .xml files to use with User State Migration Tool (USMT).
manager: aaroncz
ms.author: frankroj
ms.prod: windows-client
@ -12,21 +12,21 @@ ms.technology: itpro-deploy
# XML elements library
This article describes the XML elements and helper functions that you can employ to author migration .xml files to use with User State Migration Tool (USMT). This article assumes a basic knowledge of XML.
This article describes the XML elements and helper functions that can be employed to author migration **.xml** files to use with User State Migration Tool (USMT). This article assumes a basic knowledge of XML.
In addition to XML elements and helper functions, this article:
- Describes how to specify encoded locations and locations patterns.
- Functions that are for internal USMT use only.
- The version tags that you can use with helper functions.
- The version tags that can be used with helper functions.
## Elements and helper functions
The following table describes the XML elements and helper functions you can use with USMT.
The following table describes the XML elements and helper functions can be used with USMT.
| Elements A-K | Elements L-Z | Helper functions |
|-----|----|-----|
| [\<addObjects\>](#addobjects) <br/>[\<attributes\>](#attributes) <br/>[\<bytes\>](#bytes) <br/>[\<commandLine\>](#commandline) <br/>[\<component\>](#component) <br/>[\<condition\>](#condition) <br/>[\<conditions\>](#conditions) <br/>[\<content\>](#content) <br/>[\<contentModify\>](#contentmodify) <br/>[\<description\>](#description) <br/>[\<destinationCleanup\>](#destinationcleanup) <br/>[\<detect\>](#detect) <br/>[\<detects\>](#detects) <br/>[\<detection\>](#detection) <br/>[\<displayName\>](#displayname) <br/>[\<environment\>](#environment) <br/>[\<exclude\>](#exclude) <br/>[\<excludeAttributes\>](#excludeattributes) <br/>[\<extensions\>](#extensions) <br/>[\<extension\>](#extension) <br/>[\<externalProcess\>](#externalprocess) <br/>[\<icon\>](#icon) <br/>[\<include\>](#include) <br/>[\<includeAttribute\>](#includeattributes) | [\<library\>](#library) <br/>[\<location\>](#location) <br/>[\<locationModify\>](#locationmodify) <br/>[\<_locDefinition\>](#_locdefinition) <br/>[\<manufacturer\>](#manufacturer) <br/>[\<merge\>](#merge) <br/>[\<migration\>](#migration) <br/>[\<namedElements\>](#namedelements) <br/>[\<object\>](#object) <br/>[\<objectSet\>](#objectset) <br/>[\<path\>](#path) <br/>[\<paths\>](#paths) <br/>[\<pattern\>](#pattern) <br/>[\<processing\>](#processing) <br/>[\<plugin\>](#plugin) <br/>[\<role\>](#role) <br/>[\<rules\>](#rules) <br/>[\<script\>](#script) <br/>[\<text\>](#text) <br/>[\<unconditionalExclude\>](#unconditionalexclude) <br/>[\<variable\>](#variable) <br/>[\<version\>](#version) <br/>[\<windowsObjects\>](#windowsobjects) | [\<condition\> functions](#condition-functions) <br/>[\<content\> functions](#content-functions) <br/>[\<contentModify\> functions](#contentmodify-functions) <br/>[\<include\> and \<exclude\> filter functions](#include-and-exclude-filter-functions) <br/>[\<locationModify\> functions](#locationmodify-functions) <br/>[\<merge\> functions](#merge-functions) <br/>[\<script\> functions](#script-functions) <br/>[Internal USMT functions](#internal-usmt-functions) |
| [\<addObjects\>](#addobjects) <br>[\<attributes\>](#attributes) <br>[\<bytes\>](#bytes) <br>[\<commandLine\>](#commandline) <br>[\<component\>](#component) <br>[\<condition\>](#condition) <br>[\<conditions\>](#conditions) <br>[\<content\>](#content) <br>[\<contentModify\>](#contentmodify) <br>[\<description\>](#description) <br>[\<destinationCleanup\>](#destinationcleanup) <br>[\<detect\>](#detect) <br>[\<detects\>](#detects) <br>[\<detection\>](#detection) <br>[\<displayName\>](#displayname) <br>[\<environment\>](#environment) <br>[\<exclude\>](#exclude) <br>[\<excludeAttributes\>](#excludeattributes) <br>[\<extensions\>](#extensions) <br>[\<extension\>](#extension) <br>[\<externalProcess\>](#externalprocess) <br>[\<icon\>](#icon) <br>[\<include\>](#include) <br>[\<includeAttribute\>](#includeattributes) | [\<library\>](#library) <br>[\<location\>](#location) <br>[\<locationModify\>](#locationmodify) <br>[\<_locDefinition\>](#_locdefinition) <br>[\<manufacturer\>](#manufacturer) <br>[\<merge\>](#merge) <br>[\<migration\>](#migration) <br>[\<namedElements\>](#namedelements) <br>[\<object\>](#object) <br>[\<objectSet\>](#objectset) <br>[\<path\>](#path) <br>[\<paths\>](#paths) <br>[\<pattern\>](#pattern) <br>[\<processing\>](#processing) <br>[\<plugin\>](#plugin) <br>[\<role\>](#role) <br>[\<rules\>](#rules) <br>[\<script\>](#script) <br>[\<text\>](#text) <br>[\<unconditionalExclude\>](#unconditionalexclude) <br>[\<variable\>](#variable) <br>[\<version\>](#version) <br>[\<windowsObjects\>](#windowsobjects) | [\<condition\> functions](#condition-functions) <br>[\<content\> functions](#content-functions) <br>[\<contentModify\> functions](#contentmodify-functions) <br>[\<include\> and \<exclude\> filter functions](#include-and-exclude-filter-functions) <br>[\<locationModify\> functions](#locationmodify-functions) <br>[\<merge\> functions](#merge-functions) <br>[\<script\> functions](#script-functions) <br>[Internal USMT functions](#internal-usmt-functions) |
## \<addObjects\>
@ -36,7 +36,7 @@ The **\<addObjects\>** element emulates the existence of one or more objects on
- **Parent elements:** [\<rules\>](#rules)
- **Required child elements:** [\<object\>](#object) In addition, you must specify [\<location\>](#location) and [\<attribute\>](#attributes) as child elements of this **\<object\>** element.
- **Required child elements:** [\<object\>](#object) In addition, [\<location\>](#location) and [\<attribute\>](#attributes) must be specified as child elements of this **\<object\>** element.
- **Optional child elements:** [\<conditions\>](#conditions), [\<condition\>](#condition), [\<script\>](#script)
@ -82,13 +82,13 @@ Syntax:
| Setting | Required? | Value |
|------|-----|----|
| *Content* | Yes | The content depends on the type of object specified. <br/><ul><li>For files, the content can be a string containing any of the following attributes separated by commas:<ul><li>Archive</li><li>Read-only</li><li>System</li><li>Hidden</li></ul></li><li>For registry keys, the content can be one of the following types:<ul><li>None</li><li>String</li><li>ExpandString</li><li>Binary</li><li>Dword</li><li>REG_SZ</li></ul></li></ul>|
| *Content* | Yes | The content depends on the type of object specified. <br><ul><li>For files, the content can be a string containing any of the following attributes separated by commas:<ul><li>Archive</li><li>Read-only</li><li>System</li><li>Hidden</li></ul></li><li>For registry keys, the content can be one of the following types:<ul><li>None</li><li>String</li><li>ExpandString</li><li>Binary</li><li>Dword</li><li>REG_SZ</li></ul></li></ul>|
The following example is from the `MigApp.xml` file:
```xml
<object>
<location type="Registry">%HklmWowSoftware%\Microsoft\Office\12.0\Common\Migration\Office [Lang]</location>
<location type="Registry">%HklmWowSoftware%\Microsoft\Office\16.0\Common\Migration\Office [Lang]</location>
<attributes>DWORD</attributes>
<bytes>00000000</bytes>
</object>
@ -96,7 +96,7 @@ The following example is from the `MigApp.xml` file:
## \<bytes\>
You must specify the **\<bytes\>** element only for files because, if **\<location\>** corresponds to a registry key or a directory, then **\<bytes\>** is ignored.
The **\<bytes\>** element can only be specified for files because, if **\<location\>** corresponds to a registry key or a directory, then **\<bytes\>** is ignored.
- **Number of occurrences:** zero or one
@ -120,7 +120,7 @@ The following example is from the `MigApp.xml` file:
```xml
<object>
<location type="Registry">%HklmWowSoftware%\Microsoft\Office\12.0\Common\Migration\Office [Lang]</location>
<location type="Registry">%HklmWowSoftware%\Microsoft\Office\16.0\Common\Migration\Office [Lang]</location>
<attributes>DWORD</attributes>
<bytes>00000000</bytes>
</object>
@ -128,7 +128,7 @@ The following example is from the `MigApp.xml` file:
## \<commandLine\>
You might want to use the **\<commandLine\>** element if you want to start or stop a service or application before or after you run the **ScanState** and **LoadState** tools.
The **\<commandLine\>** element might be used to start or stop a service or application before or after running the **ScanState** and **LoadState** tools.
- **Number of occurrences:** unlimited
@ -148,7 +148,7 @@ Syntax:
## \<component\>
The **\<component\>** element is required in a custom .xml file. This element defines the most basic construct of a migration .xml file. For example, in the `MigApp.xml` file, **Microsoft Office 2016** is a component that contains another component, **Microsoft Office Access 2016**. You can use the child elements to define the component.
The **\<component\>** element is required in a custom **.xml** file. This element defines the most basic construct of a migration **.xml** file. For example, in the `MigApp.xml` file, **Microsoft Office 2016** is a component that contains another component, **Microsoft Office Access 2016**. The child elements can be used to define the component.
A component can be nested inside another component; that is, the **\<component\>** element can be a child of the **\<role\>** element within the **\<component\>** element in two cases:
@ -173,18 +173,18 @@ hidden="Yes|No">
|Setting|Required?|Value|
|--- |--- |--- |
| type | Yes | You can use the following to group settings, and define the type of the component.<ul><li>**System:** Operating system settings. All Windows components are defined by this type. <br/>When **type="System"** and **defaultSupported="FALSE"**, the settings don't migrate unless there's an equivalent component in the .xml files that is specified on the `LoadState.exe` command line. For example, the default `MigSys.xml` file contains components with **type="System"** and **defaultSupported="FALSE"**. If you specify this file on the `ScanState.exe` command line, you must also specify the file on the `LoadState.exe` command line for the settings to migrate. The file must be specified because the `LoadState.exe` tool must detect an equivalent component. That is, the component must have the same migration urlid of the .xml file and an identical display name. Otherwise, the **LoadState** tool doesn't migrate those settings from the store. This setting is helpful because a store can be used for destination computers that are the same or different version of Windows as the source computer.</li><li>**Application:** Settings for an application.</li><li>**Device:** Settings for a device.</li><li>**Documents:** Specifies files.</li></ul> |
| context | No <br/>Default = UserAndSystem | Defines the scope of this parameter; that is, whether to process this component in the context of the specific user, across the entire operating system, or both. <br/>The largest possible scope is set by the **\<component\>** element. For example, if a **\<component\>** element has a context of **User** and a **\<rules\>** element had a context of **UserAndSystem**, then the **\<rules\>** element would act as though it has a context of **User**. If a **\<rules\>** element has a context of **System**, it would act as though the **\<rules\>** element isn't there. <ul><li>**User**: Evaluates the component for each user.</li><li>**System**: Evaluates the component only once for the system.</li><li>**UserAndSystem**: Evaluates the component for the entire operating system and each user.</li></ul> |
| defaultSupported | No <br/>(default = TRUE) | Can be any of **TRUE**, **FALSE**, **YES**, or **NO**. If this parameter is **FALSE** (or **NO**), the component isn't migrated unless there's an equivalent component on the destination computer. <br/>When **type="System"** and **defaultSupported="FALSE"**, the settings aren't migrated unless there's an equivalent component in the .xml files that are specified on the `LoadState.exe` command line. For example, the default `MigSys.xml` file contains components with **type="System"** and **defaultSupported="FALSE"**. If you specify this file on the `ScanState.exe` command line, you must also specify the file on the `LoadState.exe` command line for the settings to migrate. The file has to be specified in both command lines because the **LoadState** tool must detect an equivalent component. That is, the component must have the same migration urlid of the .xml file and an identical display name or the **LoadState** tool doesn't migrate those settings from the store. This setting is helpful because a store can be used for destination computers that are the same or different version of Windows as the source computer. |
| type | Yes | The following items can be used to group settings, and define the type of the component.<ul><li>**System:** Operating system settings. All Windows components are defined by this type. <br>When **type="System"** and **defaultSupported="FALSE"**, the settings don't migrate unless there's an equivalent component in the **.xml** files that is specified on the `LoadState.exe` command line. For example, the default `MigSys.xml` file contains components with **type="System"** and **defaultSupported="FALSE"**. If this file is specified on the `ScanState.exe` command line, the file must also be specified on the `LoadState.exe` command line for the settings to migrate. The file must be specified because the `LoadState.exe` tool must detect an equivalent component. That is, the component must have the same migration urlid of the **.xml** file and an identical display name. Otherwise, the **LoadState** tool doesn't migrate those settings from the store. This setting is helpful because a store can be used for destination computers that are the same or different version of Windows as the source computer.</li><li>**Application:** Settings for an application.</li><li>**Device:** Settings for a device.</li><li>**Documents:** Specifies files.</li></ul> |
| context | No <br>Default = UserAndSystem | Defines the scope of this parameter; that is, whether to process this component in the context of the specific user, across the entire operating system, or both. <br>The largest possible scope is set by the **\<component\>** element. For example, if a **\<component\>** element has a context of **User** and a **\<rules\>** element had a context of **UserAndSystem**, then the **\<rules\>** element would act as though it has a context of **User**. If a **\<rules\>** element has a context of **System**, it would act as though the **\<rules\>** element isn't there. <ul><li>**User**: Evaluates the component for each user.</li><li>**System**: Evaluates the component only once for the system.</li><li>**UserAndSystem**: Evaluates the component for the entire operating system and each user.</li></ul> |
| defaultSupported | No <br>(default = TRUE) | Can be any of **TRUE**, **FALSE**, **YES**, or **NO**. If this parameter is **FALSE** (or **NO**), the component isn't migrated unless there's an equivalent component on the destination computer. <br>When **type="System"** and **defaultSupported="FALSE"**, the settings aren't migrated unless there's an equivalent component in the **.xml** files that are specified on the `LoadState.exe` command line. For example, the default `MigSys.xml` file contains components with **type="System"** and **defaultSupported="FALSE"**. If this file is specified on the `ScanState.exe` command line, the file must also be specified on the `LoadState.exe` command line for the settings to migrate. The file has to be specified in both command lines because the **LoadState** tool must detect an equivalent component. That is, the component must have the same migration urlid of the **.xml** file and an identical display name or the **LoadState** tool doesn't migrate those settings from the store. This setting is helpful because a store can be used for destination computers that are the same or different version of Windows as the source computer. |
| hidden | | This parameter is for internal USMT use only. |
For an example, see any of the default migration .xml files.
For an example, see any of the default migration **.xml** files.
## \<condition\>
Although the **\<condition\>** element under the **\<detect\>**, **\<objectSet\>**, and **\<addObjects\>** elements is still supported, Microsoft recommends to no longer use the **\<condition\>** element because it might be deprecated in future versions of USMT. If the **\<condition\>** element is deprecated, it would require a rewrite of any scripts that use the **\<condition\>** element. Instead, if you need to use a condition within the **\<objectSet\>** and **\<addObjects\>** elements, Microsoft recommends using the more powerful **[\<conditions\>](#conditions)** element. The **\<conditions\>** element allows for formulation of complex Boolean statements.
Although the **\<condition\>** element under the **\<detect\>**, **\<objectSet\>**, and **\<addObjects\>** elements is still supported, Microsoft recommends to no longer use the **\<condition\>** element because it might be deprecated in future versions of USMT. If the **\<condition\>** element is deprecated, it would require a rewrite of any scripts that use the **\<condition\>** element. Instead, if a condition needs to be used within the **\<objectSet\>** and **\<addObjects\>** elements, Microsoft recommends using the more powerful **[\<conditions\>](#conditions)** element. The **\<conditions\>** element allows for formulation of complex Boolean statements.
The **\<condition\>** element has a Boolean result. You can use this element to specify the conditions in which the parent element is evaluated. If any of the present conditions return **FALSE**, the parent element isn't be evaluated.
The **\<condition\>** element has a Boolean result. This element can be used to specify the conditions in which the parent element is evaluated. If any of the present conditions return **FALSE**, the parent element isn't be evaluated.
- **Number of occurrences:** unlimited.
@ -192,7 +192,7 @@ The **\<condition\>** element has a Boolean result. You can use this element to
- **Child elements:** none
- **Helper functions:** You can use the following [\<condition\> functions](#condition-functions) with this element: `DoesOSMatch`, `IsNative64Bit()`, `IsOSLaterThan`, `IsOSEarlierThan`, `DoesObjectExist`, `DoesFileVersionMatch`, `IsFileVersionAbove`, `IsFileVersionBelow`, `IsSystemContext`, `DoesStringContentEqual`, `DoesStringContentContain`, `IsSameObject`, `IsSameContent`, and `IsSameStringContent`.
- **Helper functions:** The following [\<condition\> functions](#condition-functions) can be used with this element: `DoesOSMatch`, `IsNative64Bit()`, `IsOSLaterThan`, `IsOSEarlierThan`, `DoesObjectExist`, `DoesFileVersionMatch`, `IsFileVersionAbove`, `IsFileVersionBelow`, `IsSystemContext`, `DoesStringContentEqual`, `DoesStringContentContain`, `IsSameObject`, `IsSameContent`, and `IsSameStringContent`.
Syntax:
@ -202,7 +202,7 @@ Syntax:
|Setting|Required?|Value|
|--- |--- |--- |
|negation|No <br/>Default = No|**"Yes"** reverses the True/False value of the condition.|
|negation|No <br>Default = No|**"Yes"** reverses the True/False value of the condition.|
|*ScriptName*|Yes|A script that is defined within this migration section.|
For example, in the following code sample, the **\<condition\>** elements, **A** and **B**, are joined together by the **AND** operator because they are in separate **\<conditions\>** sections:
@ -231,7 +231,7 @@ However, in the following code sample, the **\<condition\>** elements, **A** and
### \<condition\> functions
The **\<condition\>** functions return a Boolean value. You can use these elements in **\<addObjects\>** conditions.
The **\<condition\>** functions return a Boolean value. These elements can be used in **\<addObjects\>** conditions.
- [Operating system version functions](#operating-system-version-functions)
@ -247,8 +247,8 @@ The **\<condition\>** functions return a Boolean value. You can use these elemen
|Setting|Required?|Value|
|--- |--- |--- |
|*OSType*|Yes|The only valid value for this setting is **NT**. Note, however, that you must set this setting for the **\<condition\>** functions to work correctly.|
|*OSVersion*|Yes|The major version, minor version, build number and corrected service diskette version separated by periods. For example, `5.0.2600.Service Pack 1`. You can also specify partial specification of the version with a pattern such as `5.0.*`.|
|*OSType*|Yes|The only valid value for this setting is **NT**. However, this setting must be set for the **\<condition\>** functions to work correctly.|
|*OSVersion*|Yes|The major version, minor version, build number and corrected service diskette version separated by periods. For example, `5.0.2600.Service Pack 1`. Partial specification of the version can also be specified with a pattern such as `5.0.*`.|
For example:
@ -269,7 +269,7 @@ The **\<condition\>** functions return a Boolean value. You can use these elemen
|Setting|Required?|Value|
|--- |--- |--- |
|*OSType*|Yes|Can be **9x** or **NT**. If *OSType* doesn't match the type of the current operating system, then it returns **FALSE**. For example, if the current operating system is Windows NT-based and *OSType* is **"9x"**, the result is **FALSE**.|
|*OSVersion*|Yes|The major version, minor version, build number, and corrected service diskette version separated by periods. For example, `5.0.2600.Service Pack 1`. You can also specify partial specification of the version but no pattern is allowed such as `5.0`. <br/><br/>The **IsOSLaterThan** function returns **TRUE** if the current operating system is later than or equal to *OSVersion*.|
|*OSVersion*|Yes|The major version, minor version, build number, and corrected service diskette version separated by periods. For example, `5.0.2600.Service Pack 1`. Partial specification of the version can also be specified but no pattern is allowed such as `5.0`. <br><br>The **IsOSLaterThan** function returns **TRUE** if the current operating system is later than or equal to *OSVersion*.|
For example:
@ -286,7 +286,7 @@ The **\<condition\>** functions return a Boolean value. You can use these elemen
|Setting|Required?|Value|
|--- |--- |--- |
|*OSType*|Yes|Can be **9x** or **NT**. If *OSType* doesn't match the type of the current operating system, then it returns **FALSE**. For example, if the current operating system is Windows NT-based and *OSType* is **"9x"** the result is **FALSE**.|
|*OSVersion*|Yes|The major version, minor version, build number, and corrected service diskette version separated by periods. For example, `5.0.2600.Service Pack 1`. You can also specify partial specification of the version but no pattern is allowed such as `5.0`. <br/><br/>The **IsOSEarlierThan** function returns **TRUE** if the current operating system is earlier than *OSVersion*.|
|*OSVersion*|Yes|The major version, minor version, build number, and corrected service diskette version separated by periods. For example, `5.0.2600.Service Pack 1`. Partial specification of the version can also be specified but no pattern is allowed such as `5.0`. <br><br>The **IsOSEarlierThan** function returns **TRUE** if the current operating system is earlier than *OSVersion*.|
### Object content functions
@ -331,7 +331,7 @@ The **\<condition\>** functions return a Boolean value. You can use these elemen
|--- |--- |--- |
|*EncodedFileLocation*|Yes|The **[location pattern](#specifying-locations)** for the file that is checked. Environment variables are allowed.|
|*VersionTag*|Yes|The **[version tag](#valid-version-tags)** value that is checked.|
|*VersionValue*|Yes|The value to compare to. You can't specify a pattern.|
|*VersionValue*|Yes|The value to compare to. A pattern can't be specified.|
- **IsFileVersionBelow**
@ -341,7 +341,7 @@ The **\<condition\>** functions return a Boolean value. You can use these elemen
|--- |--- |--- |
|*EncodedFileLocation*|Yes|The **[location pattern](#specifying-locations)** for the file that is checked. Environment variables are allowed.|
|*VersionTag*|Yes|The **[version tag](#valid-version-tags)** value that is checked.|
|*VersionValue*|Yes|The value to compare to. You can't specify a pattern.|
|*VersionValue*|Yes|The value to compare to. A pattern can't be specified.|
- **IsSystemContext**
@ -358,7 +358,7 @@ The **\<condition\>** functions return a Boolean value. You can use these elemen
|Setting|Required?|Value|
|--- |--- |--- |
|*ObjectType*|Yes|Defines the type of object. Can be File or Registry.|
|*EncodedLocationPattern*|Yes|The **[encoded location](#specifying-locations)** for the object that is examined. You can specify environment variables.|
|*EncodedLocationPattern*|Yes|The **[encoded location](#specifying-locations)** for the object that is examined. Environment variables can be specified.|
|StringContent|Yes|The string that is checked against.|
For example:
@ -376,7 +376,7 @@ The **\<condition\>** functions return a Boolean value. You can use these elemen
|Setting|Required?|Value|
|--- |--- |--- |
|*ObjectType*|Yes|Defines the type of object. Can be File or Registry.|
|*EncodedLocationPattern*|Yes|The **[encoded location](#specifying-locations)** for the object that is examined. You can specify environment variables.|
|*EncodedLocationPattern*|Yes|The **[encoded location](#specifying-locations)** for the object that is examined. Environment variables can be specified.|
|*StrToFind*|Yes|A string that is searched inside the content of the given object.|
- **IsSameObject**
@ -388,8 +388,8 @@ The **\<condition\>** functions return a Boolean value. You can use these elemen
|Setting|Required?|Value|
|--- |--- |--- |
|*ObjectType*|Yes|Defines the type of object. Can be File or Registry.|
|*EncodedLocation1*|Yes|The **[encoded location](#specifying-locations)** for the first object. You can specify environment variables.|
|*EncodedLocation2*|Yes|The **[encoded location](#specifying-locations)** for the second object. You can specify environment variables.|
|*EncodedLocation1*|Yes|The **[encoded location](#specifying-locations)** for the first object. Environment variables can be specified.|
|*EncodedLocation2*|Yes|The **[encoded location](#specifying-locations)** for the second object. Environment variables can be specified.|
For example:
@ -409,9 +409,9 @@ The **\<condition\>** functions return a Boolean value. You can use these elemen
|Setting|Required?|Value|
|--- |--- |--- |
|*ObjectType1*|Yes|Defines the type of the first object. Can be File or Registry.|
|*EncodedLocation1*|Yes|The **[encoded location](#specifying-locations)** for the first object. You can specify environment variables.|
|*EncodedLocation1*|Yes|The **[encoded location](#specifying-locations)** for the first object. Environment variables can be specified.|
|*ObjectType2*|Yes|Defines the type of the second object. Can be File or Registry.|
|*EncodedLocation2*|Yes|The **[encoded location](#specifying-locations)** for the second object. You can specify environment variables.|
|*EncodedLocation2*|Yes|The **[encoded location](#specifying-locations)** for the second object. Environment variables can be specified.|
- **IsSameStringContent**
@ -422,9 +422,9 @@ The **\<condition\>** functions return a Boolean value. You can use these elemen
|Setting|Required?|Value|
|--- |--- |--- |
|*ObjectType1*|Yes|Defines the type of the first object. Can be File or Registry.|
|*EncodedLocation1*|Yes|The **[encoded location](#specifying-locations)** for the first object. You can specify environment variables.|
|*EncodedLocation1*|Yes|The **[encoded location](#specifying-locations)** for the first object. Environment variables can be specified.|
|*ObjectType2*|Yes|Defines the type of the second object. Can be File or Registry.|
|*EncodedLocation2*|Yes|The **[encoded location](#specifying-locations)** for the second object. You can specify environment variables.|
|*EncodedLocation2*|Yes|The **[encoded location](#specifying-locations)** for the second object. Environment variables can be specified.|
## \<conditions\>
@ -462,7 +462,7 @@ The following example is from the `MigApp.xml` file:
## \<content\>
You can use the **\<content\>** element to specify a list of object patterns to obtain an object set from the source computer. Each **\<objectSet\>** within a **\<content\>** element is evaluated. For each resulting object pattern list, the objects that match it are enumerated and their content is filtered by the filter parameter. The resulting string array is the output for the **\<content\>** element. The filter script returns an array of locations. The parent **\<objectSet\>** element can contain multiple child **\<content\>** elements.
The **\<content\>** element can be used to specify a list of object patterns to obtain an object set from the source computer. Each **\<objectSet\>** within a **\<content\>** element is evaluated. For each resulting object pattern list, the objects that match it are enumerated and their content is filtered by the filter parameter. The resulting string array is the output for the **\<content\>** element. The filter script returns an array of locations. The parent **\<objectSet\>** element can contain multiple child **\<content\>** elements.
- **Number of occurrences:** unlimited
@ -470,7 +470,7 @@ You can use the **\<content\>** element to specify a list of object patterns to
- **Child elements:** [\<objectSet\>](#objectset)
- **Helper functions:** You can use the following [\<content\> functions](#content-functions) with this element: `ExtractSingleFile`, `ExtractMultipleFiles`, and `ExtractDirectory`.
- **Helper functions:** The following [\<content\> functions](#content-functions) can be used with this element: `ExtractSingleFile`, `ExtractMultipleFiles`, and `ExtractDirectory`.
Syntax:
@ -481,7 +481,7 @@ Syntax:
|Setting|Required?|Value|
|--- |--- |--- |
|filter|Yes|A script followed by any number of string arguments that are separated by a comma and enclosed in parenthesis. For example, `MyScripts.AScript ("Arg1","Arg2")`. <br/>The script is called for each object that is enumerated by the object sets in the **\<include\>** rule. The filter script returns a Boolean value. If the return value is **TRUE**, the object is migrated. If it's **FALSE**, it isn't migrated.|
|filter|Yes|A script followed by any number of string arguments that are separated by a comma and enclosed in parenthesis. For example, `MyScripts.AScript ("Arg1","Arg2")`. <br>The script is called for each object that is enumerated by the object sets in the **\<include\>** rule. The filter script returns a Boolean value. If the return value is **TRUE**, the object is migrated. If it's **FALSE**, it isn't migrated.|
### \<content\> functions
@ -495,8 +495,8 @@ The following functions generate patterns out of the content of an object. These
|Setting|Required?|Value|
|--- |--- |--- |
|*Separators*|Yes|A list of possible separators that might follow the file specification in this registry value name. For example, if the content is **"C:\Windows\Notepad.exe,-2"**, the separator is a comma. You can specify **NULL**.|
|*PathHints*|Yes|A list of extra paths, separated by colons (`;`), where the function looks for a file matching the current content. For example, if the content is **"Notepad.exe"** and the path is the **%Path%** environment variable, the function finds **Notepad.exe** in `%windir%` and returns **"c:\Windows [Notepad.exe]"**. You can specify **NULL**.|
|*Separators*|Yes|A list of possible separators that might follow the file specification in this registry value name. For example, if the content is **"C:\Windows\Notepad.exe,-2"**, the separator is a comma. **NULL** can be specified.|
|*PathHints*|Yes|A list of extra paths, separated by colons (`;`), where the function looks for a file matching the current content. For example, if the content is **"Notepad.exe"** and the path is the **%Path%** environment variable, the function finds **Notepad.exe** in `%windir%` and returns **"c:\Windows [Notepad.exe]"**. **NULL** can be specified.|
For example:
@ -521,7 +521,7 @@ The following functions generate patterns out of the content of an object. These
|Setting|Required?|Value|
|--- |--- |--- |
|*Separators*|Yes|A list of possible separators that might follow the file specification in this registry value name. For example, if the content is **"C:\Windows\Notepad.exe,-2"**, the separator is a comma. This parameter must be NULL when processing **MULTI-SZ** registry values.|
|*PathHints*|Yes|A list of extra paths, separated by colons (`;`), where the function looks for a file matching the current content. For example, if the content is **"Notepad.exe"** and the path is the **%Path%** environment variable, the function finds **Notepad.exe** in `%windir%` and returns **"c:\Windows [Notepad.exe]"**. You can specify **NULL**.|
|*PathHints*|Yes|A list of extra paths, separated by colons (`;`), where the function looks for a file matching the current content. For example, if the content is **"Notepad.exe"** and the path is the **%Path%** environment variable, the function finds **Notepad.exe** in `%windir%` and returns **"c:\Windows [Notepad.exe]"**. **NULL** can be specified.|
- **ExtractDirectory**
@ -531,8 +531,8 @@ The following functions generate patterns out of the content of an object. These
|Setting|Required?|Value|
|--- |--- |--- |
|*Separators*|No|A list of possible separators that might follow the file specification in this registry value name. For example, if the content is **"C:\Windows\Notepad.exe,-2"**, the separator is a comma. You must specify **NULL** when processing **MULTI-SZ** registry values.|
|*LevelsToTrim*|Yes|The number of levels to delete from the end of the directory specification. Use this function to extract a root directory when you have a registry value that points inside that root directory in a known location.|
|*Separators*|No|A list of possible separators that might follow the file specification in this registry value name. For example, if the content is **"C:\Windows\Notepad.exe,-2"**, the separator is a comma. **NULL** must be specified when processing **MULTI-SZ** registry values.|
|*LevelsToTrim*|Yes|The number of levels to delete from the end of the directory specification. Use this function to extract a root directory when there's a registry value that points inside that root directory in a known location.|
|*PatternSuffix*|Yes|The pattern to add to the directory specification. For example, `* [*]`.|
For example:
@ -557,7 +557,7 @@ The **\<contentModify\>** element modifies the content of an object before the o
- **Required child elements:** [\<objectSet\>](#objectset)
- **Helper functions**: You can use the following [\<contentModify\> functions](#contentmodify-functions) with this element: **ConvertToDWORD**, **ConvertToString**, **ConvertToBinary**, **KeepExisting**, **OffsetValue**, **SetValueByTable**, **MergeMultiSzContent**, and **MergeDelimitedContent**.
- **Helper functions**: The following [\<contentModify\> functions](#contentmodify-functions) can be used with this element: **ConvertToDWORD**, **ConvertToString**, **ConvertToBinary**, **KeepExisting**, **OffsetValue**, **SetValueByTable**, **MergeMultiSzContent**, and **MergeDelimitedContent**.
Syntax:
@ -568,7 +568,7 @@ Syntax:
|Setting|Required?|Value|
|--- |--- |--- |
|script|Yes|A script followed by any number of string arguments that are separated by a comma and enclosed in parenthesis. For example, `MyScripts.AScript ("Arg1","Arg2").` <br/><br/>The script is called for each object that is enumerated by the object sets in the include rule. The filter script returns a Boolean value. If the return value is **TRUE**, the object is migrated. If it's **FALSE**, it isn't migrated.|
|script|Yes|A script followed by any number of string arguments that are separated by a comma and enclosed in parenthesis. For example, `MyScripts.AScript ("Arg1","Arg2").` <br><br>The script is called for each object that is enumerated by the object sets in the include rule. The filter script returns a Boolean value. If the return value is **TRUE**, the object is migrated. If it's **FALSE**, it isn't migrated.|
### \<contentModify\> functions
@ -582,7 +582,7 @@ The following functions change the content of objects as they're migrated. These
|Setting|Required?|Value|
|--- |--- |--- |
|*DefaultValueOnError*|No|The value that is written into the value name if the conversion fails. You can specify **NULL**, and `0` is written if the conversion fails.|
|*DefaultValueOnError*|No|The value that is written into the value name if the conversion fails. **NULL** can be specified, and `0` is written if the conversion fails.|
- **ConvertToString**
@ -592,7 +592,7 @@ The following functions change the content of objects as they're migrated. These
|Setting|Required?|Value|
|--- |--- |--- |
|*DefaultValueOnError*|No|The value that is written into the value name if the conversion fails. You can specify **NULL**, and `0` is written if the conversion fails.|
|*DefaultValueOnError*|No|The value that is written into the value name if the conversion fails. **NULL** can be specified, and `0` is written if the conversion fails.|
For example:
@ -634,13 +634,13 @@ The following functions change the content of objects as they're migrated. These
- **KeepExisting**
You can use the **KeepExisting** function when there are conflicts on the destination computer. This function keeps (not overwrites) the specified attributes for the object that is on the destination computer.
The **KeepExisting** function can be used when there are conflicts on the destination computer. This function keeps (not overwrites) the specified attributes for the object that is on the destination computer.
Syntax: `KeepExisting("OptionString","OptionString","OptionString",…)`
|Setting|Required?|Value|
|--- |--- |--- |
| *OptionString* | Yes | *OptionString* can be **Security**, **TimeFields**, or **FileAttrib**:*Letter*. You can specify one of each type of *OptionStrings*. Don't specify multiple *OptionStrings* with the same value. If you do, the right-most option of that type is kept. For example, don't specify **("FileAttrib:H", "FileAttrib:R")** because only Read-only is evaluated. Instead specify **("FileAttrib:HR")** and both Hidden and Read-only attributes are kept on the destination computer. <ul><li>**Security**: Keeps the destination object's security descriptor if it exists.</li><li>**TimeFields**: Keeps the destination object's time stamps. This parameter is for files only.</li><li>**FileAttrib:\<Letter\>**: Keeps the destination object's attribute value, either **ON** or **OFF**, for the specified set of file attributes. This parameter is for files only. The following are case-insensitive, but USMT will ignore any values that are invalid, repeated, or if there's a space after **FileAttrib:**. You can specify any combination of the following attributes: <ul><li>**A** = Archive</li><li>**C** = Compressed</li><li>**E** = Encrypted</li><li>**H** = Hidden</li><li>**I** = Not Content Indexed</li><li>**O** = Offline</li><li>**R** = Read-Only</li><li>**S** = System</li><li>**T** = Temporary</li></ul></li></ul> |
| *OptionString* | Yes | *OptionString* can be **Security**, **TimeFields**, or **FileAttrib**:*Letter*. One of each type of *OptionStrings* can be specified. Don't specify multiple *OptionStrings* with the same value. If multiple *OptionStrings* with the same value are specified, the right-most option of that type is kept. For example, don't specify **("FileAttrib:H", "FileAttrib:R")** because only Read-only is evaluated. Instead specify **("FileAttrib:HR")** and both Hidden and Read-only attributes are kept on the destination computer. <ul><li>**Security**: Keeps the destination object's security descriptor if it exists.</li><li>**TimeFields**: Keeps the destination object's time stamps. This parameter is for files only.</li><li>**FileAttrib:\<Letter\>**: Keeps the destination object's attribute value, either **ON** or **OFF**, for the specified set of file attributes. This parameter is for files only. The following are case-insensitive, but USMT will ignore any values that are invalid, repeated, or if there's a space after **FileAttrib:**. Any combination of the following attributes can be specified: <ul><li>**A** = Archive</li><li>**C** = Compressed</li><li>**E** = Encrypted</li><li>**H** = Hidden</li><li>**I** = Not Content Indexed</li><li>**O** = Offline</li><li>**R** = Read-Only</li><li>**S** = System</li><li>**T** = Temporary</li></ul></li></ul> |
- **MergeMultiSzContent**
@ -661,7 +661,7 @@ The following functions change the content of objects as they're migrated. These
|Setting|Required?|Value|
|--- |--- |--- |
| *Delimiters* | Yes | A single character that is used to separate the content of the object that is being processed. The content is considered as a list of elements that is separated by the *Delimiters*. <br/>For example, `"."` separates the string based on a period. |
| *Delimiters* | Yes | A single character that is used to separate the content of the object that is being processed. The content is considered as a list of elements that is separated by the *Delimiters*. <br>For example, `"."` separates the string based on a period. |
| *Instruction* | Yes | Can be one of the following values: <ul><li>**Add**: Adds *String* to the resulting MULTI-SZ if it isn't already there.</li><li>**Remove**: Removes *String* from the resulting MULTI-SZ.</li></ul> |
| *String* | Yes | The string to be added or removed. |
@ -698,7 +698,7 @@ The **\<destinationCleanup\>** element deletes objects, such as files and regist
> [!IMPORTANT]
> Use this option with extreme caution because it will delete objects from the destination computer.
For each **\<destinationCleanup\>** element, there can be multiple **\<objectSet\>** elements. A common use for this element is if there's a missing registry key on the source computer and you want to ensure that a component is migrated. In this case, you can delete all of the component's registry keys before migrating the source registry keys. Deleting all of the component's registry keys ensures that if there's a missing key on the source computer, it will also be missing on the destination computer.
For each **\<destinationCleanup\>** element, there can be multiple **\<objectSet\>** elements. A common use for this element is if there's a missing registry key on the source computer but the component still needs to be migrated. In this case, all of the component's registry keys can be deleted before migrating the source registry keys. Deleting all of the component's registry keys ensures that if there's a missing key on the source computer, it will also be missing on the destination computer.
- **Number of occurrences:** Unlimited
@ -715,7 +715,7 @@ Syntax:
|Setting|Required?|Value|
|--- |--- |--- |
|filter|Yes|A script followed by any number of string arguments that are separated by a comma and enclosed in parenthesis. For example, `MyScripts.AScript ("Arg1","Arg2")`. <br/><br/>The script is called for each object that is enumerated by the object sets in the include rule. The filter script returns a Boolean value. If the return value is **TRUE**, the object is migrated. If it's **FALSE**, it isn't migrated.|
|filter|Yes|A script followed by any number of string arguments that are separated by a comma and enclosed in parenthesis. For example, `MyScripts.AScript ("Arg1","Arg2")`. <br><br>The script is called for each object that is enumerated by the object sets in the include rule. The filter script returns a Boolean value. If the return value is **TRUE**, the object is migrated. If it's **FALSE**, it isn't migrated.|
For example:
@ -734,7 +734,7 @@ Although the **\<detect\>** element is still supported, Microsoft recommends no
The **\<detect\>** element can be used to determine if the component is present on a system. If all child **\<detect\>** elements within a **\<detect\>** element resolve to **TRUE**, then the **\<detect\>** element resolves to **TRUE**. If any child **\<detect\>** elements resolve to **FALSE**, then their parent **\<detect\>** element resolves to **FALSE**. If there's no **\<detect\>** element section, then USMT assumes that the component is present.
For each **\<detect\>** element there can be multiple child **\<condition\>** or **\<objectSet\>** elements, which are logically joined by an **OR** operator. If at least one **\<condition\>** or **\<objectSet\>** element evaluates to **TRUE**, then the **\<detect\>** element evaluates to **TRUE**.
For each **\<detect\>** element there can be multiple children **\<condition\>** or **\<objectSet\>** elements, which are logically joined by an **OR** operator. If at least one **\<condition\>** or **\<objectSet\>** element evaluates to **TRUE**, then the **\<detect\>** element evaluates to **TRUE**.
- **Number of occurrences:** unlimited
@ -753,8 +753,8 @@ Syntax:
|Setting|Required?|Value|
|--- |--- |--- |
| name | Yes, when **\<detect\>** is a child to **\<namedElements\>** <br/>No, when **\<detect\>** is a child to \<detects\> | When *ID* is specified, any child elements aren't processed. Instead, any other **\<detect\>** elements with the same name that are declared within the **\<namedElements\>** element are processed. |
| context | No <br/>(default = UserAndSystem) | Defines the scope of this parameter, which is whether to process this component in the context of the specific user, across the entire operating system, or both. <br/>The largest possible scope is set by the component element. For example, if a **\<component\>** element has a context of **User**, and a **\<rules\>** element had a context of **UserAndSystem**, then the **\<rules\>** element would act as though it had a context of **User**. If the **\<rules\>** element had a context of **System**, it would act as though the **\<rules\>** element weren't there. <ul><li>**User**: Evaluates the variables for each user.</li><li>**System**: Evaluates the variables only once for the system.</li><li>**UserAndSystem**: Evaluates the variables for the entire operating system and each user.</li></ul> |
| name | Yes, when **\<detect\>** is a child to **\<namedElements\>** <br>No, when **\<detect\>** is a child to \<detects\> | When *ID* is specified, any child elements aren't processed. Instead, any other **\<detect\>** elements with the same name that are declared within the **\<namedElements\>** element are processed. |
| context | No <br>(default = UserAndSystem) | Defines the scope of this parameter, which is whether to process this component in the context of the specific user, across the entire operating system, or both. <br>The largest possible scope is set by the component element. For example, if a **\<component\>** element has a context of **User**, and a **\<rules\>** element had a context of **UserAndSystem**, then the **\<rules\>** element would act as though it had a context of **User**. If the **\<rules\>** element had a context of **System**, it would act as though the **\<rules\>** element weren't there. <ul><li>**User**: Evaluates the variables for each user.</li><li>**System**: Evaluates the variables only once for the system.</li><li>**UserAndSystem**: Evaluates the variables for the entire operating system and each user.</li></ul> |
For examples, see the examples for [\<detection\>](#detection).
@ -762,7 +762,7 @@ For examples, see the examples for [\<detection\>](#detection).
Although the **\<detects\>** element is still supported, Microsoft recommends no longer using the **\<detects\>** element because it might be deprecated in future versions of USMT. If the **\<detects\>** element is deprecated, it would require a rewrite of any scripts that use the **\<detects\>** element. Instead, Microsoft recommends using the **[\<detection\>](#detection)** element if the parent element is **\<role\>** or **\<namedElements\>**, or use the **[\<conditions\>](#conditions)** element if the parent element is **\<rules\>**. The **\<detection\>** element allows for more clearly formulated complex Boolean statements and the **\<conditions\>** element allows for formulation of complex Boolean statements.
The **\<detects\>** element is a container for one or more **\<detect\>** elements. If all of the child **\<detect\>** elements within a **\<detects\>** element resolve to **TRUE**, then **\<detects\>** resolves to **TRUE**. If any of the child **\<detect\>** elements resolve to **FALSE**, then **\<detects\>** resolves to **FALSE**. If you don't want to write the **\<detects\>** elements within a component, then you can create the **\<detects\>** element under the **\<namedElements\>** element, and then refer to it. If there's no **\<detects\>** element section, then USMT assumes that the component is present. The results from each **\<detects\>** element are joined together by the **OR** operator to form the rule used to detect the parent element.
The **\<detects\>** element is a container for one or more **\<detect\>** elements. If all of the child **\<detect\>** elements within a **\<detects\>** element resolve to **TRUE**, then **\<detects\>** resolves to **TRUE**. If any of the child **\<detect\>** elements resolve to **FALSE**, then **\<detects\>** resolves to **FALSE**. To prevent the **\<detects\>** element to be written within a component, create the **\<detects\>** element under the **\<namedElements\>** element, and then refer to it. If there's no **\<detects\>** element section, then USMT assumes that the component is present. The results from each **\<detects\>** element are joined together by the **OR** operator to form the rule used to detect the parent element.
Syntax:
@ -779,8 +779,8 @@ Syntax:
|Setting|Required?|Value|
|--- |--- |--- |
| name | Yes, when \<detects\> is a child to **\<namedElements\>** <br/>No, when \<detects\> is a child to **\<role\>** or **\<rules\>** | When *ID* is specified, no child **\<detect\>** elements are processed. Instead, any other **\<detects\>** elements with the same name that are declared within the **\<namedElements\>** element are processed. |
| context | No <br/>(default = UserAndSystem) | Defines the scope of this parameter: whether to process this component in the context of the specific user, across the entire operating system, or both. <br/>The largest possible scope is set by the **\<component element\>**. For example, if a **\<component\>** element has a context of **User** and a **\<rules\>** element had a context of **UserAndSystem**, then the **\<rules\>** element would act as though it had a context of **User**. If the **\<rules\>** element had a context of **System**, it would act as though the **\<rules\>** element weren't there. <ul><li>**User**: Evaluates the variables for each user.</li><li>**System**: Evaluates the variables only once for the system.</li><li>**UserAndSystem**: Evaluates the variables for the entire operating system and each user.</li></ul> <br/>The context parameter is ignored for **\<detects\>** elements that are inside **\<rules\>** elements. |
| name | Yes, when \<detects\> is a child to **\<namedElements\>** <br>No, when \<detects\> is a child to **\<role\>** or **\<rules\>** | When *ID* is specified, no child **\<detect\>** elements are processed. Instead, any other **\<detects\>** elements with the same name that are declared within the **\<namedElements\>** element are processed. |
| context | No <br>(default = UserAndSystem) | Defines the scope of this parameter: whether to process this component in the context of the specific user, across the entire operating system, or both. <br>The largest possible scope is set by the **\<component element\>**. For example, if a **\<component\>** element has a context of **User** and a **\<rules\>** element had a context of **UserAndSystem**, then the **\<rules\>** element would act as though it had a context of **User**. If the **\<rules\>** element had a context of **System**, it would act as though the **\<rules\>** element weren't there. <ul><li>**User**: Evaluates the variables for each user.</li><li>**System**: Evaluates the variables only once for the system.</li><li>**UserAndSystem**: Evaluates the variables for the entire operating system and each user.</li></ul> <br>The context parameter is ignored for **\<detects\>** elements that are inside **\<rules\>** elements. |
The following example is from the `MigApp.xml` file.
@ -799,9 +799,9 @@ The following example is from the `MigApp.xml` file.
The **\<detection\>** element is a container for one **\<conditions\>** element. The result of the child **\<condition\>** elements, located underneath the **\<conditions\>** element, determines the result of this element. For example, if all of the child **\<conditions\>** elements within the **\<detection\>** element resolve to **TRUE**, then the **\<detection\>** element resolves to **TRUE**. If any of the child **\<conditions\>** elements resolve to **FALSE**, then the **\<detection\>** element resolves to **FALSE**.
In addition, the results from each **\<detection\>** section within the **\<role\>** element are joined together by the **OR** operator to form the detection rule of the parent element. That is, if one of the **\<detection\>** sections resolves to **TRUE**, then the **\<role\>** element is processed. Otherwise, the **\<role\>** element isn't processed.
In addition, the results from each **\<detection\>** section within the **\<role\>** element are joined together by the **OR** operator to form the detection rule of the parent element. That is, if one of the **\<detection\>** sections resolve to **TRUE**, then the **\<role\>** element is processed. Otherwise, the **\<role\>** element isn't processed.
Use the **\<detection\>** element under the **\<namedElements\>** element if you don't want to write it within a component. Then include a matching **\<detection\>** section under the **\<role\>** element to control whether the component is migrated. If there isn't a **\<detection\>** section for a component, then USMT assumes that the component is present.
Use the **\<detection\>** element under the **\<namedElements\>** element to not write within a component. Then include a matching **\<detection\>** section under the **\<role\>** element to control whether the component is migrated. If there isn't a **\<detection\>** section for a component, then USMT assumes that the component is present.
- **Number of occurrences:** Unlimited.
@ -873,7 +873,7 @@ For example:
## \<environment\>
The **\<environment\>** element is a container for **\<variable\>** elements in which you can define variables to use in your .xml file. All environment variables defined this way are private. That is, they're available only for their child components and the component in which they were defined. For two example scenarios, see [Examples](#examples).
The **\<environment\>** element is a container for **\<variable\>** elements in which variables can be defined for use in an **.xml** file. All environment variables defined this way are private. That is, they're available only for their child components and the component in which they were defined. For two example scenarios, see [Examples](#examples).
- **Number of occurrences:** unlimited
@ -892,14 +892,14 @@ Syntax:
|Setting|Required?|Value|
|--- |--- |--- |
| name | Yes, when **\<environment\>** is a child of **\<namedElements\>** <br/>No, when **\<environment\>** is a child of **\<role\>** or **\<component\>** | When declared as a child of the **\<role\>** or **\<component\>** elements, if *ID* is declared, USMT ignores the content of the **\<environment\>** element and the content of the **\<environment\>** element with the same name declared in the **\<namedElements\>** element is processed. |
| context | No <br/>(default = UserAndSystem) | Defines the scope of this parameter: whether to process this component in the context of the specific user, across the entire operating system, or both. <br/>The largest possible scope is set by the **\<component\>** element. For example, if a **\<component\>** element has a context of **User** and a **\<rules\>** element had a context of **UserAndSystem**, then the **\<rules\>** element would act as though it had a context of **User**. If the **\<rules\>** element had a context of **System**, it would act as though **\<rules\>** weren't there. <ul><li>**User**: Evaluates the variables for each user.</li><li>**System**: Evaluates the variables only once for the system.</li><li>**UserAndSystem**: Evaluates the variables for the entire operating system and each user.</li></ul> |
| name | Yes, when **\<environment\>** is a child of **\<namedElements\>** <br>No, when **\<environment\>** is a child of **\<role\>** or **\<component\>** | When declared as a child of the **\<role\>** or **\<component\>** elements, if *ID* is declared, USMT ignores the content of the **\<environment\>** element and the content of the **\<environment\>** element with the same name declared in the **\<namedElements\>** element is processed. |
| context | No <br>(default = UserAndSystem) | Defines the scope of this parameter: whether to process this component in the context of the specific user, across the entire operating system, or both. <br>The largest possible scope is set by the **\<component\>** element. For example, if a **\<component\>** element has a context of **User** and a **\<rules\>** element had a context of **UserAndSystem**, then the **\<rules\>** element would act as though it had a context of **User**. If the **\<rules\>** element had a context of **System**, it would act as though **\<rules\>** weren't there. <ul><li>**User**: Evaluates the variables for each user.</li><li>**System**: Evaluates the variables only once for the system.</li><li>**UserAndSystem**: Evaluates the variables for the entire operating system and each user.</li></ul> |
## Examples
### Example scenario 1
In this scenario, you want to generate the location of objects at run time depending on the configuration of the destination computer. For example, if an application writes data in the directory where the application is installed, and users can install the application anywhere on the computer. If the application writes a registry value `hklm\software\companyname\install [path\]` and then updates this value with the location where the application is installed, then the only way for you to migrate the required data correctly is to define an environment variable. For example:
In this scenario, generate the location of objects at run time depending on the configuration of the destination computer. For example, if an application writes data in the directory where the application is installed, and users can install the application anywhere on the computer. If the application writes a registry value `hklm\software\companyname\install [path\]` and then updates this value with the location where the application is installed, then the only way to migrate the required data correctly is to define an environment variable. For example:
```xml
<environment>
@ -909,7 +909,7 @@ In this scenario, you want to generate the location of objects at run time depen
</environment>
```
Then you can use an include rule as follows. You can use any of the [\<script\> functions](#script-functions) to perform similar tasks.
Then an include rule can be used as follows. Any of the [\<script\> functions](#script-functions) can be used to perform similar tasks.
```xml
<include>
@ -919,7 +919,7 @@ Then you can use an include rule as follows. You can use any of the [\<script\>
</include>
```
Second, you can also filter registry values that contain data that you need. The following example extracts the first string (before the separator "`,`") in the value of the registry `Hklm\software\companyname\application\ [Path\]`.
Second, registry values can be filtered to contain the data that is needed. The following example extracts the first string (before the separator "`,`") in the value of the registry `Hklm\software\companyname\application\ [Path\]`.
```xml
<environment>
@ -937,7 +937,7 @@ Second, you can also filter registry values that contain data that you need. The
### Example scenario 2
In this scenario, you want to migrate five files named `File1.txt`, `File2.txt`, and so on, from `%SYSTEMDRIVE%\data\userdata\dir1\dir2\`. To migrate these files, you must have the following **\<include\>** rule in an .xml file:
In this scenario, five files named `File1.txt`, `File2.txt`, and so on, need to be migrated from `%SYSTEMDRIVE%\data\userdata\dir1\dir2\`. To migrate these files, the following **\<include\>** rule must be in an **.xml** file:
```xml
<include>
@ -951,7 +951,7 @@ In this scenario, you want to migrate five files named `File1.txt`, `File2.txt`,
</include>
```
Instead of typing the path five times, you can create a variable for the location as follows:
Instead of typing the path five times, create a variable for the location as follows:
```xml
<environment>
@ -961,7 +961,7 @@ Instead of typing the path five times, you can create a variable for the locatio
</environment>
```
Then, you can specify the variable in an **\<include\>** rule as follows:
Then, specify the variable in an **\<include\>** rule as follows:
```xml
<include>
@ -985,7 +985,7 @@ The **\<exclude\>** element determines what objects aren't migrated, unless ther
- **Child elements:** [\<objectSet\>](#objectset)
- **Helper functions:** You can use the following [\<exclude\> filter functions](#include-and-exclude-filter-functions) with this element: `CompareStringContent`, `IgnoreIrrelevantLinks`, `AnswerNo`, `NeverRestore`, and `SameRegContent`.
- **Helper functions:** The following [\<exclude\> filter functions](#include-and-exclude-filter-functions) can be used with this element: `CompareStringContent`, `IgnoreIrrelevantLinks`, `AnswerNo`, `NeverRestore`, and `SameRegContent`.
Syntax:
@ -996,7 +996,7 @@ Syntax:
|Setting|Required?|Value|
|--- |--- |--- |
|filter|No <br/>(default = No)|A script followed by any number of string arguments that are separated by a comma and enclosed in parenthesis. For example, `MyScripts.AScript ("Arg1","Arg2")`. <br/><br/>The script is called for each object that is enumerated by the object sets in the include rule. The filter script returns a Boolean value. If the return value is **TRUE**, the object is migrated. If it's **FALSE**, it isn't migrated.|
|filter|No <br>(default = No)|A script followed by any number of string arguments that are separated by a comma and enclosed in parenthesis. For example, `MyScripts.AScript ("Arg1","Arg2")`. <br><br>The script is called for each object that is enumerated by the object sets in the include rule. The filter script returns a Boolean value. If the return value is **TRUE**, the object is migrated. If it's **FALSE**, it isn't migrated.|
For example, from the `MigUser.xml` file:
@ -1012,7 +1012,7 @@ For example, from the `MigUser.xml` file:
## \<excludeAttributes\>
You can use the **\<excludeAttributes\>** element to determine which parameters associated with an object aren't migrated. If there are conflicts between the **\<includeAttributes\>** and **\<excludeAttributes\>** elements, the most specific pattern determines the patterns that aren't migrated. If an object doesn't have an **\<includeAttributes\>** or **\<excludeAttributes\>** element, then all of its parameters are migrated.
The **\<excludeAttributes\>** element can be used to determine which parameters associated with an object aren't migrated. If there are conflicts between the **\<includeAttributes\>** and **\<excludeAttributes\>** elements, the most specific pattern determines the patterns that aren't migrated. If an object doesn't have an **\<includeAttributes\>** or **\<excludeAttributes\>** element, then all of its parameters are migrated.
- **Number of occurrences:** Unlimited
@ -1029,7 +1029,7 @@ Syntax:
|Setting|Required?|Value|
|--- |--- |--- |
| attributes | Yes | Specifies the attributes to be excluded. You can specify one of the following, or both separated by quotes; for example, `"Security","TimeFields"`: <ul><li>Security can be one of Owner, Group, DACL, or SACL.</li><li>TimeFields can be one of CreationTime, LastAccessTime and LastWrittenTime</li></ul> |
| attributes | Yes | Specifies the attributes to be excluded. Either one of the following or both can be specified. If specifying both, they need to be separated by quotes. For example, `"Security","TimeFields"`: <ul><li>Security can be one of Owner, Group, DACL, or SACL.</li><li>TimeFields can be one of CreationTime, LastAccessTime and LastWrittenTime</li></ul> |
Example:
@ -1101,7 +1101,7 @@ Syntax:
## \<extension\>
You can use the \<extension\> element to specify documents of a specific extension.
The \<extension\> element can be used to specify documents of a specific extension.
- **Number of occurrences:** unlimited
@ -1119,7 +1119,7 @@ Syntax:
|--- |--- |--- |
|*FilenameExtension*|Yes|A file name extension.|
For example, if you want to migrate all \*.doc files from the source computer, specifying the following code under the **\<component\>** element:
For example, to migrate all \*.doc files from the source computer, specifying the following code under the **\<component\>** element:
```xml
<extensions>
@ -1141,7 +1141,7 @@ For another example of how to use the \<extension\> element, see the example for
## \<externalProcess\>
You can use the \<externalProcess\> element to run a command line during the migration process. For example, you might want to run a command after the **LoadState** process completes.
The \<externalProcess\> element can be used to run a command line during the migration process. For example, a run a command might need to run after the **LoadState** process completes.
- **Number of occurrences:** Unlimited
@ -1168,7 +1168,7 @@ This element is an internal USMT element. Don't use this element.
## \<include\>
The **\<include\>** element determines what to migrate, unless there's a more specific [\<exclude\>](#exclude) rule. You can specify a script to be more specific to extend the definition of what you want to collect. For each **\<include\>** element, there can be multiple **\<objectSet\>** elements.
The **\<include\>** element determines what to migrate, unless there's a more specific [\<exclude\>](#exclude) rule. A script can be specified to be more specific to extend the definition of what want needs to be collected. For each **\<include\>** element, there can be multiple **\<objectSet\>** elements.
- **Number of occurrences:** Unlimited
@ -1176,7 +1176,7 @@ The **\<include\>** element determines what to migrate, unless there's a more sp
- **Required child element:** [\<objectSet\>](#objectset)
- **Helper functions:** You can use the following [\<include\> filter functions](#include-and-exclude-filter-functions) with this element: `CompareStringContent`, `IgnoreIrrelevantLinks`, `AnswerNo`, and `NeverRestore`.
- **Helper functions:** The following [\<include\> filter functions](#include-and-exclude-filter-functions) can be used with this element: `CompareStringContent`, `IgnoreIrrelevantLinks`, `AnswerNo`, and `NeverRestore`.
Syntax:
@ -1187,7 +1187,7 @@ Syntax:
|Setting|Required?|Value|
|--- |--- |--- |
| filter | No. <br/>If this parameter isn't specified, then all patterns that are inside the child **\<objectSet\>** element are processed. | A script followed by any number of string arguments that are separated by a comma and enclosed in parenthesis. For example, `MyScripts.AScript ("Arg1","Arg2")`. <br/>The script is called for each object that is enumerated by the object sets in the **\<include\>** rule. The filter script returns a Boolean value. If the return value is **TRUE**, the object is migrated. If it's **FALSE**, it isn't migrated. |
| filter | No. <br>If this parameter isn't specified, then all patterns that are inside the child **\<objectSet\>** element are processed. | A script followed by any number of string arguments that are separated by a comma and enclosed in parenthesis. For example, `MyScripts.AScript ("Arg1","Arg2")`. <br>The script is called for each object that is enumerated by the object sets in the **\<include\>** rule. The filter script returns a Boolean value. If the return value is **TRUE**, the object is migrated. If it's **FALSE**, it isn't migrated. |
The following example is from the MigUser.xml file:
@ -1221,7 +1221,7 @@ The following example is from the MigUser.xml file:
### \<include\> and **\<exclude\>** filter functions
The following functions return a Boolean value. You can use them to migrate certain objects based on when certain conditions are met.
The following functions return a Boolean value. They can be used to migrate certain objects based on when certain conditions are met.
- **AnswerNo**
@ -1240,7 +1240,7 @@ The following functions return a Boolean value. You can use them to migrate cert
- **IgnoreIrrelevantLinks**
This filter screens out the .lnk files that point to an object that isn't valid on the destination computer. The screening takes place on the destination computer, so all .lnk files are saved to the store during **ScanState**. Then they're screened out when you run the **LoadState** tool.
This filter screens out the .lnk files that point to an object that isn't valid on the destination computer. The screening takes place on the destination computer, so all .lnk files are saved to the store during **ScanState**. Then they're screened out when the **LoadState** tool runs.
Syntax: `IgnoreIrrelevantLinks ()`
@ -1256,7 +1256,7 @@ The following functions return a Boolean value. You can use them to migrate cert
- **NeverRestore**
You can use this function to collect the specified objects from the source computer but then not migrate the objects to the destination computer. When run with the **ScanState** tool, this function evaluates to **TRUE**. When run with the **LoadState** tool, this function evaluates to **FALSE**. This function might be used to check an object's value on the destination computer but there's no intention to migrate the object to the destination.
This function can be used to collect the specified objects from the source computer but then not migrate the objects to the destination computer. When run with the **ScanState** tool, this function evaluates to **TRUE**. When run with the **LoadState** tool, this function evaluates to **FALSE**. This function might be used to check an object's value on the destination computer but there's no intention to migrate the object to the destination.
Syntax: `NeverRestore()`
@ -1272,7 +1272,7 @@ The following functions return a Boolean value. You can use them to migrate cert
## \<includeAttributes\>
You can use the **\<includeAttributes\>** element to determine whether certain parameters associated with an object are migrated along with the object itself. If there are conflicts between the **\<includeAttributes\>** and **\<excludeAttributes\>** elements, the most specific pattern determines which parameters are migrated. If an object doesn't have an **\<includeAttributes\>** or **\<excludeAttributes\>** element, then all of its parameters are migrated.
The **\<includeAttributes\>** element can be used to determine whether certain parameters associated with an object are migrated along with the object itself. If there are conflicts between the **\<includeAttributes\>** and **\<excludeAttributes\>** elements, the most specific pattern determines which parameters are migrated. If an object doesn't have an **\<includeAttributes\>** or **\<excludeAttributes\>** element, then all of its parameters are migrated.
- **Number of occurrences:** unlimited
@ -1289,7 +1289,7 @@ Syntax:
|Setting|Required?|Value|
|--- |--- |--- |
| attributes | Yes | Specifies the attributes to be included with a migrated object. You can specify one of the following, or both separated by quotes; for example, `"Security","TimeFields"`: <ul><li>Security can be one of the following values: <ul><li>**Owner**: The owner of the object (SID).</li><li>**Group**: The primary group for the object (SID).</li><li>**DACL** (discretionary access control list): An access control list that is controlled by the owner of an object and that specifies the access particular users or groups can have to the object.</li><li>**SACL** (system access control list): An ACL that controls the generation of audit messages for attempts to access a securable object. The ability to get or set an object&#39;s SACL is controlled by a privilege typically held only by system administrators.</li></ul></li><li>TimeFields can be one of the following values: <ul><li>**CreationTime**: Specifies when the file or directory was created.</li><li>**LastAccessTime**: Specifies when the file is last read from, written to, or for executable files, run.</li><li>**LastWrittenTime**: Specifies when the file is last written to, truncated, or overwritten.</li></ul></li></ul> |
| attributes | Yes | Specifies the attributes to be included with a migrated object. Either one of the following or both can be specified. If specifying both, they need to be separated by quotes. For example, `"Security","TimeFields"`: <ul><li>Security can be one of the following values: <ul><li>**Owner**: The owner of the object (SID).</li><li>**Group**: The primary group for the object (SID).</li><li>**DACL** (discretionary access control list): An access control list that is controlled by the owner of an object and that specifies the access particular users or groups can have to the object.</li><li>**SACL** (system access control list): An ACL that controls the generation of audit messages for attempts to access a securable object. The ability to get or set an object&#39;s SACL is controlled by a privilege typically held only by system administrators.</li></ul></li><li>TimeFields can be one of the following values: <ul><li>**CreationTime**: Specifies when the file or directory was created.</li><li>**LastAccessTime**: Specifies when the file is last read from, written to, or for executable files, run.</li><li>**LastWrittenTime**: Specifies when the file is last written to, truncated, or overwritten.</li></ul></li></ul> |
For an example of how to use the **\<includeAttributes\>** element, see the example for [\<excludeAttributes\>](#excludeattributes).
@ -1323,12 +1323,12 @@ The following example is from the `MigApp.xml` file:
```xml
<addObjects>
<object>
<location type="Registry">%HklmWowSoftware%\Microsoft\Office\12.0\Common\Migration\Office [UpgradeVersion]</location>
<location type="Registry">%HklmWowSoftware%\Microsoft\Office\16.0\Common\Migration\Office [UpgradeVersion]</location>
<attributes>DWORD</attributes>
<bytes>0B000000</bytes>
</object>
<object>
<location type="Registry">%HklmWowSoftware%\Microsoft\Office\12.0\Common\Migration\Office [Lang]</location>
<location type="Registry">%HklmWowSoftware%\Microsoft\Office\16.0\Common\Migration\Office [Lang]</location>
<attributes>DWORD</attributes>
<bytes>00000000</bytes>
</object>
@ -1337,7 +1337,7 @@ The following example is from the `MigApp.xml` file:
## \<locationModify\>
You can use the **\<locationModify\>** element to change the location and name of an object before the object is migrated to the destination computer. The **\<locationModify\>** element is processed only when the **LoadState** tool is run on the destination computer. In other words, this element is ignored by the **ScanState** tool. The **\<locationModify\>** element creates the appropriate folder on the destination computer if it doesn't already exist.
The **\<locationModify\>** element can be used to change the location and name of an object before the object is migrated to the destination computer. The **\<locationModify\>** element is processed only when the **LoadState** tool is run on the destination computer. In other words, this element is ignored by the **ScanState** tool. The **\<locationModify\>** element creates the appropriate folder on the destination computer if it doesn't already exist.
**Number of occurrences:** Unlimited
@ -1345,7 +1345,7 @@ You can use the **\<locationModify\>** element to change the location and name o
- **Required child element:** [\<objectSet\>](#objectset)
- **Helper functions:** You can use the following [\<locationModify\> functions](#locationmodify-functions) with this element: `ExactMove`, `RelativeMove`, and `Move`.
- **Helper functions:** The following [\<locationModify\> functions](#locationmodify-functions) can be used with this element: `ExactMove`, `RelativeMove`, and `Move`.
Syntax:
@ -1356,7 +1356,7 @@ Syntax:
|Setting|Required?|Value|
|--- |--- |--- |
|script|Yes|A script followed by any number of string arguments that are separated by a comma and enclosed in parenthesis. For example, `MyScripts.AScript ("Arg1","Arg2")`. <br/><br/>The script is called for each object that is enumerated by the object sets in the include rule. The filter script returns a Boolean value. If the return value is **TRUE**, the object is migrated. If it's **FALSE**, it isn't migrated.|
|script|Yes|A script followed by any number of string arguments that are separated by a comma and enclosed in parenthesis. For example, `MyScripts.AScript ("Arg1","Arg2")`. <br><br>The script is called for each object that is enumerated by the object sets in the include rule. The filter script returns a Boolean value. If the return value is **TRUE**, the object is migrated. If it's **FALSE**, it isn't migrated.|
The following example is from the `MigApp.xml` file:
@ -1374,7 +1374,7 @@ The following functions change the location of objects as they're migrated when
- **ExactMove**
The ExactMove function moves all of the objects that are matched by the parent **\<objectSet\>** element into the given *ObjectEncodedLocation*. You can use this function when you want to move a single file to a different location on the destination computer. If the destination location is a node, all of the matching source objects are written to the node without any subdirectories. If the destination location is a leaf, the migration engine migrates all of the matching source objects to the same location. If a collision occurs, the normal collision algorithms apply.
The ExactMove function moves all of the objects that are matched by the parent **\<objectSet\>** element into the given *ObjectEncodedLocation*. This function can be used to move a single file to a different location on the destination computer. If the destination location is a node, all of the matching source objects are written to the node without any subdirectories. If the destination location is a leaf, the migration engine migrates all of the matching source objects to the same location. If a collision occurs, the normal collision algorithms apply.
Syntax: `ExactMove(ObjectEncodedLocation)`
@ -1404,7 +1404,7 @@ The following functions change the location of objects as they're migrated when
- **RelativeMove**
You can use the RelativeMove function to collect and move data. Environment variables can be used in source and destination roots, but they might be defined differently on the source and destination computers.
The RelativeMove function can be used to collect and move data. Environment variables can be used in source and destination roots, but they might be defined differently on the source and destination computers.
Syntax: `RelativeMove(SourceRoot,DestinationRoot)`
@ -1454,7 +1454,7 @@ Syntax:
## \<merge\>
The **\<merge\>** element determines what happens when a collision occurs. A collision is when an object that is migrated is already present on the destination computer. If you don't specify this element, the default behavior for the registry is for the source object to overwrite the destination object. The default behavior for files is for the source file to be renamed to `OriginalFileName(1).OriginalExtension`. This element specifies only what should be done when a collision occurs. It doesn't include objects. Therefore, for your objects to migrate, you must specify **\<include\>** rules along with the **\<merge\>** element. When an object is processed and a collision is detected, USMT selects the most specific merge rule. It then applies the rule to resolve the conflict. For example, if you have a **\<merge\>** rule `C:\* [*]` set to **\<sourcePriority\>** and a **\<merge\>** rule `C:\subfolder\* [*]` set to **\<destinationPriority\>**, then USMT would use the **\<destinationPriority\>** rule because it's the more specific.
The **\<merge\>** element determines what happens when a collision occurs. A collision is when an object that is migrated is already present on the destination computer. If this element isn't specified, the default behavior for the registry is for the source object to overwrite the destination object. The default behavior for files is for the source file to be renamed to `OriginalFileName(1).OriginalExtension`. This element specifies only what should be done when a collision occurs. It doesn't include objects. Therefore, for the objects to migrate, **\<include\>** rules must be specified along with the **\<merge\>** element. When an object is processed and a collision is detected, USMT selects the most specific merge rule. It then applies the rule to resolve the conflict. For example, if a **\<merge\>** rule `C:\* [*]` is set to **\<sourcePriority\>** and a **\<merge\>** rule `C:\subfolder\* [*]` is set to **\<destinationPriority\>**, then USMT would use the **\<destinationPriority\>** rule because it's the more specific.
For an example of this element, see [Conflicts and precedence](usmt-conflicts-and-precedence.md).
@ -1464,7 +1464,7 @@ For an example of this element, see [Conflicts and precedence](usmt-conflicts-an
- **Required child element:** [\<objectSet\>](#objectset)
- **Helper functions:** You can use the following [\<merge\> functions](#merge-functions) with this element: `SourcePriority`, `DestinationPriority`, `FindFilePlaceByPattern`, `LeafPattern`, `NewestVersion`, `HigherValue()`, and `LowerValue()`.
- **Helper functions:** The following [\<merge\> functions](#merge-functions) can be used with this element: `SourcePriority`, `DestinationPriority`, `FindFilePlaceByPattern`, `LeafPattern`, `NewestVersion`, `HigherValue()`, and `LowerValue()`.
Syntax:
@ -1475,7 +1475,7 @@ Syntax:
|Setting|Required?|Value|
|--- |--- |--- |
|script|Yes|A script followed by any number of string arguments that are separated by a comma and enclosed in parenthesis. For example, `MyScripts.AScript ("Arg1","Arg2")`. <br/><br/>The script is called for each object that is enumerated by the object sets in the **\<include\>** rule. The filter script returns a Boolean value. If the return value is **TRUE**, the object is migrated. If it's **FALSE**, it isn't migrated.|
|script|Yes|A script followed by any number of string arguments that are separated by a comma and enclosed in parenthesis. For example, `MyScripts.AScript ("Arg1","Arg2")`. <br><br>The script is called for each object that is enumerated by the object sets in the **\<include\>** rule. The filter script returns a Boolean value. If the return value is **TRUE**, the object is migrated. If it's **FALSE**, it isn't migrated.|
The following example is from the MigUser.xml file:
@ -1522,7 +1522,7 @@ These functions control how collisions are resolved.
|Setting|Required?|Value|
|--- |--- |--- |
| *FilePattern* | Yes | <ul><li>**\<F\>** is replaced by the original file name.</li><li>**\<N\>** is replaced by an incrementing counter until there's no collision with the objects on the destination computer.</li><li>**\<E\>** is replaced by the original file name extension.</li></ul> <br/>For example, `<F> (<N>).<E>` changes the source file `MyDocument.doc` into `MyDocument (1).doc` on the destination computer. |
| *FilePattern* | Yes | <ul><li>**\<F\>** is replaced by the original file name.</li><li>**\<N\>** is replaced by an incrementing counter until there's no collision with the objects on the destination computer.</li><li>**\<E\>** is replaced by the original file name extension.</li></ul> <br>For example, `<F> (<N>).<E>` changes the source file `MyDocument.doc` into `MyDocument (1).doc` on the destination computer. |
- **NewestVersion**
@ -1536,11 +1536,11 @@ These functions control how collisions are resolved.
- **HigherValue()**
You can use this function for merging registry values. The registry values are evaluated as numeric values, and the one with the higher value determines which registry values are merged.
This function can be used for merging registry values. The registry values are evaluated as numeric values, and the one with the higher value determines which registry values are merged.
- **LowerValue()**
You can use this function for merging registry values. The registry values are evaluated as numeric values and the one with the lower value determines which registry values are merged.
This function can be used for merging registry values. The registry values are evaluated as numeric values and the one with the lower value determines which registry values are merged.
- **SourcePriority**
@ -1551,16 +1551,16 @@ These functions control how collisions are resolved.
```xml
<merge script="MigXmlHelper.SourcePriority()">
<objectSet>
<pattern type="Registry">%HklmWowSoftware%\Microsoft\Office\12.0\Common\Migration\Publisher [UpgradeVersion]</pattern>
<pattern type="Registry">%HklmWowSoftware%\Microsoft\Office\11.0\Common\Migration\Publisher [UpgradeVersion]</pattern>
<pattern type="Registry">%HklmWowSoftware%\Microsoft\Office\10.0\Common\Migration\Publisher [UpgradeVersion]</pattern>
<pattern type="Registry">%HklmWowSoftware%\Microsoft\Office\14.0\Common\Migration\Publisher [UpgradeVersion]</pattern>
<pattern type="Registry">%HklmWowSoftware%\Microsoft\Office\15.0\Common\Migration\Publisher [UpgradeVersion]</pattern>
<pattern type="Registry">%HklmWowSoftware%\Microsoft\Office\16.0\Common\Migration\Publisher [UpgradeVersion]</pattern>
</objectSet>
</merge>
```
## \<migration\>
The **\<migration\>** element is the single root element of a migration .xml file and is required. Each .xml file must have a unique migration urlid. The urlid of each file that you specify on the command line must be unique. The urlids must be unique because USMT uses the urlid to define the components within the file.
The **\<migration\>** element is the single root element of a migration **.xml** file and is required. Each **.xml** file must have a unique migration urlid. The urlid of each file that is specified on the command line must be unique. The urlids must be unique because USMT uses the urlid to define the components within the file.
- **Number of occurrences:** one
@ -1579,8 +1579,8 @@ Syntax:
|Setting|Required?|Value|
|--- |--- |--- |
|urlid|Yes|*UrlID* is a string identifier that uniquely identifies this .xml file. This parameter must be a no-colon-name as defined by the XML Namespaces specification. Each migration .xml file must have a unique urlid. If two migration .xml files have the same urlid, the second .xml file that is specified on the command line isn't processed. For more information about XML Namespaces, see [Use XML Namespaces](/previous-versions/windows/desktop/ms754539(v=vs.85)).|
|Name|No|Although not required, it's good practice to use the name of the .xml file.|
|urlid|Yes|*UrlID* is a string identifier that uniquely identifies this **.xml** file. This parameter must be a no-colon-name as defined by the XML Namespaces specification. Each migration **.xml** file must have a unique urlid. If two migration **.xml** files have the same urlid, the second **.xml** file that is specified on the command line isn't processed. For more information about XML Namespaces, see [Use XML Namespaces](/previous-versions/windows/desktop/ms754539(v=vs.85)).|
|Name|No|Although not required, it's good practice to use the name of the **.xml** file.|
The following example is from the `MigApp.xml` file:
@ -1597,7 +1597,7 @@ This filter helper function can be used to filter the migration of files based o
|--- |--- |
|Property|filesize, dateCreated, dateModified, dateAccessed|
|Operator|range, neq, lte, lt, eq, gte, gt|
|valueToCompare|The value that is being compared. For example: <br/>Date: "2008/05/15-2005/05/17", "2008/05/15" <br/>Size: A numeral with B, KB, MB, or GB at the end. "5GB", "1KB-1MB"|
|valueToCompare|The value that is being compared. For example: <br>Date: "2008/05/15-2005/05/17", "2008/05/15" <br>Size: A numeral with B, KB, MB, or GB at the end. "5GB", "1KB-1MB"|
```xml
<component context="System" type="Application">
@ -1617,7 +1617,7 @@ This filter helper function can be used to filter the migration of files based o
## \<namedElements\>
You can use the **\<namedElements\>** element to define named elements. You can use these elements in any component throughout your .xml file. For an example of how to use this element, see the `MigApp.xml` file.
The **\<namedElements\>** element can be used to define named elements. These elements can be used in any component throughout the **.xml** file. For an example of how to use this element, see the `MigApp.xml` file.
Syntax:
@ -1658,12 +1658,12 @@ The following example is from the `MigApp.xml` file:
```xml
<addObjects>
<object>
<location type="Registry">%HklmWowSoftware%\Microsoft\Office\12.0\Common\Migration\Office [UpgradeVersion]</location>
<location type="Registry">%HklmWowSoftware%\Microsoft\Office\16.0\Common\Migration\Office [UpgradeVersion]</location>
<attributes>DWORD</attributes>
<bytes>0B000000</bytes>
</object>
<object>
<location type="Registry">%HklmWowSoftware%\Microsoft\Office\12.0\Common\Migration\Office [Lang]</location>
<location type="Registry">%HklmWowSoftware%\Microsoft\Office\16.0\Common\Migration\Office [Lang]</location>
<attributes>DWORD</attributes>
<bytes>00000000</bytes>
</object>
@ -1729,7 +1729,7 @@ This element is an internal USMT element. Don't use this element.
## \<pattern\>
You can use this element to specify multiple objects. You can specify multiple **\<pattern\>** elements for each **\<objectSet\>** element and they're combined. If you're specifying files, you might want to use `GenerateDrivePatterns` with **\<script\>** instead. `GenerateDrivePatterns` is basically the same as a **\<pattern\>** rule, without the drive letter specification. For example, the following two lines of code are similar:
This element can be used to specify multiple objects. Multiple **\<pattern\>** elements can be used for each **\<objectSet\>** element and they're combined. If specifying files, Microsoft recommends using `GenerateDrivePatterns` with **\<script\>** instead. `GenerateDrivePatterns` is basically the same as a **\<pattern\>** rule, without the drive letter specification. For example, the following two lines of code are similar:
```xml
<pattern type="File">C:\Folder\* [Sample.doc]</pattern>
@ -1750,8 +1750,8 @@ Syntax:
|Setting|Required?|Value|
|--- |--- |--- |
| type | Yes | *typeID* can be Registry, File, or Ini. If *typeId* is Ini, then you can't have a space between *Path* and *object*. For example, the following format is correct when type="Ini": <br/>**\<pattern type="Ini"\>%WinAmp5InstPath%\Winamp.ini&#124;WinAmp[keeponscreen]\</pattern\>** |
| *Path* [*object*] | Yes | A valid registry or file path pattern, followed by at least one space, followed by brackets [] that contain the object to be migrated. <ul><li>*Path* can contain the asterisk (`*`) wildcard character or can be an [Recognized environment variables](usmt-recognized-environment-variables.md). You can't use the question mark as a wildcard character. You can use `HKCU` and `HKLM` to refer to `HKEY_CURRENT_USER` and `HKEY_LOCAL_MACHINE` respectively.</li><li>*Object* can contain the asterisk (`*`) wildcard character. However, you can't use the question mark as a wildcard character. For example: <br/> **`C:\Folder\ [*]`** enumerates all files in `C:\Folder` but no subfolders of `C:\Folder`. <br/> **`C:\Folder* [*]`** enumerates all files and subfolders of `C:\Folder`. <br/> **`C:\Folder\ [*.mp3]`** enumerates all `.mp3` files in `C:\Folder`. <br/> **`C:\Folder\ [Sample.doc]`** enumerates only the `Sample.doc` file located in C:\Folder. <div class="alert">**Note**<br/>If migrating a file that has a square bracket character ([ or ]) in the file name, a carrot (^) character must be inserted directly before the bracket for it to be valid. For example, if there's a file named "file].txt", you must specify `<pattern type="File">c:\documents\mydocs [file^].txt]</pattern>` instead of `<pattern type="File">c:\documents\mydocs [file].txt]</pattern>`.</div></li></ul> |
| type | Yes | *typeID* can be Registry, File, or Ini. If *typeId* is Ini, then a space between *Path* and *object* isn't allowed. For example, the following format is correct when type="Ini": <br>**\<pattern type="Ini"\>%WinAmp5InstPath%\Winamp.ini&#124;WinAmp[keeponscreen]\</pattern\>** |
| *Path* [*object*] | Yes | A valid registry or file path pattern, followed by at least one space, followed by brackets [] that contain the object to be migrated. <ul><li>*Path* can contain the asterisk (`*`) wildcard character or can be an [Recognized environment variables](usmt-recognized-environment-variables.md). The question mark can't be used as a wildcard character. `HKCU` and `HKLM` can be used to refer to `HKEY_CURRENT_USER` and `HKEY_LOCAL_MACHINE` respectively.</li><li>*Object* can contain the asterisk (`*`) wildcard character. However, the question mark can't be used as a wildcard character. For example: <br> **`C:\Folder\ [*]`** enumerates all files in `C:\Folder` but no subfolders of `C:\Folder`. <br> **`C:\Folder* [*]`** enumerates all files and subfolders of `C:\Folder`. <br> **`C:\Folder\ [*.mp3]`** enumerates all `.mp3` files in `C:\Folder`. <br> **`C:\Folder\ [Sample.doc]`** enumerates only the `Sample.doc` file located in C:\Folder. <div class="alert">**Note**<br>If migrating a file that has a square bracket character ([ or ]) in the file name, a carrot (^) character must be inserted directly before the bracket for it to be valid. For example, if there's a file named "file].txt", `<pattern type="File">c:\documents\mydocs [file^].txt]</pattern>` must be specified instead of `<pattern type="File">c:\documents\mydocs [file].txt]</pattern>`.</div></li></ul> |
For example:
@ -1787,7 +1787,7 @@ For example:
## \<processing\>
You can use this element to run a script during a specific point within the migration process. Return values aren't expected from the scripts that you specify, and if there are return values, they're ignored.
This element can be used to run a script during a specific point within the migration process. Return values aren't expected from the scripts that are specified. If there are return values, they're ignored.
- **Number of occurrences:** unlimited
@ -1812,7 +1812,7 @@ This element is an internal USMT element. Don't use this element.
## \<role\>
The **\<role\>** element is required in a custom .xml file. By specifying the **\<role\>** element, you can create a concrete component. The component is defined by the parameters specified at the **\<component\>** level, and with the role that you specify here.
The **\<role\>** element is required in a custom **.xml** file. When the **\<role\>** element is specified, a concrete component can be created. The component is defined by the parameters specified at the **\<component\>** level, and with the role that is specified here.
- **Number of occurrences:** Each **\<component\>** can have one, two or three child **\<role\>** elements.
@ -1831,7 +1831,7 @@ Syntax:
|Setting|Required?|Value|
|--- |--- |--- |
| role | Yes | Defines the role for the component. Role can be one of: <ul><li>**Container**</li><li>**Binaries**</li><li>**Settings**</li><li>**Data**</li></ul> You can either: <ol><li>Specify up to three **\<role\>** elements within a **\<component\>** - one "Binaries" role element, one "Settings" role element and one "Data" role element. These parameters don't change the migration behavior - their only purpose is to help you categorize the settings that you're migrating. You can nest these **\<role\>** elements, but each nested element must be of the same role parameter.</li><li>Specify one "Container" **\<role\>** element within a **\<component\>** element. In this case, you can't specify any child **\<rules\>** elements, only other **\<component\>** elements. And each child **\<component\>** element must have the same type as that of parent **\<component\>** element. For example:</li></ol> <pre class="syntax"><code>\<component context="UserAndSystem" type="Application"\> <br/> \<displayName _locID="migapp.msoffice2003"\>Microsoft Office 2003\</displayName\> <br/> \<environment name="GlobalEnv" /\> <br/> \<role role="Container"\><br/> \<detection name="AnyOffice2003Version" /\> <br/> \<detection name="FrontPage2003" /\> <br/> \<!-- <br/> Office 2003 Common Settings <br/> --\> <br/> \<component context="UserAndSystem" type="Application"\></code></pre> |
| role | Yes | Defines the role for the component. Role can be one of: <ul><li>**Container**</li><li>**Binaries**</li><li>**Settings**</li><li>**Data**</li></ul> One of the following items can be specified: <ol><li>Up to three **\<role\>** elements within a **\<component\>** - one "Binaries" role element, one "Settings" role element and one "Data" role element. These parameters don't change the migration behavior - their only purpose is to help categorize the settings that are migrating. These **\<role\>** elements can be nested, but each nested element must be of the same role parameter.</li><li>One "Container" **\<role\>** element within a **\<component\>** element. In this case, any child **\<rules\>** elements can't be specified, only other **\<component\>** elements. And each child **\<component\>** element must have the same type as that of parent **\<component\>** element. For example:</li></ol> <pre class="syntax"><code>\<component context="UserAndSystem" type="Application"\> <br> \<displayName _locID="migapp.msoffice2016"\>Microsoft Office 2016\</displayName\> <br> \<environment name="GlobalEnv" /\> <br> \<role role="Container"\><br> \<detection name="AnyOffice2016Version" /\> <br> \<detection name="Word2016" /\> <br> \<!-- <br> Office 2003 Common Settings <br> --\> <br> \<component context="UserAndSystem" type="Application"\></code></pre> |
The following example is from the MigUser.xml file. For more examples, see the `MigApp.xml` file:
@ -1866,7 +1866,7 @@ The following example is from the MigUser.xml file. For more examples, see the `
## \<rules\>
The **\<rules\>** element is required in a custom .xml file. This element contains rules that run during the migration if the parent **\<component\>** element is selected, unless the child **\<conditions\>** element, if present, evaluates to **FALSE**. For each **\<rules\>** element, there can be multiple child **\<rules\>** elements.
The **\<rules\>** element is required in a custom **.xml** file. This element contains rules that run during the migration if the parent **\<component\>** element is selected, unless the child **\<conditions\>** element, if present, evaluates to **FALSE**. For each **\<rules\>** element, there can be multiple child **\<rules\>** elements.
- **Number of occurrences:** unlimited
@ -1885,8 +1885,8 @@ Syntax:
|Setting|Required?|Value|
|--- |--- |--- |
| name | Yes, when **\<rules\>** is a child to **\<namedElements\>** <br/>No, when **\<rules\>** is a child to any other element | When *ID* is specified, any child elements aren't processed. Instead, any other **\<rules\>** elements with the same name that are declared within **\<namedElements\>** are processed. |
| context | No <br/>(default = UserAndSystem) | Defines the scope of this parameter - whether to process this component in the context of the specific user, across the entire operating system, or both. <br/>The largest possible scope is set by the component element. For example, if a **\<component\>** element has a context of **User** and a **\<rules\>** element had a context of **UserAndSystem**, then the **\<rules\>** element would act as though it has a context of **User**. If **\<rules\>** had a context of **System**, it would act as though **\<rules\>** wasn't there. <ul><li>**User**: Evaluates the variables for each user.</li><li>**System**: Evaluates the variables only once for the system.</li><li>**UserAndSystem**: Evaluates the variables for the entire operating system and each user.</li></ul> |
| name | Yes, when **\<rules\>** is a child to **\<namedElements\>** <br>No, when **\<rules\>** is a child to any other element | When *ID* is specified, any child elements aren't processed. Instead, any other **\<rules\>** elements with the same name that are declared within **\<namedElements\>** are processed. |
| context | No <br>(default = UserAndSystem) | Defines the scope of this parameter - whether to process this component in the context of the specific user, across the entire operating system, or both. <br>The largest possible scope is set by the component element. For example, if a **\<component\>** element has a context of **User** and a **\<rules\>** element had a context of **UserAndSystem**, then the **\<rules\>** element would act as though it has a context of **User**. If **\<rules\>** had a context of **System**, it would act as though **\<rules\>** wasn't there. <ul><li>**User**: Evaluates the variables for each user.</li><li>**System**: Evaluates the variables only once for the system.</li><li>**UserAndSystem**: Evaluates the variables for the entire operating system and each user.</li></ul> |
The following example is from the MigUser.xml file:
@ -1932,25 +1932,25 @@ The return value that is required by **\<script\>** depends on the parent elemen
- General Syntax: `<script>ScriptWithArguments</script>`
- You can use [GetStringContent](#script-functions) when **\<script\>** is within **\<variable\>**.
- [GetStringContent](#script-functions) can be used when **\<script\>** is within **\<variable\>**.
Syntax: `<script>MigXmlHelper.GetStringContent("ObjectType","EncodedLocationPattern", "ExpandContent")</script>`
Example: `<script>MigXMLHelper.GetStringContent("Registry","HKLM\Software\MyApp\Installer [EXEPATH]")</script>`
- You can use [GenerateUserPatterns](#script-functions) when **\<script\>** is within **\<objectSet\>**.
- [GenerateUserPatterns](#script-functions) can be used when **\<script\>** is within **\<objectSet\>**.
Syntax: `<script>MigXmlHelper.GenerateUserPatterns("ObjectType","EncodedLocationPattern","ProcessCurrentUser")</script>`
Example: `<script>MigXmlHelper.GenerateUserPatterns ("File","%USERPROFILE%\* [*.doc]", "FALSE")</script>`
- You can use [GenerateDrivePatterns](#script-functions) when **\<script\>** is within **\<objectSet\>**.
- [GenerateDrivePatterns](#script-functions) can be used when **\<script\>** is within **\<objectSet\>**.
Syntax: `<script>MigXmlHelper.GenerateDrivePatterns("PatternSegment","DriveType")</script>`
Example: `<script>MigXmlHelper.GenerateDrivePatterns("* [sample.doc]", "Fixed")</script>`
- You can use the [Simple executing scripts](#script-functions) with **\<script\>** elements that are within **\<processing\>** elements: AskForLogoff, ConvertToShortFileName, KillExplorer, RemoveEmptyDirectories, RestartExplorer, RegisterFonts, StartService, StopService, SyncSCM.
- The [Simple executing scripts](#script-functions) can be used with **\<script\>** elements that are within **\<processing\>** elements: AskForLogoff, ConvertToShortFileName, KillExplorer, RemoveEmptyDirectories, RestartExplorer, RegisterFonts, StartService, StopService, SyncSCM.
Syntax: `<script>MigXmlHelper.ExecutingScript</script>`
@ -1958,7 +1958,7 @@ The return value that is required by **\<script\>** depends on the parent elemen
|Setting|Required?|Value|
|--- |--- |--- |
| *ScriptWithArguments* | Yes | A script followed by any number of string arguments that are separated by a comma and enclosed in parenthesis. For example, `MyScripts.AScript ("Arg1","Arg2")`. <br/>The script is called for each object that is enumerated by the object sets in the **\<include\>** rule. The filter script returns a Boolean value. If the return value is **TRUE**, the object is migrated. If it's **FALSE**, it isn't migrated. <br/>The return value that is required by **\<script\>** depends on the parent element. <ul><li>When used within **\<variable\>**, the return value must be a string.</li><li>When used within **\<objectSet\>**, the return value must be a two-dimensional array of strings.</li><li>When used within **\<location\>**, the return value must be a valid location that aligns with the type attribute of **\<location\>**. For example, if \<location type="File"\>, the child script element, if specified, must be a valid file location. <div class="alert">**Note**<br/>If you're migrating a file that has a bracket character ([ or ]) in the file name, insert the carrot (^) character directly before the bracket for it to be valid. For example, if there's a file named "file].txt", specify `<pattern type="File">c:\documents\mydocs [file^].txt]</pattern>` instead of `<pattern type="File">c:\documents\mydocs [file].txt]</pattern>`.</div></li></ul> |
| *ScriptWithArguments* | Yes | A script followed by any number of string arguments that are separated by a comma and enclosed in parenthesis. For example, `MyScripts.AScript ("Arg1","Arg2")`. <br>The script is called for each object that is enumerated by the object sets in the **\<include\>** rule. The filter script returns a Boolean value. If the return value is **TRUE**, the object is migrated. If it's **FALSE**, it isn't migrated. <br>The return value that is required by **\<script\>** depends on the parent element. <ul><li>When used within **\<variable\>**, the return value must be a string.</li><li>When used within **\<objectSet\>**, the return value must be a two-dimensional array of strings.</li><li>When used within **\<location\>**, the return value must be a valid location that aligns with the type attribute of **\<location\>**. For example, if \<location type="File"\>, the child script element, if specified, must be a valid file location. <div class="alert">**Note**<br>If migrating a file that has a bracket character ([ or ]) in the file name, insert the carrot (^) character directly before the bracket for it to be valid. For example, if there's a file named "file].txt", specify `<pattern type="File">c:\documents\mydocs [file^].txt]</pattern>` instead of `<pattern type="File">c:\documents\mydocs [file].txt]</pattern>`.</div></li></ul> |
Examples:
@ -1972,7 +1972,7 @@ For more examples of how to use this element, see [Exclude Files and Settings](u
### \<script\> functions
You can use the following functions with the **\<script\>** element
The following functions can be used with the **\<script\>** element
- [String and pattern generating functions](#string-and-pattern-generating-functions)
@ -1984,14 +1984,14 @@ These functions return either a string or a pattern.
- **GetStringContent**
You can use GetStringContent with **\<script\>** elements that are within **\<variable\>** elements. If possible, this function returns the string representation of the given object. Otherwise, it returns **NULL**. For file objects this function, always returns **NULL**.
GetStringContent can be used with **\<script\>** elements that are within **\<variable\>** elements. If possible, this function returns the string representation of the given object. Otherwise, it returns **NULL**. For file objects this function, always returns **NULL**.
Syntax: `GetStringContent("ObjectType","EncodedLocationPattern", "ExpandContent")`
|Setting|Required?|Value|
|--- |--- |--- |
| *ObjectType* | Yes | The type of object. Can be Registry or Ini (for an .ini file). |
| *EncodedLocationPattern* | Yes | <ul><li>If type of object is Registry, EncodedLocationPattern must be a valid registry path. For example, `HKLM\SOFTWARE\MyKey[]`.</li><li>If the type of object is Ini, then EncodedLocationPattern must be in the following format: <br/>**IniFilePath&#124;SectionName[SettingName]**</li></ul> |
| *EncodedLocationPattern* | Yes | <ul><li>If type of object is Registry, EncodedLocationPattern must be a valid registry path. For example, `HKLM\SOFTWARE\MyKey[]`.</li><li>If the type of object is Ini, then EncodedLocationPattern must be in the following format: <br>**IniFilePath&#124;SectionName[SettingName]**</li></ul> |
| *ExpandContent* | No (default=TRUE) | Can be **TRUE** or **FALSE**. If **FALSE**, then the given location isn't expanded before returned. |
For example:
@ -2004,14 +2004,14 @@ These functions return either a string or a pattern.
- **GenerateDrivePatterns**
The `GenerateDrivePatterns` function iterates all of the available drives and selects the ones that match the requested drive type. It then concatenates the selected drives with the end part of *PatternSegment* to form a full encoded file pattern. For example, if *PatternSegment* is `Path [file.txt]` and *DriveType* is `Fixed`, then the function generates `C:\Path [file.txt]`, and other patterns if there are fixed drives other than C:. You can't specify environment variables with this function. You can use `GenerateDrivePatterns` with **\<script\>** elements that are within [\<objectSet\>](#objectset) that are within **\<include\>**/**\<exclude\>**.
The `GenerateDrivePatterns` function iterates all of the available drives and selects the ones that match the requested drive type. It then concatenates the selected drives with the end part of *PatternSegment* to form a full encoded file pattern. For example, if *PatternSegment* is `Path [file.txt]` and *DriveType* is `Fixed`, then the function generates `C:\Path [file.txt]`, and other patterns if there are fixed drives other than C:. Environment variables can't be specified with this function. `GenerateDrivePatterns` can be used with **\<script\>** elements that are within [\<objectSet\>](#objectset) that are within **\<include\>**/**\<exclude\>**.
Syntax: `GenerateDrivePatterns("PatternSegment","DriveType")`
|Setting|Required?|Value|
|--- |--- |--- |
| *PatternSegment* | Yes | The suffix of an encoded pattern. It's concatenated with a drive specification, such as "c:", to form a complete [encoded file pattern](#specifying-locations). For example, "* [*.doc]". *PatternSegment* can't be an environment variable. |
| *DriveType* | Yes | The drive type for which the patterns are to be generated. You can specify one of: <ul><li>Fixed</li><li>CDROM</li><li>Removable</li><li>Remote</li></ul> |
| *PatternSegment* | Yes | The suffix of an encoded pattern. The value is concatenated with a drive specification, such as "c:", to form a complete [encoded file pattern](#specifying-locations). For example, "* [*.doc]". *PatternSegment* can't be an environment variable. |
| *DriveType* | Yes | The drive type for which the patterns are to be generated. One of the following items can be specified: <ul><li>Fixed</li><li>CDROM</li><li>Removable</li><li>Remote</li></ul> |
See the last component in the MigUser.xml file for an example of this element.
@ -2035,7 +2035,7 @@ These functions return either a string or a pattern.
**Example:**
If `GenerateUserPattens('File','%userprofile% [*.doc]','FALSE')` is called while USMT is processing user A, then this function only generates patterns for users B and C. You can use this helper function to build complex rules. For example, to migrate all `.doc` files from the source computer - but if user X isn't migrated, then don't migrate any of the `.doc` files from user X's profile.
If `GenerateUserPattens('File','%userprofile% [*.doc]','FALSE')` is called while USMT is processing user A, then this function only generates patterns for users B and C. This helper function can be used to build complex rules. For example, to migrate all `.doc` files from the source computer - but if user X isn't migrated, then don't migrate any of the `.doc` files from user X's profile.
The following example is example code for this scenario. The first **\<rules\>** element migrates all `.doc` files on the source computer except for those inside `C:\Documents and Settings`. The second **\<rules\>** elements migrate all `.doc` files from `C:\Documents and Settings` except for the `.doc` files in the profiles of the other users. Because the second **\<rules\>** element is processed in each migrated user context, the end result is the desired behavior. The end result is the one we expected.
@ -2099,7 +2099,7 @@ The `MigXmlHelper.GenerateDocPatterns` helper function invokes the document find
### Simple executing scripts
The following scripts have no return value. You can use the following errors with **\<script\>** elements that are within **\<processing\>** elements
The following scripts have no return value. The following errors can be used with **\<script\>** elements that are within **\<processing\>** elements
- **AskForLogoff()**. Prompts the user to sign out at the end of the migration. For example:
@ -2145,7 +2145,7 @@ The following scripts have no return value. You can use the following errors wit
## \<text\>
You can use the **\<text\>** element to set a value for any environment variables that are inside one of the migration .xml files.
The **\<text\>** element can be used to set a value for any environment variables that are inside one of the migration **.xml** files.
- **Number of occurrences:** Once in each [\<variable\>](#variable) element.
@ -2173,9 +2173,9 @@ For example:
## \<unconditionalExclude\>
The **\<unconditionalExclude\>** element excludes the specified files and registry values from the migration, regardless of the other include rules in any of the migration .xml files or in the `Config.xml` file. The objects declared here aren't migrated because this element takes precedence over all other rules. For example, even if there are explicit **\<include\>** rules to include `.mp3` files, if you specify to exclude them with this option, then they aren't migrated.
The **\<unconditionalExclude\>** element excludes the specified files and registry values from the migration, regardless of the other include rules in any of the migration **.xml** files or in the `Config.xml` file. The objects declared here aren't migrated because this element takes precedence over all other rules. For example, even if there are explicit **\<include\>** rules to include `.mp3` files, if they're excluded with this option, then they aren't migrated.
Use this element if you want to exclude all `.mp3` files from the source computer. Or, if you're backing up `C:\UserData` using another method, you can exclude the entire folder from the migration. Use this element with caution, however, because if an application needs a file that you exclude, the application might not function properly on the destination computer.
Use this element to exclude all `.mp3` files from the source computer. Or, if backing up `C:\UserData` using another method, the entire folder can be excluded from the migration. Use this element with caution. If an application needs a file that is excluded, the application might not function properly on the destination computer.
- **Number of occurrences:** Unlimited.
@ -2189,7 +2189,7 @@ Syntax:
<unconditionalExclude></unconditionalExclude>
```
The following .xml file excludes all `.mp3` files from migration. For additional examples of how to use this element, see the [Exclude Files and Settings](usmt-exclude-files-and-settings.md).
The following **.xml** file excludes all `.mp3` files from migration. For additional examples of how to use this element, see the [Exclude Files and Settings](usmt-exclude-files-and-settings.md).
```xml
<migration urlid="http://www.microsoft.com/migration/1.0/migxmlext/excludefiles">
@ -2233,7 +2233,7 @@ Syntax:
|Setting|Required?|Value|
|--- |--- |--- |
|name|Yes|*ID* is a string value that is the name used to reference the environment variable. We recommend that *ID* start with the component's name to avoid namespace collisions. For example, if your component's name is MyComponent, and you want a variable that is your component's install path, you could specify `MyComponent.InstallPath`.|
|name|Yes|*ID* is a string value that is the name used to reference the environment variable. Microsoft recommends that *ID* start with the component's name to avoid namespace collisions. For example, if the component's name is MyComponent, and a variable is desired that is the component's install path, `MyComponent.InstallPath`could be specified.|
|remap|No, default = FALSE|Specifies whether to evaluate this environment variable as a remapping environment variable. Objects that are located in a path that is underneath this environment variable's value are automatically moved to where the environment variable points on the destination computer.|
The following example is from the `MigApp.xml` file:
@ -2289,13 +2289,13 @@ The **\<windowsObjects\>** element is for USMT internal use only. Don't use this
Representing the registry is similar. The default value of a registry key is represented as an empty `[]` construct. For example, the default value for the `HKLM\SOFTWARE\MyKey` registry key is `HKLM\SOFTWARE\MyKey[]`.
- **Specifying location patterns**. You specify a location pattern in a way that is similar to how you specify an actual location. The exception is that both the node and leaf part accept patterns. However, a pattern from the node doesn't extend to the leaf.
- **Specifying location patterns**. Specifying a location pattern is similar to specifying an actual location. The exception is that both the node and leaf part accept patterns. However, a pattern from the node doesn't extend to the leaf.
For example, the pattern `c:\Windows\*` matches the Windows directory and all subdirectories, but it doesn't match any of the files in those directories. To match the files as well, you must specify `c:\Windows\*[*]`.
For example, the pattern `c:\Windows\*` matches the Windows directory and all subdirectories, but it doesn't match any of the files in those directories. To match the files as well, `c:\Windows\*[*]` must be specified.
### Internal USMT functions
The following functions are for internal USMT use only. Don't use them in an .xml file.
The following functions are for internal USMT use only. Don't use them in an **.xml** file.
- *AntiAlias*
@ -2325,7 +2325,7 @@ The following functions are for internal USMT use only. Don't use them in an .xm
### Valid version tags
You can use the following version tags with various helper functions:
The following version tags can be used with various helper functions:
- "CompanyName"

8
windows/deployment/usmt/usmt-xml-reference.md
View File

@ -1,18 +1,18 @@
---
title: USMT XML Reference (Windows 10)
description: Learn about working with and customizing the migration XML files using User State Migration Tool (USMT) XML Reference for Windows 10.
title: USMT XML Reference
description: Learn about working with and customizing the migration XML files using User State Migration Tool (USMT) XML Reference for Windows.
manager: aaroncz
ms.author: frankroj
ms.prod: windows-client
author: frankroj
ms.date: 11/01/2022
ms.date: 12/30/2023
ms.topic: article
ms.technology: itpro-deploy
---
# USMT XML reference
This section contains articles that you can use to work with and to customize the migration XML files.
This section contains articles that can be used to work with and to customize the migration XML files.
## In this section

35
windows/deployment/usmt/verify-the-condition-of-a-compressed-migration-store.md
View File

@ -1,18 +1,18 @@
---
title: Verify the Condition of a Compressed Migration Store (Windows 10)
title: Verify the Condition of a Compressed Migration Store
description: Use these tips and tricks to verify the condition of a compressed migration store when using User State Migration Tool (USMT).
manager: aaroncz
ms.author: frankroj
ms.prod: windows-client
author: frankroj
ms.date: 11/01/2022
ms.date: 12/30/2023
ms.topic: article
ms.technology: itpro-deploy
---
# Verify the condition of a compressed migration store
When you migrate files and settings during a typical PC-refresh migration, the user state is usually stored in a compressed folder on the intermediate store. This compressed folder, also called the compressed migration store, is a single image file that contains:
When files and settings are migrated during a typical PC-refresh migration, the user state is normally stored in a compressed folder on the intermediate store. This compressed folder, also called the compressed migration store, is a single image file that contains:
- All of the files being migrated.
@ -20,9 +20,9 @@ When you migrate files and settings during a typical PC-refresh migration, the u
- A catalog file that contains metadata for all files in the migration store.
When you run the `LoadState.exe` command to load the data from these files to the destination computer, **LoadState** requires a valid catalog file in order to open the migration store. You can run the `UsmtUtils.exe` command with the `/verify` option to determine whether the compressed migration store is intact, or whether it contains corrupted files or a corrupted catalog. You should run the `/verify` option on the migration store before you overwrite the original user-state files and settings.
When the `LoadState.exe` command is run to load the data from these files to the destination computer, **LoadState** requires a valid catalog file in order to open the migration store. The `UsmtUtils.exe` command can be run with the `/verify` option to determine whether the compressed migration store is intact, or whether it contains corrupted files or a corrupted catalog. The `/verify` option should be run on the migration store before overwriting the original user-state files and settings.
When you use the `/verify` option, you can specify what type of information to report in the **UsmtUtils** log file. These report types are:
When the `/verify` option is used, what type of information to report in the **UsmtUtils** log file can be specified. These report types are:
- **Catalog**: Displays the status of only the catalog file.
@ -36,23 +36,23 @@ The following sections demonstrate how to run the `UsmtUtils.exe` command with t
To verify the condition of a compressed migration store, use the following UsmtUtils syntax:
> UsmtUtils.exe /verify\[:&lt;*reportType*&gt;\] &lt;*filePath*&gt; \[/l:&lt;*logfile*&gt;\] \[/decrypt \[:&lt;*AlgID*&gt;\] {/key:&lt;*keystring*&gt; | /keyfile:&lt;*filename*&gt;}\]
> UsmtUtils.exe /verify\[:\<*reportType*\>\] \<*filePath*\> \[/l:\<*logfile*\>\] \[/decrypt \[:\<*AlgID*\>\] {/key:\<*keystring*\> | /keyfile:\<*filename*\>}\]
Where the placeholders have the following values:
- *&lt;USMTpath&gt;* is the location where you've saved the USMT files and tools.
- *\<USMTpath\>* is the location where the USMT files and tools are saved.
- *&lt;reportType&gt;* specifies whether to report on all files, corrupted files only, or the status of the catalog.
- *\<reportType\>* specifies whether to report on all files, corrupted files only, or the status of the catalog.
- *&lt;filePath&gt;* is the location of the compressed migration store.
- *\<filePath\>* is the location of the compressed migration store.
- *&lt;logfile&gt;* is the location and name of the log file.
- *\<logfile\>* is the location and name of the log file.
- *&lt;AlgID&gt;* is the cryptographic algorithm that was used to create the migration store on the `ScanState.exe` command line.
- *\<AlgID\>* is the cryptographic algorithm that was used to create the migration store on the `ScanState.exe` command line.
- *&lt;keystring&gt;* is the encryption key that was used to encrypt the migration store.
- *\<keystring\>* is the encryption key that was used to encrypt the migration store.
- *&lt;filename&gt;* is the location and name of the text file that contains the encryption key.
- *\<filename\>* is the location and name of the text file that contains the encryption key.
## To verify that the migration store is intact
@ -84,7 +84,7 @@ In addition to verifying the status of all files, this example decrypts the file
## To verify the status of the files and return only the corrupted files
In this example, the log file will only list the files that became corrupted during the **ScanState** process. This list will include the catalog file if it's also corrupted.
In this example, the log file only lists the files that became corrupted during the **ScanState** process. This list includes the catalog file if the catalog file is also corrupted.
```cmd
UsmtUtils.exe /verify:failureonly D:\MyMigrationStore\USMT\store.mig /decrypt:AES_192 /keyfile:D:\encryptionKey.txt
@ -94,10 +94,9 @@ This example also decrypts the files by specifying the cryptographic algorithm a
## Next steps
If the `/verify` option indicates that there are corrupted files in the migration store, you can use the `/extract` option in the **UsmtUtils** tool to recover data from some corrupted stores. For more information, see [Extract files from a compressed USMT migration store](usmt-extract-files-from-a-compressed-migration-store.md).
If the `/verify` option indicates that there are corrupted files in the migration store, the `/extract` option in the **UsmtUtils** tool can be used to recover data from some corrupted stores. For more information, see [Extract files from a compressed USMT migration store](usmt-extract-files-from-a-compressed-migration-store.md).
## Related articles
[UsmtUtils syntax](usmt-utilities.md)
[Return codes](/troubleshoot/windows-client/deployment/usmt-return-codes)
- [UsmtUtils syntax](usmt-utilities.md).
- [Return codes](/troubleshoot/windows-client/deployment/usmt-return-codes).

12
windows/deployment/usmt/xml-file-requirements.md
View File

@ -1,26 +1,26 @@
---
title: XML File Requirements (Windows 10)
title: XML File Requirements
description: Learn about the XML file requirements for creating custom .xml files, like the file must be in UTF-8 and have a unique migration URL ID.
manager: aaroncz
ms.author: frankroj
ms.prod: windows-client
author: frankroj
ms.date: 11/01/2022
ms.date: 12/30/2023
ms.topic: article
ms.technology: itpro-deploy
---
# XML file requirements
When creating custom .xml files, note the following requirements:
When creating custom **.xml** files, note the following requirements:
- **The file must be in Unicode Transformation Format-8 (UTF-8).** Save the file in this format, and you must specify the following syntax at the beginning of each .xml file:
- **The file must be in Unicode Transformation Format-8 (UTF-8).** Save the file in this format and the following syntax must be specified at the beginning of each **.xml** file:
```xml
<?xml version="1.0" encoding="UTF-8"?>
```
- **The file must have a unique migration URL ID**. The URL ID of each file that you specify on the command line must be different. If two migration .xml files have the same URL ID, the second .xml file that is specified on the command line won't be processed. The second file won't be processed because USMT uses the URL ID to define the components within the file. For example, you must specify the following syntax at the beginning of each file:
- **The file must have a unique migration URL ID**. The URL ID of each file that is specified on the command line must be different. If two migration **.xml** files have the same URL ID, the second **.xml** file that is specified on the command line isn't processed. The second file isn't processed because USMT uses the URL ID to define the components within the file. For example, the following syntax must be specified at the beginning of each file:
```xml
<?xml version="1.0" encoding="UTF-8"?>
@ -33,4 +33,4 @@ When creating custom .xml files, note the following requirements:
<displayName>My Application</displayName>
```
For examples of custom .xml files, see [Custom XML examples](usmt-custom-xml-examples.md).
For examples of custom **.xml** files, see [Custom XML examples](usmt-custom-xml-examples.md).