This topic describes the XML helper functions.
In This Topic
General XML Guidelines
Before you modify the .xml files, become familiar with the following guidelines.
- XML schema. You can use the Windows®
User State Migration Tool (USMT) 4.0 XML schema, MigXML.xsd, to
write and validate migration .xml files.
- Conflicts. In general, when there are
conflicts within the XML schema, 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 must specify
the required child elements for the parent element to affect the
migration.
- The required child elements apply only to the
first definition of the element. If these elements are defined and
then referred to using their name, the required child elements do
not apply. For example, if you define <detects
name="Example"> in <namedElements>, and you specify
<detects name="Example"/> in <component> to refer to
this element, the definition inside <namedElements> must have
the required child elements, but the <component> element does
not need to have the required child elements.
- USMT does not fail with an error if you do
not specify the required child elements. However, you must specify
the required child elements for the parent element to affect the
migration.
- File names with brackets. If you are
migrating a file that has a bracket character ([ or ]) in the file
name, you must insert a carat(^) character directly before the
bracket for the bracket character to be valid. For example, if
there is a file named File.txt, you must specify
<pattern type="File">c:\documents\mydocs [file^].txt]</pattern>
instead of<pattern type="File">c:\documents\mydocs [file].txt]</pattern>
.
- Using quotation marks. When you
surround code in quotation marks, you can use either double ("") or
single ('') quotation marks.
Helper Functions
You can use the XML helper functions in the XML Elements Library to change 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 a default value convention, if you have a
NULL parameter at the end of a list, you can leave it out. For
example, the following function:
SomeFunction("My String argument",NULL,NULL)
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 makes a
clear distinction between nodes and leaves.
For example, specify the file C:\Windows\Notepad.exe: c:\Windows[Notepad.exe]. Similarly, specify the directory C:\Windows\System32 like this: c:\Windows\System32; note the absence of the [] characters.
The registry is represented in a similar way. 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 is HKLM\SOFTWARE\MyKey[].
- You specify a location pattern in a way
that is similar 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. To match the files as well, you must specify c:\Windows\*[*].