共用方式為

XML 元素庫

本文說明可以用來撰寫移轉.xml檔案以搭配用戶狀態移轉工具 (USMT ) 使用的 XML 元素和協助程式函式。 本文假設您具備 XML 的基本知識。

除了 XML 元素和協助程式函式，本文：

  • 描述如何指定編碼的位置和位置模式。
  • 僅供內部 USMT 使用的函式。
  • 可用於協助程式函式的版本標籤。

元素和協助程式函式

下表描述 XML 元素和協助程式函式可以搭配 USMT 使用。

元素 A-K 元素 L-Z 協助程式函式
<addObjects>
<屬性>
<位元組>
<commandLine>
<元件>
<條件>
<條件>
<內容>
<contentModify>
<描述>
<destinationCleanup>
<檢測>
<檢測>
<檢波>
<displayName>
<環境>
<排除>
<excludeAttributes>
<擴展>
<外延>
<externalProcess>
<icon>
<include>
<includeAttribute>		 <圖書館>
<位置>
<locationModify>
<_locDefinition>
<製造者>
<合併>
<遷移>
<namedElements>
<物件>
<objectSet>
<路徑>
<路徑>
<圖樣>
<加工>
<外掛程式>
<角色>
<規則>
<腳本>
<發簡訊>
<無條件Exclude>
<變數>
<版本>
<windowsObjects>		 <condition> 函式
<內容> 函式
<contentModify> 函式
<包含> 和 <排除> 篩選函式
<locationModify> 函式
<合併> 函式
<script> 函式
內部 USMT 函式

<addObjects>

addObjects<> 元素會模擬來源計算機上存在一或多個物件。 子 <物件> 元素會提供模擬對象的詳細數據。 如果內容是 <腳本> 專案，則調用的結果會是 對象的陣列。

語法：

<addObjects>
</addObjects>

下列範例來自 MigApp.xml 檔案：

<addObjects>
   <object>
      <location type="Registry">%HklmWowSoftware%\Microsoft\Office\16.0\Common\Migration\Office [UpgradeVersion]</location>
      <attributes>DWORD</attributes>
      <bytes>0B000000</bytes>
   </object>
   <object>
      <location type="Registry">%HklmWowSoftware%\Microsoft\Office\16.0\Common\Migration\Office [Lang]</location>
      <attributes>DWORD</attributes>
      <bytes>00000000</bytes>
   </object>
</addObjects>

<屬性>

attributes<> 元素會定義登錄機碼或檔案的屬性。

語法：

<attributes>Content</attributes>
設定 必要？ 值
內容 是 內容取決於指定的物件類型。
  • 對於檔案，內容可以是字串，其中包含下列任何以逗號分隔的屬性：
    • Archive
    • 唯讀
    • 系統
    • Hidden
  • 針對登錄機碼，內容可以是下列其中一種類型：
    • 無
    • 字串
    • ExpandString
    • 二進位 (Binary)
    • Dword
    • REG_SZ

下列範例來自 MigApp.xml 檔案：

<object>
   <location type="Registry">%HklmWowSoftware%\Microsoft\Office\16.0\Common\Migration\Office [Lang]</location>
   <attributes>DWORD</attributes>
   <bytes>00000000</bytes>
</object>

<位元組>

位 <元組> 元素只能針對檔案指定，因為如果 <位置> 對應至登錄機碼或目錄，則 <會忽略位元組> 。

  • 發生次數： 零或一

  • 父元素：<object>

  • 子元素： 無

語法：

