USMT .xml Files

  • Article

In this topic

  • Overview
  • Migration .xml files
  • Custom .xml file
  • Config.xml
  • Additional information

Overview

In order for ScanState and LoadState to use any of the migration .xml files, you need to specify the files on both command lines using the /i option. Unlike previous versions of USMT, the .xml files are not copied to the store. Because ScanState and LoadState need the .xml files to control the migration, you should specify the same set of .xml files on the ScanState and LoadState command lines. However, you do not have to specify Config.xml unless you want to exclude some of the files and settings that you migrated to the store. For example, you might want to migrate the My Documents folder to the store, but not to the destination computer. To do this, simply modify the Config.xml and specify the updated file with LoadState. Then LoadState will only migrate the files and settings that you want to migrate.

If you leave out an .xml file from LoadState, then all data that was migrated with the missing .xml files (that is in the store) will be migrated. However, the migration rules that were specified on the ScanState command line will not apply. For example, if you leave out MigApp.xml, and it had a rerouting rule like MigsysHelperFunction.RelativeMove(“c:\data”, “%CSIDL_PERSONAL%”), USMT will not reroute the files, and they will be migrated to C:\data.

To modify the migration for your needs, you should do one or both of the following.

  • Modify themigration .xml files**.** You should modify the .xml files if you want to exclude a portion of a component (for example, to migrate C:\ but exclude all .mp3 files), or want to move data to a new location on the destination computer. To modify these files, you must be familiar with the migration rules and syntax. For ScanState and LoadState to use these files, you will need to specify them on both command lines.
  • Createcustom .xml filefiles. You can also create a custom .xml to migrate settings for another application, or to change the migration behavior to suite your needs. For ScanState and LoadState to use this file, you will need to specify them on both command lines.
  • Create and modify aConfig.xmlfile. Do this if you want to exclude an entire component from the migration (for example, exclude the entire My Documents folder, or exclude the settings for an application). Excluding components using this file is easier than modifying the migration .xml files because you do not need to be familiar with the migration rules and syntax. In addition, using this file is the only way to exclude the operating system settings that are migrated to computers running Windows Vista (since MigSys.xml is not applicable in this scenario).

For more information about excluding data, see How To Exclude Files and Settings.

Migration .xml files

The following are the migration .xml files that are included with USMT. Each file contains migration rules that control which components are migrated and where they are migrated to the destination computer. You can use the asterisk (*) wildcard character in each of these files. However, you cannot use a question mark (?) as a wildcard.

  • MigSys.xml. Specify this file on both command lines when the destination computer is running Windows XP to migrate operating system and browser settings.(in addition, you should specify /targetXP). You can modify MigSys.xml. When the source or destination computer is running Windows Vista, this file is not applicable because the operating system and browser settings are migrated using the manifests. Since you cannot modify the manifests, if you want to exclude certain operating system settings in this scenario, you will need to create and modify a Config.xml file.
  • MigApp.xml. Specify this file on both command lines to migrate application settings to computers running both Windows XP and Windows Vista. You can modify MigApp.xml.
  • MigUser.xml. Specify this file on both command lines to migrate user folders, files, and file types to computers running both Windows XP and Windows Vista. You can modify MigUser.xml. This file does not contain rules that migrates specific user accounts. The only way to specify which user accounts to migrate is on the command line using the User Options.

Custom .xml file

You can create custom .xml file(s) to customize the migration for your unique needs. For example, you may want to create a custom file to migrate a line-of-business application or to modify the default migration behavior. For ScanState and LoadState to use this file, you will need to specify it on both command lines. For more information, see How To Create a Custom .xml File.

Config.xml

