From 427f52ab2df0f8edee612cbd3eb68fb44f35049d Mon Sep 17 00:00:00 2001 From: Mandi Ohlinger Date: Wed, 1 Dec 2021 21:47:32 -0500 Subject: [PATCH] Added missing code tags --- .../usmt/usmt-xml-elements-library.md | 589 +++++++++--------- 1 file changed, 308 insertions(+), 281 deletions(-) diff --git a/windows/deployment/usmt/usmt-xml-elements-library.md b/windows/deployment/usmt/usmt-xml-elements-library.md index b28a1c4930..7077db2d80 100644 --- a/windows/deployment/usmt/usmt-xml-elements-library.md +++ b/windows/deployment/usmt/usmt-xml-elements-library.md @@ -54,13 +54,14 @@ The <addObjects> element emulates the existence of one or more objects on Syntax: -<addObjects> - -</addObjects> +```xml + + +``` The following example is from the MigApp.xml file: -``` xml +```xml %HklmWowSoftware%\Microsoft\Office\12.0\Common\Migration\Office [UpgradeVersion] @@ -87,7 +88,9 @@ The <attributes> element defines the attributes for a registry key or file Syntax: -<attributes>*Content*</attributes> +```xml +Content +``` | Setting | Required? | Value | |------|-----|----| @@ -95,7 +98,7 @@ Syntax: The following example is from the MigApp.xml file: -``` xml +```xml %HklmWowSoftware%\Microsoft\Office\12.0\Common\Migration\Office [Lang] DWORD @@ -115,7 +118,9 @@ You must specify the <bytes> element only for files because, if <locati Syntax: -<bytes string="Yes|No" expand="Yes|No">*Content*</bytes> +```xml +Content +``` |Setting|Required?|Value| |--- |--- |--- | @@ -125,7 +130,7 @@ Syntax: The following example is from the MigApp.xml file: -``` xml +```xml %HklmWowSoftware%\Microsoft\Office\12.0\Common\Migration\Office [Lang] DWORD @@ -146,7 +151,9 @@ You might want to use the <commandLine> element if you want to start or st Syntax: -<commandLine>*CommandLineString*</commandLine> +```xml +CommandLineString +``` |Setting|Required?|Value| |--- |--- |--- | @@ -168,11 +175,11 @@ A component can be nested inside another component; that is, the <component&g Syntax: -<component type="System|Application|Device|Documents" context="User|System|UserAndSystem" defaultSupported="TRUE|FALSE|YES|NO" - -hidden="Yes|No"> - -</component> +```xml + + +``` |Setting|Required?|Value| |--- |--- |--- | @@ -199,7 +206,9 @@ The <condition> element has a Boolean result. You can use this element to Syntax: -<condition negation="Yes|No">*ScriptName*</condition> +```xml +ScriptName +``` |Setting|Required?|Value| |--- |--- |--- | @@ -210,7 +219,7 @@ For example, In the code sample below, the <condition> elements, A and B, are joined together by the AND operator because they are in separate <conditions> sections. For example: -``` xml +```xml A @@ -223,7 +232,7 @@ In the code sample below, the <condition> elements, A and B, are joined to However, in the code sample below, the <condition> elements, A and B, are joined together by the OR operator because they are in the same <conditions> section. -``` xml +```xml A @@ -246,18 +255,18 @@ The <condition> functions return a Boolean value. You can use these elemen All matches are case insensitive. - Syntax: DoesOSMatch("*OSType*","*OSVersion*") + Syntax: `DoesOSMatch("OSType","OSVersion")` |Setting|Required?|Value| |--- |--- |--- | |*OSType*|Yes|The only valid value for this setting is **NT**. Note, however, that you must set this setting for the <condition> functions to work correctly.| |*OSVersion*|Yes|The major version, minor version, build number and corrected service diskette version separated by periods. For example, `5.0.2600.Service Pack 1`. You can also specify partial specification of the version with a pattern. For example, `5.0.*`.| -~~~ -For example: + For example: -<condition>MigXmlHelper.DoesOSMatch("NT","\*")</condition> -~~~ + ```xml + MigXmlHelper.DoesOSMatch("NT","\*") + ``` - **IsNative64Bit** @@ -267,24 +276,24 @@ For example: All comparisons are case insensitive. - Syntax: IsOSLaterThan("*OSType*","*OSVersion*") + Syntax: `IsOSLaterThan("OSType","OSVersion")` |Setting|Required?|Value| |--- |--- |--- | |*OSType*|Yes|Can be **9x** or **NT**. If *OSType* does not match the type of the current operating system, then it returns FALSE. For example, if the current operating system is Windows NT-based and *OSType* is "9x", the result will be FALSE.| |*OSVersion*|Yes|The major version, minor version, build number, and corrected service diskette version separated by periods. For example, `5.0.2600.Service Pack 1`. You can also specify partial specification of the version but no pattern is allowed. For example, `5.0`.