<bytes string="Yes|No" expand="Yes|No">Content</bytes>
設定 必要？ 值
string 否，預設值為 No 判斷 內容 應該解譯為字串或位元組。
expand 否 (預設值 = 是 當 expand 參數為 [是] 時，位元組>項目的內容<會先在來源計算機的內容中展開，然後再進行解譯。
內容 是 取決於字串的值。
  • 當字串為 [是] 時：位元組>項目的內容<會解譯為字元串。
  • 當字串為 No 時：位元組>項目的內容<會解譯為位元組。 每兩個字元代表位元組的十六進位值。 例如， 616263 是 ANSI 字串的 abc 表示。 包含字串終止符的 UNICODE 字串 abc 完整表示法為： 6100620063000000。

下列範例來自 MigApp.xml 檔案：

<object>
   <location type="Registry">%HklmWowSoftware%\Microsoft\Office\16.0\Common\Migration\Office [Lang]</location>
   <attributes>DWORD</attributes>
   <bytes>00000000</bytes>
</object>

<commandLine>

commandLine <> 元素可用來啟動或停止執行 ScanState 和 LoadState 工具之前或之後的服務或應用程式。

語法：

<commandLine>CommandLineString</commandLine>
設定 必要？ 值
CommandLineString 是 有效的命令行。

<元件>

自<訂.xml檔中需要元件>專案。 此元素會定義移轉.xml檔案的最基本建 構 。 例如，在 檔案中 MigApp.xml ， Microsoft Office 2016 是包含另一個元件的元件， Microsoft Office Access 2016。 子專案可用來定義元件。

元件可以巢狀於另一個元件內;也就是說，<元件專案可以是元件>>元素內<角色>元素的<子系，在兩種情況下：

  1. 當父 <元件> 專案是容器時
  2. 如果子<元件專案與父元件>>專案具有相同的角色。<

語法：

<component type="System|Application|Device|Documents" context="User|System|UserAndSystem" defaultSupported="TRUE|FALSE|YES|NO"
hidden="Yes|No">
</component>
設定 必要？ 值
類型 是 下列專案可用來群組設定，並定義元件的類型。
  • 系統： 操作系統設定。 所有 Windows 元件都是由這個類型所定義。
    當 type=“System” 和 defaultSupported=“FALSE” 時，除非命令行上LoadState.exe指定的 .xml 檔案中有對等的元件，否則不會移轉設定。 例如，默認 MigSys.xml 檔案包含 type=“System” 和 defaultSupported=“FALSE” 的元件。 如果在命令行上 ScanState.exe 指定此檔案，則必須在命令行上 LoadState.exe 指定檔案，以便移轉設定。 必須指定檔案， LoadState.exe 因為工具必須偵測對等的元件。 也就是說，元件必須具有相同的移轉 urlid .xml 檔案和相同的顯示名稱。 否則， LoadState 工具不會從存放區移轉這些設定。 此設定很有幫助，因為存放區可用於與來源電腦相同或不同 Windows 版本的目的地電腦。
  • 應用： 應用程式的設定。
  • 裝置： 裝置的設定。
  • 檔： 指定檔案。
上下文 否
預設值 = UserAndSystem		 定義這個參數的範圍;也就是說，是否要在整個操作系統或兩者中，於特定使用者的內容中處理此元件。
元件>項目會設定<最大可能的範圍。 例如，如果 <元件> 元素的內容是 User ，而 <rules> 元素的內容是 UserAndSystem，則 <rules> 元素的作用就如同其內容是 User。 <如果 rules> 元素的內容是 System，它的作用就如同 rules> 元素不存在一樣<。
  • 使用者：評估每個使用者的元件。
  • 系統：僅評估系統的元件一次。
  • UserAndSystem：評估整個操作系統和每個使用者的元件。
defaultSupported 否
(預設值 = TRUE) 		可以是任何 TRUE、 FALSE、 YES 或 NO。 如果此參數為 FALSE (或 NO) ，除非目的地電腦上有對等的元件，否則不會移轉元件。
當 type=“System” 和 defaultSupported=“FALSE” 時，除非命令行上LoadState.exe指定的 .xml 檔案中有對等的元件，否則不會移轉設定。 例如，默認 MigSys.xml 檔案包含 type=“System” 和 defaultSupported=“FALSE” 的元件。 如果在命令行上 ScanState.exe 指定此檔案，則必須在命令行上 LoadState.exe 指定檔案，以便移轉設定。 因為 LoadState 工具必須偵測對等的元件，所以必須在這兩個命令行中指定檔案。 也就是說，元件必須具有相同的 .xml 檔案移轉 urlid 和相同的顯示名稱，否則 LoadState 工具不會從存放區移轉這些設定。 此設定很有幫助，因為存放區可用於與來源電腦相同或不同 Windows 版本的目的地電腦。
隱藏 此參數僅供內部 USMT 使用。

如需範例，請參閱任何預設移 轉.xml 檔案。

<條件>

雖然仍支援 detect>、 objectSet 和 addObjects 元素底下的<condition> 元素，Microsoft建議您不要再使用 condition 元素，因為它在未來的 USMT 版本中可能已被取代。<<><><> <如果 condition> 元素已被取代，則需要重寫任何使用 condition> 元素的<腳本。 相反地，如果需要在 objectSet> 和 addObjects 元素內<使用條件，Microsoft建議使用功能更強大的 <condition> 元素。>< conditions<> 元素可讓您編寫複雜的布爾語句。

條件<>專案具有布爾值結果。 此元素可用來指定評估父元素的條件。 如果任何目前條件傳回 FALSE，則不會評估父元素。

  • 發生次數： 無限制。

  • 父元素：<conditions>、 <detect>、 <objectSet>、 <addObjects>

  • 子元素： 無

  • 協助程式函式：下列<條件>函式可以與這個專案搭配使用：DoesOSMatch、、、IsOSLaterThanIsNative64Bit()、、IsOSEarlierThan、DoesObjectExistDoesFileVersionMatch、IsFileVersionAbove、、、IsSystemContextIsFileVersionBelow、IsSameObjectDoesStringContentContainIsSameContentDoesStringContentEqual、 和 。IsSameStringContent

語法：

<condition negation="Yes|No">ScriptName</condition>
設定 必要？ 值
否定 否
預設 = 否		 “Yes” 會反轉條件的 True/False 值。
ScriptName 是 在這個移轉區段中定義的腳本。

例如，在下列程式代碼範例中， <條件> 元素 A 和 B 會由 AND 運算子聯結在一起，因為它們位於不同的 <條件> 區段中：

<detection>
   <conditions>
      <condition>A</condition>
   </conditions>
   <conditions operation="AND">
      <condition>B</condition>
   </conditions>
</detection>

不過，在下列程式代碼範例中 <，條件> 專案 A 和 B 會由 OR 運算符聯結在一起，因為它們位於相同的 <條件> 區段中。

<detection>
   <conditions>
      <condition>A</condition>
      <condition>B</condition>
   </conditions>
</detection>

<condition> 函式

條件<>函式會傳回布爾值。 這些元素可用於 <addObjects> 條件。

操作系統版本函式

  • DoesOSMatch

    所有相符專案都不區分大小寫。

    語法： DoesOSMatch("OSType","OSVersion")

    設定 必要？ 值
    OSType 是 此設定的唯一有效值是 NT。 不過，必須設定此設定， <條件> 函式才能正確運作。
    OSVersion 是 主要版本、次要版本、組建編號和更正的服務磁碟版本，以句點分隔。 例如，5.0.2600.Service Pack 1。 版本的部分規格也可以使用 模式來指定，例如 5.0.*。

    例如：

    <condition>MigXmlHelper.DoesOSMatch("NT","\*")</condition>

  • IsNative64Bit

    如果移轉程式是以原生 64 位進程執行， 則 IsNative64Bit 函式會傳回 TRUE ;也就是說，在沒有 Windows 上 Windows 的 64 位系統上執行的進程 (WOW) 。 否則，它會傳回 FALSE。

  • IsOSLaterThan

    所有比較都不區分大小寫。

    語法： IsOSLaterThan("OSType","OSVersion")

    設定 必要？ 值
    OSType 是 可以是 9 倍 或 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 是 可以是 9 倍 或 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< 元素會傳回布爾值結果，用來指定評估父元素的條件。 USMT 會評估子專案，然後根據作業參數使用 AND 或 OR 運算符來聯結其結果。

語法：

<conditions operation="AND|OR">
</conditions>
設定 必要？ 值
操作 否，預設 = AND 定義從子專案取得的結果上執行的布爾運算。

下列範例來自 MigApp.xml 檔案：

<environment name="GlobalEnv">
   <conditions>
      <condition negation="Yes">MigXmlHelper.IsNative64Bit()</condition>
   </conditions>
   <variable name="HklmWowSoftware">
   <text>HKLM\Software</text>
   </variable>
</environment>

<內容>

內容<>專案可用來指定物件模式清單，以從來源計算機取得物件集。 系統會評估內容>元素內的<每個 <objectSet>。 針對每個產生的物件模式清單，會列舉與其相符的物件，並由篩選參數篩選其內容。 產生的字串數位是內容>項目的輸出<。 篩選文本會傳回位置的陣列。 父 <物件Set> 元素可以包含多個子 <內容> 專案。

  • 發生次數： 無限制

  • 父元素：<objectSet>

  • 子元素：<objectSet>

  • 協助程式函式： 下列 <內容> 函式 可以與這個專案搭配使用： ExtractSingleFile、 ExtractMultipleFiles和 ExtractDirectory。

語法：

<content filter="ScriptInvocation">
</content>
設定 必要？ 值
filter 是 腳本，後面接著任意數目的字串自變數，以逗號分隔，並以括弧括住。 例如，MyScripts.AScript ("Arg1","Arg2")。
腳本會針對包含規則中的<>物件集所列舉的每個物件呼叫。 篩選文本會傳回布爾值。 如果傳回值為 TRUE，則會移轉物件。 如果為 FALSE，則不會移轉。

<內容> 函式

下列函式會從物件的內容產生模式。 這些函式會針對父 <ObjectSet> 元素所列舉的每個物件呼叫。

  • ExtractSingleFile

    如果登錄值是 MULTI-SZ，則只會處理第一個區段。 傳回的模式是必須存在於系統上之檔案的編碼位置。 如果登錄值中的規格正確，但檔案不存在，則此函式會傳回 NULL。

    語法： ExtractSingleFile(Separators,PathHints)

    設定 必要？ 值
    分隔符 是 可能遵循此登錄值名稱中檔案規格的可能分隔符清單。 例如，如果內容為 「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， <分隔符自變數> 必須是 NULL。

    傳回的模式是來源計算機上必須存在之檔案的編碼位置。 如果登錄值中的規格正確，但檔案不存在，則不會包含在產生的清單中。

    語法： ExtractMultipleFiles(Separators,PathHints)

    設定 必要？ 值
    分隔符 是 可能遵循此登錄值名稱中檔案規格的可能分隔符清單。 例如，如果內容為 「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)

    設定 必要？ 值
    分隔符 否 可能遵循此登錄值名稱中檔案規格的可能分隔符清單。 例如，如果內容為 「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>
設定 必要？ 值
腳本 是 腳本，後面接著任意數目的字串自變數，以逗號分隔，並以括弧括住。 例如 MyScripts.AScript ("Arg1","Arg2").

