Conflicts and Precedence

When you include, exclude, and reroute files and settings, it is important to know how USMT deals with conflicts and precedence. The following are the most important guidelines that you should know:

• If there are conflicting rules within a component, the most specific rule is applied. <unconditionalExclude> is an exception because it takes precedence over all others.
• 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 <unconditionalExclude>).
• If the rules are equally specific (if you <exclude> a file, and <include> the same file) then <exclude> takes precedence over <include>.
• The ordering of components does not matter. It does not matter which components are in which .xml files because each component is processed independently of each other across all of the .xml files.
• The ordering of <include> and <exclude> 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, to exclude all .mp3 files on the computer or to exclude all files from C:\UserData.
• 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> Precedence Examples.

In this topic

General

• What is the relationship between rules that are located within different components?
• How does precedence work with Config.xml?
• 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?

<include> and <exclude>

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

File collisions

• What is the default behavior when there are file collisions?
• How does <merge> 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 <unconditionalExclude>). 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 they are independent of each other.

Another example is if you have an <include> rule in one component and a <locationModify> rule in another component for the same file. In this case, the file will 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\* [*]</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 Config.xml?

Specifying migrate="no" in Config.xml 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 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 ScanState and LoadState behavior. For example, <include>, <exclude>, and <unconditionalExclude>. These 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 only LoadState behavior. For example, <locationModify>, <contentmodify>, and <destinationCleanup>. These rules do not affect ScanState — they are only processed with LoadState. First, LoadState 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.

For more information, see USMT Internal Workflow.

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. USMT processes each component within the files separately. The only reason that USMT supports having multiple .xml files is to make it easier to maintain and organize the components within them. Just make sure that each .xml file that you specify on the command line has a unique migration urlid. This is because USMT uses the urlid to distinguish each component from each other.

<include> and <exclude>

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 <unconditionalExclude>, which takes precedence over all others). If the rules are equally specific (if you exclude a file, and include the same file), then the data will be not be migrated. If there are conflicting rules within different components, then the rules do not affect each other since 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> precedence examples

These examples explain the behavior when you have both <include> rules 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 <exclude> takes precedence over <include>.
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 <unconditionalExclude>). Therefore, in this example although some .txt files were excluded when Component 1 was processed, they were included in 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 for 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 include rule is more specific than exclude rule.
Include rule: HKLM\Software\Microsoft\Command Processor [DefaultColor] Exclude rule: HKLM\Software\Microsoft\Command Processor [DefaultColor]	Does not migrate Default Color.	The rules are equally specific so <exclude> takes precedence over <include>.

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 <unconditionalExclude>). Therefore, in this example, the objects that were excluded when Component 1 was processed were included in 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.

How does <merge> 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, you have a merge rule for C:\* [*] set to sourcePriority() and another merge rule for C:\subfolder\* [*] set to destinationPriority(), then USMT would use 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.