Conflicts and Precedence

  • Article

Applies To: Windows 7, Windows 8, Windows 8.1, Windows Vista

When you include, exclude, and reroute files and settings, it is important to know how User State Migration Tool (USMT) 5.0 deals with conflicts and precedence. When working with USMT, the following are the most important conflicts and precedence guidelines to keep in mind.

  • If there are conflicting rules within a component, the most specific rule is applied. However, the <unconditionalExclude> rule is an exception because it takes precedence over all others. Directory names take precedence over file extensions. For examples, see What happens when there are conflicting <include> and <exclude> rules? and the first example in <include> and <exclude> rules precedence exampleslater in this topic.

  • Only rules inside the same component can affect each other, depending on specificity. Rules that are in different components do not affect each other, except for the <unconditionalExclude> rule.

  • If the rules are equally specific, <exclude> takes precedence over <include>. For example, if you use the <exclude> rule to exclude a file and use the <include> rule to include the same file, the file will be excluded.

  • The ordering of components does not matter. It does not matter which components are listed in which .xml file, because each component is processed independently of the other components across all of the .xml files.

  • The ordering of the <include> and <exclude> rules within a component does not matter.

  • You can use the <unconditionalExclude> element to globally exclude data. This element excludes objects, regardless of any other <include> rules that are in the .xml files. For example, you can use the <unconditionalExclude> element to exclude all MP3 files on the computer or to exclude all files from C:\UserData.

In This Topic

General

  • What is the relationship between rules that are located within different components?

  • How does precedence work with the Config.xml file?

  • How does USMT process each component in an .xml file with multiple components?

  • How are rules processed?

  • How does USMT combine all of the .xml files that I specify on the command line?

The <include> and <exclude> rules

  • What happens when there are conflicting <include> and <exclude> rules?

  • <include> and <exclude> rules precedence examples

File collisions

  • What is the default behavior when there are file collisions?

  • How does the <merge> rule work when there are file collisions?

General

What is the relationship between rules that are located within different components?

Only rules inside the same component can affect each other, depending on specificity, except for the <unconditionalExclude> rule. Rules that are in different components do not affect each other. If there is an <include> rule in one component and an identical <exclude> rule in another component, the data will be migrated because the two rules are independent of each other.

If you have an <include> rule in one component and a <locationModify> rule in another component for the same file, the file will be migrated in both places. That is, it will be included based on the <include> rule, and it will be migrated based on the <locationModify> rule.

The following .xml file migrates all files from C:\Userdocs, including .mp3 files, because the <exclude> rule is specified in a separate component.

<migration urlid="https://www.microsoft.com/migration/1.0/migxmlext/UserDocs">
<component type="Documents" context="System">
<displayName>User Documents</displayName>
        <role role="Data">
            <rules>
                <exclude>
                    <objectSet>
                        <pattern type="File">C:\Userdocs\* [*.mp3]</pattern>
                    </objectSet>
                </exclude>
          </rules>
        </role>
</component>

<component type="Documents" context="System">
<displayName> User documents to include </displayName>
        <role role="Data">
            <rules>
                <include>
                    <objectSet>
                        <pattern type="File"> C:\Userdocs\ [*]</pattern>
                    </objectSet>
                </include>
          </rules>
        </role>
</component>
</migration>

How does precedence work with the Config.xml file?

Specifying migrate="no" in the Config.xml file is the same as deleting the corresponding component from the migration .xml file. However, if you set migrate="no" for My Documents, but you have a rule similar to the one shown below in a migration .xml file (which includes all of the .doc files from My Documents), then only the .doc files will be migrated, and all other files will be excluded.

<include>
   <objectSet>
      <pattern type="File">%CSIDL_PERSONAL%\* [*.doc] </pattern>
   </objectSet>
</include>

How does USMT process each component in an .xml file with multiple components?

The ordering of components does not matter. Each component is processed independently of other components. For example, if you have an <include> rule in one component and a <locationModify> rule in another component for the same file, the file will be migrated in both places. That is, it will be included based on the <include> rule, and it will be migrated based on the <locationModify> rule.

How are rules processed?

There are two broad categories of rules.

  • Rules that affect the behavior of both the ScanState and LoadState tools. For example, the <include>, <exclude>, and <unconditionalExclude> rules are processed for each component in the .xml files. For each component, USMT creates an include list and an exclude list. Some of the rules in the component might be discarded due to specificity, but all of the remaining rules are processed. For each <include> rule, USMT iterates through the elements to see if any of the locations need to be excluded. USMT enumerates all of the objects and creates a list of objects it is going to collect for each user. Once the list is complete, each of the objects is stored or migrated to the destination computer.

  • Rules that affect the behavior of only the LoadState tool. For example, the <locationModify>, <contentModify>, and <destinationCleanup> rules do not affect ScanState. They are processed only with LoadState. First, the LoadState tool determines the content and location of each component based on the <locationModify>and <contentModify> rules. Then, LoadState processes all of the <destinationCleanup> rules and deletes data from the destination computer. Lastly, LoadState applies the components to the computer.