腳本會針對包含規則中的物件集所列舉的每個物件呼叫。 篩選文本會傳回布爾值。 如果傳回值為 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，然後將結果寫回目的地電腦上的登錄值。 例如，如果移轉的對像是值為 的 14DWORD，而 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。 您可以指定每種 OptionString 類型的 其中一種。 請勿指定具有相同值的多個 OptionString。 如果指定了多個具有相同值 的 OptionString ，則會保留該類型的最右邊選項。 例如，請勿指定 (“FileAttrib：H”、“FileAttrib：R”) ，因為只會評估只讀的。 請改為指定 (“FileAttrib：HR”) ，並將 Hidden 和 Read-only 屬性保留在目的地計算機上。
    • 安全性：如果目的地物件存在，則保留其安全描述項。
    • TimeFields：保留目的地對象的時間戳。 此參數僅適用於檔案。
    • FileAttrib：<Letter>：針對指定的檔案屬性集，保留目的地對象的屬性值 ON 或OFF。 此參數僅適用於檔案。 下列不區分大小寫，但 USMT 會忽略任何無效、重複的值，或 FileAttrib： 之後有空格。 您可以指定下列屬性的任何組合：
      • A = 封存
      • C = 壓縮
      • E = 加密
      • H = 隱藏
      • I = 未編制內容索引
      • O = 離線
      • R = Read-Only
      • S = 系統
      • T = 暫存

  • MergeMultiSzContent

    MergeMultiSzContent 函式會合併父 <ObjectSet> 元素所列舉之登錄值的 MULTI-SZ 內容，以及目的地計算機上已存在的對等登錄值內容。 Instruction 並將 String 內容移除或新增至產生的 MULTI-SZ。 系統會移除重複的專案。

    語法： MergeMultiSzContent (Instruction,String,Instruction,String,…)

    設定 必要？ 值
    指令 是 可以為下列其中一個值：
    • 新增。 如果產生的 MULTI-SZ 尚未存在，請將對應的 String 新增至產生的 MULTI-SZ。
    • 拿掉。 從產生的 MULTI-SZ 中移除對應的 String。
    字串 是 要加入或移除的字串。

  • MergeDelimitedContent

    MergeDelimitedContent 函式會將父 <ObjectSet> 元素所列舉的登錄值內容與目的地電腦上已存在的對等登錄值內容合併。 內容會被視為以 Delimiters 參數中的其中一個字元分隔的項目清單。 系統會移除重複的專案。

    語法： MergeDelimitedContent(Delimiters,Instruction,String,…)

    設定 必要？ 值
    分隔符 是 單一字元，用來分隔正在處理之對象的內容。 內容會被視為以 分隔符分隔的項目清單。
    例如， "." 會根據句點來分隔字串。
    指令 是 可以為下列其中一個值：
    • 新增：如果 字串 尚未存在，則會將字串新增至產生的 MULTI-SZ。
    • 拿掉：從產生的 MULTI-SZ 移除 String 。
    字串 是 要加入或移除的字串。

<描述>

description<> 元素會定義元件的描述，但不會影響移轉。

  • 發生次數： 零或一

  • 父元素：<component>

  • 子元素： 無

語法：

<description>ComponentDescription</description>
設定 必要？ 值
ComponentDescription 是 元件的描述。

下列程式代碼範例示範描述>元素如何<定義「我的自訂元件」描述：

<description>My custom component<description>

<destinationCleanup>

destinationCleanup<> 元素會先從目的地計算機刪除物件，例如檔案和登錄機碼，再從來源計算機套用物件。 只有在目的地電腦上執行 LoadState 工具時，才會評估這個專案。 也就是說， ScanState 工具會忽略這個專案。

重要

請特別小心使用此選項，因為它會從目的地計算機刪除物件。

對於每個 <destinationCleanup> 元素，可以有多個 <objectSet> 元素。 此元素的常見用途是來源計算機上遺失登錄機碼，但仍需要移轉元件。 在此情況下，可以先刪除元件的所有登錄機碼，再移轉來源登錄機碼。 刪除所有元件的登錄機碼可確保如果來源電腦上有遺漏的密鑰，目的地計算機上也會遺失該機碼。

  • 發生次數： 無限

  • 父元素：<rules>

  • Child elements：<objectSet> (目的地計算機會刪除所有子專案。)

語法：

<destinationCleanup filter=ScriptInvocation>
</destinationCleanup>
設定 必要？ 值
filter 是 腳本，後面接著任意數目的字串自變數，以逗號分隔，並以括弧括住。 例如，MyScripts.AScript ("Arg1","Arg2")。

腳本會針對包含規則中的物件集所列舉的每個物件呼叫。 篩選文本會傳回布爾值。 如果傳回值為 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>

<檢測>

雖然仍支援偵測>元素，Microsoft建議您不要再使用 detect 元素，因為它在未來的 USMT 版本中可能已被取代。<>< <如果 detect> 元素已被取代，則需要重寫任何使用 detect> 元素的<腳本。 相反地，Microsoft建議使用 <偵測> 專案。 偵<測>元素可讓您更清楚地制定複雜的布爾語句

偵<測>專案可用來判斷元件是否存在於系統上。 如果偵測專案內<的所有子偵測>>專案都解析為 TRUE，則 detect 元素會解<析為 TRUE。>< 如果有任何子 <偵測> 專案解析為 FALSE，則其父 <偵測> 專案會解析為 FALSE。 <如果沒有 detect> 元素區段，USMT 會假設該元件存在。

對於每個 <偵測> 專案，可以有多個子 <系條件> 或 <objectSet> 元素，這些專案會以邏輯方式由 OR 運算符聯結。 如果至少有一個 <條件> 或 <objectSet> 元素評估為 TRUE，則 <detect> 元素會評估為 TRUE。

語法：

<detect name="ID" context="User|System|UserAndSystem">
</detect>
設定 必要？ 值
name 是，偵測>為 namedElements 的子系時<><
否，偵測>為要偵測的子系時<<>		 指定 ID 時，不會處理任何子專案。 相反地，會處理在 namedElements> 元素內宣告具有相同名稱的<任何其他<偵測>專案。
上下文 否
(預設值 = UserAndSystem) 		定義此參數的範圍，也就是在特定用戶的內容中、整個操作系統或兩者中處理此元件。
元件項目會設定最大可能的範圍。 例如，如果<元件>元素的內容是User，而 <rules> 元素的內容是UserAndSystem，則 <rules> 元素的作用就如同使用者的內容一樣。 如果 rules<> 元素的內容是 System，它的作用就如同 rules> 元素不存在一樣<。
  • 用戶：評估每個使用者的變數。
  • 系統：只評估系統的變數一次。
  • UserAndSystem：評估整個操作系統和每個使用者的變數。

如需範例，請參閱偵測>範<例。

<檢測>

雖然仍支援 detects> 元素，Microsoft建議您不要再使用 detects 元素，因為它在未來的 USMT 版本中可能已被取代。<<> <如果 detects> 元素已被取代，則需要重寫任何使用 <detects 元素的>腳本。 相反地，如果父元素是 <role> 或 <namedElements>，則Microsoft建議使用<偵>測元素;如果父元素是<規則>，則使用 <conditions> 元素。 偵<測>元素可讓您更清楚地制定複雜的布爾語句，<而 conditions> 元素允許編寫複雜的布爾語句。

detects<> 元素是一或多個<偵測>專案的容器。 如果偵測到 項目內的所有子<系都偵>測>到 TRUE，則會偵測解析為 TRUE。<>< 如果任何子 <偵測元素> 解析為 FALSE，則 <會偵測> 解析為 FALSE。 若要防止<在元件中寫入 detects> 元素，請在 namedElements> 元素下<建立 detects> 元素，然後參考它。< <如果沒有 detects> 元素區段，USMT 會假設該元件存在。 OR 運算符會將每個 <detects> 專案的結果聯結在一起，以形成用來偵測父元素的規則。

語法：

<detects name="ID" context="User|System|UserAndSystem">
</detects>
設定 必要？ 值
name 是，當偵測到><是具名Elements 的子系>時<
否，當偵測到> 是角色或<規則>的子<系>時<		 指定 ID 時，不會處理任何子 <偵測> 專案。 相反地，任何其他<項目都會偵測>在 namedElements> 元素內<宣告的同名專案。
上下文 否
(預設值 = UserAndSystem) 		定義此參數的範圍：是否要在特定用戶的內容中、整個作業系統或兩者中處理此元件。
元件項目>會設定<最大可能的範圍。 例如，如果<元件>元素的內容是User，而 <rules> 元素的內容是UserAndSystem，則 <rules> 元素的運作方式就如同使用者的內容一樣。 如果 rules<> 元素的內容是 System，它的作用就如同 rules> 元素不存在一樣<。
  • 用戶：評估每個使用者的變數。
  • 系統：只評估系統的變數一次。
  • UserAndSystem：評估整個操作系統和每個使用者的變數。

