diff --git a/windows/deployment/usmt/understanding-migration-xml-files.md b/windows/deployment/usmt/understanding-migration-xml-files.md index cc32fdd543..d17a30363e 100644 --- a/windows/deployment/usmt/understanding-migration-xml-files.md +++ b/windows/deployment/usmt/understanding-migration-xml-files.md @@ -50,15 +50,15 @@ This topic provides an overview of the default and custom migration XML files an 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: `scanstate /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. +> [!NOTE] +> When modifying the XML elements in the Config.xml file, you should edit an element and set the **migrate** property to **no**, rather than deleting the element from the file. If you delete the element instead of setting the property, the component may still be migrated by rules in other XML files. ## Overview of the MigApp.xml file 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 do not 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 the [Sample migration rules for customized versions of XML files](#bkmk-samples). +> [!Important] +> The MigApps.xml file will only detect and migrate .pst files that are linked to Microsoft Office Outlook. For more information about migrating .pst files that are not linked to Outlook, see the [Sample migration rules for customized versions of XML files](#bkmk-samples). ## Overview of the MigDocs.xml file @@ -170,8 +170,8 @@ The default MigUser.xml file does not migrate the following: 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 may result in a migration that contains more files than intended. For example, if you choose to migrate all .jpg files, you may migrate image files such as thumbnails and logos from legacy applications that are installed on the source computer. -**Note**   -Each file name extension you include in the rules within the MigUser.xml file increases the amount of time needed for the ScanState tool to gather the files for the migration. If you are migrating more than 300 file types, you may experience a slow migration. For more information about other ways to organize the migration of your data, see the [Using multiple XML files](#bkmk-multiple) section of this document. +> [!NOTE] +> Each file name extension you include in the rules within the MigUser.xml file increases the amount of time needed for the ScanState tool to gather the files for the migration. If you are migrating more than 300 file types, you may experience a slow migration. For more information about other ways to organize the migration of your data, see the [Using multiple XML files](#bkmk-multiple) section of this document. ## Using multiple XML files @@ -186,14 +186,14 @@ You can use multiple XML files with the ScanState and LoadState tools. Each of t For example, you can use all of the XML migration file types for a single migration, as in the following example: -``` +```cmd Scanstate /config:c:\myFolder\config.xml /i:migapps.xml /i:migdocs.xml /i:customrules.xml ``` ### 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. +> [!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. 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. @@ -203,8 +203,8 @@ If you want more control over the migration, you can create custom XML files. Se 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. -**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. +> [!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. To generate the XML migration rules file for a source computer: @@ -214,14 +214,14 @@ To generate the XML migration rules file for a source computer: 3. At the command prompt, type: - ``` + ```cmd cd /d scanstate.exe /genmigxml: ``` Where *<USMTpath>* is the location on your source computer where you have saved the USMT files and tools, and *<filepath.xml>* is the full path to a file where you can save the report. For example, type: - ``` + ```cmd cd /d c:\USMT scanstate.exe /genmigxml:"C:\Documents and Settings\USMT Tester\Desktop\genMig.xml" ``` @@ -230,15 +230,27 @@ To generate the XML migration rules file for a source computer: The MigDocs.xml file calls the **GenerateDocPatterns** function, which takes three Boolean values. You can change the settings to modify the way the MigDocs.xml file generates the XML rules for migration. -|Setting|Value|Default Value| -|--- |--- |--- | -|ScanProgramFiles|The *ScanProgramFiles* argument is valid only when the **GenerateDocPatterns** function is called in a system context. This argument determines whether or not to scan the Program Files directory to gather registered file name extensions for known applications.
For example, when set to **TRUE**, the function discovers and migrates .doc files under the Microsoft Office directory, because .doc is a file name extension registered to a Microsoft Office application. The **GenerateDocPatterns** function generates this inclusion pattern for .doc files: 
<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.|False| -|IncludePatterns|The *IncludePatterns* 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.|True| -|SystemDrive|The *SystemDrive* argument determines whether to generate patterns for all fixed drives or only for the system drive. Changing this argument to **TRUE** restricts all patterns to the system drive.|False| +- `ScanProgramFiles`: This argument is valid only when the **GenerateDocPatterns** function is called in a system context. This argument determines whether or not to scan the Program Files directory to gather registered file name extensions for known applications. + + **Default value**: False + + For example, when set to **TRUE**, the function discovers and migrates .doc files under the Microsoft Office directory, because .doc is a file name extension registered to a Microsoft Office application. The **GenerateDocPatterns** function generates this inclusion pattern for `.doc` files: + + `C:\Program Files\Microsoft Office[.doc]` + + If a child folder of an included folder contains an installed application, ScanProgramFiles will also create an exclusion rule for the child folder. All folders under the application folder will be scanned recursively for registered file name extensions. + +- `IncludePatterns`: This argument determines whether to generate exclude or include patterns in the XML. When this argument is set to **TRUE**, the **GenerateDocPatterns** function generates include patterns and the function must be added under the `` element. Changing this argument to **FALSE** generates exclude patterns and the function must be added under the `' element. + + **Default value**: True + +- `SystemDrive`: This argument determines whether to generate patterns for all fixed drives or only for the system drive. Changing this argument to **TRUE** restricts all patterns to the system drive. + + **Default value**: False **Usage:** -``` +```cmd MigXmlHelper.GenerateDocPatterns ("", "", "") ``` @@ -324,13 +336,13 @@ 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. +> [!NOTE] +> Rules contained in a component that is assigned the user context will be run for each user profile on the computer. Files that are scanned multiple times by the MigDocs.xml files will only be copied to the migration store once; however, a large number of rules in the user context can slow down the migration. Use the system context when it is applicable. ### Sample migration rules for customized versions of XML files -**Note**   -For best practices and requirements for customized XML files in USMT, see [Customize USMT XML Files](usmt-customize-xml-files.md) and [General Conventions](usmt-general-conventions.md). +> [!NOTE] +> For best practices and requirements for customized XML files in USMT, see [Customize USMT XML Files](usmt-customize-xml-files.md) and [General Conventions](usmt-general-conventions.md). ### Exclude rules usage examples @@ -338,8 +350,8 @@ In the examples below, the source computer has a .txt file called "new text docu | Rule | Syntax | |--- |--- | -|Rule 1|
<pattern type="File">d:\new folder[new text document.txt]</pattern>
| -|Rule 2|
<pattern type="File">d:\new folder[]</pattern>
| +|Rule 1|`d:\new folder[new text document.txt]`| +|Rule 2|`d:\new folder[]`| To exclude the new text document.txt file and any .txt files in "new folder", you can do the following: @@ -419,12 +431,12 @@ 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**   -For more information about the order of precedence for XML migration rules, see [Conflicts and Precedence](usmt-conflicts-and-precedence.md). +> [!NOTE] +> For more information about the order of precedence for XML migration rules, see [Conflicts and Precedence](usmt-conflicts-and-precedence.md). ## Next steps -You can include additional rules for the migration in the MigDocs.xml file or other XML migration files. For example, you can use the <locationModify> element to move files from the folder where they were gathered to a different folder, when they are applied to the destination computer. +You can include additional rules for the migration in the MigDocs.xml file or other XML migration files. For example, you can use the `` element to move files from the folder where they were gathered to a different folder, when they are applied to the destination computer. You can use an XML schema (MigXML.xsd) file to validate the syntax of your customized XML files. For more information, see [USMT Resources](usmt-resources.md).