Freshness 04-12-2023 6

This commit is contained in:
Frank Rojas
2023-12-05 17:04:01 -05:00
parent f9c4e06677
commit 28b36af35b
8 changed files with 73 additions and 55 deletions

View File

@ -15,7 +15,7 @@ metadata:
author: frankroj
ms.author: frankroj
manager: aaroncz
ms.date: 12/05/2023
ms.date: 12/06/2023
localization_priority: medium
# linkListType: architecture | concept | deploy | download | get-started | how-to-guide | learn | overview | quickstart | reference | tutorial | video | whats-new

View File

@ -7,7 +7,7 @@ ms.prod: windows-client
author: frankroj
ms.topic: article
ms.technology: itpro-deploy
ms.date: 12/05/2023
ms.date: 12/06/2023
---
# Getting started with the User State Migration Tool (USMT)

View File

@ -5,7 +5,7 @@ manager: aaroncz
ms.author: frankroj
ms.prod: windows-client
author: frankroj
ms.date: 12/05/2023
ms.date: 12/06/2023
ms.topic: article
ms.technology: itpro-deploy
---
@ -132,7 +132,8 @@ Your script should do the following actions:
- 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:
1. Add the set of files that trigger the import using the **<addObjects>** element
1. Add the set of files that trigger the import using the **<addObjects>** element.
2. Create a mapping that applies the old settings to the correct location on the destination computer using the **<locationModify>** element, and the `RelativeMove` and `ExactMove` helper functions.
- If you must install the application before migrating the settings, delete any settings that are already on the destination computer using the **<destinationCleanup>** element.
@ -153,7 +154,7 @@ For more information, see the [Exclude files and settings](usmt-exclude-files-an
## Related articles
- [USMT XML reference](usmt-xml-reference.md)
- [Conflicts and precedence](usmt-conflicts-and-precedence.md)
- [XML elements library](usmt-xml-elements-library.md)
- [Log files](usmt-log-files.md)
- [USMT XML reference](usmt-xml-reference.md).
- [Conflicts and precedence](usmt-conflicts-and-precedence.md).
- [XML elements library](usmt-xml-elements-library.md).
- [Log files](usmt-log-files.md).

View File

@ -5,7 +5,7 @@ manager: aaroncz
ms.author: frankroj
ms.prod: windows-client
author: frankroj
ms.date: 12/05/2023
ms.date: 12/06/2023
ms.topic: article
ms.technology: itpro-deploy
---

View File

@ -5,7 +5,7 @@ manager: aaroncz
ms.author: frankroj
ms.prod: windows-client
author: frankroj
ms.date: 12/05/2023
ms.date: 12/06/2023
ms.topic: article
ms.technology: itpro-deploy
---

View File

@ -1,38 +1,40 @@
---
title: Understanding Migration XML Files (Windows 10)
description: Learn how to modify the behavior of a basic User State Migration Tool (USMT) 10.0 migration by using XML files.
title: Understanding Migration XML Files
description: Learn how to modify the behavior of a basic User State Migration Tool (USMT) migration by using XML files.
manager: aaroncz
ms.author: frankroj
ms.prod: windows-client
author: frankroj
ms.date: 11/23/2022
ms.date: 12/06/2023
ms.topic: article
ms.technology: itpro-deploy
---
# Understanding migration XML files
You can modify the behavior of a basic User State Migration Tool (USMT) 10.0 migration by using XML files; these files provide instructions on where and how the USMT tools should gather and apply files and settings. USMT includes three XML files that you can use to customize a basic migration: the `MigDocs.xml` and `MigUser.xml` files, which modify how files are discovered on the source computer, and the MigApps.xml file, which is required in order to migrate supported application settings. You can also create and edit custom XML files and a `Config.xml` file to further customize your migration.
You can modify the behavior of a basic User State Migration Tool (USMT) migration by using XML files; these files provide instructions on where and how the USMT tools should gather and apply files and settings. USMT includes three XML files that you can use to customize a basic migration: the `MigDocs.xml` and `MigUser.xml` files, which modify how files are discovered on the source computer, and the MigApps.xml file, which is required in order to migrate supported application settings. You can also create and edit custom XML files and a `Config.xml` file to further customize your migration.
This article provides an overview of the default and custom migration XML files and includes guidelines for creating and editing a customized version of the `MigDocs.xml` file. The `MigDocs.xml` file uses the new `GenerateDocPatterns` function available in USMT to automatically find user documents on a source computer.
## Overview of the Config.xml file
The `Config.xml` file is the configuration file created by the `/genconfig` option of the ScanState tool; it can be used to modify which operating-system components are migrated by USMT. The `Config.xml` file can be used with other XML files, such as in the following example:
The `Config.xml` file is the configuration file created by the `/genconfig` option of the ScanState tool. You can use it to modify which operating-system components USMT migrates. The `Config.xml` file can be used with other XML files, such as in the following example:
`ScanState.exe /i:migapps.xml /i:MigDocs.xml /genconfig:c:\myFolder\Config.xml`
When used this way, the `Config.xml` file tightly controls aspects of the migration, including user profiles, data, and settings, without modifying or creating other XML files. For more information about the `Config.xml` file, see [Customize USMT XML Files](usmt-customize-xml-files.md) and [Config.xml File](usmt-configxml-file.md).
> [!NOTE]
> When modifying the XML elements in the `Config.xml` file, you should edit an element and set the **migrate** property to **no**, rather than deleting the element from the file. If you delete the element instead of setting the property, the component may still be migrated by rules in other XML files.
>
> When modifying the XML elements in the `Config.xml` file, you should edit an element and set the **migrate** property to **no**, rather than deleting the element from the file. If you delete the element instead of setting the property, rules in other XML files can still migrate the component.
## Overview of the MigApp.xml file
The `MigApp.xml` file installed with USMT includes instructions to migrate the settings for the applications listed in [What Does USMT Migrate?](usmt-what-does-usmt-migrate.md). You must include the `MigApp.xml` file when using the ScanState and LoadState tools, by using the `/i` option in order to migrate application settings. The `MigDocs.xml` and `MigUser.xml` files don't migrate application settings. You can create a custom XML file to include additional applications. For more information, see [Customize USMT XML Files](usmt-customize-xml-files.md).
> [!IMPORTANT]
> The MigApps.xml file will only detect and migrate .pst files that are linked to Microsoft Office Outlook. For more information about migrating .pst files that are not linked to Outlook, see [Sample migration rules for customized versions of XML files](#sample-migration-rules-for-customized-versions-of-xml-files).
>
> The `MigApps.xml` file only detects and migrates .pst files that are linked to Microsoft Office Outlook. For more information about migrating .pst files that aren't linked to Outlook, see [Sample migration rules for customized versions of XML files](#sample-migration-rules-for-customized-versions-of-xml-files).
## Overview of the MigDocs.xml file
@ -42,11 +44,11 @@ The default `MigDocs.xml` file migrates the following data:
- All files on the root of the drive except `%WINDIR%`, `%PROGRAMFILES%`, `%PROGRAMDATA%`, or `%USERS%`.
- All folders in the root directory of all fixed drives. For example: `c:\data_mail\*[*]`
- All folders in the root directory of all fixed drives. For example: `c:\data_mail\*[*]`.
- All files from the root of the Profiles folder, except for files in the system profile. For example: `c:\users\name[mail.pst]`
- All files from the root of the Profiles folder, except for files in the system profile. For example: `c:\users\name[mail.pst]`.
- All folders from the root of the Profiles folder, except for the system-profile folders. For example: `c:\users\name\new folder\*[*]`
- All folders from the root of the Profiles folder, except for the system-profile folders. For example: `c:\users\name\new folder\*[*]`.
- Standard shared folders:
@ -92,7 +94,7 @@ The default `MigDocs.xml` file migrates the following data:
- FOLDERID_RecordedTV
The default `MigDocs.xml` file won't migrate the following data:
The default `MigDocs.xml` file doesn't migrate the following data:
- Files tagged with both the **hidden** and **system** attributes.
@ -102,11 +104,11 @@ The default `MigDocs.xml` file won't migrate the following data:
- Folders that contain installed applications.
You can also use the `/genmigxml` option with the ScanState tool to review and modify what files will be migrated.
You can also use the `/genmigxml` option with the ScanState tool to review and modify what files are migrated.
## Overview of the MigUser.xml file
The `MigUser.xml` file includes instructions for USMT to migrate user files based on file name extensions. You can use the `MigUser.xml` file with the ScanState and LoadState tools to perform a more targeted migration than using USMT without XML instructions. The `MigUser.xml` file will gather all files from the standard user-profile folders, and any files on the computer with the specified file name extensions.
The `MigUser.xml` file includes instructions for USMT to migrate user files based on file name extensions. You can use the `MigUser.xml` file with the ScanState and LoadState tools to perform a more targeted migration than using USMT without XML instructions. The `MigUser.xml` file gathers all files from the standard user-profile folders, and any files on the computer with the specified file name extensions.
The default `MigUser.xml` file migrates the following data:
@ -133,25 +135,28 @@ The default `MigUser.xml` file migrates the following data:
`.accdb`, `.ch3`, `.csv`, `.dif`, `.doc*`, `.dot*`, `.dqy`, `.iqy`, `.mcw`, `.mdb*`, `.mpp`, `.one*`, `.oqy`, `.or6`, `.pot*`, `.ppa`, `.pps*`, `.ppt*`, `.pre`, `.pst`, `.pub`, `.qdf`, `.qel`, `.qph`, `.qsd`, `.rqy`, `.rtf`, `.scd`, `.sh3`, `.slk`, `.txt`, `.vl*`, `.vsd`, `.wk*`, `.wpd`, `.wps`, `.wq1`, `.wri`, `.xl*`, `.xla`, `.xlb`, `.xls*`
> [!NOTE]
>
> The asterisk (`*`) stands for zero or more characters.
> [!NOTE]
>
> The OpenDocument extensions (`*.odt`, `*.odp`, `*.ods`) that Microsoft Office applications can use aren't migrated by default.
The default `MigUser.xml` file doesn't migrate the following data:
- Files tagged with both the **Hidden** and **System** attributes.
- Files and folders on removable drives,
- Files and folders on removable drives.
- Data from the `%WINDIR%`, `%PROGRAMFILES%`, `%PROGRAMDATA%` folders.
- ACLS for files in folders outside the user profile.
You can make a copy of the `MigUser.xml` file and modify it to include or exclude standard user-profile folders and file name extensions. If you know all of the extensions for the files you want to migrate from the source computer, use the `MigUser.xml` file to move all of your relevant data, regardless of the location of the files. However, this provision may result in a migration that contains more files than intended. For example, if you choose to migrate all .jpg files, you may migrate image files such as thumbnails and logos from legacy applications that are installed on the source computer.
You can make a copy of the `MigUser.xml` file and modify it to include or exclude standard user-profile folders and file name extensions. If you know all of the extensions for the files you want to migrate from the source computer, use the `MigUser.xml` file to move all of your relevant data, regardless of the location of the files. However, this provision can result in a migration that contains more files than intended. For example, if you choose to migrate all .jpg files, it can also migrate image files such as thumbnails and logos from legacy applications that are installed on the source computer.
> [!NOTE]
> Each file name extension you include in the rules within the `MigUser.xml` file increases the amount of time needed for the ScanState tool to gather the files for the migration. If you are migrating more than 300 file types, you may experience a slow migration. For more information about other ways to organize the migration of your data, see the [Using multiple XML files](#using-multiple-xml-files) section of this article.
>
> Each file name extension you include in the rules within the `MigUser.xml` file increases the amount of time needed for the ScanState tool to gather the files for the migration. If you're migrating more than 300 file types, the migration experience can be slow. For more information about other ways to organize the migration of your data, see the [Using multiple XML files](#using-multiple-xml-files) section of this article.
## Using multiple XML files
@ -159,10 +164,10 @@ 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).|
|*MigApps.xml file*|Applications settings.|
|*MigUser.xml* or *MigDocs.xml* files|User files and profile settings.|
|*Custom XML files*|Application settings, user profile settings, or user files, beyond the rules contained in the other XML files.|
|**Config.xml file**|Operating-system components such as desktop wallpaper and background theme.<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.|
For example, you can use all of the XML migration file types for a single migration, as in the following example:
@ -173,35 +178,42 @@ ScanState.exe <store> /config:c:\myFolder\Config.xml /i:migapps.xml /i:MigDocs.x
### XML rules for migrating user files
> [!IMPORTANT]
> You should not use the `MigUser.xml` and `MigDocs.xml` files together in the same command. Using both XML files can result in duplication of some migrated files. This occurs when conflicting target-location instructions are given in each XML file. The target file will be stored once during the migration, but will be applied by each XML file to a different location on the destination computer.
>
> You shouldn't use the `MigUser.xml` and `MigDocs.xml` files together in the same command. Using both XML files can result in duplication of some migrated files. Duplication of some migrated files can occur when conflicting target-location instructions are given in each XML file. The target file is stored once during the migration, but each XML file applies the file to a different location on the destination computer.
If your data set is unknown or if many files are stored outside of the standard user-profile folders, the `MigDocs.xml` is a better choice than the `MigUser.xml` file, because the `MigDocs.xml` file will gather a broader scope of data. The `MigDocs.xml` file migrates folders of data based on location. The `MigUser.xml` file migrates only the files with the specified file name extensions.
If your data set is unknown or if many files are stored outside of the standard user-profile folders, the `MigDocs.xml` is a better choice than the `MigUser.xml` file, because the `MigDocs.xml` file gathers a broader scope of data. The `MigDocs.xml` file migrates folders of data based on location. The `MigUser.xml` file migrates only the files with the specified file name extensions.
If you want more control over the migration, you can create custom XML files. See [Creating and editing a custom XML file](#creating-and-editing-a-custom-xml-file) for more information.
If you want more control over the migration, you can create custom XML files. For more information on creating custom XML files, see [Creating and editing a custom XML file](#creating-and-editing-a-custom-xml-file) for more information.
## Creating and editing a custom XML file
You can use the `/genmigxml` command-line option to determine which files will be included in your migration. The `/genmigxml` option creates a file in a location you specify, so that you can review the XML rules and make modifications as necessary.
You can use the `/genmigxml` command-line option to determine which files are included in your migration. The `/genmigxml` option creates a file in a location you specify, so that you can review the XML rules and make modifications as necessary.
> [!NOTE]
> If you reinstall USMT, the default migration XML files will be overwritten and any customizations you make directly to these files will be lost. Consider creating separate XML files for your custom migration rules and saving them in a secure location.
>
> If you reinstall USMT, the default migration XML files are overwritten and any customizations you make directly to these files are lost. Consider creating separate XML files for your custom migration rules and saving them in a secure location.
To generate the XML migration rules file for a source computer:
1. Select **Start** > **All Programs** > **Accessories**
2. Right-click **Command Prompt**, and then select **Run as**.
1. Right-click **Command Prompt**, and then select **Run as**.
3. Select an account with administrator privileges, supply a password, and then select **OK**.
1. Select an account with administrator privileges, supply a password, and then select **OK**.
4. At the command prompt, enter:
1. At the command prompt, enter:
```cmd
cd /d <USMTpath>
ScanState.exe /genmigxml: <filepath.xml>
```
Where *&lt;USMTpath&gt;* is the location on your source computer where you've saved the USMT files and tools, and *&lt;filepath.xml&gt;* is the full path to a file where you can save the report. For example, enter:
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.
For example, enter:
```cmd
cd /d c:\USMT
@ -220,7 +232,7 @@ The `MigDocs.xml` file calls the `GenerateDocPatterns` function, which takes thr
`<pattern type="File">C:\Program Files\Microsoft Office[.doc]</pattern>`
If a child folder of an included folder contains an installed application, ScanProgramFiles will also create an exclusion rule for the child folder. All folders under the application folder will be scanned recursively for registered file name extensions.
If a child folder of an included folder contains an installed application, `ScanProgramFiles` also creates an exclusion rule for the child folder. All folders under the application folder are scanned recursively for registered file name extensions.
- `IncludePatterns`: This argument determines whether to generate exclude or include patterns in the XML. When this argument is set to **TRUE**, the `GenerateDocPatterns` function generates include patterns, and the function must be added under the `<include>` element. Changing this argument to **FALSE** generates exclude patterns and the function must be added under the `<exclude>` element.
@ -268,7 +280,10 @@ 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 system context applies to files on the computer that aren't stored in the User Profiles directory, while the user context applies to files that are particular to an individual user.
The migration XML files contain two &lt;component&gt; elements with different **context** settings:
- The system context applies to files on the computer that aren't stored in the User Profiles directory.
- The user context applies to files that are particular to an individual user.
#### System context
@ -319,23 +334,25 @@ The user context includes rules for data in the User Profiles directory. When ca
- FOLDERID_RecordedTV
> [!NOTE]
> Rules contained in a component that is assigned the user context will be run for each user profile on the computer. Files that are scanned multiple times by the `MigDocs.xml` files will only be copied to the migration store once; however, a large number of rules in the user context can slow down the migration. Use the system context when it is applicable.
>
> Rules contained in a component that is assigned the user context runs for each user profile on the computer. Files that are scanned multiple times by the `MigDocs.xml` files are only copied to the migration store once. However, a large number of rules in the user context can slow down the migration. Use the system context when it's applicable.
### Sample migration rules for customized versions of XML files
> [!NOTE]
> [!TIP]
>
> For best practices and requirements for customized XML files in USMT, see [Customize USMT XML Files](usmt-customize-xml-files.md) and [General Conventions](usmt-general-conventions.md).
### Exclude rules usage examples
In the examples below, the source computer has a .txt file called "new text document" in a directory called "new folder". The default `MigDocs.xml` behavior migrates the new text document.txt file and all files contained in the "new folder" directory. The rules generated by the function are:
In the following examples, the source computer has a .txt file called `new text document` in a directory called `new folder`. The default `MigDocs.xml` behavior migrates the new text `document.txt` file and all files contained in the `new folder` directory. The rules generated by the function are:
| Rule | Syntax |
|--- |--- |
|Rule 1|`<pattern type="File">d:\new folder[new text document.txt]</pattern>`|
|Rule 2|`<pattern type="File">d:\new folder[]</pattern>`|
To exclude the new text document.txt file and any .txt files in "new folder", you can do the following modification:
To exclude the new text `document.txt` file and any .txt files in `new folder`, you can do the following modification:
#### Example 1: Exclude all .txt files in a folder
@ -352,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 will be less specific than the default include rule generated by the `MigDocs.xml` file, so it will not have precedence. You must use the &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 &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).
```xml
<unconditionalExclude>
@ -364,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 will be run 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.
```xml
<component type="Documents" context="UserandSystem">
@ -389,7 +406,7 @@ The application data directory is the most common location that you would need t
#### Example 1: Include a file name extension in a known user folder
This rule will include .pst files that are located in the default location, but aren't linked to Microsoft Outlook. Use the user context to run this rule for each user on the computer.
This rule includes .pst files that are located in the default location, but aren't linked to Microsoft Outlook. Use the user context to run this rule for each user on the computer.
```xml
<include filter='MigXmlHelper.IgnoreIrrelevantLinks()'>
@ -413,7 +430,8 @@ For locations outside the user profile, such as the Program Files folder, you ca
For more examples of include rules that you can use in custom migration XML files, see [Include Files and Settings](usmt-include-files-and-settings.md).
> [!NOTE]
> [!TIP]
>
> For more information about the order of precedence for XML migration rules, see [Conflicts and Precedence](usmt-conflicts-and-precedence.md).
## Next steps
@ -424,6 +442,5 @@ You can use an XML schema (MigXML.xsd) file to validate the syntax of your custo
## Related articles
[Exclude files and settings](usmt-exclude-files-and-settings.md)
[Include files and settings](usmt-include-files-and-settings.md)
- [Exclude files and settings](usmt-exclude-files-and-settings.md).
- [Include files and settings](usmt-include-files-and-settings.md).

View File

@ -6,7 +6,7 @@ ms.technology: itpro-deploy
author: frankroj
manager: aaroncz
ms.author: frankroj
ms.date: 12/05/2023
ms.date: 12/06/2023
ms.topic: overview
ms.collection:
- highpri
@ -47,4 +47,4 @@ There are some scenarios in which the use of USMT isn't recommended. These scena
## Related articles
- [User State Migration Tool (USMT) technical reference](usmt-technical-reference.md)
- [User State Migration Tool (USMT) technical reference](usmt-technical-reference.md).

View File

@ -6,7 +6,7 @@ ms.technology: itpro-deploy
manager: aaroncz
ms.author: frankroj
author: frankroj
ms.date: 12/05/2023
ms.date: 12/06/2023
ms.topic: conceptual
ms.collection:
- highpri