偵測規則>元素內<的專案>會忽略<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>

<檢波>

偵<測>專案是一個條件>專案的容器<。 位於 condition> 專案下方<的子<條件>項目結果會決定這個項目的結果。 例如，如果偵>測元素內<的所有子<條件>專案都解析為 TRUE，則<偵測>元素會解析為 TRUE。 如果任何子 <條件> 專案解析為 FALSE，則 <偵測> 專案會解析為 FALSE。

此外，角色>元素內<每個<偵測>區段的結果會由 OR 運算符聯結在一起，以形成父元素的偵測規則。 也就是說，如果其中一個 <偵測> 區段解析為 TRUE，則 <會處理角色> 元素。 否則， <不會處理角色> 專案。

使用 namedElements> 元素下的<偵測>專案，不在元件內寫入。< 然後在 role> 元素下方包含相符的<偵測>區段，以控制是否要移轉元件。< 如果元件沒有 <偵> 測區段，則USMT會假設該元件存在。

語法：

<detection name="ID" context="User|System|UserAndSystem">
</detection>
設定 必要？ 值
name
  • 是，在 namedElements> 下<宣告偵測>時<
  • 選擇性，在角色>下<宣告時
 如果宣告，則會忽略偵測>項目的內容<，並評估在 namedElements> 元素中<宣告名稱相同的偵>測項目內容<。
上下文 否，預設值 = UserAndSystem 定義此參數的範圍：是否要在特定用戶的內容中、整個作業系統或兩者中處理此元件。
  • 使用者：評估每個使用者的元件。
  • 系統：僅評估系統的元件一次。
  • 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>

  • 子元素： 無

語法：

<displayName _locID="ID">ComponentName</displayName>
設定 必要？ 值
locID 否 此參數適用於內部 USMT 使用。 請勿使用此參數。
ComponentName 是 元件的名稱。

例如：

<displayName>Command Prompt settings</displayName>

<環境>

環境<>元素是變數>元素的<容器，可在其中定義變數以用於 .xml 檔中。 以這種方式定義的所有環境變數都是私用的。 也就是說，它們僅適用於其子元件及其定義所在的元件。 如需兩個範例案例，請參閱 範例。

語法：

<environment name="ID" context="User|System|UserAndSystem">
</environment>
設定 必要？ 值
name 是，當 environment> 是 namedElements 的子系時<><
否，當環境>是角色或元件的子系時<><<>		 當宣告為角色>或元件元素的<子系時，如果已宣告ID，USMT會忽略環境>元素的內容<，並處理在 namedElements> 元素中<宣告名稱相同的環境>項目內容<。><
上下文 否
(預設值 = UserAndSystem) 		定義此參數的範圍：是否要在特定用戶的內容中、整個作業系統或兩者中處理此元件。
元件>項目會設定<最大可能的範圍。 例如，如果<元件>元素的內容是User，而 <rules> 元素的內容是UserAndSystem，則 <rules> 元素的運作方式就如同使用者的內容一樣。 如果 rules<> 元素的內容是 System，它的作用就如同規則>不存在一樣<。
  • 用戶：評估每個使用者的變數。
  • 系統：只評估系統的變數一次。
  • UserAndSystem：評估整個操作系統和每個使用者的變數。

範例

範例案例 1

在此案例中，根據目的地計算機的設定，在運行時間產生物件的位置。 例如，如果應用程式在安裝應用程式的目錄中寫入數據，而且使用者可以在計算機上的任何位置安裝應用程式。 如果應用程式寫入登錄值 hklm\software\companyname\install [path\] ，然後使用安裝應用程式的位置來更新此值，則正確移轉所需數據的唯一方法是定義環境變數。 例如：

<environment>
   <variable name="INSTALLPATH">
      <script>MigXmlHelper.GetStringContent("Registry","\software\companyname\install [path]")</script>
   </variable>
</environment>

然後可以使用包含規則，如下所示。 <任何腳本>函式都可以用來執行類似的工作。

<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\移轉名為 、 File2.txt等的五個File1.txt檔案。 若要移轉這些檔案，下列 <include> 規則必須位於 .xml 檔案中：

<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> 元素，則會包含 物件。 對於每個 <排除> 專案，可以有多個子 <物件Set> 元素。

  • 發生次數： 無限

  • 父元素：<rules>

  • 子元素：<objectSet>

  • 協助程式函式： 下列 <排除> 篩選函 式可以與這個專案搭配使用： CompareStringContent、 IgnoreIrrelevantLinks、 AnswerNo、 NeverRestore和 SameRegContent。

語法：

<exclude filter="ScriptInvocation">
</exclude>
設定 必要？ 值
filter 否
(預設值 = 沒有) 		腳本，後面接著任意數目的字串自變數，以逗號分隔，並以括弧括住。 例如，MyScripts.AScript ("Arg1","Arg2")。

腳本會針對包含規則中的物件集所列舉的每個物件呼叫。 篩選文本會傳回布爾值。 如果傳回值為 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> 元素，則會移轉其所有參數。

語法：

<excludeAttributes attributes="Security|TimeFields|Security,TimeFields">
</excludeAttributes>
設定 必要？ 值
屬性 是 指定要排除的屬性。 可以指定下列其中一項或兩者。 如果同時指定這兩者，則必須以引號分隔。 例如： "Security","TimeFields"
  • 安全性可以是擁有者、群組、DACL 或 SACL 的其中一個。
  • TimeFields 可以是 CreationTime、LastAccessTime 和 LastWrittenTime 之一

範例：

<migration urlid="http://www.microsoft.com/migration/1.0/migxmlext/miguser">
<!-- This component migrates the files in the Video folder -->
   <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>
</extensions>

<外延>

擴 <充> 元素可用來指定特定延伸模組的檔。

  • 發生次數： 無限制

  • 父元素：<extensions>

  • 子元素： 無

語法：

<extension>FilenameExtension</extension>
設定 必要？ 值
FilenameExtension 是 擴展名。

例如，若要從來源計算機移轉所有 *.doc 檔案，請在元件>元素下<指定下列程式代碼：

<extensions> 
        <extension>doc</extension> 
<extensions>

與在 rules 元素下方 <指定下列程式> 代碼相同：

<include> 
        <objectSet> 
                <script>MigXmlHelper.GenerateDrivePatterns ("* [*.doc]", "Fixed")</script> 
        </objectSet> 
</include>

如需如何使用<擴>充元素的另一個範例，請參閱 excludeAttributes 的<範例>。

<externalProcess>

externalProcess <> 元素可用來在移轉程式期間執行命令行。 例如，執行 命令可能需要在 LoadState 程式完成之後執行。

語法：

<externalProcess when="pre-scan|scan-success|post-scan|pre-apply|apply-success|post-apply">
</externalProcess>
設定 必要？ 值
什麼時候 是 指出應該執行命令行的時機。 此值可以是下列其中一個值：
  • 在掃描 程序開始之前預先掃描。
  • 掃描 程式成功完成之後掃描成功。
  • 掃描程式完成之後，不論是否成功。
  • 在套用程序開始之前預先套用。
  • 套用程式成功完成之後，apply-success。
  • 在套用程式完成後套用，不論是否成功。

如需如何使用 externalProcess> 元素的<範例，請參閱 excludeAttributes 的<範例>。

<icon>

此元素是內部 USMT 元素。 請勿使用這個專案。

<include>

