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:

SCANSTATE /I:MigApp.xml

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:

MigsysHelperFunction.RelativeMove("c:\data","%CSIDL_PERSONAL%")

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.