How does USMT combine all of the .xml files that I specify on the command line?

USMT does not distinguish the .xml files based on their name or content. It processes each component within the files separately. USMT supports multiple .xml files only to make it easier to maintain and organize the components within them. Because USMT uses a urlid to distinguish each component from the others, be sure that each .xml file that you specify on the command line has a unique migration urlid.

The <include> and <exclude> rules

What happens when there are conflicting <include> and <exclude> rules?

If there are conflicting rules within a component, the most specific rule is applied, except with the <unconditionalExclude> rule, which takes precedence over all other rules. If the rules are equally specific, then the data will be not be migrated. For example if you exclude a file, and include the same file, the file will not be migrated. If there are conflicting rules within different components, the rules do not affect each other because each component is processed independently.

In the following example, mp3 files will not be excluded from the migration. This is because directory names take precedence over the file extensions.

<include>
     <objectSet>
          <pattern type="File">C:\Data\* [*]</pattern>
     </objectSet>
</include>
<exclude>
     <objectSet>
          <pattern type="File"> C:\* [*.mp3]</pattern>
     </objectSet>
</exclude>

<include> and <exclude> rules precedence examples

These examples explain how USMT deals with <include> and <exclude> rules. When the rules are in different components, the resulting behavior will be the same regardless of whether the components are in the same or in different migration .xml files.

  • Including and excluding files

  • Including and excluding registry objects

Including and excluding files

If you have the following code in the same component Resulting behavior Explanation
  • Include rule: <pattern type="File">C:\Dir1\* [*]</pattern>

  • Exclude rule: <pattern type="File">C:\* [*.txt]</pattern>

Migrates all files and subfolders in Dir1 (including all .txt files in C:).

The <exclude> rule does not affect the migration because the <include> rule is more specific.
  • Include rule: <pattern type="File">C:\Dir1\* [*]</pattern>

  • Exclude rule: <pattern type="File">C:\Dir1\Dir2\* [*.txt]</pattern>

Migrates all files and subfolders in C:\Dir1, except the .txt files in C:\Dir1\Dir2 and its subfolders.

Both rules are processed as intended.
  • Include rule: <pattern type="File">C:\Dir1\* [*]</pattern>

  • Exclude rule: <pattern type="File">C:\Dir1\ * [*.txt]</pattern>

Migrates all files and subfolders in C:\Dir1, except the .txt files in C:\Dir1 and its subfolders.

Both rules are processed as intended.
  • Include rule: <pattern type="File">C:\Dir1\Dir2\* [*.txt]</pattern>

  • Exclude rule: <pattern type="File">C:\Dir1\Dir2\* [*.txt]</pattern>

Nothing will be migrated.

The rules are equally specific, so the <exclude> rule takes precedence over the <include> rule.
  • Include rule: C:\Dir1\* [*.txt]

  • Exclude rule: C:\Dir1\Dir2\* [*]

Migrates the .txt files in Dir1 and the .txt files from subfolders other than Dir2.

No files are migrated from Dir2 or its subfolders.

Both rules are processed as intended.
  • Include rule: C:\Dir1\Dir2\* [*]

  • Exclude rule: C:\Dir1\* [*.txt]

Migrates all files and subfolders of Dir2, except the .txt files from Dir1 and any subfolders of Dir1 (including Dir2).

Both rules are processed as intended.
If you have the following code in different components Resulting behavior Explanation

Component 1:

  • Include rule: <pattern type="File">C:\Dir1\* [*]</pattern>

  • Exclude rule: <pattern type="File">C:\Dir1\Dir2\* [*.txt]</pattern>

Component 2:

  • Include rule: <pattern type="File">C:\Dir1\Dir2\* [*.txt]</pattern>

  • Exclude rule: <pattern type="File">C:\Dir1\* [*]</pattern>

Migrates all files and subfolders of C:\Dir1\ (including C:\Dir1\Dir2\).

Rules that are in different components do not affect each other, except for the <unconditionalExclude> rule. Therefore, in this example, although some .txt files were excluded when Component 1 was processed, they were included when Component 2 was processed.

Component 1:

  • Include rule: C:\Dir1\Dir2\* [*]

