SolutionBase: Working with migration rule files <br>in the User State Migration Tool

The User State Migration Tool is designed to follow instructions that are contained in migration rule files. Since these files are all in XML format, you have the option of modifying any or all of the default migration rule files or creating a custom migration rule file. In this article, Brien Posey shows you how it's done.

The User State Migration Tool is used to move user's files and settings from one system to another during the migration process. When running the tool, the ScanState component collects the user files and settings from the source computer and places them into an intermediate store. Later, the LoadState component is run on the destination computer to move the files and settings from the store to the machine running Vista.

The User State Migration Tool is designed to follow instructions that are contained in migration rule files. The tool contains three built-in migration rule files: MigApp.xml, MigUser.xml, and MigSys.xml. Since these files are in XML format, you have the option of modifying any or all of the default migration rule files. You also have the option of creating a custom migration rule file. In this article, I will show you how it's done.

Migration rule file basics

Both the ScanState and the LoadState utilities offer several command line switches that you can use to custom-tailor the migration process to meet your needs. If you plan on using any of the built in migration rule files, modified migration rule files, or a custom migration rule file, you will have to use the /I switch with both ScanState and with LoadState.

The syntax for using the /I switch is relatively simple: just specify the /I switch followed by a colon and the name of the migration rule file that you want to use. For example, if you wanted to tell ScanState to use the MigApp.xml file, you would use the following command:


As you have probably already figured out, each of the migration rules files have a different purpose, and the only way to gain total control over the migration process is to use multiple rules files. If you should need to use multiple rules files, you must use the /I switch once for each rules file. For example, if you wanted to tell ScanState to use the MigApp.xml, MigSys.xml, and MigUser.xml files, you would use the following command:

SCANSTATE /I:MigApp.xml /I:MigSys.xml /i:MigUser.xml

Before I move on, there are two other things that you need to know about the /I switch. First, you will notice in the sample commands above that I did not specify a path to the various XML files. If you don't specify a path, then the migration rules files must be located in the same folder as ScanState.exe and LoadState.exe.

If you decide to store your migration rules files elsewhere, you must provide the path to the file after the /I switch. You can specify a full path or you can use a relative path. ScanState and LoadState will work with either.

The /I switch does not have to be used by itself. You can use the /I switch in conjunction with any of the other switches that ScanState and LoadState support.

Using the /I switch With LoadState

When it comes to using the /I switch, LoadState uses exactly the same syntax as ScanState does, so I'm not going to waste your time going over the syntax again. However, you do need to know that if you use the /I switch with ScanState, then you must also use it with LoadState. Mismatching migration rules files has some rather interesting consequences.

In previous versions of Microsoft's User State Migration Tool, the various XML files were considered to be so important to the migration process that they were copied to the store along with the migration data; this isn't the case with the current version. If you specify an XML file when you run ScanState, you must also specify that same file when you run LoadState. There is one exception to this, which I will cover later.

Right now, you're probably wondering what happens if you do mismatch migration rules files when running ScanState and LoadState. The most common type of mismatch is specifying a migration rules file when running ScanState, but accidentally omitting the file when running LoadState. As I have explained, the migration rules files provide rules for the migration process. They tell the User State Migration Tool what needs to be migrated, and what needs to happen to that data during the migration process.

With this in mind, let's consider what happens if you specify an XML file when running ScanState, but forget to specify it when running LoadState. Since you have used the XML when running ScanState, the User State Migration Tool knows what data you want to migrate. In fact, the data that is to be migrated is written to the store by ScanState. When you run LoadState, it migrates everything in the store. Since the data that was specified within the XML file was written to the store, that data is migrated, even though the XML file was not specified when you ran LoadState.

Although it sounds as though the migration will work perfectly even if you don't specify the XML files when you run LoadState, there is one very big problem with not specifying the various migration rules files. The problem stems from the fact that the migration rules files' purposes are twofold. Yes, the migration rules files tell the User State Migration Tool which files and settings to migrate, but they also tell the tool what must be done with the data as a part of the migration process.

For example, suppose some of the systems being migrated contain a folder named C:\DATA that contains all of the user's documents. Since this folder isn't really a conventional place to store the user's documents, you decide to move the files to the user's My Documents folder on the target system. To do so, you would insert the following command into the MigApp.xml file:


In case you are wondering, CSIDL provides you with a way of specifying a location on a target computer even when you don't know the absolute path of the target folder. For example, %CSIDL_PERSONAL% maps to My Documents. You can find a list of the various CSIDL mappings at Microsoft's Web site.

At any rate, including this command in the MigApp.xml file ensures that all of the files contained in the C:\DATA folder are written to the store. If you don't call the MigApp.xml file when you run LoadState, though, LoadState will create a folder named C:\DATA on the target machine and place the user's documents into it. The files are not moved to the My Documents folder, because LoadState is unaware of the instruction to do so.

A reverse scenario

I have covered what happens if you include the migration rules files when you run ScanState, but forget to specify them when you run LoadState. But what happens if you do things the other way around? What happens if you run ScanState without specifying any migration rules files?

Well, it depends on what other switches you have specified for use with ScanState. As you may recall from the first article in this series, ScanState supports the use of a switch named /TargetXP, which you can use to specify that the target system will be running Windows XP. You would not use this switch during a Windows XP to Vista migration; but, if you did, ScanState would copy all of the user accounts from the source machine to the store but wouldn't attempt to copy anything else. If you were to run ScanState without the /TargetXP switch (as with a migration to Vista) and you did not specify any migration rules files, then ScanState would copy the source machine's user accounts, as well as the default operating system components, to the store.

As you can see, it is important to use the /I switch with both ScanState and with LoadState. I don't want to give you the wrong idea, though: If you are going to be migrating to Windows Vista, don't blindly tell ScanState and LoadState to use MigApp.xml, MigUser.xml, and MigSys.xml.

In a real world XP to Vista migration, you don't want to use MigSys.xml at all. This file is only used in migrations in which both the source and the target computer are running Windows XP. When the target computer is running Vista, the User State Migration Tool uses manifests in place of the MigSys.xml file. You don't have to do anything to get ScanState and LoadState to use these manifests. Manifest use is automatic, and the manifests themselves cannot be modified.

The MigApp.xml and MigUser.xml files are both valid for Windows XP to Vista migrations. Prior to using these files, you should go through them and omit any code that isn't applicable to your organization, and add code for anything that isn't being migrated by default. Modifying this code should be fairly straightforward for anyone with basic XML knowledge.

Generating the Config.xml file

Earlier in the article, I briefly mentioned that you should always use the same /I parameters with ScanState as you do with LoadState, but with one big exception. That exception involves a migration rule file that I haven't talked about yet, named Config.xml. The thing that makes the Config.xml file so special is that unlike the other XML files that I have discussed, it does not exist by default. You will have to use ScanState to create it.

Using the Config.xml file isn't mandatory, but I recommend using it any way. Creating a Custom.xml file allows you to preserve the default XML files. That way, you can keep all of your modifications in one place, which makes those modifications easier to keep track of. The Custom.xml file is particularly useful for specifying exclusions. For example, if you knew that some users had been storing MP3 files on their systems, you could use the Config.xml file to migrate all of the files found in C:\DATA, except for MP3 files. There are lots of other ways that you can use the Config.xml file to include or exclude various types of data; there is a great reference at TechNet.  

About the only thing that you can't do with the Config.xml file is exclude user accounts from being migrated. If you need to exclude user accounts from the migration, you will have to use the /UE switch to exclude the user account. You can find a complete reference to the command in Microsoft's Windows Vista TechNet site.  

Generating Config.xml

As I said, creating a Config.xml file isn't mandatory. You can just modify the other XML files; but, you don't even have to do that. You can run ScanState and LoadState using the default XML files. I recommend creating and customizing the Config.xml file, however, because doing so will give you a lot more control over the migration process.

Having said that, Microsoft recommends beginning the process by installing the User State Migration Tool on a PC that is a good representation of what you will be migrating. There will probably be some variance among the PCs in your organization, but you want to pick a PC that has most of the same applications as the other PCs that will be migrated. It will also be helpful if any data stored on the hard drive exists in the same folders as the data on other PCs that will be migrated. Once you have installed the User State Migration Tool on such a PC, run the following command:

ScanState /genconfig:Config.xml /I:MigUser.xml /I:MigApp.xml

This command generates the Config.xml file, but, contrary to its appearance, it does not create a store or prepare any data for migration. The MigUser.xml and MigApp.xml files are included in the command because ScanState uses these files as a template for building the Config.xml file. Assuming you make the necessary modifications only to the Config.xml file, you will not need to use the MigUser.xml or the MigApp.xml files when you later run ScanState and LoadState.