>include< 元素會決定要移轉的專案，除非有更明確的<排除>規則。 您可以將腳本指定為更明確，以擴充需要收集之項目的定義。 對於每個 <include> 元素，可以有多個 <objectSet> 元素。

  • 發生次數： 無限

  • 父元素：<rules>

  • 必要的子元素：<objectSet>

  • 協助程式函式： 下列 <包含> 篩選函式 可以與這個專案搭配使用： CompareStringContent、 IgnoreIrrelevantLinks、 AnswerNo和 NeverRestore。

語法：

<include filter="ScriptInvocation">
</include>
設定 必要？ 值
filter 否。
如果未指定此參數，則會處理子 <物件Set> 元素內的所有模式。		 腳本，後面接著任意數目的字串自變數，以逗號分隔，並以括弧括住。 例如，MyScripts.AScript ("Arg1","Arg2")。
腳本會針對包含規則中的<>物件集所列舉的每個物件呼叫。 篩選文本會傳回布爾值。 如果傳回值為 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>

<包含> 和 <排除> 篩選函式

下列函式會傳回布爾值。 它們可用來根據符合特定條件的時機來移轉特定物件。

  • AnswerNo

    此篩選條件一律會 傳回 FALSE。

    語法： AnswerNo ()

  • CompareStringContent

    語法： CompareStringContent("StringContent","CompareType")

    設定 必要？ 值
    StringContent 是 要檢查的字串。
    CompareType 是 字串。 使用下列其中一個值：
    • 等 (不區分大小寫) 。 如果移轉引擎所處理之目前物件的字串表示與 相同StringContent，則函式會傳回 TRUE。
    • NULL或任何其他值。 如果移轉引擎StringContent所處理之目前物件的字串表示不符合 ，則函式會傳回 TRUE。

  • 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> 元素，則會移轉其所有參數。

語法：

<includeAttributes attributes="Security|TimeFields|Security,TimeFields">
</includeAttributes>
設定 必要？ 值
屬性 是 指定要包含在移轉物件中的屬性。 可以指定下列其中一項或兩者。 如果同時指定這兩者，則必須以引號分隔。 例如： "Security","TimeFields"
  • 安全性可以是下列其中一個值：
    • 擁有者：對象的擁有者 (SID) 。
    • 群組：物件的主要群組 (SID) 。
    • DACL (選擇性訪問控制清單) ：由對象擁有者控制的訪問控制清單，指定特定使用者或群組對物件的存取權。
    • SACL (系統訪問控制清單) ：ACL，可控制嘗試存取安全物件的稽核訊息產生。 取得或設定物件 SACL 的能力是由通常僅由系統管理員持有的許可權所控制。
  • TimeFields 可以是下列其中一個值：
    • CreationTime：指定檔案或目錄的建立時間。
    • LastAccessTime：指定上次讀取、寫入或執行檔的檔案何時執行。
    • LastWrittenTime：指定上次寫入、截斷或覆寫檔案的時間。

如需如何使用 includeAttributes> 元素的<範例，請參閱 excludeAttributes 的<範例>。

<圖書館>

此元素是內部 USMT 元素。 請勿使用這個專案。

<位置>

location<> 元素會定義物件>專案的位置<。

語法：

<location type="typeID">ObjectLocation</location>
設定 必要？ 值
類型 是 typeID 可以是登錄或檔案。
ObjectLocation 是 物件的位置。

下列範例來自 MigApp.xml 檔案：

<addObjects>
   <object>
      <location type="Registry">%HklmWowSoftware%\Microsoft\Office\16.0\Common\Migration\Office [UpgradeVersion]</location>
      <attributes>DWORD</attributes>
      <bytes>0B000000</bytes>
   </object>
   <object>
      <location type="Registry">%HklmWowSoftware%\Microsoft\Office\16.0\Common\Migration\Office [Lang]</location>
      <attributes>DWORD</attributes>
      <bytes>00000000</bytes>
   </object>
</addObjects>

<locationModify>

locationModify<> 元素可用來變更物件的位置和名稱，然後再將物件移轉至目的地計算機。 只有在目的地計算機上執行 LoadState 工具時，才會處理locationModify> 元素。< 換句話說， ScanState 工具會忽略這個專案。 如果目的地計算機不存在，locationModify<> 元素會在該資料夾上建立適當的資料夾。

發生次數： 無限

語法：

<locationModify script="ScriptInvocation">
</locationModify>
設定 必要？ 值
腳本 是 腳本，後面接著任意數目的字串自變數，以逗號分隔，並以括弧括住。 例如，MyScripts.AScript ("Arg1","Arg2")。

腳本會針對包含規則中的物件集所列舉的每個物件呼叫。 篩選文本會傳回布爾值。 如果傳回值為 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 函式會將物件移至目的地電腦上的不同位置。 此外，此函式會建立來源物件名稱中高於最長 CSIDL 的子目錄。

    語法： Move(DestinationRoot)

    設定 必要？ 值
    DestinationRoot 是 來源物件移動的位置。 如有需要，此函式會在來源物件名稱中建立高於最長 CSIDL 的任何子目錄。

  • RelativeMove

    RelativeMove 函式可用來收集和行動數據。 環境變數可用於來源和目的地根目錄，但在來源和目的地計算機上定義的方式可能不同。

    語法： RelativeMove(SourceRoot,DestinationRoot)

    設定 必要？ 值
    SourceRoot 是 對象的移動來源位置。 不在此位置的父 <物件Set> 元素所列舉的任何來源物件，不會移動。
    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<> 元素會定義元件的製造商，但不會影響移轉。

  • 發生次數： 零或一

  • 父元素：<component>

  • 子元素： 無

語法：

<manufacturer>Name</manufacturer>
設定 必要？ 值
名稱 是 元件的製造商名稱。

<合併>

合併<>專案會決定當發生衝突時會發生什麼事。 當移轉的物件已經存在於目的地計算機上時，就會發生衝突。 如果未指定此元素，則登錄的預設行為是讓來源物件覆寫目的地物件。 檔案預設行為是將來源檔案重新命名為 OriginalFileName(1).OriginalExtension。 這個專案只會指定當發生衝突時應該執行的動作。 它不包含物件。 因此，若要移轉對象， <必須指定 include> 規則以及 <合併> 專案。 處理物件並偵測到衝突時，USMT 會選取最特定的合併規則。 然後，它會套用規則來解決衝突。 例如，如果 <合併> 規則 C:\* [*] 設定為 <sourcePriority> ，且 <合併> 規則 C:\subfolder\* [*] 設定為 <destinationPriority>，則 USMT 會使用 <destinationPriority> 規則，因為它更明確。

如需此專案的範例，請參閱 衝突和優先順序。

  • 發生次數： 無限

  • 父元素：<rules>

  • 必要的子元素：<objectSet>

  • 協助程式函式：下列<合併>函式可以與這個專案搭配使用：SourcePriority、、FindFilePlaceByPatternDestinationPriority、LeafPattern、NewestVersion、 HigherValue()和 LowerValue()。

語法：

<merge script="ScriptInvocation">
</merge>
設定 必要？ 值
腳本 是 腳本，後面接著任意數目的字串自變數，以逗號分隔，並以括弧括住。 例如，MyScripts.AScript ("Arg1","Arg2")。

腳本會針對包含規則中的<>物件集所列舉的每個物件呼叫。 篩選文本會傳回布爾值。 如果傳回值為 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>

<合併> 函式

這些函式會控制如何解決衝突。

  • DestinationPriority

    指定保留目的地計算機上的物件，而不是從來源計算機移轉物件。

    例如：

    <merge script="MigXmlHelper.DestinationPriority()">
     <objectSet>
          <pattern type="Registry">HKCU\Software\Microsoft\Office\16.0\PhotoDraw\ [MyPictures]</pattern>
          <pattern type="Registry">HKCU\Software\Microsoft\Office\16.0\PhotoDraw\Settings\ [PicturesPath]</pattern>
          <pattern type="Registry">HKCU\Software\Microsoft\Office\16.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 。

  • 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\14.0\Common\Migration\Publisher [UpgradeVersion]</pattern>
   <pattern type="Registry">%HklmWowSoftware%\Microsoft\Office\15.0\Common\Migration\Publisher [UpgradeVersion]</pattern>
   <pattern type="Registry">%HklmWowSoftware%\Microsoft\Office\16.0\Common\Migration\Publisher [UpgradeVersion]</pattern>
 </objectSet>
