General Conventions

  • Article

XML

Before you modify the .xml files, note the following:

  • XML schema. You can use the USMT XML schema (MigXML.xsd) to write and validate migration .xml files.
  • Conflicts. In general, when there are conflicts within the XML, the most specific pattern takes precedence. For more information, see Conflicts and Precedence.
  • Required elements. The required elements for a migration .xml file are <migration>, <component>, <role>, and <rules>.
  • Required child elements.
    • USMT does not fail with an error if you do not specify the "Required child elements". However, you need to specify the required child elements in order for the parent element to be meaningful (that is, for it to effect the migration).
    • The required child elements only apply to the first definition of the element. If these elements are defined, and then referred to using their name, then the required child elements do not apply. For example, if you define <detects name="Example"> in <namedElements>, and then you specify <detects name="Example"/> in <component> to refer to this element, then the definition inside <namedElement> must have the required child elements — but the <component> element does not need to.
  • File names with brackets. If you are migrating a file that has a bracket character ([ or ]) in the file name, you need to insert the "^" character directly before the bracket in order for it to be valid. For example, if there is a file named "file].txt", you will need to specify <pattern type="File">c:\documents\mydocs [file^].txt]</pattern> instead of <pattern type=”File”>c:\documents\mydocs [file].txt]</pattern>.
  • Using quotes. When you surround code in quotes, you can use either double quotes ("") or single quotes ('').

Helper functions

You can use the following functions to change the migration behavior. Before you use these functions in an .xml file, note the following:

  • All of the parameters are strings.

  • You can leave NULL parameters blank. As with parameters with default value convention, if you have a NULL parameter at the end of a list, you can leave them out. For example, the following function:

    SomeFunction("My String argument",NULL,NULL)

    is equivalent to:

    SomeFunction("My String argument")

  • The encoded location used in all the helper functions is an unambiguous string representation for the name of an object. It is composed of the node part, optionally followed by the leaf enclosed in square brackets. This way, there is a clear distinction between nodes and leaves.
    For example, you should specify the file C:\Windows\Notepad.exe like this: c:\Windows[Notepad.exe]. Similarly, you should specify the directory C:\Windows\System32 like this: c:\Windows\System32 (notice the absence of the [] construct).
    Representing the registry is very similar. The default value of a registry key is represented as an empty [] construct. For example, the default value for the HKLM\SOFTWARE\MyKey registry key will be HKLM\SOFTWARE\MyKey[].

  • You specify a location pattern in a similar way to how you specify an actual location. The exception is that both the node and leaf part accept patterns. However, a pattern from the node does not extend to the leaf.
    For example, the pattern c:\Windows\* will match the Windows directory and all subdirectories, but it will not match any of the files in those directories. In order to match the files as well, you need to specify c:\Windows\*[*].