This is an optional file that you can create using the /genconfig option on the ScanState command line. You should create and modify this file if you want to exclude certain components from the migration. In addition, you must create and modify this file if you want to exclude any of the operating system settings that are migrated to computers running Windows Vista (because MigSys.xml is not applicable in that scenario). This file has a different format than the migration .xml files because it does not contain any migration rules — it only contains a list of the operating system components, applications, and the user documents that can be migrated. For an example, see the Sample Config.xml file. For this reason, excluding components using this file is easier than modifying the migration .xml files because you do not need to be familiar with the migration rules and syntax. You cannot use wildcard characters in this file.

If you want to include all of the default components, you do not need to create this file. Alternatively, if you are satisfied with the default migration behavior defined in MigSys.xml, MigApp.xml, and MigUser.xml, and you only want to exclude some components, you can create and modify a Config.xml and leave the other .xml files as is.

When you run /genconfig, ScanState reads the other .xml files (that you specify using /i) and the manifests to create a custom list of components that can be migrated from the computer. This file will only contain operating system components, applications and the user document sections that are in both the .xml files and installed on the computer when you run /genconfig. Therefore, you should create this file on a source computer that contains all the components, applications and settings that will be present on the destination computers. This will ensure that this file contains every component that can be migrated. The components are organized into sections: <Applications>, <WindowsComponents>, and <Documents>. To choose not to migrate a component, simply change its entry to migrate="no".

After you create this file, you only need to specify it on the ScanState command line using /config in order for it to effect the migration. However, if you want to exclude additional data that you migrated to the store, simply modify Config.xml and specify the updated file with LoadState. For example, if you collected the My Documents folder in the store, but you decide that you do not want to migrate the My Documents folder to a destination computer, you can modify Config.xml (migrate=no) before you run LoadState and the file will not be migrated. For more information about the precedence that takes place when excluding data, see How To Exclude Files and Settings.

In addition, note the following functionality with this file:

  • If a parent component is removed from the migration in Config.xml by specifying migrate = "no", then all of its child components will automatically be removed from the migration also (even if the child component is set to migrate = "yes").
  • If, by mistake, you have two lines of code for the same component where one specifies migrate="no" and the other specifies migrate="yes", the component will be migrated.
  • When creating this file for Windows Vista, you should not specify /i:migsys.xml because MigSys.xml is not applicable. For example, you could run scanstate /genconfig:config.xml /i:miguser.xml /i:migapp.xml /v:13 /l:scan.log

Examples

Destination computer running Windows Vista:

  • This command creates a Config.xml file in the current directory (does not create a store):
    scanstate /i:migapp.xml /i:miguser.xml /genconfig:config.xml /v:13
  • This command creates an encrypted store using Config.xml and the default migration .xml files:
    scanstate \\fileserver\migration\mystore /i:migapp.xml /i:miguser.xml /o /config:config.xml /v:13 /encrypt /key:"mykey"
  • This command decrypts the store and migrates the files and settings:
    loadstate \\fileserver\migration\mystore /i:migapp.xml /i:miguser.xml /v:13 /decrypt /key:"mykey"

Destination computer running Windows XP:

  • This command creates a Config.xml file in the current directory (does not create a store):
    scanstate /targetxp /i:migsys.xml /i:migapp.xml /i:miguser.xml /genconfig:config.xml /v:13
  • This command creates an encrypted store using Config.xml and the default migration .xml files:
    scanstate \\fileserver\migration\mystore /targetxp /i:migsys.xml /i:migapp.xml /i:miguser.xml /o /config:config.xml /v:13 /encrypt /key:"mykey"
  • This command decrypts the store and migrates the files and settings:
    loadstate \\fileserver\migration\mystore /i:migsys.xml /i:migapp.xml /i:miguser.xml /v:13 /decrypt /key:"mykey"

Additional information

  • For more information about how to change the files and settings that are migrated, see Using USMT.
  • For more information about each XML element, see XML Elements Reference.
  • For answers to common questions, see ".xml files" in the Frequently Asked Questions topic.
  • For instructions for using the XML schema to write and validate migration .xml files, see MigXML.xsd.