Migrating application settings with USMT 4.0: Sample #1

Out of the box, USMT 4.0 migrates settings for Windows, Office, and various other applications (typically current versions as of 2009), mostly consumer-focused. (See http://technet.microsoft.com/en-us/library/dd560792(WS.10).aspx for the full list.) So what if you want to migrate settings from additional applications? Well, then you need to author your own migration XML file.

First though, you need to figure out what application settings need to be migrated. Does the application store its settings in a file? In a registry key? Per user or per system? There’s no single right way to do this, so you have to do some investigative work to figure this out for each application. Tools like ProcMon from SysInternals can help with that, by capturing details of all registry and file accesses made by the process. But there can be lots of data captured, so finding the data can be somewhat time-consuming.

So let’s look at a real example using Angry Birds, which is available for download from http://download.angrybirds.com/. Install this on a computer, then start ProcMon and tell it to capture details from process name AngryBirds.exe:

Then launch Angry Birds and click on “Play” to see where you left off – at that point, you know it’s read the saved settings, wherever those came from. At that point, you can stop the capture and begin scanning the captured data. Usually I start at the bottom (most recent) and work my way up, looking for something “interesting”. (What is “interesting” can vary by app, but you will begin to notice patterns that applications follow so the more applications you do this with, the better you’ll get at it.)

From scanning the ProcMon output, I can see a few references to my user profile folder:

Those files (“highscores.lua” and “settings.lua”) sound promising, especially since I noticed that the settings are per user (log in as someone else and you have different progress displayed) and I don’t see any relevant HKCU registry access in the trace.

OK, so we know what we want to capture and restore. Now we have to figure out how. Using your favorite XML editor (I use Visual Studio), create a new XML file that looks like this:

A few things to point out:

The “urlid” value on the first line can be any URL – it just needs to be unique among all XML files being used (no duplicates). Make up whatever value you want, as it’s effectively just a text string, not used for anything beyond identification.
The component type can be either “Application” or “Documents”, depending on what you are capturing. It doesn’t really matter what you specify, as it just controls where the component shows up in the config.xml file (if you generate one). For Angry Birds, I specified “Application”. (If you specify an invalid value, USMT typically doesn’t complain – it does end up ignoring the component though.)
The context is very important. It should be “System” if you are capturing machine-level configuration, or “User” if you are capturing user-specific configuration. You can also specify “UserAndSystem” if you need to capture both. In the case of Angry Birds, we’ve already determined that it is using user settings, so that’s what we need to specify.
The remaining entries generally occur in this type of pattern:

A role node. The type can be “Data”, “Binaries”, “Settings” or “Data” – really just labels for you to use, as all values are treated the same.
One or more detection rules. In this case, we look for the existence of a folder to indicate that this rule should be processed.
A rules node that specifies whether these are “User” or “System” settings. (Typically this is the same as the component value, although it can be a subset, e.g. the component specified “UserAndSystem” while the rule specifies “User”.)
One or more include rules that specify what to migrate.
Potentially more optional elements, e.g. exclusions. See http://technet.microsoft.com/en-us/library/dd560769(WS.10).aspx for a description of all the possible XML elements.

So then lets look at the condition:

MigXmlHelper.DoesObjectExist("File","%CSIDL_APPDATA%\Rovio\Angry Birds")

This uses a helper function to determine if the specified directory exists. The “%CSIDL_APPDATA%” text is a reference to one of the many “environment variables” (listed at http://technet.microsoft.com/en-us/library/dd560744(WS.10).aspx) that can be used; the value will be substituted when evaluating the condition. Because this is a per-user rule, the condition will be checked for each user, with “%CSIDL_APPDATA%” pointing to the user profile’s roaming data folder (e.g. C:\Users\<userID>\AppData\Roaming on Windows 7).

The "include" rule specifies to capture all files and subfolders under the detected path. By default, these will be put back into the same location they were captured from, doing any necessarily translation for changes in %CSIDL_APPDATA% (e.g. drive letter changes).

That’s all there is to it – just tell Scanstate and Loadstate to use this new XML file and all of your Angry Birds progress will be preserved even through an OS refresh or replacement process.