The IsOSLaterThan function returns TRUE if the current operating system is later than or equal to *OSVersion*.| -~~~ -For example: + For example: -<condition negation="Yes">MigXmlHelper.IsOSLaterThan("NT","6.0")</condition> -~~~ + ```xml + MigXmlHelper.IsOSLaterThan("NT","6.0") + ``` - **IsOSEarlierThan** All comparisons are case insensitive. - Syntax: IsOSEarlierThan("*OSType*","*OSVersion*") + Syntax: `IsOSEarlierThan("OSType","OSVersion")` |Setting|Required?|Value| |--- |--- |--- | @@ -298,22 +307,20 @@ For example: The DoesObjectExist function returns TRUE if any object exists that matches the location pattern. Otherwise, it returns FALSE. The location pattern is expanded before attempting the enumeration. - Syntax: DoesObjectExist("*ObjectType*","*EncodedLocationPattern*") + Syntax: `DoesObjectExist("ObjectType","EncodedLocationPattern")` |Setting|Required?|Value| |--- |--- |--- | |*ObjectType*|Yes|Defines the object type. Can be File or Registry.| |*EncodedLocationPattern*|Yes|The [location pattern](#locations). Environment variables are allowed.| -~~~ -For an example of this element, see the MigApp.xml file. -~~~ + For an example of this element, see the MigApp.xml file. - **DoesFileVersionMatch** The pattern check is case insensitive. - Syntax: DoesFileVersionMatch("*EncodedFileLocation*","*VersionTag*","*VersionValue*") + Syntax: `DoesFileVersionMatch("EncodedFileLocation","VersionTag","VersionValue")` |Setting|Required?|Value| |--- |--- |--- | @@ -321,19 +328,17 @@ For an example of this element, see the MigApp.xml file. |*VersionTag*|Yes|The [version tag](#allowed) value that will be checked.| |*VersionValue*|Yes|A string pattern. For example, "Microsoft*".| -~~~ -For example: + For example: -<condition>MigXmlHelper.DoesFileVersionMatch("%MSNMessengerInstPath%\\msnmsgr.exe","ProductVersion","6.\*")</condition> - -<condition>MigXmlHelper.DoesFileVersionMatch("%MSNMessengerInstPath%\\msnmsgr.exe","ProductVersion","7.\*")</condition> -~~~ + ```xml + MigXmlHelper.DoesFileVersionMatch("%MSNMessengerInstPath%\\msnmsgr.exe","ProductVersion","6.\*") MigXmlHelper.DoesFileVersionMatch("%MSNMessengerInstPath%\\msnmsgr.exe","ProductVersion","7.\*") + ``` - **IsFileVersionAbove** The IsFileVersionAbove function returns TRUE if the version of the file is higher than *VersionValue*. - Syntax: IsFileVersionAbove("*EncodedFileLocation*","*VersionTag*","*VersionValue*") + Syntax: `IsFileVersionAbove("EncodedFileLocation","VersionTag","VersionValue")` |Setting|Required?|Value| |--- |--- |--- | @@ -343,7 +348,7 @@ For example: - **IsFileVersionBelow** - Syntax: IsFileVersionBelow("*EncodedFileLocation*","*VersionTag*","*VersionValue*") + Syntax: `IsFileVersionBelow("EncodedFileLocation","VersionTag","VersionValue")` |Setting|Required?|Value| |--- |--- |--- | @@ -355,13 +360,13 @@ For example: The IsSystemContext function returns TRUE if the current context is "System". Otherwise, it returns FALSE. - Syntax: IsSystemContext() + Syntax: `IsSystemContext()` - **DoesStringContentEqual** The DoesStringContentEqual function returns TRUE if the string representation of the given object is identical to `StringContent`. - Syntax: DoesStringContentEqual("*ObjectType*","*EncodedLocation*","*StringContent*") + Syntax: `DoesStringContentEqual("ObjectType","EncodedLocation","StringContent")` |Setting|Required?|Value| |--- |--- |--- | @@ -369,19 +374,17 @@ For example: |*EncodedLocationPattern*|Yes|The [encoded location](#locations) for the object that will be examined. You can specify environment variables.| |StringContent|Yes|The string that will be checked against.| -~~~ -For example: + For example: -``` xml -MigXmlHelper.DoesStringContentEqual("File","%USERNAME%","") -``` -~~~ + ```xml + MigXmlHelper.DoesStringContentEqual("File","%USERNAME%","") + ``` - **DoesStringContentContain** The DoesStringContentContain function returns TRUE if there is at least one occurrence of *StrToFind* in the string representation of the object. - Syntax: DoesStringContentContain("*ObjectType*","*EncodedLocation*","*StrToFind*") + Syntax: `DoesStringContentContain("ObjectType","EncodedLocation","StrToFind")` |Setting|Required?|Value| |--- |--- |--- | @@ -393,7 +396,7 @@ For example: The IsSameObject function returns TRUE if the given encoded locations resolve to the same physical object. Otherwise, it returns FALSE. - Syntax: IsSameObject("*ObjectType*","*EncodedLocation1*","*EncodedLocation2*") + Syntax: `IsSameObject("ObjectType","EncodedLocation1","EncodedLocation2")` |Setting|Required?|Value| |--- |--- |--- | @@ -401,22 +404,20 @@ For example: |*EncodedLocation1*|Yes|The [encoded location](#locations) for the first object. You can specify environment variables.| |*EncodedLocation2*|Yes|The [encoded location](#locations) for the second object. You can specify environment variables.| -~~~ -For example: + For example: -``` xml - + ```xml + MigXmlHelper.IsSameObject("File","%CSIDL_FAVORITES%","%CSIDL_COMMON_FAVORITES%") %CSIDL_FAVORITES%\* [*] - -``` -~~~ + + ``` - **IsSameContent** The IsSameContent function returns TRUE if the given objects have the same content. Otherwise, it returns FALSE. The content will be compared byte by byte. - Syntax: IsSameContent("*ObjectType1*","*EncodedLocation1*","*ObjectType2*","*EncodedLocation2*") + Syntax: `IsSameContent("ObjectType1","EncodedLocation1","ObjectType2","EncodedLocation2")` |Setting|Required?|Value| |--- |--- |--- | @@ -429,7 +430,7 @@ For example: The IsSameStringContent function returns TRUE if the given objects have the same content. Otherwise, it returns FALSE. The content will be interpreted as a string. - Syntax: IsSameStringContent("*ObjectType1*","*EncodedLocation1*","*ObjectType2*","*EncodedLocation2*") + Syntax: `IsSameStringContent("ObjectType1","EncodedLocation1","ObjectType2","EncodedLocation2")` |Setting|Required?|Value| |--- |--- |--- | @@ -450,9 +451,10 @@ The <conditions> element returns a Boolean result that is used to specify Syntax: -<conditions operation="AND|OR"> - -</conditions> +```xml + + +``` |Setting|Required?|Value| |--- |--- |--- | @@ -460,7 +462,7 @@ Syntax: The following example is from the MigApp.xml file: -``` xml +```xml MigXmlHelper.IsNative64Bit() @@ -485,9 +487,10 @@ You can use the <content> element to specify a list of object patterns to Syntax: -<content filter="*ScriptInvocation*"> - -</content> +```xml + + +``` |Setting|Required?|Value| |--- |--- |--- | @@ -501,26 +504,24 @@ The following functions generate patterns out of the content of an object. These If the registry value is a MULTI-SZ, only the first segment is processed. The returned pattern is the encoded location for a file that must exist on the system. If the specification is correct in the registry value, but the file does not exist, this function returns NULL. - Syntax: ExtractSingleFile(*Separators*,*PathHints*) + Syntax: `ExtractSingleFile(Separators,PathHints)` |Setting|Required?|Value| |--- |--- |--- | |*Separators*|Yes|A list of possible separators that might follow the file specification in this registry value name. For example, if the content is "C:\Windows\Notepad.exe,-2", the separator is a comma. You can specify NULL.| |*PathHints*|Yes|A list of extra paths, separated by colons (;), where the function will look for a file matching the current content. For example, if the content is "Notepad.exe" and the path is the %Path% environment variable, the function will find Notepad.exe in %windir% and returns "c:\Windows [Notepad.exe]". You can specify NULL.| -~~~ -For example: + For example: -``` xml - -``` + ```xml + + ``` -and + and -``` xml - -``` -~~~ + ```xml + + ``` - **ExtractMultipleFiles** @@ -528,7 +529,7 @@ and The returned patterns are the encoded locations for files that must exist on the source computer. If the specification is correct in the registry value but the file does not exist, it will not be included in the resulting list. - Syntax: ExtractMultipleFiles(*Separators*,*PathHints*) + Syntax: `ExtractMultipleFiles(Separators,PathHints)` |Setting|Required?|Value| |--- |--- |--- | @@ -539,7 +540,7 @@ and The ExtractDirectory function returns a pattern that is the encoded location for a directory that must exist on the source computer. If the specification is correct in the registry value, but the directory does not exist, this function returns NULL. If it is processing a registry value that is a MULTI-SZ, only the first segment will be processed. - Syntax: ExtractDirectory(*Separators*,*LevelsToTrim*,*PatternSuffix*) + Syntax: `ExtractDirectory(Separators,LevelsToTrim,PatternSuffix)` |Setting|Required?|Value| |--- |--- |--- | @@ -547,19 +548,17 @@ and |*LevelsToTrim*|Yes|The number of levels to delete from the end of the directory specification. Use this function to extract a root directory when you have a registry value that points inside that root directory in a known location.| |*PatternSuffix*|Yes|The pattern to add to the directory specification. For example, `* [*]`.| -~~~ -For example: + For example: -``` xml - + ```xml + %HklmWowSoftware%\Classes\Software\RealNetworks\Preferences\DT_Common [] - -``` -~~~ + + ``` ## <contentModify> @@ -575,9 +574,10 @@ The <contentModify> element modifies the content of an object before it is Syntax: -<contentModify script="*ScriptInvocation*"> - -</contentModify> +```xml + + +``` |Setting|Required?|Value| |--- |--- |--- | @@ -591,7 +591,7 @@ The following functions change the content of objects as they are migrated. Thes The ConvertToDWORD function converts the content of registry values that are enumerated by the parent <ObjectSet> element to a DWORD. For example, ConvertToDWORD will convert the string "1" to the DWORD 0x00000001. If the conversion fails, then the value of DefaultValueOnError will be applied. - Syntax: ConvertToDWORD(*DefaultValueOnError*) + Syntax: `ConvertToDWORD(DefaultValueOnError)` |Setting|Required?|Value| |--- |--- |--- | @@ -601,35 +601,33 @@ The following functions change the content of objects as they are migrated. Thes The ConvertToString function converts the content of registry values that match the parent <ObjectSet> element to a string. For example, it will convert the DWORD 0x00000001 to the string "1". If the conversion fails, then the value of DefaultValueOnError will be applied. - Syntax: ConvertToString(*DefaultValueOnError*) + Syntax: `ConvertToString(DefaultValueOnError)` |Setting|Required?|Value| |--- |--- |--- | |*DefaultValueOnError*|No|The value that will be written into the value name if the conversion fails. You can specify NULL, and 0 will be written if the conversion fails.| -~~~ -For example: + For example: -``` xml - + ```xml + HKCU\Control Panel\Desktop [ScreenSaveUsePassword] - -``` -~~~ + + ``` - **ConvertToBinary** The ConvertToBinary function converts the content of registry values that match the parent <ObjectSet> element to a binary type. - Syntax: ConvertToBinary () + Syntax: `ConvertToBinary ()` - **OffsetValue** The OffsetValue function adds or subtracts *Value* from the value of the migrated object, and then writes the result back into the registry value on the destination computer. For example, if the migrated object is a DWORD with a value of 14, and the *Value* is "-2", the registry value will be 12 on the destination computer. - Syntax: OffsetValue(*Value*) + Syntax: `OffsetValue(Value)` |Setting|Required?|Value| |--- |--- |--- | @@ -639,7 +637,7 @@ For example: The SetValueByTable function matches the value from the source computer to the source table. If the value is there, the equivalent value in the destination table will be applied. If the value is not there, or if the destination table has no equivalent value, the *DefaultValueOnError* will be applied. - Syntax: SetValueByTable(*SourceTable*,*DestinationTable*,*DefaultValueOnError*) + Syntax: `SetValueByTable(SourceTable,DestinationTable,DefaultValueOnError)` |Setting|Required?|Value| |--- |--- |--- | @@ -651,7 +649,7 @@ For example: You can use the KeepExisting function when there are conflicts on the destination computer. This function will keep (not overwrite) the specified attributes for the object that is on the destination computer. - Syntax: KeepExisting("*OptionString*","*OptionString*","*OptionString*",…) + Syntax: `KeepExisting("OptionString","OptionString","OptionString",…)` |Setting|Required?|Value| |--- |--- |--- | @@ -661,7 +659,7 @@ For example: The MergeMultiSzContent function merges the MULTI-SZ content of the registry values that are enumerated by the parent <ObjectSet> element with the content of the equivalent registry values that already exist on the destination computer. `Instruction` and `String` either remove or add content to the resulting MULTI-SZ. Duplicate elements will be removed. - Syntax: MergeMultiSzContent (*Instruction*,*String*,*Instruction*,*String*,…) + Syntax: `MergeMultiSzContent (Instruction,String,Instruction,String,…)` |Setting|Required?|Value| |--- |--- |--- | @@ -672,7 +670,7 @@ For example: The MergeDelimitedContent function merges the content of the registry values that are enumerated by the parent <ObjectSet> element with the content of the equivalent registry values that already exist on the destination computer. The content is considered a list of elements separated by one of the characters in the Delimiters parameter. Duplicate elements will be removed. - Syntax: MergeDelimitedContent(*Delimiters*,*Instruction*,*String*,…) + Syntax: `MergeDelimitedContent(Delimiters,Instruction,String,…)` |Setting|Required?|Value| |--- |--- |--- | @@ -692,7 +690,9 @@ The <description> element defines a description for the component but does Syntax: -<description>*ComponentDescription*</description> +```xml +ComponentDescription +``` |Setting|Required?|Value| |--- |--- |--- | @@ -700,7 +700,7 @@ Syntax: The following code sample shows how the <description> element defines the "My custom component" description.: -``` xml +```xml My custom component ``` @@ -708,8 +708,8 @@ The following code sample shows how the <description> element defines the The <destinationCleanup> element deletes objects, such as files and registry keys, from the destination computer before applying the objects from the source computer. This element is evaluated only when the LoadState tool is run on the destination computer. That is, this element is ignored by the ScanState tool. -**Important** -Use this option with extreme caution because it will delete objects from the destination computer. +> [!IMPORTANT] +> Use this option with extreme caution because it will delete objects from the destination computer. @@ -723,9 +723,10 @@ For each <destinationCleanup> element there can be multiple <objectSet& Syntax: -<destinationCleanup filter=*ScriptInvocation*> - -</destinationCleanup> +```xml + + +``` |Setting|Required?|Value| |--- |--- |--- | @@ -733,7 +734,7 @@ Syntax: For example: -``` xml +```xml HKCU\Software\Lotus\123\99.0\DDE Preferences\* [*] @@ -760,9 +761,10 @@ For each <detect> element there can be multiple child <condition> or Syntax: -<detect name="*ID*" context="User|System|UserAndSystem"> - -</detect> +```xml + + +``` |Setting|Required?|Value| |--- |--- |--- | @@ -779,9 +781,10 @@ The <detects> element is a container for one or more <detect> elemen Syntax: -<detects name="*ID*" context="User|System|UserAndSystem"> - -</detects> +```xml + + +``` - **Number of occurrences:** Unlimited. @@ -796,7 +799,7 @@ Syntax: The following example is from the MigApp.xml file. -``` xml +```xml MigXmlHelper.DoesFileVersionMatch("%Lotus123InstPath%\123w.exe","ProductVersion","9.*") @@ -824,9 +827,10 @@ Use the <detection> element under the <namedElements> element if you Syntax: -<detection name="*ID*" context="User|System|UserAndSystem"> - -</detection> +```xml + + +``` |Setting|Required?|Value| |--- |--- |--- | @@ -835,7 +839,7 @@ Syntax: For example: -``` xml +```xml MigXmlHelper.DoesObjectExist("Registry","HKCU\Software\Adobe\Photoshop\8.0") @@ -846,7 +850,7 @@ For example: and -``` xml +```xml @@ -869,7 +873,9 @@ The <displayName> element is a required field within each <component> Syntax: -<displayName \_locID="*ID*">*ComponentName*</displayName> +```xml +ComponentName +``` |Setting|Required?|Value| |--- |--- |--- | @@ -878,7 +884,7 @@ Syntax: For example: -``` xml +```xml Command Prompt settings ``` @@ -896,9 +902,10 @@ The <environment> element is a container for <variable> elements in Syntax: -<environment name="ID" context="User|System|UserAndSystem"> - -</environment> +```xml + + +``` |Setting|Required?|Value| |--- |--- |--- | @@ -911,7 +918,7 @@ Syntax: In this scenario, you want to generate the location of objects at run time depending on the configuration of the destination computer. For example, you must do this if an application writes data in the directory where it is installed, and users can install the application anywhere on the computer. If the application writes a registry value hklm\\software\\companyname\\install \[path\] and then updates this value with the location where the application is installed, then the only way for you to migrate the required data correctly is to define an environment variable. For example: -``` xml +```xml @@ -921,7 +928,7 @@ In this scenario, you want to generate the location of objects at run time depen Then you can use an include rule as follows. You can use any of the [<script> functions](#scriptfunctions) to perform similar tasks. -``` xml +```xml %INSTALLPATH%\ [*.xyz] @@ -931,7 +938,7 @@ Then you can use an include rule as follows. You can use any of the [<script& Second, you can also filter registry values that contain data that you need. The following example extracts the first string (before the separator ",") in the value of the registry Hklm\\software\\companyname\\application\\ \[Path\]. -``` xml +```xml @@ -949,7 +956,7 @@ Second, you can also filter registry values that contain data that you need. The In this scenario, you want to migrate five files named File1.txt, File2.txt, and so on, from %SYSTEMDRIVE%\\data\\userdata\\dir1\\dir2\\. To do this you must have the following <include> rule in an .xml file: -``` xml +```xml %SYSTEMDRIVE%\data\userdata\dir1\dir2 [File1.txt] @@ -963,7 +970,7 @@ In this scenario, you want to migrate five files named File1.txt, File2.txt, and Instead of typing the path five times, you can create a variable for the location as follows: -``` xml +```xml %SYSTEMDRIVE%\data\userdata\dir1\dir2 @@ -973,7 +980,7 @@ Instead of typing the path five times, you can create a variable for the locatio Then, you can specify the variable in an <include> rule as follows: -``` xml +```xml %DATAPATH% [File1.txt] @@ -1000,9 +1007,10 @@ The <exclude> element determines what objects will not be migrated, unless Syntax: -<exclude filter="*ScriptInvocation*"> - -</exclude> +```xml + + +``` |Setting|Required?|Value| |--- |--- |--- | @@ -1011,7 +1019,7 @@ Syntax: For example, from the MigUser.xml file: -``` xml +```xml %CSIDL_MYMUSIC%\* [*] @@ -1034,9 +1042,10 @@ You can use the <excludeAttributes> element to determine which parameters Syntax: -<excludeAttributes attributes="Security|TimeFields|Security,TimeFields"> - -</excludeAttributes> +```xml + + +``` |Setting|Required?|Value| |--- |--- |--- | @@ -1044,7 +1053,7 @@ Syntax: Example: -``` xml +```xml @@ -1106,9 +1115,10 @@ The <extensions> element is a container for one or more <extension> Syntax: -<extensions> - -</extensions> +```xml + + +``` ## <extension> @@ -1123,7 +1133,9 @@ You can use the <extension> element to specify documents of a specific ext Syntax: -<extension>*FilenameExtension*</extension> +```xml +FilenameExtension +``` |Setting|Required?|Value| |--- |--- |--- | @@ -1131,7 +1143,7 @@ Syntax: For example, if you want to migrate all \*.doc files from the source computer, specifying the following code under the <component> element: -``` xml +```xml doc @@ -1139,7 +1151,7 @@ For example, if you want to migrate all \*.doc files from the source computer, s is the same as specifying the following code below the <rules> element: -``` xml +```xml @@ -1162,9 +1174,10 @@ You can use the <externalProcess> element to run a command line during the Syntax: -<externalProcess when="pre-scan|scan-success|post-scan|pre-apply|apply-success|post-apply"> - -</externalProcess> +```xml + + +``` |Setting|Required?|Value| |--- |--- |--- | @@ -1190,9 +1203,10 @@ The <include> element determines what to migrate, unless there is a more s Syntax: -<include filter="*ScriptInvocation*"> - -</include> +```xml + + +``` |Setting|Required?|Value| |--- |--- |--- | @@ -1200,7 +1214,7 @@ Syntax: The following example is from the MigUser.xml file: -``` xml +```xml My Video @@ -1236,11 +1250,11 @@ The following functions return a Boolean value. You can use them to migrate cert This filter always returns FALSE. - Syntax: AnswerNo () + Syntax: `AnswerNo ()` - **CompareStringContent** - Syntax: CompareStringContent("*StringContent*","*CompareType*") + Syntax: `CompareStringContent("StringContent","CompareType")` |Setting|Required?|Value| |--- |--- |--- | @@ -1251,11 +1265,11 @@ The following functions return a Boolean value. You can use them to migrate cert This filter screens out the .lnk files that point to an object that is not valid on the destination computer. Note that the screening takes place on the destination computer, so all .lnk files will be saved to the store during ScanState. Then they will be screened out when you run the LoadState tool. - Syntax: IgnoreIrrelevantLinks () + Syntax: `IgnoreIrrelevantLinks ()` For example: - ``` xml + ```xml %CSIDL_COMMON_VIDEO%\* [*] @@ -1267,11 +1281,11 @@ The following functions return a Boolean value. You can use them to migrate cert You can use this function to collect the specified objects from the source computer but then not migrate the objects to the destination computer. When run with the ScanState tool, this function evaluates to TRUE. When run with the LoadState tool, this function evaluates to FALSE. You may want to use this function when you want to check an object's value on the destination computer but do not intend to migrate the object to the destination. - Syntax: NeverRestore() + Syntax: `NeverRestore()` In the following example, HKCU\\Control Panel\\International \[Locale\] will be included in the store, but it will not be migrated to the destination computer: - ``` xml + ```xml HKCU\Control Panel\International [Locale] @@ -1292,9 +1306,10 @@ You can use the <includeAttributes> element to determine whether certain p Syntax: -<includeAttributes attributes="Security|TimeFields|Security,TimeFields"> - -</includeAttributes> +```xml + + +``` |Setting|Required?|Value| |--- |--- |--- | @@ -1318,7 +1333,9 @@ The <location> element defines the location of the <object> element. Syntax: -<location type="*typeID*">*ObjectLocation*</location> +```xml +ObjectLocation +``` |Setting|Required?|Value| |--- |--- |--- | @@ -1327,7 +1344,7 @@ Syntax: The following example is from the MigApp.xml file: -``` xml +```xml %HklmWowSoftware%\Microsoft\Office\12.0\Common\Migration\Office [UpgradeVersion] @@ -1356,9 +1373,10 @@ You can use the <locationModify> element to change the location and name o Syntax: -<locationModify script="*ScriptInvocation*"> - -</locationModify> +```xml + + +``` |Setting|Required?|Value| |--- |--- |--- | @@ -1366,7 +1384,7 @@ Syntax: The following example is from the MigApp.xml file: -``` xml +```xml %CSIDL_APPDATA%\Microsoft\Office\ [Access10.pip] @@ -1382,29 +1400,27 @@ The following functions change the location of objects as they are migrated when The ExactMove function moves all of the objects that are matched by the parent <ObjectSet> element into the given *ObjectEncodedLocation*. You can use this function when you want to move a single file to a different location on the destination computer. If the destination location is a node, all of the matching source objects will be written to the node without any subdirectories. If the destination location is a leaf, the migration engine will migrate all of the matching source objects to the same location. If a collision occurs, the normal collision algorithms will apply. - Syntax: ExactMove(*ObjectEncodedLocation*) + Syntax: `ExactMove(ObjectEncodedLocation)` |Setting|Required?|Value| |--- |--- |--- | |*ObjectEncodedLocation*|Yes|The destination [location](#locations) for all of the source objects.| -~~~ -For example: + For example: -``` xml - + ```xml + HKCU\Keyboard Layout\Toggle [] - -``` -~~~ + + ``` - **Move** The Move function moves objects to a different location on the destination computer. In addition, this function creates subdirectories that were above the longest CSIDL in the source object name. - Syntax: Move(*DestinationRoot*) + Syntax: `Move(DestinationRoot)` |Setting|Required?|Value| |--- |--- |--- | @@ -1414,17 +1430,16 @@ For example: You can use the RelativeMove function to collect and move data. Note that you can use environment variables in source and destination roots, but they may be defined differently on the source and destination computers. - Syntax: RelativeMove(*SourceRoot*,*DestinationRoot*) + Syntax: `RelativeMove(SourceRoot,DestinationRoot)` |Setting|Required?|Value| |--- |--- |--- | |*SourceRoot*|Yes|The location from where the objects will be moved. Any source objects that are enumerated by the parent <ObjectSet> element that are not in this location will not be moved.| |*DestinationRoot*|Yes|The location where the source objects will be moved to on the destination computer. If needed, this function will create any subdirectories that were above *SourceRoot*.| -~~~ For example: -``` xml +```xml %CSIDL_COMMON_FAVORITES%\* [*] @@ -1436,7 +1451,6 @@ For example: ``` -~~~ ## <\_locDefinition> @@ -1456,7 +1470,9 @@ The <manufacturer> element defines the manufacturer for the component, but Syntax: -<manufacturer>*Name*</manufacturer> +```xml +Name +``` |Setting|Required?|Value| |--- |--- |--- | @@ -1478,9 +1494,10 @@ For an example of this element, see [Conflicts and Precedence](usmt-conflicts-an Syntax: -<merge script="*ScriptInvocation*"> - -</merge> +```xml + + +``` |Setting|Required?|Value| |--- |--- |--- | @@ -1488,7 +1505,7 @@ Syntax: The following example is from the MigUser.xml file: -``` xml +```xml @@ -1513,7 +1530,7 @@ These functions control how collisions are resolved. For example: - ``` xml + ```xml HKCU\Software\Microsoft\Office\9.0\PhotoDraw\ [MyPictures] @@ -1527,7 +1544,7 @@ These functions control how collisions are resolved. The FindFilePlaceByPattern function saves files with an incrementing counter when a collision occurs. It is a string that contains one of each constructs: <F>, <E>, <N> in any order. - Syntax: FindFilePlaceByPattern(*FilePattern*) + Syntax: `FindFilePlaceByPattern(FilePattern)` |Setting|Required?|Value| |--- |--- |--- | @@ -1537,7 +1554,7 @@ These functions control how collisions are resolved. The NewestVersion function will resolve conflicts on the destination computer based on the version of the file. - Syntax: NewestVersion(*VersionTag*) + Syntax: `NewestVersion(VersionTag)` |Setting|Required?|Value| |--- |--- |--- | @@ -1557,7 +1574,7 @@ These functions control how collisions are resolved. For example: - ``` xml + ```xml %HklmWowSoftware%\Microsoft\Office\12.0\Common\Migration\Publisher [UpgradeVersion] @@ -1581,9 +1598,10 @@ The <migration> element is the single root element of a migration .xml fil Syntax: -<migration urlid="*UrlID/*Name"> - -</migration> +```xml + + +``` |Setting|Required?|Value| |--- |--- |--- | @@ -1592,7 +1610,7 @@ Syntax: The following example is from the MigApp.xml file: -``` xml +```xml ``` @@ -1607,7 +1625,7 @@ This filter helper function can be used to filter the migration of files based o |Operator|range, neq, lte, lt, eq, gte, gt| |valueToCompare|The value we are comparing. For example:
Date: "2008/05/15-2005/05/17", "2008/05/15"
Size: A numeral with B, KB, MB, or GB at the end. "5GB", "1KB-1MB"| -``` xml +```xml File_size @@ -1629,9 +1647,10 @@ You can use the **<namedElements>** element to define named elements. You Syntax: -<namedElements> - -</namedElements> +```xml + + +``` - **Number of occurrences:** Unlimited @@ -1655,13 +1674,14 @@ The <object> element represents a file or registry key. Syntax: -<object> - -</object> +```xml + + +``` The following example is from the MigApp.xml file: -``` xml +```xml %HklmWowSoftware%\Microsoft\Office\12.0\Common\Migration\Office [UpgradeVersion] @@ -1691,13 +1711,14 @@ The <objectSet> element contains a list of object patterns ; for example, Syntax: -<objectSet> - -</objectSet> +```xml + + +``` The following example is from the MigUser.xml file: -``` xml +```xml My Music @@ -1740,7 +1761,7 @@ This is an internal USMT element. Do not use this element. You can use this element to specify multiple objects. You can specify multiple <pattern> elements for each <objectSet> element and they will be combined. If you are specifying files, you may want to use GenerateDrivePatterns with <script> instead. GenerateDrivePatterns is basically the same as a <pattern> rule, without the drive letter specification. For example, the following two lines of code are similar: -``` xml +```xml C:\Folder\* [Sample.doc] ``` @@ -1753,7 +1774,9 @@ You can use this element to specify multiple objects. You can specify multiple & Syntax: -<pattern type="*typeID*">*Path* \[*object*\]</pattern> +```xml +Path [object] +``` |Setting|Required?|Value| |--- |--- |--- | @@ -1764,13 +1787,13 @@ For example: - To migrate a single registry key: - ``` xml + ```xml HKLM\Software\Microsoft\Windows\CurrentVersion\Internet Settings\Cache [Persistent] ``` - To migrate the EngineeringDrafts folder and any subfolders from the C: drive: - ``` xml + ```xml C:\EngineeringDrafts\* [*] ``` @@ -1780,13 +1803,13 @@ For example: - To migrate the Sample.doc file from C:\\EngineeringDrafts: - ``` xml + ```xml C:\EngineeringDrafts\ [Sample.doc] ``` - To migrate the Sample.doc file from where ever it exists on the C: drive use pattern in the following way. If multiple files exist with the same name on the C: drive, then all of these files will be migrated. - ``` xml + ```xml C:\* [Sample.doc] ``` @@ -1804,9 +1827,10 @@ You can use this element to run a script during a specific point within the migr Syntax: -<processing when="pre-scan|scan-success|post-scan|pre-apply|apply-success|post-apply"> - -</processing> +```xml + + +``` |Setting|Required?|Value| |--- |--- |--- | @@ -1830,9 +1854,10 @@ The <role> element is required in a custom .xml file. By specifying the &l Syntax: -<role role="Container|Binaries|Settings|Data"> - -</role> +```xml + + +``` |Setting|Required?|Value| |--- |--- |--- | @@ -1840,7 +1865,7 @@ Syntax: The following example is from the MigUser.xml file. For more examples, see the MigApp.xml file: -``` xml +```xml Start Menu @@ -1884,9 +1909,10 @@ The <rules> element is required in a custom .xml file. This element contai Syntax: -<rules name="*ID*" context="User|System|UserAndSystem"> - -</rules> +```xml + + +``` |Setting|Required?|Value| |--- |--- |--- | @@ -1895,7 +1921,7 @@ Syntax: The following example is from the MigUser.xml file: -``` xml +```xml My Music @@ -1936,29 +1962,29 @@ The return value that is required by <script> depends on the parent elemen **Syntax and helper functions:** -- General Syntax: <script>*ScriptWithArguments*</script> +- General Syntax: `` - You can use [GetStringContent](#scriptfunctions) when <script> is within <variable>. - Syntax: <script>MigXmlHelper.GetStringContent("*ObjectType*","*EncodedLocationPattern*", "*ExpandContent*")</script> + Syntax: `` Example: `` - You can use [GenerateUserPatterns](#scriptfunctions) when <script> is within <objectSet>. - Syntax: <script>MigXmlHelper.GenerateUserPatterns("*ObjectType*","*EncodedLocationPattern*","*ProcessCurrentUser*")</script> + Syntax: `` Example: `` - You can use [GenerateDrivePatterns](#scriptfunctions) when <script> is within <objectSet>. - Syntax: <script>MigXmlHelper.GenerateDrivePatterns("*PatternSegment*","*DriveType*")</script> + Syntax: `` Example: `` - You can use the [Simple executing scripts](#scriptfunctions) with <script> elements that are within <processing> elements: AskForLogoff, ConvertToShortFileName, KillExplorer, RemoveEmptyDirectories, RestartExplorer, RegisterFonts, StartService, StopService, SyncSCM. - Syntax: <script>MigXmlHelper.*ExecutingScript*</script> + Syntax: `` Example: `` @@ -1970,7 +1996,7 @@ Examples: To migrate the Sample.doc file from any drive on the source computer, use <script> as follows. If multiple files exist with the same name, all such files will get migrated. -``` xml +```xml ``` @@ -1992,7 +2018,7 @@ These functions return either a string or a pattern. You can use GetStringContent with <script> elements that are within <variable> elements. If possible, this function returns the string representation of the given object. Otherwise, it returns NULL. For file objects this function always returns NULL. - Syntax: GetStringContent("*ObjectType*","*EncodedLocationPattern*", "*ExpandContent*") + Syntax: `GetStringContent("ObjectType","EncodedLocationPattern", "ExpandContent")` |Setting|Required?|Value| |--- |--- |--- | @@ -2000,30 +2026,26 @@ These functions return either a string or a pattern. | *EncodedLocationPattern* | Yes |
  • If type of object is Registry, EncodedLocationPattern must be a valid registry path. For example, HKLM\SOFTWARE\MyKey[].
  • If the type of object is Ini, then EncodedLocationPattern must be in the following format:
    IniFilePath|SectionName[SettingName]
| | *ExpandContent* | No (default=TRUE) | Can be TRUE or FALSE. If FALSE, then the given location will not be expanded before it is returned. | -~~~ -For example: + For example: -``` xml - - - -``` -~~~ + ```xml + + + + ``` - **GenerateDrivePatterns** The GenerateDrivePatterns function will iterate all of the available drives and select the ones that match the requested drive type. It will then concatenate the selected drives with the end part of *PatternSegment* to form a full encoded file pattern. For example, if *PatternSegment* is `Path [file.txt]` and DriveType is `Fixed`, then the function will generate `C:\Path [file.txt]`, and other patterns if there are fixed drives other than C:. You cannot specify environment variables with this function. You can use GenerateDrivePatterns with <script> elements that are within [<objectSet>](#objectset) that are within <include>/<exclude>. - Syntax: GenerateDrivePatterns("*PatternSegment*","*DriveType*") + Syntax: `GenerateDrivePatterns("PatternSegment","DriveType")` |Setting|Required?|Value| |--- |--- |--- | | *PatternSegment* | Yes | The suffix of an encoded pattern. It will be concatenated with a drive specification, such as "c:", to form a complete [encoded file pattern](#locations). For example, "* [*.doc]". *PatternSegment* cannot be an environment variable. | | *DriveType* | Yes | The drive type for which the patterns are to be generated. You can specify one of:
  • Fixed
  • CDROM
  • Removable
  • Remote
| -~~~ -See the last component in the MigUser.xml file for an example of this element. -~~~ + See the last component in the MigUser.xml file for an example of this element. - **GenerateUserPatterns** @@ -2035,7 +2057,7 @@ See the last component in the MigUser.xml file for an example of this element. - "C:\\Documents and Settings\\C\\\* \[\*.doc\]" - Syntax:GenerateUserPatterns("*ObjectType*","*EncodedLocationPattern*","*ProcessCurrentUser*") + Syntax: `GenerateUserPatterns("ObjectType","EncodedLocationPattern","ProcessCurrentUser")` |Setting|Required?|Value| |--- |--- |--- | @@ -2043,14 +2065,13 @@ See the last component in the MigUser.xml file for an example of this element. |*EncodedLocationPattern*|Yes|The [location pattern](#locations). Environment variables are allowed.| |*ProcessCurrentUser*|Yes|Can be TRUE or FALSE. Indicates if the patterns should be generated for the current user.| -~~~ **Example:** If GenerateUserPattens('File','%userprofile% \[\*.doc\]','FALSE') is called while USMT is processing user A, then this function will only generate patterns for users B and C. You can use this helper function to build complex rules. For example, to migrate all .doc files from the source computer — but if user X is not migrated, then do not migrate any of the .doc files from user X's profile. The following is example code for this scenario. The first <rules> element migrates all.doc files on the source computer with the exception of those inside C:\\Documents and Settings. The second <rules> elements will migrate all .doc files from C:\\Documents and Settings with the exception of the .doc files in the profiles of the other users. Because the second <rules> element will be processed in each migrated user context, the end result will be the desired behavior. The end result is the one we expected. -``` xml +```xml @@ -2076,7 +2097,6 @@ The following is example code for this scenario. The first <rules> element ``` -~~~ ### MigXmlHelper.GenerateDocPatterns @@ -2088,7 +2108,7 @@ This helper function invokes the document finder to scan the system for all file |*IncludePatterns*|No (default = TRUE)|Can be TRUE or FALSE. TRUE will generate include patterns and can be added under the <include> element. FALSE will generate exclude patterns and can be added under the <exclude> element.| |*SystemDrive*|No (default = FALSE)|Can be TRUE or FALSE. If TRUE, restricts all patterns to the system drive.| -``` xml +```xml MigDocUser @@ -2115,39 +2135,39 @@ The following scripts have no return value. You can use the following errors wit - **AskForLogoff()**. Prompts the user to log off at the end of the migration. For example: - ``` xml - - - - ``` + ```xml + + + + ``` - **ConvertToShortFileName(RegistryEncodedLocation)**. If *RegistryEncodedLocation* is the full path of an existing file, this function will convert the file to its short file name and then it will update the registry value. - **KillExplorer()**. Stops Explorer.exe for the current user context. This allows access to certain keys and files that are kept open when Explorer.exe is running. For example: - ``` xml - - - - ``` + ```xml + + + + ``` - **RegisterFonts(FileEncodedLocation)**. Registers the given font or all of the fonts in the given directory. For example: - ``` xml - + ```xml + - - ``` + + ``` - **RemoveEmptyDirectories (DirectoryEncodedPattern).** Deletes any empty directories that match *DirectoryEncodedPattern* on the destination computer. - **RestartExplorer().** Restarts Explorer.exe at the end of the migration. For example: - ``` xml - - - - ``` + ```xml + + + + ``` - **StartService (ServiceName, OptionalParam1, OptionalParam2,…).** Starts the service identified by *ServiceName. ServiceName* is the subkey in HKLM\\System\\CurrentControlSet\\Services that holds the data for the given service. The optional parameters, if any, will be passed to the StartService API. For more information, see [this Microsoft Web site](/windows/win32/api/winsvc/nf-winsvc-startservicea). @@ -2168,7 +2188,9 @@ You can use the <text> element to set a value for any environment variable Syntax: -<text>*NormalText*</text> +```xml +NormalText +``` |Setting|Value| |--- |--- | @@ -2176,7 +2198,7 @@ Syntax: For example: -``` xml +```xml %CSIDL_COMMON_APPDATA%\QuickTime @@ -2197,11 +2219,13 @@ Use this element if you want to exclude all .mp3 files from the source computer. Syntax: -<unconditionalExclude></unconditionalExclude> +```xml + +``` The following .xml file excludes all .mp3 files from migration. For additional examples of how to use this element, see the [Exclude Files and Settings](usmt-exclude-files-and-settings.md). -``` xml +```xml Test @@ -2237,9 +2261,10 @@ The <variable> element is required in an <environment> element. For Syntax: -<variable name="*ID*" remap=TRUE|FALSE> - -</variable> +```xml + + +``` |Setting|Required?|Value| |--- |--- |--- | @@ -2248,7 +2273,7 @@ Syntax: The following example is from the MigApp.xml file: -``` xml +```xml HKLM\Software @@ -2272,7 +2297,9 @@ The <version> element defines the version for the component, but does not Syntax: -<version>*ComponentVersion*</version> +```xml +ComponentVersion +``` |Setting|Required?|Value| |--- |--- |--- | @@ -2280,7 +2307,7 @@ Syntax: For example: -``` xml +```xml 4.* ``` @@ -2360,4 +2387,4 @@ The following version tags contain values that can be compared: ## Related topics -[USMT XML Reference](usmt-xml-reference.md) \ No newline at end of file +[USMT XML Reference](usmt-xml-reference.md)