XML 元素庫
概觀
本主題描述的 XML 元素以及 Helper 函式,可讓您用來撰寫與使用者狀態遷移工具 (USMT) 搭配使用的移轉 .xml 檔案。我們假設您已經了解 XML 的基本知識。。
在本主題中
除了 XML 元素和 Helper 函式之外,本主題也描述如何指定編碼位置和位置模式、僅供內部 USMT 使用的函式,以及您可以與 Helper 函式搭配使用的版本標籤。
元素和 Helper 函式
附錄
指定位置
內部 USMT 函式
有效的版本標籤
元素和 Helper 函式
下表描述您可以與 USMT 搭配使用的 XML 元素和 Helper 函式。
元素 A-K | 元素 L-Z | Helper 函式 |
---|---|---|
<addObjects> <attributes> <bytes> <commandLine> <component> <condition> <conditions> <content> <contentModify> <description> <destinationCleanup> <detect> <detects> <detection> <displayName> <environment> <exclude> <excludeAttributes> <extensions> <extension> <externalProcess> <icon> <include> <includeAttributes> |
<library> <location> <locationModify> <_locDefinition> <manufacturer> <merge> <migration> <namedElements> <object> <objectSet> <path> <paths> <pattern> <processing> <plugin> <role> <rules> <script> <text> <unconditionalExclude> <variable> <version> <windowsObjects> |
<condition> 函式 <content> 函式 <contentModify> 函式 <include> 和 <exclude> 篩選函式 <locationModify> 函式 <merge> 函式 <script> 函式 內部 USMT 函式 |
<addObjects>
<addObjects> 元素模擬來源電腦上的一或多個物件。子 <object> 元素提供模擬之物件的詳細資料。如果內容為 <script> 元素,則呼叫的結果將會是物件陣列。
**出現次數:**無限制
父元素: <rules>
必要的子元素: <object> 此外,您必須指定 <location> 和 <attributes> 當作此 <object> 元素的子元素。
選用的子元素: <conditions>、<condition>、<script>
語法:
<addObjects>
</addObjects>
下列是取自 MigApp.xml 檔案的範例:
<addObjects>
<object>
<location type="Registry">%HklmWowSoftware%\Microsoft\Office\12.0\Common\Migration\Office [UpgradeVersion]</location>
<attributes>DWORD</attributes>
<bytes>0B000000</bytes>
</object>
<object>
<location type="Registry">%HklmWowSoftware%\Microsoft\Office\12.0\Common\Migration\Office [Lang]</location>
<attributes>DWORD</attributes>
<bytes>00000000</bytes>
</object>
</addObjects>
<attributes>
<attributes> 元素會定義登錄機碼或檔案的屬性。
**出現次數:**每個 <object> 一次
父元素: <object>
**子元素:**無
語法:
<attributes>Content</attributes>
設定 | 必要? | 值 |
---|---|---|
Content |
是 |
內容取決於指定的物件類型。
|
下列是取自 MigApp.xml 檔案的範例:
<object>
<location type="Registry">%HklmWowSoftware%\Microsoft\Office\12.0\Common\Migration\Office [Lang]</location>
<attributes>DWORD</attributes>
<bytes>00000000</bytes>
</object>
<bytes>
您只能針對檔案指定 <bytes> 元素,因為如果 <location> 對應至登錄機碼或目錄,會略過 <bytes>。
**出現次數:**零或一次
父元素: <object>
**子元素:**無
語法:
<bytes string="Yes|No" expand="Yes|No">Content</bytes>
設定 | 必要? | 值 |
---|---|---|
string |
否,預設為 No |
決定 Content 應解譯為字串或位元組。 |
expand |
否 (預設值 = Yes) |
當 expand 參數為 Yes 時,<bytes> 元素的內容會先在來源電腦的內容中展開,然後進行解譯。 |
Content |
是 |
取決於 string 的值。
|
下列是取自 MigApp.xml 檔案的範例:
<object>
<location type="Registry">%HklmWowSoftware%\Microsoft\Office\12.0\Common\Migration\Office [Lang]</location>
<attributes>DWORD</attributes>
<bytes>00000000</bytes>
</object>
<commandLine>
如果想在執行 ScanState 和 LoadState 工具之前或之後開始或停止服務或應用程式,可以使用 <commandLine> 元素。
**出現次數:**無限制
父元素: <externalProcess>
**子元素:**無
語法:
<commandLine>CommandLineString</commandLine>
設定 | 必要? | 值 |
---|---|---|
CommandLineString |
是 |
有效的命令列。 |
<component>
自訂 .xml 檔案需要 <component> 元素。這個元素會為移轉 .xml 檔案定義最基本的結構。例如,在 MigApp.xml 檔案中,"Microsoft(R) Office 2003" 是一個元件,它還包含另一個元件 - "Microsoft Office Access(R) 2003"。您可以使用子元素來定義元件。
元件可以巢狀堆疊在另一個元件內部;也就是說,<component> 元素可以是 <component> 元素內部之 <role> 元素的子項,但須符合以下兩種情況:1) 當父 <component> 元素是一個容器,或者 2) 當子 <component> 元素的角色與父 <component> 元素相同。
**出現次數:**無限制
父元素: <migration>、<role>
必要的子元素: <role>、<displayName>
選用的子元素: <manufacturer>、<version>、<description>、<paths>、<icon>、<environment>、<extensions>
語法:
<component type="System|Application|Device|Documents" context="User|System|UserAndSystem" defaultSupported="TRUE|FALSE|YES|NO"
hidden="Yes|No">
</component>
設定 | 必要? | 值 |
---|---|---|
type |
是 |
您可以使用以下各項將設定分組,並定義元件的類型。
|
context |
否 預設值 = UserAndSystem |
定義此參數的範圍;也就是定義要在特定使用者的內容、跨整個作業系統或在這兩個範圍中處理這個元件。 最大的可能範圍是由 <component> 元素設定。例如,如果 <component> 元素有 User 內容而 <rules> 元素有 UserAndSystem 內容,則 <rules> 元素的作用會和它具備 User 內容一樣。如果 <rules> 元素有 System 內容,作用會和沒有 <rules> 元素一樣。
|
defaultSupported |
否 (預設值 = TRUE) |
可以是 TRUE、FALSE、YES 或 NO 之一。如果這個參數是 FALSE (或 NO),除非目的電腦上有對等元件,否則不會移轉這些元件。 當 type="System" 而且 defaultSupported="FALSE" 時,除非 LoadState 命令列上指定之 .xml 檔案中有對等元件,否則不會移轉這些設定。例如,預設的 MigSys.xml 檔案包含 type="System" 以及 defaultSupported="FALSE" 的元件。如果在 ScanState 命令列指定這個檔案,您也必須在 LoadState 命令列指定這個檔案,才能移轉設定。這是因為 LoadState 工具必須偵測到對等元件。也就是說,元件必須有相同的 .xml 檔案移轉 urlid 和相同的顯示名稱,否則 LoadState 工具將不會從存放區移轉這些設定。當來源電腦執行 Windows XP,而您移轉至 Windows Vista 和 Windows XP 時,就會發現這很實用,因為您可以讓兩台目的電腦使用相同的存放區。 |
hidden |
|
這個參數僅供內部 USMT 使用。 |
如需範例,請參閱任何預設的移轉 .xml 檔案。
<condition>
雖然可支援 <detect>、<objectSet> 以及 <addObjects> 元素底下的 <condition>,不過我們建議您不要使用它。未來的 USMT 版本可能不會再使用這個元素,您需要重新編寫指令碼。我們建議您,如果需要在 <objectSet> 和 <addObjects> 元素中使用條件,可以使用功能更強的 <conditions> 元素,您可以使用這個元素編寫複雜的布林陳述式。
<condition> 元素有一個布林結果。您可以使用這個元素指定用來評估父元素的條件。如果目前的任何條件傳回 FALSE,就不會評估父元素。
**出現次數:**無限制。
父元素: <conditions>、<detect>、<objectSet>、<addObjects>
**子元素:**無
**Helper 函式:**您可以將以下 <condition> 函式與這個元素搭配使用:DoesOSMatch、IsNative64Bit()、IsOSLaterThan、IsOSEarlierThan、DoesObjectExist、DoesFileVersionMatch、IsFileVersionAbove、IsFileVersionBelow、IsSystemContext、DoesStringContentEqual、DoesStringContentContain、IsSameObject、IsSameContent 和 IsSameStringContent。
語法:
<condition negation="Yes|No">ScriptName</condition>
設定 | 必要? | 值 |
---|---|---|
negation |
否 預設值 = No |
"Yes" 會反轉條件的 True/False 值。 |
ScriptName |
是 |
已經在此移轉區段中定義的指令碼。 |
例如,
在以下程式碼範例中,<condition> 元素 A 和 B 是透過 AND 運算子連結在一起,因為它們是在不同的 <conditions> 區段中。例如:
<detection>
<conditions>
<condition>A</condition>
</conditions>
<conditions operation="AND">
<condition>B</condition>
</conditions>
</detection>
不過,在以下程式碼範例中,<condition> 元素 A 和 B 是透過 OR 運算子連結在一起,因為它們是在相同的 <conditions> 區段中。
<detection>
<conditions>
<condition>A</condition>
<condition>B</condition>
</conditions>
</detection>
<condition> 函式
<condition> 元素會傳回布林值。您可以在 <addObjects> 條件中使用這些元素。
作業系統版本函式
物件內容函式
作業系統版本函式
DoesOSMatch
所有比對都不區分大小寫。
語法:DoesOSMatch("OSType","OSVersion")
設定 必要? 值 OSType
是
此設定的唯一有效值為 NT。不過請注意,您必須設定此值,<condition> 函式才能正常運作。
OSVersion
是
以句號分隔主要版本、次要版本、建置號碼以及更正的服務磁碟版本。例如,
5.0.2600.Service Pack 1
。您也可以用模式指定部分版本規格。例如,5.0.*
。例如:
<condition>MigXmlHelper.DoesOSMatch("NT","*")</condition>
IsNative64Bit
如果移轉程序以原生 64 位元程序執行 (也就是在不含 Windows on Windows (WOW) 的 64 位元系統上執行的程序),IsNative64Bit 函式會傳回 TRUE。否則,會傳回 FALSE。
IsOSLaterThan
所有比較都不區分大小寫。
語法:IsOSLaterThan("OSType","OSVersion")
設定 必要? 值 OSType
是
可以是 9x 或 NT。如果 OSType 不符合目前作業系統的類型,會傳回 FALSE。例如,如果目前的作業系統是 Windows NT,而且 OSType 是 "9x",則結果會是 FALSE。
OSVersion
是
以句號分隔主要版本、次要版本、建置號碼以及更正的服務磁碟版本。例如,
5.0.2600.Service Pack 1
。您也可以指定部分版本規格,但不允許模式。例如,5.0
。如果目前的作業系統晚於或等於 OSVersion,則 IsOSLaterThan 函式會傳回 TRUE 。
例如:
<condition negation="Yes">MigXmlHelper.IsOSLaterThan("NT","6.0")</condition>
IsOSEarlierThan
所有比較都不區分大小寫。
語法:IsOSEarlierThan("OSType","OSVersion")
設定 必要? 值 OSType
是
可以是 9x 或 NT。如果 OSType 不符合目前作業系統的類型,會傳回 FALSE。例如,如果目前的作業系統是 Windows NT,而且 OSType 是 "9x",則結果會是 FALSE。
OSVersion
是
以句號分隔主要版本、次要版本、建置號碼以及更正的服務磁碟版本。例如,
5.0.2600.Service Pack 1
。您也可以指定部分版本規格,但不允許模式。例如,5.0
。如果目前的作業系統早於 OSVersion,則 IsOSEarlierThan 函式會傳回 TRUE 。
物件內容函式
DoesObjectExist
如果任何物件存在而且符合位置模式,則 DoesObjectExist 函式會傳回 TRUE。否則,會傳回 FALSE。嘗試列舉之前,會先展開位置模式。
語法:DoesObjectExist("ObjectType","EncodedLocationPattern")
設定 必要? 值 ObjectType
是
定義物件類型。可以是檔案或登錄。
EncodedLocationPattern
是
指定位置。允許使用環境變數。
如需此元素的範例,請參閱 MigApp.xml 檔案。
DoesFileVersionMatch
模式檢查不區分大小寫。
語法:DoesFileVersionMatch("EncodedFileLocation","VersionTag","VersionValue")
設定 必要? 值 EncodedFileLocation
是
將檢查之檔案的指定位置。允許使用環境變數。
VersionTag
是
將檢查的 有效的版本標籤值。
VersionValue
是
字串模式。例如,"Microsoft*"。
例如:
<condition>MigXmlHelper.DoesFileVersionMatch("%MSNMessengerInstPath%\msnmsgr.exe","ProductVersion","6.*")</condition>
<condition>MigXmlHelper.DoesFileVersionMatch("%MSNMessengerInstPath%\msnmsgr.exe","ProductVersion","7.*")</condition>
IsFileVersionAbove
如果檔案的版本高於 VersionValue,則 IsFileVersionAbove 函式會傳回 TRUE。
語法:IsFileVersionAbove("EncodedFileLocation","VersionTag","VersionValue")
設定 必要? 值 EncodedFileLocation
是
將檢查之檔案的指定位置。允許使用環境變數。
VersionTag
是
將檢查的 有效的版本標籤值。
VersionValue
是
要比較的值。您無法指定模式。
IsFileVersionBelow
語法:IsFileVersionBelow("EncodedFileLocation","VersionTag","VersionValue")
設定 必要? 值 EncodedFileLocation
是
將檢查之檔案的指定位置。允許使用環境變數。
VersionTag
是
將檢查的 有效的版本標籤值。
VersionValue
是
要比較的值。您無法指定模式。
IsSystemContext
如果目前的內容是 "System",則 IsSystemContext 函式會傳回 TRUE。否則,會傳回 FALSE。
語法:IsSystemContext()
DoesStringContentEqual
如果指定物件的字串表示與
StringContent
完全相同,則 DoesStringContentEqual 函式會傳回 TRUE。語法:DoesStringContentEqual("ObjectType","EncodedLocation","StringContent")
設定 必要? 值 ObjectType
是
定義物件的類型。可以是檔案或登錄。
EncodedLocationPattern
是
將檢查之物件的指定位置。您可以指定環境變數。
StringContent
是
檢查所依據的字串。
例如:
<condition negation="Yes">MigXmlHelper.DoesStringContentEqual("File","%USERNAME%","")</condition>
DoesStringContentContain
如果物件的字串表示中至少出現一次 StrToFind,則 DoesStringContentContain 函式會傳回 TRUE。
語法:DoesStringContentContain("ObjectType","EncodedLocation","StrToFind")
設定 必要? 值 ObjectType
是
定義物件的類型。可以是檔案或登錄。
EncodedLocationPattern
是
將檢查之物件的指定位置。您可以指定環境變數。
StrToFind
是
將在指定物件內容中搜尋的字串。
IsSameObject
如果指定的編碼位置解析為相同的實體物件,則 IsSameObject 函式會傳回 TRUE。否則,會傳回 FALSE。
語法:IsSameObject("ObjectType","EncodedLocation1","EncodedLocation2")
設定 必要? 值 ObjectType
是
定義物件的類型。可以是檔案或登錄。
EncodedLocation1
是
第一個物件的指定位置。您可以指定環境變數。
EncodedLocation2
是
第二個物件的指定位置。您可以指定環境變數。
例如:
<objectSet> <condition negation="Yes">MigXmlHelper.IsSameObject("File","%CSIDL_FAVORITES%","%CSIDL_COMMON_FAVORITES%")</condition> <pattern type="File">%CSIDL_FAVORITES%\* [*]</pattern> </objectSet>
IsSameContent
如果指定的編碼物件擁有相同的內容,則 IsSameContent 函式會傳回 TRUE。否則,會傳回 FALSE。內容會一個位元組一個位元組地進行比較。
語法:IsSameContent("ObjectType1","EncodedLocation1","ObjectType2","EncodedLocation2")
設定 必要? 值 ObjectType1
是
定義第一個物件的類型。可以是檔案或登錄。
EncodedLocation1
是
第一個物件的指定位置。您可以指定環境變數。
ObjectType2
是
定義第二個物件的類型。可以是檔案或登錄。
EncodedLocation2
是
第二個物件的指定位置。您可以指定環境變數。
IsSameStringContent
如果指定的物件擁有相同的內容,則 IsSameStringContent 函式會傳回 TRUE。否則,會傳回 FALSE。內容會解譯為字串。
語法:IsSameStringContent("ObjectType1","EncodedLocation1","ObjectType2","EncodedLocation2")
設定 必要? 值 ObjectType1
是
定義第一個物件的類型。可以是檔案或登錄。
EncodedLocation1
是
第一個物件的指定位置。您可以指定環境變數。
ObjectType2
是
定義第二個物件的類型。可以是檔案或登錄。
EncodedLocation2
是
第二個物件的指定位置。您可以指定環境變數。
<conditions>
<conditions> 元素會傳回布林結果,用於指定評估父元素的條件。USMT 會評估子元素,然後根據 operation 參數,使用 AND 或 OR 運算子加入它們的結果。
**出現次數:**在另一個 <conditions> 元素內無限制。在 <detection>、<rules>、<addObjects> 和 <objectSet> 中只能出現一次。
父元素: <conditions>、<detection>、<environment>、<rules>、<addObjects> 和 <objectSet>
子元素: <conditions>、<condition>
語法:
<conditions operation="AND|OR">
</conditions>
設定 | 必要? | 值 |
---|---|---|
operation |
否,預設值 = AND |
定義布林值運算,該運算是在取自子元素的結果上執行。 |
下列是取自 MigApp.xml 檔案的範例:
<environment name="GlobalEnv">
<conditions>
<condition negation="Yes">MigXmlHelper.IsNative64Bit()</condition>
</conditions>
<variable name="HklmWowSoftware">
<text>HKLM\Software</text>
</variable>
</environment>
<content>
您可以使用 <content> 元素指定一份物件模式清單,用於自來源電腦取得物件集。<content> 元素內的每一個 <objectSet> 都會進行評估。至於每一份產生的物件模式清單,會列舉符合模式的物件,而且由篩選參數篩選它們的內容。產生的字串陣列是 <content> 元素的輸出。篩選指令碼會傳回位置陣列。父 <objectSet> 元素可以包含多個子 <content> 元素。
**出現次數:**無限制
父元素: <objectSet>
子元素: <objectSet>
**Helper 函式:**您可以將以下 <content> 函式與這個元素搭配使用:ExtractSingleFile、ExtractMultipleFiles 和 ExtractDirectory。
語法:
<content filter="ScriptInvocation">
</content>
設定 | 必要? | 值 |
---|---|---|
filter |
是 |
指令碼後面加上任意數量的字串引數,放在括號中並以逗號隔開。例如 <include> 規則中的物件集所列舉的每一個物件都會呼叫這個指令碼。篩選指令碼會傳回布林值。如果傳回值為 TRUE,則會移轉物件。如果為 FALSE,則不會移轉。 |
<content> 函式
下列函式會產生物件內容的模式。會為父 <ObjectSet> 元素列舉的每一個物件呼叫這些函式。
ExtractSingleFile
如果登錄值為 MULTI-SZ,只會處理第一個區段。傳回的模式是檔案必須位於系統中的編碼位置。如果登錄值中的格式正確,但是檔案不存在,則此函式會傳回 NULL。
語法:ExtractSingleFile(Separators,PathHints)
設定 必要? 值 Separators
是
可能的分隔符號清單,可能依照此登錄值名稱中的檔案規格。例如,如果內容為 "C:\Windows\Notepad.exe,-2",則分隔符號為逗號。您可以指定 NULL。
PathHints
是
額外路徑的清單,以分號 (;) 分隔,函式會在清單中尋找符合目前內容的檔案。例如,如果內容為 "Notepad.exe" 而路徑為 %Path% 環境變數,則函式會在 %windir% 中尋找 Notepad.exe,然後傳回 "c:\Windows [Notepad.exe]"。您可以指定 NULL。
例如:
<content filter="MigXmlHelper.ExtractSingleFile(',','%system%')">
和
<content filter="MigXmlHelper.ExtractSingleFile(NULL,'%CSIDL_COMMON_FONTS%')">
ExtractMultipleFiles
ExtractMultipleFiles 函式會傳回多個模式,在指定之登錄值內容中找到的每一個檔案都各有一個模式。如果登錄值為 MULTI-SZ,預設會將 MULTI-SZ 分隔符號視為一個分隔符號。因此,MULTI-SZ 的 <Separators> 引數必須為 NULL。
傳回的模式是檔案必須位於來源電腦上的編碼位置。如果登錄值中的格式正確,但是檔案不存在,檔案將不會包含在產生的清單中。
語法:ExtractMultipleFiles(Separators,PathHints)
設定 必要? 值 Separators
是
可能的分隔符號清單,可能依照此登錄值名稱中的檔案規格。例如,如果內容為 "C:\Windows\Notepad.exe,-2",則分隔符號為逗號。處理 MULTI-SZ 登錄值時,這個參數必須為 NULL。
PathHints
是
額外路徑的清單,以分號 (;) 分隔,函式會在清單中尋找符合目前內容的檔案。例如,如果內容為 "Notepad.exe" 而路徑為 %Path% 環境變數,則函式會在 %windir% 中尋找 Notepad.exe,然後傳回 "c:\Windows [Notepad.exe]"。您可以指定 NULL。
ExtractDirectory
ExtractDirectory 函式會傳回一個模式,即目錄必須位於來源電腦上的編碼位置。如果登錄值中的格式正確,但是目錄不存在,則此函式會傳回 NULL。如果它處理的登錄值為 MULTI-SZ,則只會處理第一個區段。
語法:ExtractDirectory(Separators,LevelsToTrim,PatternSuffix)
設定 必要? 值 Separators
否
可能的分隔符號清單,可能依照此登錄值名稱中的檔案規格。例如,如果內容為 "C:\Windows\Notepad.exe,-2",則分隔符號為逗號。處理 MULTI-SZ 登錄值時,您必須指定 NULL。
LevelsToTrim
是
要從目錄規格的結尾刪除的層數。當您的登錄值指向已知位置的根目錄內時,使用此函式擷取根目錄。
PatternSuffix
是
要新增至目錄規格的模式。例如,
* [*]
。例如:
<objectSet> <content filter='MigXmlHelper.ExtractDirectory (NULL, "1")'> <objectSet> <pattern type="Registry">%HklmWowSoftware%\Classes\Software\RealNetworks\Preferences\DT_Common []</pattern> </objectSet> </content> </objectSet>
<contentModify>
<contentModify> 元素可以在物件寫入目的電腦之前,修改物件的內容。每一個 <contentModify> 元素可以有多個 <objectSet> 元素。這個元素會傳回目前處理之物件的新內容。
**出現次數:**無限制
父元素: <rules>
必要的子元素: <objectSet>
Helper 函式:您可以將以下 <contentModify> 函式與這個元素搭配使用:ConvertToDWORD、ConvertToString、ConvertToBinary、KeepExisting、OffsetValue、SetValueByTable、MergeMultiSzContent 和 MergeDelimitedContent。
語法:
<contentModify script="ScriptInvocation">
</contentModify>
設定 | 必要? | Value |
---|---|---|
script |
是 |
指令碼後面加上任意數量的字串引數,放在括號中並以逗號隔開。例如 include 規則中的物件集所列舉的每一個物件都會呼叫這個指令碼。篩選指令碼會傳回布林值。如果傳回值為 TRUE,則會移轉物件。如果為 FALSE,則不會移轉。 |
<contentModify> 函式
下列函式可以在物件移轉時變更物件的內容。會為父 <ObjectSet> 元素列舉的每一個物件呼叫這些函式。
ConvertToDWORD
ConvertToDWORD 函式會將父 <ObjectSet> 元素列舉的登錄值內容轉換成 DWORD。例如,ConvertToDWORD 會將字串 "1" 轉換成 DWORD 0x00000001。如果轉換失敗,則會套用 DefaultValueOnError 的值。
語法:ConvertToDWORD(DefaultValueOnError)
設定 必要? 值 DefaultValueOnError
否
轉換失敗時,將寫入值名稱的值。您可以指定 NULL,轉換失敗時會寫入 0。
ConvertToString
ConvertToString 函式會將符合父 <ObjectSet> 元素的登錄值內容轉換成字串。例如,它會將 DWORD 0x00000001 轉換成字串 "1"。如果轉換失敗,則會套用 DefaultValueOnError 的值。
語法:ConvertToString(DefaultValueOnError)
設定 必要? 值 DefaultValueOnError
否
轉換失敗時,將寫入值名稱的值。您可以指定 NULL,轉換失敗時會寫入 0。
例如:
<contentModify script="MigXmlHelper.ConvertToString('1')"> <objectSet> <pattern type="Registry">HKCU\Control Panel\Desktop [ScreenSaveUsePassword]</pattern> </objectSet> </contentModify>
ConvertToBinary
ConvertToBinary 函式會將符合父 <ObjectSet> 元素的登錄值內容轉換成二進位類型。
語法:ConvertToBinary ()
OffsetValue
OffsetValue 函式會從移轉之物件的值增減 Value,然後將結果寫回目的電腦上的登錄值。例如,如果移轉的物件是 DWORD,值為 14,而 Value 為 "-2",則目的電腦上的登錄值將會是 12。
語法:OffsetValue(Value)
設定 必要? 值 值
是
數值的字串表示。可以是正數或負數。例如,
OffsetValue(2)
。SetValueByTable
SetValueByTable 函式會比對來源電腦與來源資料表的值。如果找到相符的值,會套用目的資料表上的對等值。如果找不到相符的值,或者目的資料表沒有對等值,則會套用 DefaultValueOnError。
語法:SetValueByTable(SourceTable,DestinationTable,DefaultValueOnError)
設定 必要? 值 SourceTable
是
可能用於來源登錄值的值清單,以逗號分隔。
DestinationTable
否
轉譯值的清單,以逗號分隔。
DefaultValueOnError
否
符合以下情況時,會套用至目的電腦的值:1) 來源電腦的值與 SourceTable 不相符,或者 2) DestinationTable 沒有對等值。
如果 DefaultValueOnError 為 NULL,則目的電腦上的值不會變更。
KeepExisting
目的電腦發生衝突時,您可以使用 KeepExisting 函式。這個函式會保留 (不會覆寫) 目的電腦上之物件的指定屬性。
語法:KeepExisting("OptionString","OptionString","OptionString",…)
設定 必要? 值 OptionString
是
OptionString 可以是 Security、TimeFields 或 FileAttrib:Letter。每一個 OptionStrings 類型都可以指定一個。不要指定多個包含相同值的 OptionStrings。如果指定,則會保留該類型最右邊的選項。例如,不要指定 ("FileAttrib:H", "FileAttrib:R"),因為只會評估「唯讀」。您應該指定 ("FileAttrib:HR"),這樣目的電腦上才會同時保留「隱藏」和「唯讀」屬性。
- Security。保留目的地物件的安全性描述元 (如果有的話)。
- TimeFields。保留目的地物件的時間戳記。這個參數只能用於檔案。
- FileAttrib:Letter。保留目的地物件之指定檔案屬性集的屬性值 (On 或 OFF)。這個參數只能用於檔案。以下各項不區分大小寫,但是 USMT 會略過任何無效、重複或者 "FileAttrib:" 後有空格的任何值。您可以指定以下屬性的任一組合:
- A = 保存
- C = 壓縮
- E = 加密
- H = 隱藏
- I = 非內容索引
- O = 離線
- R = 唯讀
- S = 系統
- T = 暫存
- A = 保存
- Security。保留目的地物件的安全性描述元 (如果有的話)。
MergeMultiSzContent
MergeMultiSzContent 函式會將父 <ObjectSet> 元素列舉之登錄值的 MULTI-SZ 內容,與目的電腦上已經存在的對等登錄值合併。
Instruction
和String
會移除產生之 MULTI-SZ 的內容或者將內容新增至產生的 MULTI-SZ。會移除重複的元素。語法:MergeMultiSzContent (Instruction,String,Instruction,String,…)
設定 必要? 值 Instruction
是
可以是下列其中一項:
- Add。將對應的 String 新增至產生的 MULTI-SZ (如果還沒有的話)。
- Remove。從產生的 MULTI-SZ 移除對應的 String。
String
是
要新增或移除的字串。
- Add。將對應的 String 新增至產生的 MULTI-SZ (如果還沒有的話)。
MergeDelimitedContent
MergeDelimitedContent 函式會將父 <ObjectSet> 元素列舉之登錄值的內容,與目的電腦上已經存在的對等登錄值合併。內容會視為元素的清單,並以 Delimiters 參數的其中一個字元分隔。會移除重複的元素。
語法:MergeDelimitedContent(Delimiters,Instruction,String,…)
設定 必要? 值 Delimiters
是
將用於分隔目前處理之物件內容的單一字元。內容會視為元素的清單,並以 Delimiters 分隔。
例如,"." 會用句號分隔字串。
Instruction
是
可以是下列其中一項:
- Add。將 String 新增至產生的 MULTI-SZ (如果還沒有的話)。
- Remove。從產生的 MULTI-SZ 移除 String。
String
是
要新增或移除的字串。
- Add。將 String 新增至產生的 MULTI-SZ (如果還沒有的話)。
<description>
<description> 元素會定義元件的描述,但不會影響移轉。
**出現次數:**零或一次
父元素: <component>
**子元素:**無
語法:
<description>ComponentDescription</description>
設定 | 必要? | 值 |
---|---|---|
ComponentDescription |
是 |
元件的描述。 |
以下程式碼範例顯示 <description> 元素如何定義 "My custom component" 描述:
<description>My custom component<description>
<destinationCleanup>
<destinationCleanup> 元素會先從目的電腦刪除物件 (例如檔案和登錄機碼),然後再從來源電腦套用物件。只有當目的電腦上執行 LoadState 工具時,才會評估這個元素。也就是說,ScanState 工具會略過這個元素。
重要
使用此選項時務必小心,因為它會刪除目的電腦的物件。
每一個 <destinationCleanup> 元素可以有多個 <objectSet> 元素。這個元素一般用於當來源電腦遺失登錄機碼,而您想確定某個元件是否移轉時。在這種情況下,您可以在移轉來源登錄機碼前,先刪除所有元件的登錄機碼。這樣可以確定如果來源電腦遺失機碼,目的電腦上也會缺少同樣的機碼。
**出現次數:**無限制
父元素: <rules>
子元素: <objectSet> (注意,目的電腦會刪除所有子元素)。
語法:
<destinationCleanup filter=ScriptInvocation>
</destinationCleanup>
設定 | 必要? | 值 |
---|---|---|
filter |
是 |
指令碼後面加上任意數量的字串引數,放在括號中並以逗號隔開。例如 include 規則中的物件集所列舉的每一個物件都會呼叫這個指令碼。篩選指令碼會傳回布林值。如果傳回值為 TRUE,則會移轉物件。如果為 FALSE,則不會移轉。 |
例如:
<destinationCleanup>
<objectSet>
<pattern type="Registry">HKCU\Software\Lotus\123\99.0\DDE Preferences\* [*]</pattern>
<pattern type="Registry">HKCU\Software\Lotus\123\99.0\Find Preferences\* [*]</pattern>
</objectSet>
</destinationCleanup>
<detect>
雖然仍然支援 <detect> 元素,不過建議您不要使用它,因為未來的 USMT 版本可能不會再使用這個元素。在這種情況下,您必須重新編寫指令碼。建議您改用 <detection>元素。
您可以使用 <detect> 元素判斷系統上是否有某個元件。如果 <detect> 元素中的所有子 <detect> 元素都解析為 TRUE,<detect> 元素會解析為 TRUE。如果有任何子 <detect> 元素解析為 FALSE,其父 <detect> 元素會解析為 FALSE。如果沒有 <detect> 元素區段,則 USMT 會假設該元件已經存在。
每一個 <detect> 元素都可以有多個子 <condition> 或 <objectSet> 元素,邏輯上它們會以 OR 運算子加入。如果至少有一個 <condition> 或 <objectSet> 元素評估為 TRUE,那麼 <detect> 元素會評估為 TRUE。
**出現次數:**無限制
父元素:<detects>、<namedElements>
必要的子元素: <condition>
選用的子元素: <objectSet>
語法:
<detect name="ID" context="User|System|UserAndSystem">
</detect>
設定 | 必要? | 值 |
---|---|---|
name |
是,當 <detect> 為 <namedElements> 的子系時 否,當 <detect> 為 <detects> 的子系時 |
指定 ID 時,不會處理任何子元素。而是會處理 <namedElements> 元素中宣告的其他同名 <detect> 元素。 |
context |
否 (預設值 = UserAndSystem) |
定義此參數的範圍:要在特定使用者的內容、跨整個作業系統或在這兩個範圍中處理這個元件。 最大的可能範圍是由 component 元素設定。例如,如果 <component> 元素有 User 內容而 <rules> 元素有 UserAndSystem 內容,則 <rules> 元素的作用會和它具備 User 內容一樣。如果 <rules> 元素有 System 內容,作用會和沒有 <rules> 元素一樣。
|
例如,請參閱 <detection> 的範例。
<detects>
雖然仍然支援 <detects> 元素,不過建議您不要使用它,因為未來的 USMT 版本可能不會再使用這個元素,您需要重新編寫指令碼。如果父元素是 <role> 或 <namedElements>,建議您改用 <detection> 元素;如果父元素是 <rules>,則改用 <conditions> 元素。使用 <detection> 可以讓您更清楚地編寫複雜的布林陳述式。
<detects> 元素是一或多個 <detect> 元素的容器。如果 <detects> 元素中的所有子 <detect> 元素都解析為 TRUE,<detects> 會解析為 TRUE。如果有任何子 <detect> 元素解析為 FALSE,則 <detects> 會解析為 FALSE。如果您不想在元件中編寫 <detects> 元素,可以在 <namedElements> 元素底下建立 <detects> 元素,然後參考它。如果沒有 <detects> 元素區段,則 USMT 會假設該元件已經存在。每一個 <detects> 元素的結果會以 OR 運算子加入,形成偵測父元素時所使用的規則。
語法:
<detects name="ID" context="User|System|UserAndSystem">
</detects>
**出現次數:**無限制。
父元素: <role>、<rules>、<namedElements>
必要的子元素:<detect>
設定 | 必要? | 值 |
---|---|---|
name |
是,當 <detects> 為 <namedElements> 的子系時 否,當 <detects> 為 <role> 或 <rules> 的子系時 |
指定 ID 時,不會處理任何子 <detect> 元素。而是會處理 <namedElements> 元素中宣告的其他同名 <detects> 元素。 |
context |
否 (預設值 = UserAndSystem) |
定義此參數的範圍:要在特定使用者的內容、跨整個作業系統或在這兩個範圍中處理這個元件。 最大的可能範圍是由 <component element> 設定。例如,如果 <component> 元素有 User 內容而 <rules> 元素有 UserAndSystem 內容,則 <rules> 元素的作用會和它具備 User 內容一樣。如果 <rules> 元素有 System 內容,作用會和沒有 <rules> 元素一樣。
會略過 <rules> 元素內 <detects> 元素的 context 參數。 |
下列是取自 MigApp.xml 檔案的範例。
<detects>
<detect>
<condition>MigXmlHelper.DoesFileVersionMatch("%Lotus123InstPath%\123w.exe","ProductVersion","9.*")</condition>
</detect>
<detect>
<condition>MigXmlHelper.DoesFileVersionMatch("%SmartSuiteInstPath%\smartctr.exe","ProductVersion","99.*")</condition>
</detect>
</detects>
<detection>
<detection> 元素是單一 <conditions> 元素的容器。子 <condition> 元素的結果 (位於 <conditions> 元素下方),會決定此元素的結果。例如,如果 <detection> 元素中的所有子 <conditions> 元素都解析為 TRUE,則 <detection> 元素會解析為 TRUE。如果有任何子 <conditions> 元素解析為 FALSE,則 <detection> 元素會解析為 FALSE。
此外,<role> 元素內每一個 <detection> 區段的結果都會以 OR 運算子加入,形成父元素的偵測規則。也就是說,如果其中一個 <detection> 區段解析為 TRUE,則會處理 <role> 元素。否則,不會處理 <role> 元素。
如果您不想在元件內撰寫 <detection> 元素,可以在 <namedElements> 元素下使用 <detection> 元素。然後在 <role> 元素下方加入一個相符的 <detection> 區段,用來控制是否移轉元件。如果元件沒有 <detection> 區段,則 USMT 會假設該元件已經存在。
**出現次數:**無限制。
父元素: <role>、<namedElements>
子元素: <conditions>
語法:
<detection name="ID" context="User|System|UserAndSystem">
</detection>
設定 | 必要? | 值 |
---|---|---|
name |
|
如果宣告,會略過 <detection> 元素的內容,並評估 <namedElements> 元素中宣告的同名 <detection> 元素內容。 |
context |
否,預設值 = UserAndSystem |
定義此參數的範圍:要在特定使用者的內容、跨整個作業系統或在這兩個範圍中處理這個元件。
|
例如:
<detection name="AdobePhotoshopCS">
<conditions>
<condition>MigXmlHelper.DoesObjectExist("Registry","HKCU\Software\Adobe\Photoshop\8.0")</condition>
<condition>MigXmlHelper.DoesFileVersionMatch("%PhotoshopSuite8Path%\Photoshop.exe","FileVersion","8.*")</condition>
</conditions>
</detection>
和
<role role="Settings">
<detection>
<conditions>
<condition>MigXmlHelper.DoesFileVersionMatch("%QuickTime5Exe%","ProductVersion","QuickTime 5.*")</condition>
<condition>MigXmlHelper.DoesFileVersionMatch("%QuickTime5Exe%","ProductVersion","QuickTime 6.*")</condition>
</conditions>
</detection>
<displayName>
<displayName> 元素是每一個 <component> 元素內的必要欄位。
出現次數:每個元件一次
父元素: <component>
**子元素:**無
語法:
<displayName _locID="ID">ComponentName</displayName>
設定 | 必要? | 值 |
---|---|---|
locID |
否 |
這個參數供內部 USMT 使用。請勿使用這個參數。 |
ComponentName |
是 |
元件的名稱。 |
例如:
<displayName>Command Prompt settings</displayName>
<environment>
<environment> 元素是 <variable> 元素的容器,您可以在此定義要用於.xml 檔案的變數。以此方式定義的所有環境變數都是私用變數。也就是說,只有其子元件以及其中定義的元件才可以使用這些變數。有兩個範例狀況,請參閱範例。
**出現次數:**無限制
父元素: <role>、<component>、<namedElements>
必要的子元素: <variable>
選用的子元素: <conditions>
語法:
<environment name="ID" context="User|System|UserAndSystem">
</environment>
設定 | 必要? | 值 |
---|---|---|
name |
是,當 <environment> 為 <namedElements> 的子系時 否,當 <environment> 為 <role> 或 <component> 的子系時 |
宣告為 <role> 或 <component> 元素的子系時,如果宣告 ID,則 USMT 會略過 <environment> 元素的內容,並處理 <namedElements> 元素中宣告的同名 <environment> 元素內容。 |
context |
否 (預設值 = UserAndSystem) |
定義此參數的範圍:要在特定使用者的內容、跨整個作業系統或在這兩個範圍中處理這個元件。 最大的可能範圍是由 <component> 元素設定。例如,如果 <component> 元素有 User 內容而 <rules> 元素有 UserAndSystem 內容,則 <rules> 元素的作用會和它具備 User 內容一樣。如果 <rules> 元素有 System 內容,作用會和沒有 <rules> 一樣。
|
範例狀況 1
在這種情況下,您想根據目的電腦的設定,在執行時間產生物件的位置。例如,如果應用程式在它的安裝目錄中寫入資料,而且使用者可以在電腦任何地方安裝應用程式,您就必須這樣做。如果應用程式寫入登錄值 hklm\software\companyname\install [path],然後將這個值更新為應用程式的安裝位置,那麼如果想正確移轉必要的資料,唯一的方法是定義環境變數。例如:
<environment>
<variable name="INSTALLPATH">
<script>MigXmlHelper.GetStringContent("Registry","\software\companyname\install [path]")</script>
</variable>
</environment>
您就可以使用 include 規則,如下所示。您可以使用任何 <script> 函式執行類似的工作。
<include>
<objectSet>
<pattern type="File">%INSTALLPATH%\ [*.xyz]</pattern>
</objectSet>
</include>
接著,您也可以篩選出包含您所需資料的登錄值。以下範例會擷取登錄值 Hklm\software\companyname\application\ [Path] 中的第一個字串 (在分隔符號 "," 前面)。
<environment>
<variable name="APPPATH">
<objectSet>
<content filter='MigXmlHelper.ExtractDirectory (",", "1")'>
<objectSet>
<pattern type="Registry">Hklm\software\companyname\application\ [Path]</pattern>
</objectSet>
</content>
</objectSet>
</variable>
</environment>
範例狀況 2
在這種情況下,您想要從 %SYSTEMDRIVE%\data\userdata\dir1\dir2\ 移轉 5 個檔案,名稱分別為 File1.txt、File2.txt,以此類推。若要這樣做,.xml 檔案中必須要有以下 <include> 規則。
<include>
<objectSet>
<pattern type="File">%SYSTEMDRIVE%\data\userdata\dir1\dir2 [File1.txt]</pattern>
<pattern type="File">%SYSTEMDRIVE%\data\userdata\dir1\dir2 [File2.txt]</pattern>
<pattern type="File">%SYSTEMDRIVE%\data\userdata\dir1\dir2 [File3.txt]</pattern>
<pattern type="File">%SYSTEMDRIVE%\data\userdata\dir1\dir2 [File4.txt]</pattern>
<pattern type="File">%SYSTEMDRIVE%\data\userdata\dir1\dir2 [File5.txt]</pattern>
</objectSet>
</include>
您不用輸入五次路徑,可以建立位置的變數,如下所示:
<environment>
<variable name="DATAPATH">
<text>%SYSTEMDRIVE%\data\userdata\dir1\dir2 </text>
</variable>
</environment>
然後,可以在 <include> 規則中指定變數,如下所示:
<include>
<objectSet>
<pattern type="File">%DATAPATH% [File1.txt]</pattern>
<pattern type="File">%DATAPATH% [File2.txt]</pattern>
<pattern type="File">%DATAPATH% [File3.txt]</pattern>
<pattern type="File">%DATAPATH% [File4.txt]</pattern>
<pattern type="File">%DATAPATH% [File5.txt]</pattern>
</objectSet>
</include>
<exclude>
除非有更具體的 <include> 元素會移轉物件,否則 <exclude> 元素會決定不會移轉哪些物件。如果物件同時具備 <include> 和 <exclude> 元素,則會包含該物件。每一個 <exclude> 元素可以有多個子 <objectSet> 元素。
**出現次數:**無限制
父元素: <rules>
子元素: <objectSet>
Helper 函式: 您可以將以下 <include> 和 <exclude> 篩選函式與這個元素搭配使用:CompareStringContent、IgnoreIrrelevantLinks、AnswerNo, NeverRestore 以及 SameRegContent。
語法:
<exclude filter="ScriptInvocation">
</exclude>
設定 | 必要? | 值 |
---|---|---|
filter |
否 (預設值 = No) |
指令碼後面加上任意數量的字串引數,放在括號中並以逗號隔開。例如 include 規則中的物件集所列舉的每一個物件都會呼叫這個指令碼。篩選指令碼會傳回布林值。如果傳回值為 TRUE,則會移轉物件。如果為 FALSE,則不會移轉。 |
例如,從 MigUser.xml 檔案:
<exclude>
<objectSet>
<pattern type="File">%CSIDL_MYMUSIC%\* [*]</pattern>
<pattern type="File">%CSIDL_MYPICTURES%\* [*]</pattern>
<pattern type="File">%CSIDL_MYVIDEO%\* [*]</pattern>
</objectSet>
</exclude>
<excludeAttributes>
您可以使用 <excludeAttributes> 元素決定不要移轉哪些與物件相關的參數。如果 <includeAttributes> 和 <excludeAttributes> 元素發生衝突,則最具體的模式會決定不會移轉的模式。如果物件沒有 <includeAttributes> 或 <excludeAttributes> 元素,則會移轉它所有的參數。
**出現次數:**無限制
父元素: <rules>
子元素: <objectSet>
語法:
<excludeAttributes attributes="Security|TimeFields|Security,TimeFields">
</excludeAttributes>
參數 | 必要? | 值 |
---|---|---|
attributes |
是 |
指定要排除的屬性。您可以指定以下其中一項,或指定兩項但以引號分隔,例如,
|
範例:
<migration urlid="https://www.microsoft.com/migration/1.0/migxmlext/miguser">
<!-- This component migrates My Video files -->
<component type="System" context="System">
<displayName>System Data</displayName>
<role role="Data">
<rules>
<!-- Include all of the text files, which are immediately in the drive where the operating system is installed -->
<include>
<objectSet>
<pattern type="File">%SYSTEMDRIVE%\ [*.txt]</pattern>
</objectSet>
</include>
<!-- Exclude the time stamps from the text file starting with the letter a -->
<excludeAttributes attributes="TimeFields">
<objectSet>
<pattern type="File">%SYSTEMDRIVE%\ [a*.txt]</pattern>
</objectSet>
</excludeAttributes>
<!-- include the time stamps from the text file aa.txt -->
<includeAttributes attributes="TimeFields">
<objectSet>
<pattern type="File">%SYSTEMDRIVE%\ [aa.txt]</pattern>
</objectSet>
</includeAttributes>
<!-- Logoff the user after loadstate successfully completed. -->
<externalProcess when="post-apply">
<commandLine>
logoff
</commandLine>
</externalProcess>
</rules>
</role>
<!-- Migrate
all doc files from the system
all power point files
all visio design files
all my c++ program files -->
<extensions>
<extension>DOC</extension>
<extension>PPT</extension>
<extension>VXD</extension>
<extension>PST</extension>
<extension>CPP</extension>
</extensions>
</component>
</migration>
<extensions>
<extensions> 元素是一或多個 <extension> 元素的容器。
**出現次數:**零或一次
父元素: <component>
必要的子元素: <extension>
語法:
<extensions>
</extensions>
<extension>
您可以使用 <extension> 元素來指定特定副檔名的文件。
**出現次數:**無限制
父元素: <extensions>
**子元素:**無
語法:
<extension>FilenameExtension</extension>
設定 | 必要? | 值 |
---|---|---|
FilenameExtension |
是 |
副檔名。 |
例如,如果想要移轉來源電腦的所有 *.doc 檔案,可以在 <component> 元素底下指定下列程式碼:
<extensions>
<extension>doc</extension>
<extensions>
與在 <rules> 元素底下指定下列程式碼相同:
<include>
<objectSet>
<script>MigXmlHelper.GenerateDrivePatterns ("* [*.doc]", "Fixed")</script>
</objectSet>
</include>
如需 <extension> 元素使用方式的其他範例,請參閱 <excludeAttributes> 的範例。
<externalProcess>
您可以使用 <externalProcess> 元素,在移轉程序期間執行命令列。例如,您可以在 LoadState 程序完成後執行命令。
**出現次數:**無限制
父元素: <rules>
必要的子元素: <commandLine>
語法:
<externalProcess when="pre-scan|scan-success|post-scan|pre-apply|apply-success|post-apply">
</externalProcess>
設定 | 必要? | 值 |
---|---|---|
when |
是 |
指示命令列何時執行。這個值可以是下列其中一項:
|
如需 <externalProcess> 元素使用方式的範例,請參閱 <excludeAttributes> 的範例。
<icon>
這是內部 USMT 元素。請勿使用這個元素。
<include>
<include> 元素會決定移轉的項目,除非有更具體的 <exclude> 規則。您可以指定一個指令碼,更具體的擴充要收集之內容的定義。每一個 <include> 元素可以有多個 <objectSet> 元素。
**出現次數:**無限制
父元素: <rules>
必要的子元素: <objectSet>
Helper 函式: 您可以將以下 <include> 和 <exclude> 篩選函式與這個元素搭配使用:CompareStringContent、IgnoreIrrelevantLinks、AnswerNo 以及 NeverRestore。
語法:
<include filter="ScriptInvocation">
</include>
設定 | 必要? | 值 |
---|---|---|
filter |
否。 如果未指定這個參數,則會處理子 <ObjectSet> 元素內的所有模式。 |
指令碼後面加上任意數量的字串引數,放在括號中並以逗號隔開。例如 <include> 規則中的物件集所列舉的每一個物件都會呼叫這個指令碼。篩選指令碼會傳回布林值。如果傳回值為 TRUE,則會移轉物件。如果為 FALSE,則不會移轉。 |
下列是取自 MigUser.xml 檔案的範例:
<component type="Documents" context="User">
<displayName _locID="miguser.myvideo">My Video</displayName>
<paths>
<path type="File">%CSIDL_MYVIDEO%</path>
</paths>
<role role="Data">
<detects>
<detect>
<condition>MigXmlHelper.DoesObjectExist("File","%CSIDL_MYVIDEO%")</condition>
</detect>
</detects>
<rules>
<include filter='MigXmlHelper.IgnoreIrrelevantLinks()'> <objectSet> <pattern type="File">%CSIDL_MYVIDEO%\* [*]</pattern> </objectSet> </include>
<merge script="MigXmlHelper.DestinationPriority()">
<objectSet>
<pattern type="File">%CSIDL_MYVIDEO% [desktop.ini]</pattern>
</objectSet>
</merge>
</rules>
</role>
</component>
<include> 和 <exclude> 篩選函式
下列函式會傳回布林值。您可以使用它們並在符合特定的條件時,移轉特定物件。
AnswerNo
這個篩選永遠傳回 FALSE。
語法:AnswerNo ()
CompareStringContent
語法:CompareStringContent("StringContent","CompareType")
設定 必要? 值 StringContent
是
檢查所依據的字串。
CompareType
是
字串。使用下列其中一個值:
- Equal (不區分大小寫)。如果由移轉引擎處理之目前物件的字串表示與
StringContent
完全相同,此函式會傳回 TRUE。
- NULL或任何其他值。如果由移轉引擎處理之目前物件的字串表示與
StringContent
不相符,此函式會傳回 TRUE。
- Equal (不區分大小寫)。如果由移轉引擎處理之目前物件的字串表示與
IgnoreIrrelevantLinks
這個篩選器會檢測出指向目的電腦上無效物件的 .lnk 檔案。請注意,檢測會在目的電腦上進行,因此所有 .lnk 檔案會在 ScanState 期間儲存至存放區。當您執行 LoadState 工具時就會將它們檢測出來。
語法:IgnoreIrrelevantLinks ()
例如:
<include filter='MigXmlHelper.IgnoreIrrelevantLinks()'> <objectSet> <pattern type="File">%CSIDL_COMMON_VIDEO%\* [*]</pattern> </objectSet> </include>
NeverRestore
您可以使用這個函式,從來源電腦收集指定的物件,但不將物件移轉至目的電腦。與 ScanState 工具搭配執行時,這個函式會評估為 TRUE。與 LoadState 工具搭配執行時,這個函式會評估為 FALSE。如果您要檢查目的電腦上某個物件的值,但不打算將物件移轉至目的電腦,可以使用這個函式。
語法:NeverRestore()
在下列範例中,HKCU\Control Panel\International [Locale] 會包含在存放區中,但是不會將它移轉至目的電腦。
<include filter="MigXmlHelper.NeverRestore()"> <objectSet> <pattern type="Registry">HKCU\Control Panel\International [Locale]</pattern> </objectSet> </include>
<includeAttributes>
您可以使用 <includeAttributes> 元素判斷與物件相關的特定參數是否會與物件本身一起移轉。如果 <includeAttributes> 和 <excludeAttributes> 元素發生衝突,則最具體的模式會決定將會移轉的參數。如果物件沒有 <includeAttributes> 或 <excludeAttributes> 元素,則會移轉它所有的參數。
**出現次數:**無限制
父元素: <rules>
子元素: <objectSet>
語法:
<includeAttributes attributes="Security|TimeFields|Security,TimeFields">
</includeAttributes>
設定 | 必要? | 值 |
---|---|---|
attributes |
是 |
指定要包含在移轉之物件的屬性。您可以指定以下其中一項,或指定兩項但以引號分隔,例如,
|
如需 <includeAttributes> 元素使用方式的範例,請參閱 <excludeAttributes> 的範例。
<library>
這是內部 USMT 元素。請勿使用這個元素。
<location>
<location> 元素會定義 <object> 元素的位置。
**出現次數:**每個 <object> 一次
父元素: <object>
子元素: <script>
語法:
<location type="typeID">ObjectLocation</location>
設定 | 必要? | 值 |
---|---|---|
type |
是 |
typeID 可以是登錄或檔案。 |
ObjectLocation |
是 |
物件的位置。 |
下列是取自 MigApp.xml 檔案的範例:
<addObjects>
<object>
<location type="Registry">%HklmWowSoftware%\Microsoft\Office\12.0\Common\Migration\Office [UpgradeVersion]</location>
<attributes>DWORD</attributes>
<bytes>0B000000</bytes>
</object>
<object>
<location type="Registry">%HklmWowSoftware%\Microsoft\Office\12.0\Common\Migration\Office [Lang]</location>
<attributes>DWORD</attributes>
<bytes>00000000</bytes>
</object>
</addObjects>
<locationModify>
您可以在物件移轉至目的電腦之前,使用 <locationModify> 元素變更物件的位置和名稱。只有當目的電腦上執行 LoadState 工具時,才會處理 <locationModify> 元素。換句話說,ScanState 工具會略過這個元素。<locationModify> 元素會在目的電腦上建立適當的資料夾 (如果還沒有資料夾)。
**出現次數:**無限制
父元素: <rules>
必要的子元素: <objectSet>
**Helper 函式:**您可以將以下 <locationModify> 函式與這個元素搭配使用:ExactMove、RelativeMove 和 Move。
語法:
<locationModify script="ScriptInvocation">
</locationModify>
設定 | 必要? | 值 |
---|---|---|
script |
是 |
指令碼後面加上任意數量的字串引數,放在括號中並以逗號隔開。例如 include 規則中的物件集所列舉的每一個物件都會呼叫這個指令碼。篩選指令碼會傳回布林值。如果傳回值為 TRUE,則會移轉物件。如果為 FALSE,則不會移轉。 |
下列是取自 MigApp.xml 檔案的範例:
<locationModify script="MigXmlHelper.RelativeMove('%CSIDL_APPDATA%\Microsoft\Office','%CSIDL_APPDATA%')">
<objectSet>
<pattern type="File">%CSIDL_APPDATA%\Microsoft\Office\ [Access10.pip]</pattern>
</objectSet>
</locationModify>
<locationModify> 函式
使用 <locationModify> 元素時,下列函式會在物件移轉時變更它們的位置。會為父 <ObjectSet> 元素列舉的每一個物件呼叫這些函式。<locationModify> 元素會在目的電腦上建立適當的資料夾 (如果還沒有資料夾)。
ExactMove
ExactMove 函式會將父 <ObjectSet> 元素所有相符的物件,移至指定的 ObjectEncodedLocation。當您想要將單一檔案移至目的電腦上的其他位置時,可以使用這個函式。如果目的地位置是節點,所有相符的來源物件都會寫入節點,而且沒有任何子目錄。如果目的地位置是分葉,移轉引擎會將所有相符的來源物件移轉至相同位置。如果發生衝突,將套用一般的衝突演算法。
語法:ExactMove(ObjectEncodedLocation)
設定 必要? 值 ObjectEncodedLocation
是
所有來源物件的目的地指定位置。
例如:
<locationModify script="MigXmlHelper.ExactMove('HKCU\Keyboard Layout\Toggle [HotKey]')"> <objectSet> <pattern type="Registry">HKCU\Keyboard Layout\Toggle []</pattern> </objectSet> </locationModify>
Move
Move 函式會將物件移至目的電腦上的其他位置。此外,這個函式會在來源物件名稱中最長的 CSIDL 上方建立子目錄。
語法:Move(DestinationRoot)
設定 必要? 值 DestinationRoot
是
來源物件將移至的位置。這個函式會視需要在來源物件名稱中最長的 CSIDL 上建立任何子目錄。
RelativeMove
您可以使用 RelativeMove 函式收集和移動資料。請注意,您可以在來源和目的地根目錄中使用環境變數,但是它們在來源和目的電腦上的定義可能不同。
語法:RelativeMove(SourceRoot,DestinationRoot)
設定 必要? 值 SourceRoot
是
從什麼位置移動物件。父 <ObjectSet> 元素所列舉但不在這個位置的任何來源物件,將不會移動。
DestinationRoot
是
來源物件將移至目的電腦上的位置。這個函式會視需要在 SourceRoot 上方建立任何子目錄。
例如:
<include> <objectSet> <pattern type="File">%CSIDL_COMMON_FAVORITES%\* [*]</pattern> <objectSet> </include> <locationModify script="MigXmlHelper.RelativeMove('%CSIDL_COMMON_FAVORITES%','%CSIDL_COMMON_FAVORITES%')"> <objectSet> <pattern type="File">%CSIDL_COMMON_FAVORITES%\* [*]</pattern> </objectSet> </locationModify>
<_locDefinition>
這是內部 USMT 元素。請勿使用這個元素。
<manufacturer>
<manufacturer> 元素會定義元件的製造商,但不會影響移轉。
**出現次數:**零或一次
父元素: <component>
**子元素:**無
語法:
<manufacturer>Name</manufacturer>
設定 | 必要? | 值 |
---|---|---|
Name |
是 |
元件的製造商名稱。 |
<merge>
<merge> 元素決定衝突時會發生的事。當移轉的物件已經存在目的電腦上時,會發生衝突狀況。如果未指定這個元素,登錄的預設行為是讓來源物件覆寫目的地物件。檔案的預設行為是將來源檔案重新命名為 "OriginalFileName(1).OriginalExtension"。這個元素只會指定發生衝突時應執行的動作。它不會包含物件。因此,若要移轉物件,您必須同時指定 <include> 規則和 <merge> 元素。處理物件時如果偵測到衝突,USMT 會選取並套用最具體的合併規則,以解決衝突。例如,如果您有一個 <merge> 規則 C:\* [*] 設定成 <sourcePriority> 以及一個 <merge> 規則 C:\subfolder\* [*] 設定成 <destinationPriority>,則 USMT 會使用 <destinationPriority> 規則,因為它較具體。
如需此元素的範例,請參閱目的電腦發生衝突時,<merge> 如何運作?。
**出現次數:**無限制
父元素: <rules>
必要的子元素: <objectSet>
**Helper 函式:**您可以將以下 <merge> 函式與這個元素搭配使用:SourcePriority、DestinationPriority、FindFilePlaceByPattern、LeafPattern、NewestVersion, HigherValue() 以及 LowerValue()。
語法:
<merge script="ScriptInvocation">
</merge>
設定 | 必要? | 值 |
---|---|---|
script |
是 |
指令碼後面加上任意數量的字串引數,放在括號中並以逗號隔開。例如 <include> 規則中的物件集所列舉的每一個物件都會呼叫這個指令碼。篩選指令碼會傳回布林值。如果傳回值為 TRUE,則會移轉物件。如果為 FALSE,則不會移轉。 |
下列是取自 MigUser.xml 檔案的範例:
<rules>
<include filter='MigXmlHelper.IgnoreIrrelevantLinks()'>
<objectSet>
<pattern type="File">%CSIDL_MYVIDEO%\* [*]</pattern>
</objectSet>
</include>
<merge script="MigXmlHelper.DestinationPriority()">
<objectSet>
<pattern type="File">%CSIDL_MYVIDEO% [desktop.ini]</pattern>
</objectSet>
</merge>
</rules>
<merge> 函式
這些函式控制衝突的解決方式。
DestinationPriority
指定保留目的電腦上的物件,而且不要從來源電腦移轉物件。
例如:
<merge script="MigXmlHelper.DestinationPriority()"> <objectSet> <pattern type="Registry">HKCU\Software\Microsoft\Office\9.0\PhotoDraw\ [MyPictures]</pattern> <pattern type="Registry">HKCU\Software\Microsoft\Office\9.0\PhotoDraw\Settings\ [PicturesPath]</pattern> <pattern type="Registry">HKCU\Software\Microsoft\Office\9.0\PhotoDraw\Settings\ [AdditionalPlugInPath]</pattern> </objectSet> </merge>
FindFilePlaceByPattern
發生衝突時,FindFilePlaceByPattern 函式會以遞增計數儲存檔案。它是包含以下建構 (各一) 的字串:<F>、<E>、<N>,不限順序。
語法:FindFilePlaceByPattern(FilePattern)
設定 必要? 值 FilePattern
是
- <F> 會以原始檔案名稱取代。
- <N> 會以遞增計數取代,直到目的電腦上的物件沒有衝突為止。
- <E> 會以原始副檔名取代。
例如,
<F> (<N>).<E>
會將原始檔案 MyDocument.doc 變更成目的電腦上的 MyDocument (1).doc。- <F> 會以原始檔案名稱取代。
NewestVersion
NewestVersion 函式會根據檔案的版本解決目的電腦上的衝突。
語法:NewestVersion(VersionTag)
設定 必要? 值 VersionTag
是
將檢查的版本欄位。可以是 "FileVersion" 或 "ProductVersion"。擁有最高 VersionTag 版本的檔案將根據檔案的版本決定解決哪些衝突。例如,如果 Myfile.txt 包含 FileVersion 1 而目的電腦上相同的檔案包含 FileVersion 2,將會保留目的電腦上的檔案。
HigherValue()
您可以使用這個函式合併登錄值。登錄值將評估為數值,而較大值將決定要合併的登錄值。
LowerValue()
您可以使用這個函式合併登錄值。登錄值將評估為數值,而較小值將決定要合併的登錄值。
SourcePriority
指定從來源電腦移轉物件,和刪除目的電腦上的物件。
例如:
<merge script="MigXmlHelper.SourcePriority()"> <objectSet> <pattern type="Registry">%HklmWowSoftware%\Microsoft\Office\12.0\Common\Migration\Publisher [UpgradeVersion]</pattern> <pattern type="Registry">%HklmWowSoftware%\Microsoft\Office\11.0\Common\Migration\Publisher [UpgradeVersion]</pattern> <pattern type="Registry">%HklmWowSoftware%\Microsoft\Office\10.0\Common\Migration\Publisher [UpgradeVersion]</pattern> </objectSet> </merge>
<migration>
<migration> 元素是移轉 .xml 檔案的單一根目錄元素,而且是必要的。每一個 .xml 檔案都必須要有唯一的移轉 urlid。您在命令列上指定的每一個檔案,其 urlid 必須是獨一無二的。這是因為 USMT 使用 urlid 來定義檔案內的元件。例如,您必須在每一個檔案的開頭指定以下各項:<CustomFileName> 是檔案的名稱;例如,"CustomApp"。
**出現次數:**一次
**父元素:**無
必要的子元素: <component>
選用的子元素: <library>、<namedElements>
語法:
<migration urlid="*UrlID/*Name">
</migration>
設定 | 必要? | 值 |
---|---|---|
urlid |
是 |
UrlID 是一個字串識別碼,是這個 .xml 檔案的唯一識別。這個參數必須是 XML 命名空間規格所定義的無冒號名稱。每一個移轉 .xml 檔案都必須要有唯一的 urlid。如果兩個移轉 .xml 檔案的 urlid 相同,則不會處理命令列上指定的第二個 .xml 檔案。如需 XML 命名空間的相關資訊,請參閱使用 XML 命名空間。 |
Name |
否 |
雖然不是必要的,但是最好使用 .xml 檔案的名稱。 |
下列是取自 MigApp.xml 檔案的範例:
<migration urlid="https://www.microsoft.com/migration/1.0/migxmlext/migapp">
</migration>
MigXMLHelper.FileProperties
這個篩選 Helper 函式可以用來根據檔案大小和日期屬性篩選檔案的移轉。
Helper 函式 | MigXMLHelper.FileProperties (property、operator、valueToCompare) |
---|---|
Property |
filesize、dateCreated、dateModified、dateAccessed |
Operator |
range、neq、lte、lt、eq、gte、gt |
valueToCompare |
正在比較的值。例如: 日期:"2008/05/15-2005/05/17"、"2008/05/15" 大小:結尾是 B、KB、MB 或 GB 的數字。 "5GB"、"1KB-1MB" |
<component context="System" type="Application">
<displayName>File_size</displayName>
<role role="Data">
<rules>
<include filter='MigXmlHelper.FileProperties("dateAccessed","range","2008/05/15-2008/05/17")'>
<objectSet>
<pattern type="File">%SYSTEMDRIVE%\DOCS\* [*]</pattern>
</objectSet>
</include>
</rules>
</role>
</component>
<namedElements>
您可以使用 <namedElements> 元素來定義命名的元素。您可以在 .xml 檔案的任何元件中使用這些元素。如需此元素的使用範例,請參閱 MigApp.xml 檔案。
語法:
<namedElements>
</namedElements>
**出現次數:**無限制
父元素: <migration>
子元素: <environment>、<rules>、<conditions>、<detection>、<detects>、<detect>
如需此元素的範例,請參閱 MigApp.xml 檔案。
<object>
<object> 元素代表一個檔案或登錄機碼。
**出現次數:**無限制
父元素: <addObjects>
必要的子元素: <location>、<attributes>
選用的子元素: <bytes>
語法:
<object>
</object>
下列是取自 MigApp.xml 檔案的範例:
<addObjects>
<object>
<location type="Registry">%HklmWowSoftware%\Microsoft\Office\12.0\Common\Migration\Office [UpgradeVersion]</location>
<attributes>DWORD</attributes>
<bytes>0B000000</bytes>
</object>
<object>
<location type="Registry">%HklmWowSoftware%\Microsoft\Office\12.0\Common\Migration\Office [Lang]</location>
<attributes>DWORD</attributes>
<bytes>00000000</bytes>
</object>
</addObjects>
<objectSet>
<objectSet> 元素包含一系列的物件模式;例如,檔案路徑、登錄位置等。會先評估任何子 <conditions> 元素。如果所有子 <conditions> 元素都傳回 FALSE,<objectSet> 元素會評估為空集合。每一個父元素只能有多個 <objectSet> 元素。
**出現次數:**無限制
父元素: <variable>、<content>、<include>、<exclude>、<merge>、<contentModify>、<locationModify>、<destinationCleanup>、<includeAttributes>、<excludeAttributes>、<unconditionalExclude>、<detect>
必要的子元素: <script> 或 <pattern>
選用的子元素: <content>、<conditions>、<condition>
語法:
<objectSet>
</objectSet>
下列是取自 MigUser.xml 檔案的範例:
<component type="Documents" context="User">
<displayName _locID="miguser.mymusic">My Music</displayName>
<paths>
<path type="File">%CSIDL_MYMUSIC%</path>
</paths>
<role role="Data">
<detects>
<detect>
<condition>MigXmlHelper.DoesObjectExist("File","%CSIDL_MYMUSIC%")</condition>
</detect>
</detects>
<rules>
<include filter='MigXmlHelper.IgnoreIrrelevantLinks()'>
<objectSet> <pattern type="File">%CSIDL_MYMUSIC%\* [*]</pattern> </objectSet>
</include>
<merge script="MigXmlHelper.DestinationPriority()">
<objectSet> <pattern type="File">%CSIDL_MYMUSIC%\ [desktop.ini]</pattern> </objectSet>
</merge>
</rules>
</role>
</component>
<path>
這是內部 USMT 元素。請勿使用這個元素。
<paths>
這是內部 USMT 元素。請勿使用這個元素。
<pattern>
您可以使用這個元素來指定多個物件。您可以為每一個 <objectSet> 元素指定多個 <pattern> 元素,這些元素會結合在一起。如果您指定檔案,可以改用 GenerateDrivePatterns 和 <script>。GenerateDrivePatterns 基本上和 <pattern> 規則相同,但未指定磁碟機代號。例如,以下兩行是類似的程式碼:
<pattern type="File">C:\Folder\* [Sample.doc]</pattern>
<script>MigXmlHelper.GenerateDrivePatterns("\Folder\* [Sample.doc]","Fixed"</script>
**出現次數:**無限制
父元素: <objectSet>
**子元素:**無,但是 Path [object] 必須有效。
語法:
<pattern type="typeID">Path [object]</pattern>
設定 | 必要? | 值 | ||
---|---|---|---|---|
type |
是 |
typeID 可以是登錄、檔案或 Ini。如果 typeId 為 Ini,則 Path 和 object 之間不可以有空格。例如,當 type="Ini" 時,以下各項正確: <pattern type="Ini">%WinAmp5InstPath%\Winamp.ini|WinAmp[keeponscreen]</pattern> |
||
Path [object] |
是 |
有效的登錄或檔案路徑模式,後面至少要有一個空格,然後接括弧 [] (內含要移轉的物件)。
|
例如:
移轉單一登錄機碼:
<pattern type="Registry">HKLM\Software\Microsoft\Windows\CurrentVersion\Internet Settings\Cache [Persistent]</pattern>
從 C: 磁碟機移轉 EngineeringDrafts 資料夾和所有子資料夾:
<pattern type="File">C:\EngineeringDrafts\* [*]</pattern>
只從 C: 磁碟機移轉 EngineeringDrafts 資料夾,不移轉任何子資料夾:
<pattern type="File"> C:\EngineeringDrafts\ [*]</pattern>
從 C:\EngineeringDrafts 移轉 Sample.doc 檔案:
<pattern type="File"> C:\EngineeringDrafts\ [Sample.doc]</pattern>
以下列方式,使用模式從 C: 磁碟機上 Sample.doc 檔案所在處移轉該檔案。如果 C:\ 磁碟機上有多個同名的檔案,則會移轉所有檔案。
<pattern type="File"> C:\* [Sample.doc] </pattern>
如需更多此元素的使用範例,請參閱排除檔案與設定、重設檔案和設定的路徑、包含檔案與設定以及自訂 XML 範例。
<processing>
您可以使用此元素,在移轉程序中的特定點執行指令碼。您指定的指令碼不會傳回任何值,而且即使傳回值,也會略過。
**出現次數:**無限制
父元素: <rules>
必要的子元素: <script>
語法:
<processing when="pre-scan|scan-success|post-scan|pre-apply|apply-success|post-apply">
</processing>
設定 | 必要? | 值 |
---|---|---|
when |
是 |
指示指令碼何時執行。這個值可以是下列其中一項:
|
<plugin>
這是內部 USMT 元素。請勿使用這個元素。
<role>
自訂 .xml 檔案需要 <role> 元素。您可以藉由指定 <role> 元素建立實體元件。元件將由 <component> 層次指定的參數定義,並擁有您在此指定的角色。
**出現次數:**每一個 <component> 可以有一、二或三個子 <role> 元素。
父元素: <component>、<role>
必要的子元素: <rules>
選用的子元素: <environment>、<detection>、<component>、<role>、<detects>、<plugin>、
語法:
<role role="Container|Binaries|Settings|Data">
</role>
設定 | 必要? | 值 |
---|---|---|
role |
是 |
定義元件的角色。角色可以是以下其中一種:
您可以:
|
下列是取自 MigUser.xml 檔案的範例。如需更多範例,請參閱 MigApp.xml 檔案:
<component type="System" context="User">
<displayName _locID="miguser.startmenu">Start Menu</displayName>
<paths>
<path type="File">%CSIDL_STARTMENU%</path>
</paths>
<role role="Settings">
<detects>
<detect>
<condition>MigXmlHelper.DoesObjectExist("File","%CSIDL_STARTMENU%")</condition>
</detect>
</detects>
<rules>
<include filter='MigXmlHelper.IgnoreIrrelevantLinks()'>
<objectSet>
<pattern type="File">%CSIDL_STARTMENU%\* [*]</pattern>
</objectSet>
</include>
<merge script="MigXmlHelper.DestinationPriority()">
<objectSet>
<pattern type="File">%CSIDL_STARTMENU% [desktop.ini]</pattern>
<pattern type="File">%CSIDL_STARTMENU%\* [*]</pattern>
</objectSet>
</merge>
</rules>
</role>
</component>
<rules>
自訂 .xml 檔案需要 <rules> 元素。這個元素包含選取父 <component> 元素時將在移轉期間執行的規則,除非子 <conditions> 元素 (如果存在) 評估為 FALSE。每一個 <rules> 元素可以有多個子 <rules> 元素。
**出現次數:**無限制
父元素: <role>、<rules>、<namedElements>
必要的子元素: <include>
選用的子元素: <rules>、<exclude>、<unconditionalExclude>、<merge>、<contentModify>、<locationModify>、<destinationCleanup>、<addObjects>、<externalProcess>、<processing>、<includeAttributes>、<excludeAttributes>、<conditions>、<detects>
語法:
<rules name="ID" context="User|System|UserAndSystem">
</rules>
設定 | 必要? | 值 |
---|---|---|
name |
是,當 <rules> 為 <namedElements> 的子系時 否,當 <rules> 為任何其他元素的子系時 |
指定 ID 時,不會處理任何子元素。而是會處理 <namedElements> 元素中宣告的其他同名 <rules> 元素。 |
context |
否 (預設值 = UserAndSystem) |
定義此參數的範圍:要在特定使用者的內容、跨整個作業系統或在這兩個範圍中處理這個元件。 最大的可能範圍是由 component 元素設定。例如,如果 <component> 元素有 User 內容而 <rules> 元素有 UserAndSystem 內容,則 <rules> 元素的作用會和它具備 User 內容一樣。如果 <rules> 有 System 內容,作用會和沒有 <rules> 一樣。
|
下列是取自 MigUser.xml 檔案的範例:
<component type="Documents" context="User">
<displayName _locID="miguser.mymusic">My Music</displayName>
<paths>
<path type="File">%CSIDL_MYMUSIC%</path>
</paths>
<role role="Data">
<detects>
<detect>
<condition>MigXmlHelper.DoesObjectExist("File","%CSIDL_MYMUSIC%")</condition>
</detect>
</detects>
<rules>
<include filter='MigXmlHelper.IgnoreIrrelevantLinks()'>
<objectSet>
<pattern type="File">%CSIDL_MYMUSIC%\* [*]</pattern>
</objectSet>
</include>
<merge script="MigXmlHelper.DestinationPriority()">
<objectSet>
<pattern type="File">%CSIDL_MYMUSIC%\ [desktop.ini]</pattern>
</objectSet>
</merge>
</rules>
</role>
</component>
<script>
<script> 所需的傳回值取決於父元素。
出現次數: <variable> 一次,<objectSet> 和 <processing> 無限制
父元素: <objectSet>、<variable>、<processing>
**子元素:**無
語法和 Helper 函式:
一般語法:<script>ScriptWithArguments</script>
當 <script> 在 <variable> 內時,可以使用 <script> 函式。
語法:<script>MigXmlHelper.GetStringContent("ObjectType","EncodedLocationPattern", "ExpandContent")</script>
範例:
<script>MigXMLHelper.GetStringContent("Registry","HKLM\Software\MyApp\Installer [EXEPATH]")</script>
當 <script> 在 <objectSet> 內時,可以使用 <script> 函式。
語法:<script>MigXmlHelper.GenerateUserPatterns("ObjectType","EncodedLocationPattern","ProcessCurrentUser")</script>
範例:
<script>MigXmlHelper.GenerateUserPatterns ("File","%USERPROFILE%\* [*.doc]", "FALSE")</script>
當 <script> 在 <objectSet> 內時,可以使用 <script> 函式。
語法:<script>MigXmlHelper.GenerateDrivePatterns("PatternSegment","DriveType")</script>
範例:
<script>MigXmlHelper.GenerateDrivePatterns("* [sample.doc]", "Fixed")</script>
您可以將<script> 函式與 <processing> 元素內的 <script> 元素搭配使用:AskForLogoff、ConvertToShortFileName、KillExplorer、RemoveEmptyDirectories、RestartExplorer、RegisterFonts、StartService、StopService、SyncSCM。
語法:<script>MigXmlHelper.ExecutingScript</script>
範例:
<script>MigXmlHelper.KillExplorer()</script>
設定 | 必要? | 值 | ||
---|---|---|---|---|
ScriptWithArguments |
是 |
指令碼後面加上任意數量的字串引數,放在括號中並以逗號隔開。例如 <include> 規則中的物件集所列舉的每一個物件都會呼叫這個指令碼。篩選指令碼會傳回布林值。如果傳回值為 TRUE,則會移轉物件。如果為 FALSE,則不會移轉。 <script> 所需的傳回值取決於父元素。
|
範例:
若要從來源電腦上的任一磁碟機移轉 Sample.doc 檔案,請使用 <script>,如下所示。如果有多個同名的檔案,則會移轉所有同名的檔案。
<script>MigXmlHelper.GenerateDrivePatterns("* [sample.doc]", "Fixed")</script>
如需更多此元素的使用範例,請參閱排除檔案與設定、重設檔案和設定的路徑、重設檔案和設定的路徑以及自訂 XML 範例。
<script> 函式
您可以將下列函式與 <script> 元素搭配使用
字串與模式產生函式
簡單執行指令碼
字串與模式產生函式
這些函式會傳回字串或模式。
GetStringContent
您可以將 GetStringContent 與 <variable> 元素內的 <script> 元素搭配使用。如果可能的話,這個函式會傳回指定物件的字串代表。否則,會傳回 NULL。至於檔案物件,這個函式永遠傳回 NULL。
語法:GetStringContent("ObjectType","EncodedLocationPattern", "ExpandContent")
設定 必要? 值 ObjectType
是
物件的類型。可以是登錄或 Ini (表示 .ini 檔案)。
EncodedLocationPattern
是
- 如果物件類型為登錄,則 EncodedLocationPattern 必須是有效的登錄路徑。例如,HKLM\SOFTWARE\MyKey[]。
- 如果物件類型為 Ini,則 EncodedLocationPattern 必須為以下格式:
IniFilePath|SectionName[SettingName]
ExpandContent
否 (預設值 = TRUE)
可以是 TRUE 或 FALSE。如果是 FALSE,則指定位置傳回之前不會展開。
例如:
<variable name="MSNMessengerInstPath"> <script>MigXmlHelper.GetStringContent("Registry","%HklmWowSoftware%\Microsoft\MSNMessenger [InstallationDirectory]")</script> </variable>
- 如果物件類型為登錄,則 EncodedLocationPattern 必須是有效的登錄路徑。例如,HKLM\SOFTWARE\MyKey[]。
GenerateDrivePatterns
GenerateDrivePatterns 函式會逐一查看所有可用的磁碟機,然後選取與要求的磁碟機類型相符的磁碟機。再以 PatternSegment 的結尾部分串連選取的磁碟機,形成完整的編碼檔案模式。例如,如果 PatternSegment 為
Path [file.txt]
,而且 DriveType 為Fixed
,則該函式會產生C:\Path [file.txt]
,以及其他模式 (如果有 C: 以外的固定磁碟機)。您無法使用這個函式指定環境變數。您可以將 GenerateDrivePatterns 與 <objectSet> (位於 <include>/<exclude> 中) 內的 <script> 搭配使用。語法:GenerateDrivePatterns("PatternSegment","DriveType")
設定 必要? 值 PatternSegment
是
編碼模式的尾碼。它會以磁碟機規格串連,例如 "c:\",形成完整的 指定位置。例如,"* [*.doc]"。PatternSegment 不能是環境變數。
DriveType
是
要為模式產生的磁碟機類型。您可以指定以下其中一項:
- Fixed
- CDROM
- Removable
- Remote
如需此元素的範例,請參閱 MigUser.xml 檔案中的最後一個元件。
- Fixed
GenerateUserPatterns
這個函式會逐一查看所有移轉中的使用者 (如果 <ProcessCurrentUser> 為 FALSE,則排除目前處理的使用者),而且會展開每一個使用者內容中指定的模式。例如,如果使用者 A、B 和 C 在 C:\Documents and Settings 中有設定檔,則呼叫
GenerateUserPattens('File','%userprofile% [*.doc]','TRUE')
後,Helper 函式會產生以下三個模式:"C:\Documents and Settings\A\* [*.doc]"
"C:\Documents and Settings\B\* [*.doc]"
"C:\Documents and Settings\C\* [*.doc]"
語法:GenerateUserPatterns("ObjectType","EncodedLocationPattern","ProcessCurrentUser")
設定 必要? 值 ObjectType
是
定義物件類型。可以是檔案或登錄。
EncodedLocationPattern
是
指定位置。允許使用環境變數。
ProcessCurrentUser
是
可以是 TRUE 或 FALSE。指示是否要為目前的使用者產生模式。
範例:
如果當 USMT 處理使用者 A 時呼叫 GenerateUserPattens('File','%userprofile% [*.doc]','FALSE'),則這個函式只會產生使用者 B 和 C 的模式。您可以使用這個 Helper 函式建立複雜的規則。例如,若要從來源電腦移轉所有 .doc 檔案,但不移轉使用者 X,則不會從使用者 X 的設定檔移轉任何 .doc 檔案。
以下是這種情況的範例程式碼。第一個 <rules> 元素會移轉來源電腦上的所有 .doc 檔案,但 C:\Documents and Settings 內的 .doc 檔案除外。第二個 <rules> 元素會從 C:\Documents and Settings 移轉所有的 .doc 檔案,但其他使用者設定檔中的 .doc 檔案除外。因為會在每一個移轉的使用者內容中處理第二個 <rules> 元素,所以最終結果將會是所需的行為。最終結果是我們預期的結果。
<rules context="System"> <include> <objectSet> <script>MigXmlHelper.GenerateDrivePatterns ("* [*.doc]", "Fixed")</script> </objectSet> </include> <exclude> <objectSet> <pattern type="File">%ProfilesFolder%\* [*.doc]</pattern> </objectSet> </exclude> </rules> <rules context="User"> <include> <objectSet> <pattern type="File">%ProfilesFolder%\* [*.doc]</pattern> </objectSet> </include> <exclude> <objectSet> <script>MigXmlHelper.GenerateUserPatterns ("File","%userprofile%\* [*.doc]", "FALSE")</script> </objectSet> </exclude> </rules>
MigXmlHelper.GenerateDocPatterns
這個 Helper 函式會呼叫文件尋找程式,掃描系統中所有可移轉的檔案。您可以在系統內容或使用者內容中呼叫文件尋找程式,以集中掃描對象。
設定 | 必要? | 值 |
---|---|---|
ScanProgramFiles |
否 (預設值 = FALSE) |
可以是 TRUE 或 FALSE。ScanProgramFiles 參數會決定文件尋找程式是否掃描 Program Files 目錄,以收集已知應用程式的已登錄副檔名。例如,當設定為 TRUE 時,如果 .jpg 是在 Photoshop 登錄的副檔名,它會探索並移轉 Photoshop 目錄下的 .jpg 檔案。 |
IncludePatterns |
否 (預設值 = TRUE) |
可以是 TRUE 或 FALSE。TRUE 會產生包含模式,而且可以新增到 <include> 元素下。FALSE 會產生排除模式,而且可以新增到 <exclude> 元素下。 |
SystemDrive |
否 (預設值 = FALSE) |
可以是 TRUE 或 FALSE。如果為 TRUE,會將所有模式限制為系統磁碟機。 |
<!-- This component migrates data in user context -->
<component type="Documents" context="User">
<displayName>MigDocUser</displayName>
<role role="Data">
<rules>
<include filter='MigXmlHelper.IgnoreIrrelevantLinks()'>
<objectSet>
<script>MigXmlHelper.GenerateDocPatterns ("false")</script>
</objectSet>
</include>
<exclude>
<objectSet>
<script>MigXmlHelper.GenerateDocPatterns ("false", "false", "false")</script>
</objectSet>
</exclude>
</rules>
</role>
</component>
簡單執行指令碼
下列指令碼沒有傳回值。您可以將以下錯誤與 <processing> 元素內的 <script> 元素搭配使用。
AskForLogoff()。提示使用者在移轉結束時登出。例如:
<processing when="apply-success"> <script>MigXmlHelper.AskForLogoff()</script> </processing>
ConvertToShortFileName(RegistryEncodedLocation)。如果 RegistryEncodedLocation 是現有檔案的完整路徑,這個函式會將檔案轉換成簡短檔案名稱,然後更新登錄值。
KillExplorer()。停止目前使用者內容的 Explorer.exe。這樣可以允許存取當 Explorer.exe 執行時保持開啟的特定機碼以及檔案。例如:
<processing when="pre-apply"> <script>MigXmlHelper.KillExplorer()</script> </processing>
RegisterFonts(FileEncodedLocation)。登錄指定的字型或指定目錄中的所有字型。例如:
<processing when="apply-success"> <script>MigXmlHelper.RegisterFonts("%CSIDL_COMMON_FONTS%")</script> </processing>
**RemoveEmptyDirectories (DirectoryEncodedPattern)。**刪除與目的電腦上的 DirectoryEncodedPattern 相符的任何空目錄。
**RestartExplorer()。**移轉結束時重新啟動 Explorer.exe。例如:
<processing when="post-apply"> <script>MigXmlHelper.RestartExplorer()</script> </processing>
**StartService (ServiceName, OptionalParam1, OptionalParam2,…)。**啟動 ServiceName 識別的服務。ServiceName 是 HKLM\System\CurrentControlSet\Services 中的子機碼,負責保存指定服務的資料。選用的參數 (如果有的話) 會傳送至 StartService API。如需詳細資訊,請參閱 這個 Microsoft 網站。
StopService (ServiceName) 停止 ServiceName 識別的服務。ServiceName 是 HKLM\System\CurrentControlSet\Services 中的子機碼,負責保存指定服務的資料。
**SyncSCM(ServiceShortName)。**移轉引擎變更啟動類型值後,從登錄 (HKLM\System\CurrentControlSet\Services\ServiceShortName [Start]) 讀取該值,然後以新的值同步處理服務控制管理員 (SCM)。
<text>
您可以使用 <text> 元素設定移轉 .xml 檔案中任何環境變數的值。
**出現次數:**每個 <variable> 元素一次。
父元素: <variable>
**子元素:**無。
語法:
<text>NormalText</text>
設定 | 值 |
---|---|
NormalText |
解譯為一般文字。 |
例如:
<variable name="QuickTime5or6DataSys">
<text>%CSIDL_COMMON_APPDATA%\QuickTime</text>
</variable>
<unconditionalExclude>
<unconditionalExclude> 元素會從移轉排除指定的檔案以及登錄值,無論任何移轉 .xml 檔案或 Config.xml 檔案中的其他包含規則為何。在此宣告的物件不會被移轉,因為這個元素的優先順序高於所有其他規則。例如,即使有明確的 <include> 規則包含 .mp3 檔案,但如果您以這個選項指定排除它們,就不會移轉這些檔案。
如果想從來源電腦排除所有 .mp3 檔案,請使用這個元素。或是,如果使用另一種方法備份 C:\UserData,則可以從移轉中排除整個資料夾。不過,使用這個元素時請小心,因為如果應用程式需要使用被您排除的檔案,應用程式可能無法在目的電腦上正常運作。
**出現次數:**無限制。
父元素: <rules>
子元素: <objectSet>
語法:
<unconditionalExclude></unconditionalExclude>
下列 .xml 檔案會從移轉排除所有 .mp3 檔案。如需此元素的其他使用範例,請參閱排除檔案與設定。
<migration urlid="https://www.microsoft.com/migration/1.0/migxmlext/excludefiles">
<component context="System" type="Documents">
<displayName>Test</displayName>
<role role="Data">
<rules>
<unconditionalExclude>
<objectSet>
<script>MigXmlHelper.GenerateDrivePatterns ("* [*.mp3]", "Fixed")</script>
</objectSet>
</unconditionalExclude>
</rules>
</role>
</component>
</migration>
<variable>
<variable> 元素是 <environment> 元素內的必要元素。每一個 <variable> 元素必須要有一個 <objectSet>、<script> 或 <text> 元素。<variable> 元素的內容會指派一個文字值給環境變數。這個元素有以下三個選項:
如果 <variable> 元素包含 <text> 元素,則 variable 元素的值將會是 <text> 元素的值。
如果 <variable> 元素包含 <script> 元素,而且呼叫指令碼後產生非空值字串,則 <variable> 元素的值將會是指令碼呼叫的結果。
如果 <variable> 元素包含 <objectSet> 元素,而且 <objectSet> 元素評估後至少產生一個物件模式,則要符合結果物件模式的 first 物件值將會是變數元素的值。
**出現次數:**無限制
父元素: <environment>
必要的子元素: <text> 或 <script> 或 <objectSet>
語法:
<variable name="ID" remap=TRUE|FALSE>
</variable>
設定 | 必要? | 值 |
---|---|---|
name |
是 |
ID 是一個字串值,這是用於參考環境變數的名稱。建議 ID 以元件的名稱開頭,可以避免命名空間衝突。例如,如果元件的名稱是 MyComponent,而您希望變數是元件的安裝路徑,您可以指定 |
remap |
否,預設值 = FALSE |
指定是否將這個環境變數評估為重新對應環境變數。位於這個環境變數值底下之路徑中的物件,會自動移至環境變數指向的目的電腦位置。 |
下列是取自 MigApp.xml 檔案的範例:
<environment>
<variable name="HklmWowSoftware">
<text>HKLM\Software</text>
</variable>
<variable name="WinZip8or9or10Exe">
<script>MigXmlHelper.GetStringContent("Registry","%HklmWowSoftware%\Microsoft\Windows\CurrentVersion\App Paths\winzip32.exe []")</script>
</variable>
</environment>
<version>
<version> 元素會定義元件的版本,但不會影響移轉。
**出現次數:**零或一次
父元素: <component>
**子元素:**無
語法:
<version>ComponentVersion</version>
設定 | 必要? | 值 |
---|---|---|
ComponentVersion |
是 |
元件的版本,可以包含模式。 |
例如:
<version>4.*</version>
<windowsObjects>
<windowsObjects> 元素僅供 USMT 內部使用。請勿使用這個元素。
附錄
指定位置
指定編碼位置。所有 Helper 函式中使用的編碼位置是物件名稱的明確字串表示。它是由節點部分所組成,後面可選擇性地加上以方括弧括住的分葉。這可以清楚區分節點和分葉。
例如,如下指定檔案 C:\Windows\Notepad.exe:
c:\Windows[Notepad.exe]
。同樣地,如下指定目錄 C:\Windows\System32:c:\Windows\System32
。(請注意,沒有 [] 結構)。代表登錄十分類似。登錄機碼的預設值會呈現為空的 [] 結構。例如,HKLM\SOFTWARE\MyKey 登錄機碼的預設值將會是
HKLM\SOFTWARE\MyKey[]
。指定位置模式。指定位置模式的方法和指定實際位置的方法類似。不同之處在於節點和分葉部分都接受模式。不過,節點的模式並不會延伸至分葉。
例如,模式
c:\Windows\*
會比對 Windows 目錄以及所有子目錄。但是,不會比對這些目錄中的任何檔案。若要同時比對這些檔案,您必須指定c:\Windows\*[*]
。
內部 USMT 函式
下列函式僅供內部 USMT 使用。請不要在 .xml 檔案中使用它們。
AntiAlias
ConvertScreenSaver
ConvertShowIEOnDesktop
ConvertToOfficeLangID
MigrateActiveDesktop
MigrateAppearanceUPM
MigrateDisplayCS
MigrateDisplaySS
MigrateIEAutoSearch
MigrateMouseUPM
MigrateSoundSysTray
MigrateTaskBarSS
SetPstPathInMapiStruc
有效的版本標籤
您可以將下列版本標籤與各種 Helper 函式搭配使用:
“CompanyName”
“FileDescription”
“FileVersion”
“InternalName”
“LegalCopyright”
“OriginalFilename”
“ProductName”
“ProductVersion”
下列版本標籤包含可以比較的值:
“FileVersion”
“ProductVersion”