</merge>

<遷移>

>移<轉專案是移轉 .xml 檔案的單一根元素，且為必要專案。 每個 .xml 檔案都必須有唯一的移轉 urlid。 在命令行上指定之每個檔案的urlid必須是唯一的。 URL 必須是唯一的，因為 USMT 會使用 urlid 來定義檔案內的元件。

語法：

<migration urlid="*UrlID/*Name">
</migration>
設定 必要？ 值
urlid 是 UrlID 是可唯一識別此 .xml檔案的 字串標識碼。 這個參數必須是 XML 命名空間規格所定義的無冒號名稱。 每個移 轉.xml 檔案都必須有唯一的 urlid。 如果兩 個移轉.xml 檔案具有相同的 urlid，則不會處理在命令行上指定的第二個 .xml 檔案。 如需 XML 命名空間的詳細資訊，請 參閱使用 XML 命名空間。
名稱 否 雖然並非必要，但最好使用 .xml 檔的名稱。

下列範例來自 MigApp.xml 檔案：

<migration urlid="http://www.microsoft.com/migration/1.0/migxmlext/migapp">
</migration>

MigXMLHelper.FileProperties

此篩選協助程式函式可用來根據檔案大小和日期屬性來篩選檔案的移轉。

Helper 函式 MigXMLHelper.FileProperties (属性、運算符、valueToCompare)
屬性 filesize、dateCreated、dateModified、dateAccessed
運算子 range、neq、lte、lt、eq、gte、gt
valueToCompare 正在比較的值。 例如：
日期：“2023/05/15-2020/05/17”， “2023/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","2023/05/15-2020/05/17")'>
         <objectSet>
         <pattern type="File">%SYSTEMDRIVE%\DOCS\* [*]</pattern>
         </objectSet>
      </include>
   </rules>
</role>
</component>

<namedElements>

namedElements<> 元素可用來定義具名專案。 這些元素可用於 .xml檔案中 的任何元件。 如需如何使用這個專案的範例，請參閱 MigApp.xml 檔案。

語法：

<namedElements>
</namedElements>

如需此專案的範例，請參閱 MigApp.xml 檔案。

<物件>

對象<>專案代表檔案或登錄機碼。

語法：

<object>
</object>

下列範例來自 MigApp.xml 檔案：

<addObjects>
   <object>
      <location type="Registry">%HklmWowSoftware%\Microsoft\Office\16.0\Common\Migration\Office [UpgradeVersion]</location>
      <attributes>DWORD</attributes>
      <bytes>0B000000</bytes>
   </object>
   <object>
      <location type="Registry">%HklmWowSoftware%\Microsoft\Office\16.0\Common\Migration\Office [Lang]</location>
      <attributes>DWORD</attributes>
      <bytes>00000000</bytes>
      </object>
</addObjects>

<objectSet>

objectSet <> 元素包含物件模式的清單，例如檔案路徑、登錄位置等等。 系統會先評估任何子 <條件> 專案。 如果所有子<條件>專案都傳回 FALSE，objectSet<> 元素會評估為空集合。 每個父元素只能有多個 <objectSet> 元素。

語法：

<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 元素。 請勿使用這個專案。

<路徑>

此元素是內部 USMT 元素。 請勿使用這個專案。

<圖樣>

這個專案可用來指定多個物件。 每個 objectSet> 元素都可以使用多個<<模式>專案，並加以結合。 如果指定檔案，Microsoft建議改用 GenerateDrivePatterns 搭配 <腳本> 。 GenerateDrivePatterns基本上與模式>規則相同<，不含驅動器號規格。 例如，下列兩行程式代碼類似：

<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>
設定 必要？ 值
類型 是 typeID 可以是 Registry、File 或 Ini。 如果 typeId 是 Ini，則不允許 Path 和 對象 之間的空格。 例如，當 type=“Ini”時，下列格式是正確的：
<pattern type=“Ini”>%WinAmp5InstPath%\Winamp.ini|WinAmp[keeponscreen]</pattern>
路徑 [object] 是 有效的登錄或檔案路徑模式，後面接著至少一個空格，後面接著包含要移轉之物件的括號 []。
  • 路徑 可以包含星號 (*) 通配符，也可以是 可辨識的環境變數。 問號不能當做通配符使用。 HKCU 與 HKLM 可用來分別參考 HKEY_CURRENT_USER 和 HKEY_LOCAL_MACHINE 。
  • 物件 可以包含星號 () * 通配符。 不過，問號不能當做通配符使用。 例如：
    C:\Folder\ [*] 列舉 中的所有檔案， C:\Folder 但沒有 的 C:\Folder子資料夾。
    C:\Folder* [*] 列舉 的所有檔案和 子資料夾 C:\Folder。
    C:\Folder\ [*.mp3]列舉 中C:\Folder的所有.mp3檔案。
    C:\Folder\ [Sample.doc] 只 Sample.doc 列舉位於 C：\Folder 中的檔案。
    注意
    如果移轉檔名中具有方括號字元 ([ 或 ]) 的檔案，則必須在括號之前直接插入一個子 (^) 字元，才能有效。 例如，如果有名為 「file].txt」 的檔案， <pattern type="File">c:\documents\mydocs [file^].txt]</pattern> 則必須指定 而不是 <pattern type="File">c:\documents\mydocs [file].txt]</pattern>。

例如：

  • 若要移轉單一登入機碼：

    <pattern type="Registry">HKLM\Software\Microsoft\Windows\CurrentVersion\Internet Settings\Cache [Persistent]</pattern>

  • 若要從 C： 磁碟驅動器移轉 C:\EngineeringDrafts 資料夾與任何子資料夾：

    <pattern type="File">C:\EngineeringDrafts\* [*]</pattern>

  • 若只要 C:\EngineeringDrafts 從 C： 磁碟驅動器移轉資料夾，但不包括任何子資料夾：

    重新路由檔案和設定

  • 若要從 C:\EngineeringDrafts移轉Sample.doc檔案：

    <pattern type="File"> C:\EngineeringDrafts\ [Sample.doc]</pattern>

  • 若要將檔案從 C： 磁碟驅動器上存在的位置移 Sample.doc 轉，請以下列方式使用模式。 如果 C： 磁碟驅動器上有多個具有相同名稱的檔案，則會移轉所有這些檔案。

    <pattern type="File"> C:\* [Sample.doc] </pattern>

  • 如需如何使用此元素的詳細範例，請參閱 排除檔案和設定、 重新路由檔案和設定、 包含檔案和設定，以及 自定義 XML 範例。

<加工>

此元素可用來在移轉程式內的特定時間點執行腳本。 預期不會從指定的腳本傳回值。 如果有傳回值，則會忽略這些值。

  • 發生次數： 無限制

  • 父元素：<rules>

  • 必要的子元素：<script>

語法：

<processing when="pre-scan|scan-success|post-scan|pre-apply|apply-success|post-apply">
</processing>
設定 必要？ 值
什麼時候 是 指出應該執行腳本的時機。 此值可以是下列其中一個值：
  • 預先掃描 表示掃描程序開始之前。
  • scan-success 表示掃描程式成功完成之後。
  • 掃描后 表示掃描程式完成之後，不論是否成功。
  • 在套用程序開始之前，預先套用表示。
  • apply-success 表示套用程式成功完成之後。
  • 套用后 表示套用程式完成之後，不論是否成功。

<外掛程式>

此元素是內部 USMT 元素。 請勿使用這個專案。

<角色>

