Does USMT Migrate ?
Hi folks, Ned here again. Below are the two most common USMT questions I get asked these days:
- USMT is not migrating setting X for application Y. Is USMT broken or is this expected behavior?
- I am in the planning phase and have not yet tried, but will USMT migrate setting X for application Y?
There are a million little knobs in Windows and all of its applications and it’s impossible to document them all with much specificity. Today I discuss how to determine this no matter what the registry setting or application. I also explain how USMT decides to migrate settings using component XML files. As long as you’re systematic in your investigation, you can’t go wrong. Perhaps this saves you a support case or delayed rollout someday.
The Sample Scenario
I’ll approximate a recent real-world example, where the customer is testing migration from Windows XP to Windows 7 and is having trouble with customized Internet Explorer Favorites. The Favorites migrate fine but the user’s customized sort order is not preserved. In my semi-fictionalized example, they are also migrating from IE7 to IE9 and from 32-bit to 64-bit, just to make things interesting.
The key to solving any problem is a disciplined approach. You must remove distractions and carefully narrow down the genuine error conditions. Sir Arthur Conan Doyle said it best:
“When you have eliminated the impossible, whatever remains, however improbable, must be the truth.”
Let’s walk through solving this USMT behavior case, and therefore, any USMT behavior case.
Step 1 – Find the actual settings
Naturally, you must discover where the settings really live. The easiest way is to let the Internet do the walking: search. Maybe someone has already documented this. Start with trustworthy spots like TechNet, MSDN, and the MS Knowledgebase, and then fan out to the woolier Internet.
In this case, I’m not finding much, so I move to direct data analysis. There are a couple ways to do this with Microsoft tools:
1. Process Monitor (download x86/x64)
These two utilities can monitor for changes and tell you what changed under the covers when you flipped some switch in the UI. They each have their advantages and limitations: WSSA is simple and shows changes without much modification, but is slower and sometimes unstable (I found it crashing on third party virtual hosts, but working fine on Virtual PC and Hyper-V). Process Monitor is fast, but complex and cumbersome. I demonstrate both below and you can decide – remember, my example is with Internet Explorer Favorites customization on XP so your steps will naturally vary. Before you get all bothered, there are plenty of snapshot comparison tools out there too; I can’t discuss their merits obviously or lawyers with sharks for arms will eat me.
Scanning with Windows System State Analyzer
1. I install WSSA and start it up (as an Administrator).
2. I use the Tools menu to modify the options to monitor only registry and the user profiles directory. You can go as deep as the test user but some settings might exist in the All Users or Public profiles. I avoid scanning the entire drive, drivers, or services.
3. I start my application. In this case, I run Internet Explorer and open the Favorites menu (I want to be as close as possible to the change to avoid gathering unrelated data)
4. I start a Baseline Snapshot and allow it to complete then move to section “Make the Change”.
Scanning with Process Monitor
1. I Install ProcMon and start it up (as an Administrator).
2. I disable capturing and set the following filters to gather registry changes:
Note: I may have to do this multiple times for various filters. For example, if I wanted to see file changes I’d switch my filter to instead:
Operation is CreateFile
Path begins with c:\documents and settings
3. I start my application In this case, I run Internet Explorer and open the Favorites menu (I want to be as close as possible to the change to avoid gathering unrelated data)
4. I clear the current data then start capturing.
Make the change
1. I alter my setting using the application. For example, here I move the AskDS blog link to the top of my favorites menu. Where it belongs. :)
2. I close the application to flush the change into the registry (there’s no guarantee that my change was immediately stored).
Examine the Results with Process Monitor
I stop capturing and look at the filtered results:
Order = <binary goo>
Examine the Results with Windows System State Analyzer
I create a Current Snapshot, then compare to the baseline:
Isn’t that interesting? There’s a registry value named “Order” in our “MenuOrder\Favorites” key. I think we have a winner. I can confirm by looking up that specific key and yep, it’s the one. This also tells me that the key has been in use since (at least) Internet Explorer 4.0 and in every operating system since NT 4.0. The odds that this setting exists and works like this in Windows 7 and IE9 have gone way up.
I take a quick look and yes, the same keys exist on my brand new test destination computer. A couple of red herrings out of the way – the OS and Browser version don’t matter.
Sometimes you can understand the before and after settings, but this example isn’t pretty:
Step 2 – Find the XML
Ok, so now I need to find out if USMT migrates the Favorites customizations (I‘m sure it will migrate the Favorites themselves, that’s simply a shell folder in the user profile that we gather up). Luckily, much of the data migrated by USMT is defined in human-readable XML files. Since I now know the registry paths, I can examine them with confidence using FINDSTR.EXE within the USMT folder structure.
Findstr.exe /s /i "currentversion\explorer\menuorder" *.*
See how FINDSTR returned the .man files containing data about those registry keys. Many application’s settings are migrated using these files rather than the migapp.xml (it is mainly for apps not included with Windows). There two kinds of manifests here: the DLManifests used on Windows XP and the ReplacementManifests used on Windows 7 and Vista.
Since I’m on XP I’ll examine microsoft-windows-ie-internetexplorer-dl.man (using Visual Studio 2010 Express, as I previously described here). Right away, I see that these Favorites customizations absolutely will migrate.
<pattern type="Registry">HKCU\SOFTWARE\Microsoft\Internet Explorer\* [*]</pattern>
<pattern type="Registry">HKCU\SOFTWARE\Microsoft\Windows\CurrentVersion\Internet Settings\* [*]</pattern>
<pattern type="Registry">HKCU\SOFTWARE\Microsoft\Windows\CurrentVersion\Explorer\AutoComplete\* [*]</pattern>
<pattern type = "Registry">HKCU\SOFTWARE\Microsoft\Windows\CurrentVersion\Explorer\MenuOrder\Favorites\* [*]</pattern>
<pattern type="Registry">HKCU\SOFTWARE\Microsoft\Windows\CurrentVersion\Webcheck\* [*]</pattern>
<pattern type="Registry">HKCU\SOFTWARE\Microsoft\Windows\CurrentVersion\Ext\* [*]</pattern>
<pattern type="Registry">HKCU\SOFTWARE\Microsoft\Search Assistant\* [*]</pattern>
<pattern type="File">%CSIDL_LOCAL_APPDATA%\Microsoft\Internet Explorer\* [*]</pattern>
<pattern type="File">%CSIDL_LOCAL_APPDATA%\Microsoft\Windows\History\* [*]</pattern>
<pattern type="File">%CSIDL_APPDATA%\Microsoft\Windows\Cookies\* [*]</pattern>
<pattern type="File">%CSIDL_APPDATA%\Microsoft\Internet Explorer\* [*]</pattern>
I chose wisely here but it might take you a little digging to find the migrating manifest. For example, the entire HKCU\Software\Microsoft\Windows key and its contents could be migrated and there would be no mention of the much deeper Favorites folder – my search would have failed in that case. If you don’t find it low, search high.
Important note: Windows Vista and Windows 7 also include XML in the %systemroot%\winsxs\manifests folder, stored as .manifest files. You should examine these files with FINDSTR.EXE if you do not return any data when searching the USMT manifests and using a Vista or Windows 7 computer as the source machine. They are used automatically if there is no replacement manifest.
There are a lot of manifests here and the ones that have a migration scope that includes “USMT” are the only ones that matter; the latest versioned one will be used if there are multiples:
To find them all on your test computer, search your windows\winsxs\manifests folder like this:
C:\Windows\winsxs\Manifests>findstr /m /i "usmt" *.manifest
Step 3 – Validate the Processing
This part should be easy: I migrate and logon as the test user to make sure the settings migrated successfully.
But what if they didn’t?
My investigation looked correct and I am confident that USMT will migrate these settings. I need to ensure that nothing else is blocking transfer, despite USMT’s best efforts. Again, the methodical approach works best.
1. I run scanstate to gather the settings on my test XP computer.
2. I run loadstate to restore the settings on my test Windows 7 computer.
Critical note: remember, I am using the USMT manifests for both the scanstate and loadstate. If those manifests are not available, my settings will not migrate. If you look very carefully at the debug logs you will see the indications of failure:
"Downlevel Manifests Folder is not present. System component settings will not be gathered."
The ReplacementManifests folder used to service system component manifests is not present. OS settings migration will be done with system component manifests installed onto the system.
The manifests might be missing because:
- You forgot to copy them to the computer.
- The manifest folders are not in the USMT working directory. For example, you are doing this (bad):
C:\>c:\usmt\x86\scanstate.exe c:\store /i:migapp.xml /i:migdocs.xml
C:\>\\server\share\scanstate.exe c:\store /i:migapp.xml /i:migdocs.xml
C:\>c:\usmt\amd64\scanstate.exe c:\store /i:c:\usmt\xml\migdocs.xml /i:c:\usmt\xml\migapp.xml
Instead of doing this (good):
C:\usmt\x86\>scanstate.exe c:\store /i:migapp.xml /i:migdocs.xml
C:\>NET USE U: \\server\share
U:\>scanstate.exe c:\store /i:migapp.xml /i:migdocs.xml
C:\usmt\AMD64>scanstate.exe c:\store /i:c:\usmt\xml\migdocs.xml /i:c:\usmt\xml\migapp.xml
Notice how the executable is running within the folder path in the latter examples. There’s no USMT command-line to provide a path to the manifest folders! You can also run into this issue with SCCM or MDT as well, see:
3. Before I log on to the test destination computer with my test user I load his user registry hive with regedit.exe and validate that the settings transferred:
It looks good so I unload the hive. Don’t forget to do this!
4. Then I logon as the migrated test user, but don’t start Internet Explorer. I examine the registry again and make sure it’s still unchanged. Why this step? The settings could be changing due to:
- A logon script
- A group policy
- The act of logging on itself (as the first logon triggers a number of “personalization” steps that might override certain migrated settings).
5. If I still didn’t know why the data was changing, I’d run Process Monitor in boot logging mode to see when and where the settings changed. That’s a theory though - I’ve never reached this stage using this methodical approach.
Sir Arthur also said, “It is a capital mistake to theorize before one has data.” Sherlock Holmes would have made a good Support Engineer.
These techniques apply throughout USMT, not just with IE settings in a manifest file. I'm often asked about Office and migapp.xml, for example, and the answer is always the same - do the legwork above and you'll know. These techniques also apply to preventing migration of settings - once you know how USMT migrates it, making an unconditionalExclude to prevent it is easy.
For those keeping score: the customer’s issue was the insidious missing manifest folders I pointed out in the validation phase. It happens to nearly everyone once… but never twice. :)
Until next time.
Ned “The game is afoot!” Pyle