Appendix C: Converting Control Files from Previous Versions of USMT

  • Article

Previous versions of the USMT used .inf files to control collection and migration of documents and settings. Many organizations have spent time and resources creating migrations based on this technology. While there are significant differences between the two control file formats, an understanding of how each format controls the USMT can enable developers to create .xml files that closely replicate the effects of the former migrations.

On This Page

A Primer on USMT .inf File Formats A Primer on USMT .inf File Formats
Finding Equivalent Settings in XML Finding Equivalent Settings in XML
Creating a Complete Migration in XML Creating a Complete Migration in XML

A Primer on USMT .inf File Formats

Developers of legacy .inf files should already be familiar with the format and function of the commands in these files. Below is a quick overview of .inf file sections and syntax.

Sections of a USMT .inf File

USMT .inf files are segmented based on the type of migration being performed. Following are examples of the resulting sections:

  • [Applications]. The Applications section defines application settings that the USMT will migrate.

  • [System Settings]. The System Settings section migrates system configuration settings such as fonts and accessibility.

  • [User Settings]. This section migrates user preferences, such as desktop configuration, screen saver settings, and favorites.

  • [Files and Folders]. This section migrates files and folders. Migrations can be specified for specific files, specific folders, and for files and folders based on pattern or file extension.

Other sections exist. See Help from the previous USMT version for a complete listing.

USMT .inf File Syntax

USMT .inf files use commands to control USMT operation. Examples of these commands are listed below. Some examples of .inf command syntax follow each command.

[CopyFiles]

The CopyFiles command specifies files that the migration must copy. The syntax for this command is:

Path\FileName.ext, NewRootPath

Wildcards can be used as well as environment variables. To migrate .doc files from My Documents to the same folder on the new system, use the syntax:

[Copy This State]
CopyFiles=WordDocs
[WordDocs]
%CSIDL_PERSONAL%\*\*.doc, %CSIDL_PERSONAL%
[CopyFilesFiltered]

This command copies only files that are relevant to the new system. For example, if the User State Migration feature team is copying program shortcuts to the desktop of a new system and a link points to a file that will not be migrated, CopyFilesFiltered does not copy the associated .lnk file. Here is an example of the CopyFilesFiltered syntax:

[Copy This State]
CopyFiles=Shortcuts
[Shortcuts]
%CSIDL_DESKTOP%\*.lnk, %CSIDL_DESKTOP%

Note   The CopyFilesFiltered command performs this filtering action during Loadstate.exe execution.

[AddReg]

The syntax for the AddReg command is:

RegRoot\RegKey\RegSubKey [RegValue]

This command migrates registry entries on the destination computer according to the syntax of the command. To migrate an entry that runs Notepad automatically on startup, use the syntax:

Note Some parts of the following code snippet have been displayed in multiple lines only for better readability. These should be entered in a single line.

[Copy This User State]
AddReg=RunNotepad AddReg
[RunNotepad AddReg]
HKCU\Software\Microsoft\Windows\CurrentVersion\Run
\Notepad.exe C:\Windows\system32\notepad.exe

Note   The specified registry key must exist in the source system to be successfully migrated.

[DelReg]

The syntax for the DelReg command is:

RegRoot\RegKey\RegSubKey [RegValue]

This command removes registry entries on the destination computer according to the syntax of the command. To create an entry to remove the AddReg example above, use the syntax:

Note Some parts of the following code snippet have been displayed in multiple lines only for better readability. These should be entered in a single line.

[Copy This User State]
DelReg=RunNotepad DelReg
[RunNotepad DelReg]
HKCU\Software\Microsoft\Windows\CurrentVersion\Run
\Notepad.exe C:\Windows\system32\notepad.exe

Note   This command does not actively delete the defined registry key; it merely excludes it from the migration.

The USMT Help file defines many more commands. See Help from the previous USMT version for a complete listing.

Finding Equivalent Settings in XML

XML language formats differ dramatically from the section-based formatting of .inf files. XML sections are defined by the tags <headings> and </headings>. Syntax within the settings is changed as well. A complete reference is included in the USMT installation folder. See "USMT XML Elements Reference" in USMT.chm for details of XML syntax. This section converts examples from “USMT .inf File Syntax” (above) to XML to illustrate this process.