自<訂.xml檔中需要role>元素。 <指定角色>專案時，可以建立具象元件。 元件是由元件>層級所<指定的參數，以及此處指定的角色所定義。

語法：

<role role="Container|Binaries|Settings|Data">
</role>
設定 必要？ 值
角色 是 定義元件的角色。 角色可以是下列其中一項：
  • 容器
  • 二進位檔
  • 設定
  • 資料
您可以指定下列其中一個專案：
  1. 元件>內最多三個<角色>元素 - 一個「二進位檔」角色元素、一個「設定」角色元素和一個「數據」角色元素。< 這些參數不會變更移轉行為 - 其唯一目的是協助分類正在移轉的設定。 這些 <角色> 元素可以是巢狀的，但每個巢狀元素都必須是相同的角色參數。
  2. 元件>元素內的一個<「容器」<角色>專案。 在此情況下，無法指定任何子 <規則> 元素，只能指定其他 <元件> 專案。 而且每個子<元件元素的類型必須與父元件>>項目的類型<相同。 例如：
              
              
              <component context=“UserAndSystem” type=“Application”>
  
              <displayName _locID=“migapp.msoffice2016”>Microsoft Office 2016</displayName>
  
              <environment name=“GlobalEnv” />
  
              <role role=“Container”>
    
              <detection name=“AnyOffice2016Version” />
    
              <detection name=“Word2016” />
    
              <!--
 Office 2016 通用設定
  -->
     <component context="UserAndSystem" type="Application">

下列範例來自 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>

<規則>

自<訂.xml檔中需要 rules> 元素。 此元素包含在選取父 <元件> 專案時於移轉期間執行的規則，除非子 <條件> 專案如果有，則評估為 FALSE。 針對每個 <rules> 元素，可以有多個子 <規則> 專案。

語法：

<rules name="ID" context="User|System|UserAndSystem">
</rules>
設定 必要？ 值
name 是，當規則>是 namedElements 的子系時<<>
否，當規則>是任何其他專案的子系時<		 指定 ID 時，不會處理任何子專案。 相反地，會處理在 namedElements> 內<宣告的相同名稱的任何其他<規則>專案。
上下文 否
(預設值 = UserAndSystem) 		定義此參數的範圍 - 是否要在特定使用者的內容中、整個作業系統或兩者中處理此元件。
元件項目會設定最大可能的範圍。 例如，如果 <元件> 元素的內容是 User ，而 <rules> 元素的內容是 UserAndSystem，則 <rules> 元素的作用就如同其內容是 User。 如果<規則>的內容是 System，它的作用就如同規則>不存在一樣<。
  • 用戶：評估每個使用者的變數。
  • 系統：只評估系統的變數一次。
  • UserAndSystem：評估整個操作系統和每個使用者的變數。

下列範例來自 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>

<腳本>

腳本>所需的<傳回值取決於父元素。

發生次數：一次用於<變數>，objectSet> 和處理則無<限制><

父元素：<objectSet>、 <變數>、 <處理>

子元素： 無

語法和協助程式函式：

  • 一般語法： <script>ScriptWithArguments</script>

  • 當文稿在變數內時<，可以使用 GetStringContent。><>

    語法： <script>MigXmlHelper.GetStringContent("ObjectType","EncodedLocationPattern", "ExpandContent")</script>

    例： <script>MigXMLHelper.GetStringContent("Registry","HKLM\Software\MyApp\Installer [EXEPATH]")</script>

  • 當腳本在 objectSet 內時<，可以使用 GenerateUserPatterns。><>

    語法： <script>MigXmlHelper.GenerateUserPatterns("ObjectType","EncodedLocationPattern","ProcessCurrentUser")</script>

    例： <script>MigXmlHelper.GenerateUserPatterns ("File","%USERPROFILE%\* [*.doc]", "FALSE")</script>

  • 當腳本在 objectSet 內時<，可以使用 GenerateDrivePatterns。><>

    語法： <script>MigXmlHelper.GenerateDrivePatterns("PatternSegment","DriveType")</script>

    例： <script>MigXmlHelper.GenerateDrivePatterns("* [sample.doc]", "Fixed")</script>

  • 簡單執行腳本可以與處理>專案內<的腳本>元素搭配使用：AskForLogoff、ConvertToShortFileName、KillExplorer、RemoveEmptyDirectories、RestartExplorer、RegisterFonts、StartService、StopService、SyncSCM。<

    語法： <script>MigXmlHelper.ExecutingScript</script>

    例： <script>MigXmlHelper.KillExplorer()</script>

設定 必要？ 值
ScriptWithArguments 是 腳本，後面接著任意數目的字串自變數，以逗號分隔，並以括弧括住。 例如，MyScripts.AScript ("Arg1","Arg2")。
腳本會針對包含規則中的<>物件集所列舉的每個物件呼叫。 篩選文本會傳回布爾值。 如果傳回值為 TRUE，則會移轉物件。 如果為 FALSE，則不會移轉。
腳本>所需的<傳回值取決於父元素。
  • 在變數>內<使用時，傳回值必須是字串。
  • 在 objectSet> 內<使用時，傳回值必須是字串的二維數位列。
  • 在location>內<使用時，傳回值必須是符合location類型屬性<的有效位置>。 例如，如果 <location type=“File”>，子腳本專案如果指定，就必須是有效的檔案位置。
    注意
    如果在檔名中移轉具有括號字元 ([ 或 ]) 的檔案，請在括號前面直接插入 (^) 字元，使其有效。 例如，如果有名為 「file].txt」 的檔案，請指定 <pattern type="File">c:\documents\mydocs [file^].txt]</pattern> 而不是 <pattern type="File">c:\documents\mydocs [file].txt]</pattern>。

範例：

若要從來源計算機上的任何磁碟驅動器移轉 Sample.doc 檔案，請使用 <腳本> ，如下所示。 如果存在多個具有相同名稱的檔案，則會移轉所有這類檔案。

<script>MigXmlHelper.GenerateDrivePatterns("* [sample.doc]", "Fixed")</script>

如需如何使用此元素的詳細範例，請參閱 排除檔案和設定、 重新路由檔案和設定，以及 自定義 XML 範例。

<script> 函式

下列函式可以與 <腳本> 專案搭配使用

產生函式的字串和模式