Component 2:

  • Exclude rule: C:\Dir1\* [*.txt]

Migrates all files and subfolders from Dir2 except the .txt files in C:\Dir1 and its subfolders.

Both rules are processed as intended.

Component 1:

  • Exclude rule: C:\Dir1\Dir2\* [*]

Component 2:

  • Include rule: C:\Dir1\* [*.txt]

Migrates all .txt files in Dir1 and any subfolders.

Component 1 does not contain an <include> rule, so the <exclude> rule is not processed.

Including and excluding registry objects

If you have the following code in the same component Resulting behavior Explanation
  • Include rule: HKLM\Software\Microsoft\Command Processor\* [*]

  • Exclude Rule: HKLM\Software\Microsoft\Command Processor [DefaultColor]

Migrates all keys in HKLM\Software\Microsoft\Command Processor except DefaultColor.

Both rules are processed as intended.
  • Include rule: HKLM\Software\Microsoft\Command Processor [DefaultColor]

  • Exclude Rule: HKLM\Software\Microsoft\Command Processor\* [*]

Migrates only DefaultColor in HKLM\Software\Microsoft\Command Processor.

DefaultColor is migrated because the <include> rule is more specific than the <exclude> rule.
  • Include rule: HKLM\Software\Microsoft\Command Processor [DefaultColor]

  • Exclude rule: HKLM\Software\Microsoft\Command Processor [DefaultColor]

Does not migrate DefaultColor.

The rules are equally specific, so the <exclude> rule takes precedence over the <include> rule.
If you have the following code in different components Resulting behavior Explanation

Component 1:

  • Include rule: HKLM\Software\Microsoft\Command Processor [DefaultColor]

  • Exclude rule: HKLM\Software\Microsoft\Command Processor\* [*]

Component 2:

  • Include rule: HKLM\Software\Microsoft\Command Processor\* [*]

  • Exclude rule: HKLM\Software\Microsoft\Command Processor [DefaultColor]

Migrates all the keys/values under HKLM\Software\Microsoft\Command Processor.

Rules that are in different components do not affect each other, except for the <unconditionalExclude> rule. Therefore, in this example, the objects that were excluded when Component 1 was processed were included when Component 2 was processed.

File collisions

What is the default behavior when there are file collisions?

If there is not a <merge> rule, the default behavior for the registry is for the source to overwrite the destination. The default behavior for files is for the source to be renamed incrementally: for example, OriginalFileName(1).OriginalExtension, OriginalFileName(2).OriginalExtension, and so on.

How does the <merge> rule work when there are file collisions?

When a collision is detected, USMT will select the most specific <merge> rule and apply it to resolve the conflict. For example, if you have a <merge> rule for C:\* [*] set to sourcePriority() and another <merge> rule for C:\subfolder\* [*] set to destinationPriority(), then USMT uses the destinationPriority() rule because it is the most specific.

Example scenario

The source computer contains the following files:

  • C:\Data\SampleA.txt

  • C:\Data\SampleB.txt

  • C:\Data\Folder\SampleB.txt

The destination computer contains the following files:

  • C:\Data\SampleB.txt

  • C:\Data\Folder\SampleB.txt

You have a custom .xml file that contains the following code:

<include> 
   <objectSet> 
      <pattern type="File">c:\data\* [*]</pattern> 
   </objectSet> 
</include>

For this example, the following table describes the resulting behavior if you add the code in the first column to your custom .xml file.

If you specify the following code Resulting behavior 
<merge script="MigXmlHelper.DestinationPriority()"> 
   <objectSet> 
      <pattern type="File">c:\data\* [*]</pattern> 
   </objectSet> 
</merge>

During ScanState, all the files will be added to the store.

During LoadState, only C:\Data\SampleA.txt will be restored.

 
<merge script="MigXmlHelper.SourcePriority()"> 
   <objectSet> 
      <pattern type="File">c:\data\* [*]</pattern> 
   </objectSet> 
</merge>

During ScanState, all the files will be added to the store.

During LoadState, all the files will be restored, overwriting the existing files on the destination computer.

 
<merge script="MigXmlHelper.SourcePriority()"> 
   <objectSet> 
      <pattern type="File">c:\data\ [*]</pattern> 
   </objectSet> 
</merge>

During ScanState, all the files will be added to the store.

During LoadState, the following will occur:

  • C:\Data\SampleA.txt will be restored.

  • C:\Data\SampleB.txt will be restored, overwriting the existing file on the destination computer.

  • C:\Data\Folder\SampleB.txt will not be restored.

See Also

Other Resources

USMT XML Reference