[CopyFiles]

The following example migrates all .doc files from My Documents on one system to My Documents on another:

<component type="Documents" context="User">
<displayName>User Data</displayName>
 <role role="Data">
  <rules>
  <!-- Migrate all .doc from My Documents to the new system -->
   <include>
    <objectSet>
     <pattern type="File">%CSIDL_PERSONAL%\[*.doc]</pattern>
    </objectSet>
   </include>
  </rules>
 </role>
</component>

[CopyFilesFiltered]

The User State Migration feature team can filter files by first attempting to detect the condition under which team members would migrate the file. If the condition is detected, then the subsequent migration actions would occur; otherwise, Loadstate.exe would ignore the subsequent child statements, as shown in Listing 5.

Listing 5. Using CopyFilesFiltered to Filter Files

Note Some parts of the following code snippet have been displayed in multiple lines only for better readability. These should be entered in a single line.

<component type="Documents" context="User">
<displayName>User Data</displayName>
 <role role="Data">
  <detects>
   <detect>
<condition>MigXmlHelper.DoesObjectExist
("File","%CSIDL_PERSONAL%\MyFile.Doc")</condition>
   </detect>
  </detects>
  <rules>
  <!-- Migrate specific .lnk from My Documents to new system -->
   <include>
    <objectSet>
     <pattern type="File">%CSIDL_DESKTOP%\[MyFile.lnk]</pattern>
    </objectSet>
   </include>
  </rules>
 </role>
</component>

Note   In the above example, the Detect condition must be true for the subsequent Rules instructions to be processed.

[AddReg]

The XML code in Listing 6 migrates a specific registry setting.

Listing 6. Migrate a Specific Registry Setting

Note Some parts of the following code snippet have been displayed in multiple lines only for better readability. These should be entered in a single line.

<migration urlid="https://www.microsoft.com/migration/1.0/migxmlext/test">
 <component type="Application">
 <displayName>Component to migrate only registry value string</displayName>
  <role role="Settings">
   <rules context="UserAndSystem">
    <include>
     <objectSet>
      <pattern type="Registry">HKCU\Software\Microsoft
      \Windows\CurrentVersion\Run [Notepad.exe]</pattern>
     </objectSet>
    </include>
   </rules>
  </role>
 </component>
</migration>

Note   If the registry key specified by the script in Listing 5 does not exist on the source system, it will not be created on the destination system.

[DelReg]

The example in Listing 7 replicates the DelReg action of the former .inf file. (Notice the <exclude>...</exclude> pair.)

Listing 7. The DelReg Command

Note Some parts of the following code snippet have been displayed in multiple lines only for better readability. These should be entered in a single line.

<migration urlid="https://www.microsoft.com/migration/1.0/migxmlext/test">
 <component type="Application">
 <displayName>Component to migrate only registry value string</displayName>
  <role role="Settings">
   <rules context="UserAndSystem">
    <exclude>
     <objectSet>
      <pattern type="Registry">HKCU\Software\Microsoft
      \Windows\CurrentVersion\Run [Notepad.exe]</pattern>
     </objectSet>
    </exclude>
   </rules>
  </role>
 </component>
</migration>

Note   In many cases, it is sufficient simply not to define an object to exclude it from migration. The process above might be necessary when migrating a parent but excluding certain children.

Creating a Complete Migration in XML

Obviously, the User State Migration feature team would have to write a lot of XML code to create a complete conversion. It is important, therefore, to attempt to migrate most settings using the included .xml control files. Running Scanstate with the /genconfig option creates a fairly complete migration. When this migration is complete, create a custom.xml file for the remaining elements that must be migrated. The finished product might be executed with a command similar to the following:

Note Some parts of the following code snippet have been displayed in multiple lines only for better readability. These should be entered in a single line.

Scanstate /config:Migration.xml /i:Migapp.xml 
/i:MigUser.xml /i:CustMigration.xml /l:Migration.log /v:15

Download

Get the Microsoft Solution Accelerator for Business Desktop Deployment 2007

Update Notifications

Sign up to learn about updates and new releases

Feedback

Send us your comments or suggestions