這些函式會傳回字串或模式。

  • GetStringContent

    GetStringContent 可以與變數>元素內<的腳本>專案搭配使用。< 如果可能，此函式會傳回指定物件的字串表示。 否則，它會傳回 NULL。 對於這個函式的檔案物件，一律會傳回 NULL。

    語法： GetStringContent("ObjectType","EncodedLocationPattern", "ExpandContent")

    設定 必要？ 值
    ObjectType 是 物件的類型。 可以是.ini檔案) 的登錄或 Ini (。
    EncodedLocationPattern 是
    • 如果對象的類型是 Registry，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>

  • GenerateDrivePatterns

    函 GenerateDrivePatterns 式會逐一查看所有可用的磁碟驅動器，並選取符合所要求磁碟驅動器類型的磁碟驅動器。 然後，它會將選取的磁碟驅動器與 PatternSegment 的結尾部分串連，以形成完整編碼的檔案模式。 例如，如果 PatternSegment 是 Path [file.txt] 且 DriveType 是 Fixed，則如果 C： 以外的固定磁碟驅動器，則函式會產生 C:\Path [file.txt]和其他模式。 無法使用此函式指定環境變數。 GenerateDrivePatterns可以與 objectSet<>/<內包含排除>的腳稿>專案搭配使用。<<>

    語法： GenerateDrivePatterns("PatternSegment","DriveType")

    設定 必要？ 值
    PatternSegment 是 編碼模式的後綴。 此值會與磁碟驅動器規格串連，例如 「c：“，以形成完整的 編碼檔案模式。 例如，“* [*.doc]”。 PatternSegment 不能是環境變數。
    DriveType 是 要產生模式的磁碟驅動器類型。 您可以指定下列其中一個專案：
    • 已修正
    • CDROM
    • 移動
    • 遠端

    如需這個專案的範例， MigUser.xml 請參閱 檔案中的最後一個元件。

  • GenerateUserPatterns

    函 GenerateUserPatterns 式會逐一查看正在移轉的所有使用者，如果 <ProcessCurrentUser> 為 FALSE，則不包括目前處理的使用者，並在每個使用者的內容中展開指定的模式。 例如，如果使用者 A、B 和 C 透過呼叫 GenerateUserPattens('File','%userprofile% [*.doc]','TRUE')在 中有設定檔C:\Users，協助程式函式會產生下列三種模式：

    • “C：\Users\A\* [*.doc]”

    • “C：\Users\B\* [*.doc]”

    • “C：\Users\C\* [*.doc]”

    語法： GenerateUserPatterns("ObjectType","EncodedLocationPattern","ProcessCurrentUser")

    設定 必要？ 值
    ObjectType 是 定義物件類型。 可以是檔案或登錄。
    EncodedLocationPattern 是 位置模式。 允許環境變數。
    ProcessCurrentUser 是 可以是 TRUE 或 FALSE。 指出是否應該為目前的用戶產生模式。

範例：

如果 GenerateUserPattens('File','%userprofile% [*.doc]','FALSE') 在 USMT 處理使用者 A 時呼叫 ，則此函式只會產生使用者 B 和 C 的模式。此協助程式函式可用來建置複雜的規則。 例如，若要從來源計算機移轉所有 .doc 檔案，但如果使用者 X 未移轉，則請勿從使用者 X 的設定檔移轉任何 .doc 檔案。

下列範例是此案例的範例程序代碼。 第一個 <rules> 元素會移轉來源計算機上的所有 .doc 檔案，但內 C:\Users的檔案除外。 第二個<規則>元素會從 C:\Users 移轉所有.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

協助 MigXmlHelper.GenerateDocPatterns 程式函式會叫用文件尋找程式，以掃描系統中所有可移轉的檔案。 您可以在 [系統 ] 或 [ 使用者 ] 內容中叫用它，以專注於掃描。

設定 必要？ 值
ScanProgramFiles 無 (預設值 = FALSE) 可以是 TRUE 或 FALSE。 ScanProgramFiles 參數會決定檔尋找程式是否掃描 Program Files 目錄，以收集已知應用程式的已註冊擴展名。 例如，當設定為 TRUE 時，如果 .jpg 是已註冊至 Photoshop 的擴展名，它會探索並移轉 Photoshop 目錄下的 .jpg 檔案。
IncludePatterns 無 (預設值 = TRUE) 可以是 TRUE 或 FALSE。 TRUE 會產生 include 模式，而且可以在 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>

簡單執行腳本

下列腳本沒有傳回值。 下列錯誤可以與處理>專案內<的腳本>專案搭配使用<

  • AskForLogoff () 。 提示使用者在移轉結束時註銷。 例如：

    <processing when="apply-success">
  <script>MigXmlHelper.AskForLogoff()</script>
</processing>

  • ConvertToShortFileName (RegistryEncodedLocation) 。 如果 RegistryEncodedLocation 是現有檔案的完整路徑，此函式會將檔案轉換成其簡短的檔名，然後更新登錄值。

  • KillExplorer () 。 停止目前用戶內容的 Explorer.exe。 停止 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。 如需詳細資訊，請參閱 startServiceA 函式 (winsvc.h) 一文。

  • StopService (ServiceName) 。 停止 ServiceName 所識別的服務。ServiceName 是 中的子機碼 HKLM\System\CurrentControlSet\Services ，可保存指定服務的數據。

  • SyncSCM (ServiceShortName) 。 在移轉引擎變更值之後，從登錄 (HKLM\System\CurrentControlSet\Services\ServiceShortName [Start]) 讀取 [開始類型] 值，然後將服務控制管理員 (SCM) 與新值同步處理。

<發簡訊>

文字<>元素可用來為其中一個移轉 .xml檔案內的任何環境變數設定值。

  • 發生次數： 在每個 <變數> 專案中一次。

  • 父元素：<variable>

  • 子元素： 沒有。

語法：

<text>NormalText</text>
設定 值
NormalText 此文字會解譯為一般文字。

例如：

<variable name="QuickTime5or6DataSys">
  <text>%CSIDL_COMMON_APPDATA%\QuickTime</text> 
</variable>

<無條件Exclude>

無<條件Exclude> 元素會從移轉中排除指定的檔案和登錄值，不論移轉檔案中或檔案中Config.xml是否有其他包含規則 .xml。 此處宣告的物件不會移轉，因為這個專案的優先順序高於所有其他規則。 例如，即使有包含檔案的明確 <包含> 規則 .mp3 ，如果使用此選項將其排除，則不會移轉它們。

使用此元素可從來源計算機排除所有 .mp3 檔案。 或者，如果使用其他方法進行備份 C:\UserData ，則可以從移轉中排除整個資料夾。 請小心使用此元素。 如果應用程式需要排除的檔案，應用程式可能無法在目的地電腦上正常運作。

語法：

<unconditionalExclude></unconditionalExclude>

下列 .xml 檔案會排除移轉中的所有 .mp3 檔案。 如需如何使用此元素的其他範例，請參閱 排除檔案和設定。

<migration urlid="http://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>

<變數>

環境專案中<>需要變數>專案。< 每個 <變數> 項目都必須有一個 <objectSet>、 <script> 或 <text> 元素。 變數>項目的內容<會將文字值指派給環境變數。 此元素有下列三個選項：

  1. <如果變數>專案包含<文字>專案，則變數元素的值就是 text> 元素的<值。

  2. <如果變數>專案包含<文稿>專案，而且腳本的調用會產生非 Null 字串，則變數>元素的<值就是腳本調用的結果。

  3. <如果變數>專案包含 <objectSet> 元素，而且 objectSet> 元素的<評估會產生至少一個物件模式，則第一個符合所產生物件模式之物件的值就是變數專案的值。

語法：

<variable name="ID" remap=TRUE|FALSE>
</variable>
設定 必要？ 值
name 是 ID 是用來參考環境變數的字串值。 Microsoft建議以元件名稱開頭的 標識 碼，以避免命名空間衝突。 例如，如果元件的名稱是 MyComponent，而且需要是元件安裝路徑的變數， MyComponent.InstallPath則可以指定 。
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< 元素會定義元件的版本，但不會影響移轉。

  • 發生次數： 零或一

  • 父元素：<component>

  • 子元素： 無

語法：

<version>ComponentVersion</version>
設定 必要？ 值
ComponentVersion 是 元件的版本，可以包含模式。

例如：

<version>4.*</version>

<windowsObjects>

<windowsObjects> 元素僅供 USMT 內部使用。 請勿使用這個專案。

附錄

指定位置

  • 指定編碼的位置。 所有協助程式函式中使用的編碼位置是物件名稱的明確字串表示。 編碼的位置是由節點部分所組成，後面接著方括弧括住的分葉。 此格式清楚區分節點和分葉。

    例如，指定檔案 C:\Windows\Notepad.exe ，如下所示： c:\Windows[Notepad.exe]。 同樣地，請指定如下所示的目錄 C:\Windows\System32 ： c:\Windows\System32。 (請注意沒有 [] construct.)

    表示登錄很類似。 登錄機碼的預設值會以空 [] 的建構表示。 例如，登入機碼的 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

有效的版本標籤

下列版本標籤可以與各種協助程式函式搭配使用：

  • “CompanyName”

  • “FileDescription”

  • “FileVersion”

  • “InternalName”

  • “LegalCopyright”

  • “OriginalFilename”

  • “ProductName”

  • “ProductVersion”

下列版本標籤包含可比較的值：

  • “FileVersion”

  • “ProductVersion”