使用者驅動安裝 - 開發人員指南

使用者驅動安裝 (UDI) 有助於簡化將 Windows® 用戶端作業系統（例如 Windows 8.1）部署至使用 Microsoft® System Center 2012 R 設定管理員 2 中的作業系統部署 (OSD) 功能的電腦。 UDI 是 Microsoft Deployment Toolkit (MDT) 的一部分。

簡介

通常，使用 OSD 功能部署作業系統時，您必須提供部署作業系統的所有必要資訊。 資訊是在組態檔或資料庫中進行設定 (，例如 CustomSettings.ini 檔案或 MDT 資料庫 [MDT DB]) 。 您必須先提供所有組態設定，才能啟動部署。

UDI 提供精靈驅動的介面，可讓您在執行部署之前立即提供設定資訊。 此行為可讓您建立一般 OSD 工作順序，然後在部署時提供電腦特定資訊，這在部署過程中提供了更大的靈活性。

目標受眾

本指南是專為建立 UDI 精靈自訂精靈頁面，以及為 UDI 精靈 Designer 自訂精靈頁面編輯器的開發人員所編寫。 本指南假設您熟悉使用下列方法開發 Windows 應用程式：

• C++，用來建立自訂精靈頁面

• Microsoft .NET Framework，用來建立自訂精靈頁面編輯器

• Windows Presentation Foundation (WPF) ，用來建立自訂精靈頁面編輯器

• WPF 支援的語言，例如 C#、C++ 或 Microsoft Visual Basic® .NET，用來建立自訂精靈頁面編輯器

關於本指南

本指南提供必要的參考資訊，可協助您為組織自訂 UTI。 本指南不會討論系統管理或操作主題，例如安裝包含 UDI) 的 MDT (、設定 UDI 以部署作業系統和應用程式，或使用 UDI 精靈執行部署。 如需這些主題的詳細資訊，請參閱使用隨附於 MDT 的 Microsoft 部署工具組中的 UDI 主題。

UDI 開發概觀

UDI 開發可讓您擴充 UDI 提供的功能。 當您想要收集 UDI 部署程序取用的其他資訊時，通常需要 UDI 開發。 此額外資訊通常會儲存為工作順序變數，以供 設定管理員 中 UDI 工作順序中的工作順序步驟讀取。

UDI 架構

UDI 開發的高階目標是建立可在 UDI 精靈中顯示的自訂精靈頁面。 藉由建立自訂精靈頁面，您可以擴充 UDI 的現有功能，以滿足組織的商務和技術需求。 自訂精靈頁面會收集資訊，以補充或取代 UDI 提供的精靈頁面。

圖 1 說明 UDI 精靈 Designer 與 UDI 精靈之間的關係。

圖 1。 UDI 精靈與 UDI 精靈 Designer 之間的關係

圖 1： UDI 精靈與 UDI 精靈 Designer 之間的關係

在概念層面上，UDI 開發包括創建：

• 自訂精靈頁面。 UDI 精靈中會顯示精靈頁面，並收集完成部署程序所需的資訊。 您可以在 Microsoft Visual Studio® 中使用 C++ 建立精靈頁面。 自訂精靈頁面會實作為 UDI 精靈讀取的 DLL。 ) SDK (UDI 軟體開發套件包含如何建立自訂精靈頁面的範例。

• 自訂精靈頁面編輯器。 您可以使用精靈頁面編輯器來設定自訂精靈頁面的行為。 自訂精靈頁面編輯器會實作為 UDI 精靈 Designer 讀取的 DLL。 您可以使用以下方式建立精靈頁面編輯器：

  • WPF 4.0 版

  • Microsoft Prism 版本 4.0

  • Microsoft Unity 應用程式區塊 ( Unity) 2.1 版

    MDT 包含建立自訂精靈頁面編輯器所需的所有組件，以便在 UDI 精靈 Designer 中使用。 UDI SDK 包含如何建立自訂精靈頁面編輯器的範例。

  此外，UDI 精靈 Designer 會取用支援精靈頁面編輯器設定檔。 在建立自訂精靈頁面及自訂精靈頁面編輯器的過程中，您可以建立精靈頁面編輯器組態檔。 UDI 精靈Designer會在 UDI 精靈設定檔和對應的 .app 檔案中建立必要的 XML 資訊。

準備 UDI 開發環境

在開始建立自訂精靈頁面和精靈頁面編輯器之前，請先執行下列步驟來準備 UDI 開發環境：

1. 按照準備 UDI 開發環境先決條件中所述準備 UDI 開發環境先決條件。

2. 依照 設定 UDI 開發環境中所述設定 UDI 開發環境。

3. 確認 UDI 開發環境已正確設定，如 驗證 UDI 開發環境中所述。

準備 UDI 開發環境先決條件

若要準備 UDI 開發環境必要條件，請執行下列步驟：

1. 如 準備 UDI 開發環境硬體先決條件中所述，準備 UDI 開發環境硬體必要條件。

2. 如 準備 UDI 開發環境軟體先決條件中所述，準備 UDI 開發環境軟體先決條件。

準備 UDI 開發環境硬體先決條件

UDI 開發環境的硬體必要條件與您所使用的 Microsoft Visual Studio 版本的硬體需求相同。 如需有關這些需求的詳細資訊，請參閱 Visual Studio 文件中每個版本的系統需求。

準備 UDI 開發環境軟體先決條件

UDI 開發環境具有下列軟體必要條件：

• 建議使用 Visual Studio 2010 支援的任何 Windows 作業系統 (Windows 7 或 Windows Server ® 2008 R2。)

  您需要支援要開發之處理器架構的 Windows 作業系統。 您可以使用 64 位元作業系統執行 32 位元和 64 位元 UDI 開發。 您只能在 32 位元作業系統上進行 32 位元 UDI 開發。 因此，您應該使用 64 位元作業系統。

  注意事項

  UDI 開發環境不支援 Windows 作業系統 (IA-64) 的 IntelItanium 版本。

  如需有關 Visual Studio 2010 支援的作業系統的詳細資訊，請參閱 Visual Studio 文件中每個版本的系統需求。

• Microsoft Visual Studio 2010) 所需的 .NET Framework 4.0 版 (

• C++ 語言 (用於將 UDI 精靈頁面延伸) 的語言

• WPF 支援的其他語言，例如 C#、Visual Basic .NET 或 C++/通用語言基礎結構，用來擴充 UDI 精靈 Designer 精靈頁面編輯器

  注意事項

  UDI 精靈 Designer 精靈頁面編輯器的範例原始程式碼是以 C# 撰寫。 如果您想要使用範例原始程式碼，請安裝 C# 語言。

設定 UDI 開發環境

在符合 UDI 開發環境必要條件之後，請執行下列步驟以設定 UDI 開發環境：

1. 安裝 Visual Studio 2010。

   請確定您安裝的是 C++ 語言，以及 WPF 支援的任何其他語言。

   注意事項

   UDI 精靈 Designer 編輯器頁面的範例原始程式碼是以 C# 撰寫。 如果您想要使用範例原始程式碼，請安裝 C# 語言。

   如需有關安裝 Visual Studio 2010 的詳細資訊，請參閱 安裝 Visual Studio。

2. 安裝 MDT。

   如需有關如何安裝 MDT 的詳細資訊，請參閱 使用 Microsoft 部署工具組 MDT 文件中的「安裝或升級至 MDT」一節。

3. 在 Windows 檔案總管中，建立 local_folder (，其中 local_folder 位於開發電腦) 上本機磁碟機上的任何資料夾。

4. 將 installation_folder\SDK 資料夾複製到 local_folder (其中 installation_folder 是安裝 MDT 的資料夾， 而local_folder 是位於開發電腦) 上本機磁碟機上的任何資料夾。

   將 SDK 資料夾複製到另一個位置，因為 MDT 安裝在 Program Files 資料夾中，如果沒有較高的權限，則無法寫入該資料夾。 將 SDK 資料夾複製到另一個位置可讓您修改 SDK 資料夾中的檔案，而不需要較高的權限。

5. 將 installation_folder\Templates\Distribution\Tools 資料夾複製到 local_folder (，其中 installation_folder 是安裝 MDT 的資料夾， 而 local_folder 是先前在程序) 中建立的資料夾。

6. 將 local_folder\Tools 資料夾重新命名為 local_folder\OSDSetupWizard (其中 local_folder 是您先前在處理程序) 中建立的資料夾。

   完成後， local_folder 底下的資料夾結構看起來應該像圖 2 所示的資料夾結構 (其中 local_folder 是您在流程中稍早建立的資料夾，在圖) 中顯示為 UDIDevelopment 。

   圖 2。 UDI 開發的資料夾結構

   圖 2： UDI 開發的資料夾結構

驗證 UDI 開發環境

配置 UDI 開發環境時，請通過確保示例專案在 Visual Studio 2010 中正確構建，以驗證 UDI 開發環境是否正確配置。

驗證 UDI 開發環境是否已正確設定，方法是判斷：

• SamplePage 專案會按照驗證 SamplePage 專案正確建置中所述正確建置

• SampleEditor 專案會按照驗證 SampleEditor 專案正確建置中所述正確建置

確認 SamplePage 專案正確建置

SamplePage 專案提供範例，說明如何建立 UDI 精靈的自訂精靈頁面。 如需 SamplePage 專案的詳細資訊，請參閱 檢閱 SamplePage Visual Studio 解決方案。

若要驗證 SamplePage 專案可正確建置

1. 啟動 Visual Studio 2010。

2. 開啟 SamplePage 專案。

   SamplePage 專案位於 local_folder\SDK\UDI\SamplePage 資料夾 (其中 local_folder 是您在先前的程序) 中建立的資料夾。

3. 在 Visual Studio 2010 的方案總管中，以滑鼠右鍵按一下 SamplePage 專案，然後選取 [屬性]。

   此時會出現 [SamplePage 屬性頁] 對話方塊。

4. 在 [SamplePage 屬性頁] 對話方塊中，移至 [設定屬性/偵錯]。

5. 在偵錯屬性的 [設定] 底下，選取 [ 所有設定]。

6. 在偵錯屬性的 命令下，輸入 $ (TargetDir) \OSDSetupWizard.exe。

7. 在偵錯屬性的 [工作目錄] 底下，輸入 $ (TargetDir) 。

8. 在 [SamplePage 屬性頁 ] 對話方塊中，移至 [設定屬性]/[組建事件]/[建置後事件]。

9. 在 [建置後事件] 屬性的 [命令列] 底下，輸入下列命令：

   copy /y "$(ProjectDir)..\..\..\..\OSDSetupWizard\x86\*.*" "$(TargetDir)"
   xcopy /y /i "$(ProjectDir)..\..\..\..\OSDSetupWizard\x86\en-us" "$(TargetDir)en-us"
   copy /y "$(ProjectDir)..\..\..\..\OSDSetupWizard\OSDResults\Images\UDI_Wizard_Banner.bmp" "$(ProjectDir)header.bmp"
   copy /y "$(ProjectDir)Config.xml" "$(TargetDir)"
   copy /y "$(ProjectDir)header.bmp" "$(TargetDir)header.bmp"
   

10. 在 [SamplePage 屬性頁面] 對話方塊中，選取 [確定]。

11. 儲存專案。

12. 從 [偵錯 ] 功能表中，選取 [ 開始偵錯]。

    此時會出現 [Microsoft Visual Studio] 對話方塊，指出來源已過期，並詢問您是否要建置專案。

13. 在 [Microsoft Visual Studio ] 對話方塊中，選取 [ 是]。

    此時會出現 [ 無偵錯資訊 ] 對話方塊，通知您沒有可供 OSDSetupWizard.exe 使用的偵錯資訊。

14. 在 [ 無偵錯資訊 ] 對話方塊中，選取 [是]。

    UDI 精靈隨即開啟，並顯示自訂精靈頁面。

15. 確認您可以在 [選擇您的位置] 中選取值。

16. 在 [具有範例頁面的精靈] 表單中，選取 [取消]。

    此時會出現 [ 取消精靈 ] 對話方塊。

17. 在 [ 取消精靈 ] 對話方塊中，選取 [是]。

18. 關閉 Visual Studio 2010。

確認 SampleEditor 專案正確建置

SampleEditor 專案提供範例，說明如何為 UDI 精靈 Designer 建立自訂精靈頁面編輯器。 如需 SampleEditor 專案的詳細資訊，請參閱 檢閱 SamplePage Visual Studio 解決方案。

若要驗證 SampleEditor 專案是否正確建置

1. 啟動 Visual Studio 2010。

2. 開啟 SampleEditor 專案。

   SampleEditor 專案位於 local_folder\SDK\UDI\SampleEditor 資料夾 (其中 local_folder 是您先前在程序) 中建立的資料夾。

3. 在 Visual Studio 2010 中，在方案總管中，選取 SampleEditor 專案。

4. 從 [專案 ] 功能表中，選取 [新增參照]。

   [ 新增參照 ] 對話方塊隨即開啟。

5. 在 [ 新增參照 ] 對話方塊中，選取 [ 瀏覽] 索引標籤。

6. 在 [ 瀏覽 ] 索引標籤上，移至 installation_folder\Bin (其中 installation_folder 安裝 MDT) 的資料夾。 選取下列檔案，然後選取 [確定]：

   • Microsoft.Enterprise.UDIDesigner.Common.dll

   • Microsoft.Enterprise.UDIDesigner.DataService.dll

   • Microsoft.Enterprise.UDIDesigner.Infrastructure.dll

   • Microsoft.Practices.Prism.dll

   • Microsoft.Practices.ServiceLocation.dll

   • Microsoft.Practices.Unity.dll

   • RibbonControlsLibrary.dll

   注意事項

   您可以在 [ 瀏覽 ] 索引標籤上選取多個檔案，方法是在選取檔案時按住 CTRL 鍵。

7. 在方案總管中，移至 SampleEditor/參考。

8. 確認所有參照沒有任何警告或錯誤。

9. 在方案總管中，以滑鼠右鍵按一下 SampleEditor 專案，然後選取 [屬性]。

   此時會出現 [SampleEditor 屬性頁 ] 對話方塊。

10. 在 [SampleEditor 屬性頁 ] 對話方塊中，選取 [ 偵錯 ] 索引標籤。

11. 在 偵錯 索引標籤上，選取啟動 外部程式。

12. 在 [啟動外部程式] 中，輸入 installation_folder\Bin\UDIDesigner.exe (，其中installation_folder是安裝 MDT) 的資料夾，然後選取 [確定]。

    提示

    您可以選取省略符號 (...) 按鈕以瀏覽至資料夾，然後選取 [UDIDesigner.exe]。

13. 從 [檔案 ] 功能表中，選取 [全部儲存]。

14. 將 local_folder\SDK\SamplePage\SamplePage.dll.config 檔案複製到 installation_folder\Bin\Config 資料夾 (其中 local_folder 是您先前在開發電腦上建立的設定程序資料夾，installation_folder 是安裝 MDT) 的資料夾。

15. 在 Visual Studio 2010 中，從 [偵錯 ] 功能表中選取 [ 開始偵錯]。

    UDI 精靈 Designer 隨即啟動。

16. 在 UDI 精靈 Designer 的 [功能區] 上，選取 [開啟]。

    此時會出現 [ 開啟] 對話方塊。

17. 在 [ 開啟 ] 對話方塊中，開啟 [ local_folder\SDK\SamplePage\SamplePage\Config.xml 檔案] (，其中 local_folder 您先前在組態程序) 在開發電腦上建立的資料夾。

    Config.xml 檔案隨即開啟，且 [自訂 StageGroup ] 會顯示在詳細資料窗格中。

18. 在詳細資料窗格中，選取 [設定 ] 索引標籤。

19. 檢閱 [位置] 方塊的設定資訊，包括下列內容：

    • [解除鎖定 ] 按鈕，用來啟用或停用 [位置] 方塊

    • [預設值] 方塊，您在其中輸入要在 [位置] 方塊中顯示的預設值

    • 易記顯示名稱會顯示在摘要頁面中，您可於其中輸入 [摘要] 頁面上所顯示資訊的標題

    • 位置清單 方塊，其中包含可能的位置清單

20. 關閉 UDI 精靈Designer。

21. 關閉 Visual Studio 2010。

檢閱 UDI SDK 範例

開始開發之前，請檢閱 UDI SDK 中提供的範例。 使用本指南中的資訊和範例中的原始程式碼，協助您建立自己的 UDI 自訂精靈頁面和精靈頁面編輯器。

透過檢閱以下內容，完成 UDI SDK 範例：

• 如檢閱 SDK 資料夾的內容中所述，您在安裝過程中先前複製的 SDK 資料夾的內容

• 自訂 UDI 精靈頁面範例，如檢閱 SamplePage Visual Studio 解決方案中所述

• 自訂 UDI 精靈頁面編輯器範例，如檢閱 SampleEditor Visual Studio 解決方案中所述

檢閱 SDK 資料夾的內容

在設定 UDI 開發環境期間，您將 SDK 資料夾從安裝 MDT 的資料夾複製到您建立的另一個資料夾。 表 1 列出了 SDK 資料夾正下方的資料夾，並提供每個資料夾的簡要說明。

表 1. UDI SDK 中的資料夾

檢閱 SamplePage Visual Studio 解決方案

開始建立自訂精靈頁面和精靈頁面編輯器之前，請執行下列工作以準備 UDI 開發環境：

• 如 檢閱精靈頁面生命週期中所述，檢閱 UDI 精靈頁面生命週期中的階段。

• 檢閱 UDI SDK 中 SamplePage 範例的 Visual Studio 解決方案，如 檢閱 SamplePage 範例中所述。

檢閱精靈頁面生命週期

UDI 精靈頁面具有對應至頁面生命週期的每個階段 (或階段) 的方法。 在建立自訂精靈頁面時，您必須使用程式碼覆寫這些方法。 表 2 列出您需要覆寫的方法，並提供每個方法的簡短說明，包括在嚮導頁面生命週期中何時使用該方法。

表 2. 精靈頁面生命週期中的方法

檢閱 SamplePage 範例

使用下列清單檢閱 SamplePage 範例，其代表 SamplePage 範例的精靈頁面生命週期內的事件順序：

1. OSDSetupWizard.exe UDI 精靈會從範例中的 UDI 精靈組態檔讀取組態設定資訊， (Config.xml 檔案) 如 步驟 1：UDI 精靈 (OSDSetupWizard.exe) 讀取 Config.xml 檔案中所述。

2. UDI 精靈會載入 UDI 精靈設定檔中列出的每個精靈頁面所需的 DLL，如 步驟 2 所述： UDI 精靈會載入自訂精靈頁面的 DLL。

3. UDI 精靈會顯示自訂精靈頁面，並允許所需的控制項互動，如 步驟 3 中所述： UDI 精靈會顯示自訂精靈頁面。

4. 當 [自訂精靈] 頁面收集資訊後，請執行所有必要的工作，然後選取 [下一步 ] 以繼續進行下一個精靈，如 步驟 4：在 [自訂精靈] 頁面中選取 [下一步] 按鈕中所述。

步驟 1：UDI 精靈 (OSDSetupWizard.exe) 讀取 Config.xml 檔案

當 UDI 精靈 (OSDSetupWizard.exe) 啟動時，預設會讀取 UDI 精靈設定檔，也就是 UDIWizard_Config.xml 檔案，也就是 UDI 精靈的主要設定檔。

您可以將 UDI 精靈工作順序步驟修改為使用 /definition 參數，以覆寫 UDI 精靈使用的預設設定檔案。 如需覆寫 UDI 精靈所使用之預設設定檔的詳細資訊，請參閱〈覆寫 UDI 精靈所使用的組態檔〉。

Config.xml 檔案中的頂層元素為

• DLLs 元素

• 樣式 元素

• Pages 元素

• StageGroups 元素

  如需 UDI 精靈設定檔的架構和每個元素的詳細資訊，請參閱 UDI 精靈組態檔架構參考。

  UDI 精靈會掃描 DLL 元素，尋找要載入的 .dll 檔案。 本範例列出了兩個 .dll 檔案：SamplePage.dll 和 SharedPages.dll。 這些 .dll 檔案必須與 OSDSetupWizard.exe 位於相同的資料夾中， (Tools\platform 資料夾，其中 32 位元版本的 platform 為 x86,64 位元版本的 x64 則為 x64) 。

  UDI 精靈會掃描 Pages 元素，尋找已定義的頁面。 在此範例中，定義了兩個頁面： Custom 和 SummaryPage。 Page 元素的 Type 屬性定義於 PageClassIDs.h 檔案中，並唯一定義自訂頁面的類型。

  在本範例中，定義的類型為 Microsoft.SamplePage.LocationPage。 對於您的自訂頁面，請替換以下內容，以避免與您將來可能建立的其他頁面發生任何潛在衝突：

• 您的組織名稱取代 Microsoft。

• 您的專案名稱取代 SamplePage。

• 您的自訂精靈頁面名稱取代 LocationPage。

步驟 2： UDI 精靈載入自訂精靈頁面的 DLL

當 UDI 精靈載入您的 DLL 時，它會呼叫 RegisterFactories 函數，必須在 .dll 檔案中實作。 在範例中，此函式是在 dllmain.ccp 檔案中實作。 您建立的每個精靈頁面都必須實作 RegisterFactories 函數。

RegisterFactories 函數可用來將精靈頁面的工廠類別向 UDI 精靈的類別工廠登錄註冊。 類別工廠 是可以建立另一個類別執行個體的類別。 RegisterFactories 函式會建立工廠類別的新執行個體，並將該類別傳遞給 UDI 精靈的類別工廠登錄，讓精靈可以使用該工廠類別。 UDI 精靈會尋找使用與自訂精靈頁面之 Page 元素的 Type 屬性相符之識別碼註冊的工廠類別。

在範例中，識別碼在 PageClassIds.h 檔案中定義為 ID_Location，Microsoft.SamplePage.LocationPage，這符合 Config.xml 檔案中 Page 元素的 Type 屬性。 ID_Location 會以 dllmain.ccp 檔案中實作的 RegisterFactories 函數中的參數方式傳遞。

您可以使用 Register_name 函數範本建立函數，以簡化新工廠執行個體的建立，並註冊新建立的執行個體。 使用 Register 函數範本提供的 名稱 值必須實作 iClassFactory 介面。 ClassFactoryImpl 類別處理實作類別工廠的大部分細節。

您也可以使用 RegisterFactories 函數來註冊任務類型和驗證器類型。 如需詳細資訊，請參閱下列各主題：

• 建立自訂 UDI 工作

• 建立自訂 UDI 驗證器

步驟 3：UDI 精靈顯示自訂精靈頁面

範例中的自訂精靈頁面是在 LocationPage.cpp 檔中定義的。 精靈頁面衍生自提供頁面所具有的大部分功能的範本類別。 所有精靈頁面都應該衍生自 WizardPageImpl 範本類別，其實作 IWizardPage 介面。 每個精靈頁面都可以根據頁面的需求，實現其他可選的範本類別和對應的介面。

WizardPageImpl 範本類別有幾個有用的介面，可協助您撰寫自訂精靈頁面。 將 WizardPageImpl 範本類別 實作為自訂精靈頁面的基底類別。

如需可用的清單：

• 範本類別 若要精靈頁面，請參閱精 靈頁面協助程式類別

• 介面 關於精靈頁面範本類別的介面，請參閱 精靈頁面介面

  範例中的自訂精靈頁面衍生自 WizardPageImpl 範本類別 ，並實作 IWizardPage 介面。 此外，自訂精靈頁面會實作 IFieldCallback 介面。 這兩者都是在 LocationPage.cpp 檔案中實作。

  範例自訂精靈頁面會覆寫下列方法：

• OnWindowCreated。 範例精靈頁面中的 OnWindowCreated 方法會呼叫下列方法：

  • AddField。 這個方法會將 IDD_LOCATION_PAGE 資源中的 IDC_COMBO_LOCATION 方塊控制項與 Config.xml 檔案中名為 Location的資料元素建立關聯。

    除了 AddField 方法，您還可以使用 AddRadioGroup 和 AddToGroup 方法來支援其他控制項和行為。

    注意事項

    請確定在呼叫 InitFields 方法之前，先呼叫 AddField、AddRadioGroup 或 AddToGroup 方法。

  • InitFields。 使用此方法可以初始化您已新增至表單的欄位 (控制項) 。 頁面的指標是一個參數。 在此範例中，會傳遞 this 指標，其會參照目前的頁面。

    注意事項

    若要支援 this 指標的使用，除了 WizardPageImpl 範本類別支援的介面之外，您還必須實作 IFieldCallback 介面。

    IFieldCallback 介面會呼叫 SetFieldDefault 方法，可用來設定文字方塊和核取方塊控制項以外的控制項預設值。 在範例中，SetFieldDefault 方法會根據 Config.xml 檔案中欄位元素的預設元素中指定的預設值來設定下拉式方塊控制項的初始索引。

    OnWindowCreated 方法會使用 IFormController 介面設定表單控制器。 如需設定表單控制器的詳細資訊，請參閱 設定表單。

• InitLocations。 這個方法會從 Config.xml 檔案中的位置清單填入下拉式方塊。 Confg.xml 檔案的 Data 元素和子 DataItem 元素提供可能的值清單。

• OnNextSelected。 這個方法會執行下列工作：

  • 使用 SaveFields 方法，以在下拉式方塊中選取的值匯報 TSLocation 工作順序變數

  • 使用 SaveFields 方法新增將在 [摘要] 頁面上顯示的資訊

步驟 4： 在「自訂精靈」頁面中選取「下一步」按鈕

當使用者完成自訂精靈頁面上的欄位時，選取 [下一步]，這會呼叫 OnNextSelected 方法。 OnNextSelected 方法會在繼續下一個精靈頁面之前，先執行任何必要的工作，例如，記錄在 [自訂精靈] 頁面上所做的任何設定變更。

針對範例自訂精靈頁面， OnNextSelected 方法的覆寫是在 LocationPage.ccp 檔案中實作。 在範例自訂精靈頁面的 OnNextSelected 方法中，會呼叫下列方法：

1. InitSection。 這個方法會初始化 [摘要] 頁面上顯示之摘要資料的標頭 (標籤標題) 。 一般而言，您可以使用 DisplayName () 函數來設定此值。 與此標題相關聯的資料會使用 SaveFields 方法儲存。

2. SaveFields。 這個方法會將欄位值儲存至工作順序變數和 [摘要 ] 頁面上顯示的資料。

檢閱 SampleEditor Visual Studio 解決方案

在開始建立自訂精靈頁面和精靈頁面編輯器之前，請先執行下列步驟來準備 UDI 開發環境：

• 檢閱 UDI Wizard Designer 的架構，如檢閱 UDI 精靈 Designer 架構中所述。

• 檢閱可使用 UDI 精靈設定檔自訂的 UDI 精靈頁面元件，如 檢閱 UDI 精靈頁面的可設定元件中所述。

• 檢閱 UDI SDK 中提供的 EditorPage 範例，如 檢閱 EditorPage 範例中所述。

檢閱 UDI 精靈 Designer 架構

UDI 精靈 Designer 是使用 WPF、Prism 和 Unity 開發。 UDI Designer用於編輯 UDI 精靈設定檔 (UDIWizard_Config.xml) ，UDI 精靈 (OSDSetupWizard.exe) 在執行階段讀取該檔案。 UDI 精靈設定檔中的 Pages 元素包含頁面清單，每個精靈頁面都有個別的 Page 元素。

當您編輯精靈頁面的組態設定時，UDI 精靈 Designer 會載入對應至精靈頁面類型的自訂頁面編輯器。 自訂精靈頁面編輯器是開發為 WPF 使用者控制項。 自訂精靈頁面編輯器頁面使用 Model-View-ViewModel (MVVM 適用於 WPF) 設計模式。

MVVM 設計模式有助於分隔使用者介面 (UI;簡報) 來自呈現的資料。 資料是 UDI 精靈設定檔中的 Page 元素外觀， (範例) 中的 Config.xml 檔案，可使用 IDataService 介面的 CurrentPage 屬性存取。

UDI 精靈 Designer 使用 DependencyAttribute 根據 Unity 中的相依性插入架構來取得 DataService 類別的存取權。 如需 Unity 中相依性感嘆詞架構的詳細資訊，請參閱為您的 應用程式注入一些活力 — 了解 Unity 應用程式區塊。

檢閱 UDI 精靈頁面的可設定元件

當您建立自訂精靈頁面時，某些組態設定可能會在程式碼中設定，並且在編譯頁面後無法變更。 但是，對於其他組態設定，您必須允許使用 UDI 精靈 Designer 變更這些組態設定。

一般而言，您想要使用 UDI 精靈Designer設定的組態設定會儲存在 UDI 精靈組態檔 (範例) 中的 Config.xml 檔案中。 不過，如有必要，您也可以建立自己的單獨設定檔。 使用個別設定檔的其中一個範例是 UDIWizard_Config.xml.app 檔案， 該應用程式探索 工作和 ApplicationPage 精靈頁面類型都會使用該檔案。

以下是您可以使用 UDI 精靈Designer 管理的一般組態設定清單：

• 欄位。 使用欄位允許使用者提供輸入。 欄位在 UDI 精靈設定檔 (UDIWizard_Config.xml) 中顯示為 欄位 元素，其中包含每個欄位的組態設定。 對應的精靈頁面編輯器必須提供使用 FieldElementControl 編輯欄位欄位組態設定的方法。

• 屬性。 設定者可協助建立頁面上實體的屬性，例如 Page 元素中的頁面、 Field 元素中的欄位，或 Data 或 DataItem 元素中的資料。 您可以在 Setter 元素中設定屬性。 為每個您要定義的屬性新增個別的 Setter 元素。 您可以使用 SetterControl 編輯屬性，並使用其他控制項來設定其他 Setter 元素。

• 資料。 資料是用來儲存資訊，供精靈頁面和其他元件使用。 您可以使用 Data 或 DataItem 元素定義頁面或欄位的資料。 透過正確使用 Data 或 DataItem 元素，可以在一般或階層結構中定義資料。 SDK 中範例中的 Config.xml 示範如何建置一般資料結構。

  您建立的自訂精靈頁面編輯器必須能夠管理這些組態設定。

檢閱 EditorPage 範例

EditorPage 範例可用來設定 UDI 精靈設定檔中 SamplePage 精靈頁面的組態設定。 EditorPage 範例具有下列主要元件：

• 設定 [位置 ] 下拉式方塊設定的 UI

• 在可能位置清單中新增或編輯位置的 UI，如 [ 位置 ] 下拉式方塊中所示

• 從 UDI 精靈設定檔讀取並儲存組態設定

• 其他元件的支援程式碼

  執行下列步驟，檢視 Visual Studio 中的 EditorPage 範例：

1. 檢閱如何在 UDI 精靈 Designer 中載入及初始化 SampleEditor 精靈頁面編輯器，如檢閱精靈頁面編輯器載入和初始化中所述。

2. 檢閱用於在 LocationPageEditor.xaml 中編輯 位置 下拉式方塊的 UI，並LocationPageEditor.xaml.cs檔案中所述，如 檢閱用來設定位置下拉式方塊的使用者介面中所述。

3. 檢閱用來在 AddEditLocationView.xaml 和 AddEditLocationView.xaml.cs 檔案清單中新增或編輯位置的 UI，如以下所述： 檢閱用來修改可能位置清單的使用者介面。

4. 檢閱用來管理儲存在 UDI 精靈組態檔中的組態資訊的程式碼，如 檢閱用來管理組態資訊的程式碼中所述。

[校閱精靈] 頁面編輯器載入和初始化

自訂精靈頁面編輯器會依據 UDI 精靈Designer 的需求載入。 UDI 精靈 Designer 設定檔會在 UDI 精靈 Designer 啟動時載入。 UDI 精靈Designer會掃描 install_folder\Bin\Config 資料夾 (其中 install_folder 是安裝 MDT 的資料夾名稱，) 尋找副檔名為 .config 的檔案。

在設定 UDI 開發環境期間，您將 SamplePage.dll.confg 檔案複製到 install_folder\Bin\Config 資料夾。 當您啟動 UDI 精靈Designer時，可以找到並載入 SamplePage.dll.confg 檔案。

UDI 精靈Designer使用 SamplePage.dll.confg 檔案中 Page 元素的下列屬性來載入和初始化 EditorPage 範例：

• DesignerAssembly。 此屬性決定要載入的 DLL 名稱。 此 DLL 必須與 UDIDesigner.exe 檔案放在相同的資料夾中，也就是 install_folder\Bin 資料夾 (其中 install_folder 是安裝 MDT 的資料夾名稱) 。

• DesignerType。 這個屬性是包含 WPF 使用者控制項之類別的 Microsoft .NET 類型名稱。

• 類型。 使用此屬性來設定自訂精靈頁面的頁面類型，UDI 精靈會載入該頁面。 UDI 精靈 Designer 使用此屬性在 UDI 精靈設定檔中找到適當的 Page 元素。

• Dll。 使用此屬性來設定 UDI 精靈設定檔中的 DLL 元素，該檔案由 UDI 精靈 Designer 建立。

• 描述。 使用此屬性來提供精靈頁面編輯器的相關資訊。 此屬性的值會顯示在 UDI 精靈 Designer 的 [新增頁面] 對話方塊中，用來將精靈頁面新增至「頁面庫」。

• DisplayName。 使用此屬性來提供 UDI 精靈Designer中顯示的自訂精靈頁面名稱。 此屬性的值會顯示在 UDI 精靈 Designer 的 [新增頁面] 對話方塊中，用來將精靈頁面新增至「頁面庫」。

  在範例中， SamplePage 自訂精靈頁面的類型為 Microsoft.SamplePage.LocationPage，會儲存在 Config.xml 檔案中。 Config.xml 檔案位於 local_folder\SDK\SamplePage\SamplePage 資料夾中， (其中 local_folder 是您先前在組態程序) 在開發電腦上建立的資料夾。

檢視用來設定 [位置] 下拉式方塊的使用者介面

載入精靈頁面編輯器並初始化時，當編輯類型為 Microsoft.SamplePage.LocationPage 的頁面時，會載入 SampleEditor 精靈頁面編輯器。 頁面編輯器的 UI 會儲存在 LocationPageEditor.xaml 檔案中。

如果您檢查 [ 設計 ] 索引標籤上的 UI 和 [XAML ] 索引標籤上的程式碼，您可以看到圖形 UI 與可延伸應用程式標記語言 (XAML) 中的元素和屬性之間的關係。

例如，如果您檢閱 XAML 中的 Controls：FieldElementControl 元素，可以看到它與對應 UI 的版面配置有何關聯。 使用 Controls：FieldElementControl 元素來定義 FieldElementControl 控制項。

XAML 檔案中的 繫結 參數會將範例頁面編輯器上的欄位與 UDI 精靈組態檔中的資訊繫結。 例如，下列程式碼會將 預設值 文字方塊與範例) 中 (Config.xml 的 UDI 精靈設定檔中的 預設 元素繫結：

<TextBox Text="{Binding FieldData.DefaultValue,
 UpdateSourceTrigger=PropertyChanged,
 Mode=TwoWay}"/>

如需詳細資訊，請參閱 如何：讓資料可用於 XAML 中的繫結。

使用 XAML 中的 Views：CollectionTControl.ColumnCollectionView 元素來編輯格線檢視中的可用位置清單。 您可以使用 CollectionTControl 控制項來顯示方格檢視，並將方格檢視繫結至 UDI 組態檔中名稱為 [位置]的資料元素。

檢閱用來修改可能位置清單的使用者介面

修改可能位置清單的 UI 包括：

• 內容相關的功能表和功能區按鈕，可讓您新增、編輯、移除或變更位置清單中的項目順序，如檢閱可修改位置清單的內容功能表和功能區按鈕中所述

• 當您選取新增或編輯位置清單中的項目時所啟動的對話方塊，如檢閱新增或編輯位置的對話方塊中所述

檢閱可修改位置清單的關聯式功能表和功能區按鈕

當您以滑鼠右鍵按一下包含位置清單的清單方塊時，會顯示關聯式功能表。 功能區具有對應的按鈕，可讓您執行相同的工作。 LocationPageEditor.xaml 檔案中的 Views：CollectionsTControl 控制項元素會定義根據所採取的動作和您設定的屬性來呼叫的方法，如下所示：

• SelectedItem。 當使用者從清單中選取項目時，會啟用此資料繫結屬性。 這個屬性會繫結至檢視模型中的 CurrentLocation 屬性，其位於LocationPageEditorViewModel.cs檔案中，並在您編輯或移除現有項目時，由 CollectionTControl 控制項用來傳遞選取的項目。

• AddItemAction。 當使用者從操作功能表或功能區上的對應按鈕中選取 [ 新增項目 ] 選項時，就會執行此動作。 檢視模型中有一個資料繫結可傳回 AddLocationAction 物件的屬性。 此物件就是 位於 LocationPageEditorViewModel.cs 檔案中的 AddLocationCallback 方法，並在 AddEditLocationView.xaml 檔案中顯示對話方塊。

• EditItemAction。 當使用者從上下文相關的功能表中選取 [編輯項目 ] 選項時，會執行此動作。 檢視模型中的屬性有一個資料繫結，會傳回 EditLocationAction 物件。 此物件就是位於 LocationPageEditorViewModel.cs 檔案中的 EditLocationCallback 方法，並在 AddEditLocationView.xaml 檔案中顯示對話方塊。

• RemoveAction。 當使用者從上下文相關的功能表中選取 [ 移除項目 ] 選項時，就會執行此動作。 檢視模型中有一個資料繫結可傳回 RemoveAction 物件的屬性。 此物件是位於 LocationPageEditorViewModel.cs 檔案中的 EditLocationCallback 方法，並顯示確認刪除位置的訊息。

檢視新增或編輯位置的對話方塊

如果您將新位置新增到位置清單或編輯現有位置，將顯示位於 AddEditLocationView.xaml 檔案中的訊息。 訊息是使用 LocationPageEditorViewModel.cs 檔案中的 ShowDialogWindow window 方法顯示。

AddEditLocationView.xaml 檔案中的 UI 包含：

• 名為 DialogFrame 的對話框，其中包含下列元素：

  • 標題，您可以使用對話框的 DialogTitle 屬性設定

  • 一個 [確定] 按鈕，可將 [已核准] 屬性的傳回狀態設定為 True (會在 LocationPageEditorViewModel.cs 檔案的 AddLocationCallback 方法中檢查傳回狀態，以判斷使用者是否選取 [確定 ) ]。

  • 取消 按鈕， 可將 Approved 屬性的傳回狀態設定為 False (會在 LocationPageEditorViewModel.cs 檔案的 AddLocationCallback 方法中檢查傳回狀態，以判斷使用者是否選取 了 [取消]。)

• 包含下列內容的 WPF 元素：

  • 標籤，您使用 Content 屬性設定

  • 文字方塊，會繫結至 UDI 組態檔中名稱為 Location的資料元素， (範例) 中的 Config.xml 檔案

檢閱用來管理組態資訊的程式碼

自訂精靈頁面的組態資訊會儲存在 UDI 精靈組態檔中，即：

• UDI SDK 提供的範例中的 Config.xml 檔案 (此檔案只包含範例的組態設定。)

• 隨著 MDT 提供的 UDIWizard_Config.xml 檔案，儲存在 installation_folder\Templates\Distribution\Scripts 資料夾中， (installation_folder 是安裝 MDT) 的資料夾;此檔案包含所有內建精靈頁面和階段的組態設定

  在 SampleEditor 範例中， 位置 常式可協助管理組態資訊，且位於LocationPageEditorViewModel.cs檔中。 位置常式會從 UDI 精靈設定檔傳回位置清單。 具體而言，傳回的清單包含 UDI 精靈設定檔中每個 DataItem 元素的項目。

建立自訂 UDI 精靈頁面

建立自訂 UDI 精靈頁面的高階流程如下：

1. 製作 SamplePage 解決方案的副本作為起點。

2. 將所需的控制項 (欄位) 表單上放置。

3. 撰寫程式碼以在精靈頁面載入 OnWindowCreated 方法) 的覆寫 (時執行適當的工作，包括下列步驟：

   1. 初始化表單。

   2. 讀取記憶體變數、工作順序變數、環境變數或 XML 檔案資訊 (，例如 Setter 屬性) 。

4. 撰寫任何程式碼，以在頁面顯示時執行適當的工作， (覆寫 OnWindowShown 方法) ，包括下列步驟：

   1. 根據步驟 3 中頁面載入時讀取的資訊來啟用或停用控制項。

   2. 根據在步驟 3 中載入頁面時所讀取的資訊更新控制項，例如根據讀取的資訊母體控制項。

5. 撰寫任何程式碼，以便在使用者與精靈頁面互動時執行適當的工作。

6. 當使用者在 UDI 精靈中選取 [ 下一步 ] 時，撰寫任何程式碼以執行適當的工作， (覆寫 OnNextSelected 方法) ，包括下列步驟：

   1. 更新任何記憶體變數、工作順序變數、環境變數或 XML 檔案資訊。

   2. 如果頁面) 上的欄位未執行，則 (更新摘要頁面資訊。

7. 建置解決方案。

   請確定您建立的 DLL 版本與 MDT 安裝相同的處理器平台，特別是適用於 Windows 預先安裝環境 (Windows PE) 的處理器平台。 UDI 精靈可以在下列位置執行：

   • 目標電腦上的現有作業系統。 您可以在 32 位元或 64 位元 Windows 作業系統上執行 32 位元版本的精靈頁面。 不過，您只能在 64 位元 Windows 作業系統上執行 64 位元版本的精靈頁面。

   • 目標電腦上的 Windows PE。 Windows PE 不支援在 64 位元版本的 Windows PE 上執行 32 位元應用程式。 因此，您必須針對您計劃使用的每個 Windows PE 處理器架構，為精靈頁面建置一個版本。

8. 將自訂精靈頁面的 DLL 複製到 installation_folder\Templates\Distribution\Tools\ platform 資料夾 (其中 installation_folder 是安裝 MDT 的資料夾，而 platform 是 x86 的 32 位元版本，或 x64 是 64 位元版本) 。

9. 完成建立自訂頁面編輯器的步驟。

建立自訂精靈頁面編輯器

建立自訂 UDI 精靈頁面編輯器的高階程序如下：

1. 製作 SampleEditor 解決方案的複本做為起點。

2. 在 .xaml 檔案中建立主要頁面編輯器 UI。

3. 根據精靈頁面的需求新增 FieldElementControl 控制項的實例，以在) 進行設定 (。

4. 根據精靈頁面的要求新增 SetterControl 控制項的實例，以進行設定 () 。

5. 根據精靈頁面的要求新增 CollectionTControl 控制項的執行個體，以視需要 (進行設定) 。

6. 新增 IDataService 介面。

7. 撰寫適當的程式碼，以根據要使用自訂精靈頁面編輯器進行設定的組態設定來更新 UDI 精靈設定檔。

8. 在 .xaml 檔案中建立子對話方塊，並視要設定的精靈頁面需求，使用 IMessageBoxService 介面從主要頁面編輯器呼叫它們。

9. 根據要設定的精靈頁面需求，將適當的介面新增至 UDI 精靈 Designer 功能區。

10. 建置解決方案。

    注意事項

    請確定您建立的 DLL 版本與安裝 MDT 的處理器平台相同。 例如，如果您安裝 64 位元版本的 MDT，則請建置 64 位元版本的自訂頁面編輯器。

11. 建立 UDI 精靈Designer組態檔以載入必要的 DLL，並將精靈頁面編輯器與對應的精靈頁面對應 (範例) 中的 SamplePage.dll.config 檔案。

    如需在精靈頁面與精靈頁面編輯器之間執行對應所需元素的詳細資訊，請參閱 DesignerMappings 元素、子元素和對應的屬性。

12. 將您在上一個步驟中建立的 UDI 精靈Designer設定檔複製到 installation_folder\Bin\Config 資料夾 (其中installation_folder是安裝 MDT 版本) 的資料夾。

13. 將自訂精靈頁面編輯器的 DLL 複製到 installation_folder\Bin 資料夾 (其中 installation_folder 是安裝 MDT) 的資料夾。

建立自訂 UDI 工作

UDI 工作 是以 C++ 撰寫的 DLL，可實作 ITask 介面。 您可以建立 UDI 精靈Designer設定檔 (.config 檔案) ，並將它放在 installation_folder\Bin\Config 資料夾中， (其中installation_folder安裝 MDT) 的資料夾，以向 UDI 精靈Designer工作程式庫註冊 DLL。

建立自訂 UDI 工作

1. 撰寫實作 ITask 介面 和下列方法的程式碼：

   • 初始化。 呼叫此方法來初始化您的工作。

   • 執行。 呼叫此方法來執行您的工作。

2. 撰寫代碼，將自訂工作類別 factory 註冊到工廠登錄。

3. 為您的自訂工作建置解決方案。

   注意事項

   請確定您建立的 DLL 版本與安裝 MDT 的處理器平台相同。 例如，如果您安裝 64 位元版本的 MDT，則請建置 64 位元版本的自訂 UDI 工作。

4. 在 UDI 精靈 Designer 組態檔的 TaskLibrary 元素下建立 Task 元素，如下所示：

   <Task DLL="OSDRefreshWizard.dll" Description="Discovers supported applications for install." Type="Microsoft.OSDRefresh.AppDiscoveryTask" Name="Application Discovery">
      <TaskItem Type="Setter" Name="Status Bitmap">
         <Param Name="BitmapFilename"/>
      </TaskItem>
      <TaskItem Type="Setter" Name="Log File">
         <Param Name="log"/>
      </TaskItem>
      <TaskItem Type="Setter" Name="Write Configuration File">
         <Param Name="writecfg"/>
      </TaskItem>
      <TaskItem Type="Setter" Name="Read Configuration File">
         <Param Name="readcfg"/>
      </TaskItem>
   </Task>
   

   注意事項

   所有 Task 元素都應包含 BitmapFilename 參數。 指定工作需要的所有其他參數。 例如，在先前的摘錄中， log 參數是用來指定日誌檔位置的參數。

5. 將先前步驟建立的 UDI 精靈Designer設定檔複製到 installation_folder\Bin\Config 資料夾 (其中 installation_folder 是安裝 MDT) 的資料夾。

6. 將自訂工作的 DLL 複製到 installation_folder\Templates\Distribution\Tools\ platform 資料夾 (其中 installation_folder 是安裝 MDT 的資料夾，而 platform 是 x86 的 32 位元版本， x64 是 64 位元版本) 。

建立自訂 UDI 驗證器

UDI 驗證程式 是以 C++ 撰寫的 DLL，可實作 IValidator 介面。 您可以建立 UDI 精靈Designer設定檔 (.config 檔案) ，並將它放在 installation_folder\Bin\Config 資料夾 (，其中 installation_folder 是安裝 MDT) 的資料夾，以向 UDI 精靈Designer驗證程式庫註冊 DLL。

建立自訂 UDI 驗證程式

1. 撰寫程式碼可建立 BaseValidator 類別的子類別，並實作下列方法：

   • 初始化 (IControl *pControl， IWizardPageContainer *pContainer， IStringProperties *pProperties) 。 表單控制器會呼叫 Init 成員來初始化驗證程式。 這個方法必須呼叫 BaseValidator 類別的 Init 方法。 它通常會從 UDI 精靈設定檔讀取為驗證程式設定的任何屬性。 例如， InvalidCharactersValidator 驗證程式會使用此方法來擷取 InvalidChars 屬性的值。

   • IsValid。 表單控制器會呼叫這個方法，以查看控制項是否包含有效的文字。 下列範例是驗證工具的 IsValid 方法，可驗證欄位是否為空白：

     BOOL IsValid(LPBSTR pMessage)
     {
         __super::IsValid(pMessage);
     
         _bstr_t text;
         m_pText->GetText(text.GetAddress());
         return (text.length() > 0);
     }
     

   • Init (IControl *pControl， LPCTSTR 訊息) 。 表單控制器會針對每個按鍵和其他事件呼叫此成員，讓驗證程式驗證精靈頁面底部的控制項內容和更新訊息， (或清除它們) 。

     通常，這些是您需要覆寫的唯一方法。 不過，視驗證器而定，您可能需要覆寫所建立 BaseValidator 類別子類別中的其他方法。 如需這些其他方法的詳細資訊，請參閱 BaseValidator 類別。

2. 撰寫將自訂工作類別登錄到登錄工廠的程式碼。

3. 為您的自訂工作建置解決方案。

   注意事項

   請確定您建立的 DLL 版本與安裝 MDT 的處理器平台相同。 例如，如果您安裝 64 位元版本的 MDT，則請建置 64 位元版本的自訂 UDI 工作。

4. 在 UDI 精靈 Designer 組態檔的 ValidatorLibrary 元素下建立 Validator 元素，如下所示：

   <Validator
   <Validator DLL="" Description="Must follow a pre-defined pattern" Type="Microsoft.Wizard.Validation.RegEx" Name="NamedPattern">
      <Param Description="Enter the message you want displayed when the text in this field doesn't match the pattern:" Name="Message" DisplayName="Message"/>
      <Param Description="The name of a pre-defined regular expression pattern. Must be Username, ComputerName, or Workgroup" Name="NamedPattern" DisplayName="Named Pattern"/>
   </Validator>
   

   警告

   所有 驗證程式 元素都應包含 Message 參數。 指定驗證程式所需的所有其他參數。 例如，在先前的摘錄中， NamedPattern 參數可用來指定預先定義規則運算式模式名稱的參數。

5. 將先前步驟建立的 UDI 精靈Designer設定檔複製到 installation_folder\Bin\Config 資料夾 (其中 installation_folder 是安裝 MDT) 的資料夾。

6. 將自訂工作的 DLL 複製到 installation_folder\Templates\Distribution\Tools\ platform 資料夾 (其中 installation_folder 是安裝 MDT 的資料夾，而 platform 是 x86 的 32 位元版本， x64 是 64 位元版本) 。

UDI 精靈參考

精靈頁面元件

您可以使用數個預先建置元件中的任何一個來建立自訂頁面。

建立元件執行個體

UDI 精靈會使用類別處理站來為您建立新的物件執行個體。 這些 Factory 會使用字串做為 Factory 的金鑰，向 Factory 登錄註冊。 例如， WmiRepository 元件由字串「Microsoft.Wizard.WmiRepository」所識別，該字串可在 IWmiRepository 標頭檔案中以 ID_WmiRepository使用。

假設您已將頁面寫寫為 WizardPageImpl 的子類別，您可以建立 WmiRepoistory 的新執行個體，如下所示：

PWmiRepository pWmi;
CreateInstance(Container(), ID_WmiRepository, &pWmi);

CreateInstance 函式是類型安全的範本函式，用於建立元件的新執行個體。 PWmiRepository 是一個智慧指標，因此它可以為您處理參照計數。

可建立的元件

您可以向登錄註冊一組元件。 第一組元件一律會登錄，因為主要的 UDI 精靈可執行檔會提供它。 其他兩組元件是在「選用」DLL 中提供。 若要讓這些元件可用，DLL 必須列在 .config XML 檔案的 DLL 區段中。 您的程式碼不需要知道哪個可執行檔包含特定元件。

元件的元件 ID 清單 (元件名稱與 ID 相同，但沒有使用 OSDSetupWizard 中定義的原廠登錄 (登錄的初始 ID_) ) 如表 3 所示。

表格 3 元件識別碼

定義的 OSDRefreshWizard.dll、共用頁面和其他控制元件如表 4 和表 5 所示。

表格 4 目錄控制項

表格 5 定義 SharedPages.dll

控制元件

您可以透過 GetControlWrapper 範本函式與頁面上的控制項互動，該函式提供表 6 中所列元件類型之一的存取權。

表格 6 元件

影像清單元件

此元件是頁面上 ImageList 控制項的外觀。 您可以透過 IListView 或 ITreeView 介面建立影像清單。

FormController 元件

精靈會為您建立此元件，並將它傳遞至您的頁面。 您可以使用 WizardPageImpl 基底類別實作的 Form 方法從頁面存取它。

InvalidCharacterValidator 元件

這是一種可以包含在頁面上的驗證器類型。 識別碼 ID_InvalidCharactersValidator ( IValidator.h) 中定義，其文字值為「Microsoft.Wizard.Validation.InvalidChars」。

此驗證程式會在 .config 檔案) 中尋找 Setter 元素 (單一屬性，稱為 InvalidChars，這是不允許的字元清單。 它會檢查文字方塊中的字元;如果文字包含此清單中的任何字元，元件會報告失敗。

NonEmptyValidator 元件

這是一種可以包含在頁面上的驗證器類型。 識別碼 ID_NonEmptyValidator ( IValidator.h) 中定義，其文字值為「Microsoft.Wizard.Validation.NonEmpty」。

如果文字輸入框 (或任何其他支援 IStaticText) 的控制項含有空白字串值，此驗證程式會報告失敗。

PasswordValidator 元件

這是一種可以包含在頁面上的驗證器類型。 識別碼 ID_PasswordValidator (IValidator.h) 中定義，其文字值為「Microsoft.Wizard.Validation.Password」。

此驗證程式可搭配兩個不同的文字控制項使用， (控制項支援 IStaticText) ，如果它們不包含相同的值，則會報告失敗。 換句話說，如果 [密碼] 和 [ 確認密碼 ] 文字方塊不相符，則會失敗。

由於此驗證器需要兩個控件，因此它需要比其他驗證器更多的設定。 設定看起來可能像這樣：

Form()->AddToGroup(IDC_EDIT_PASSWORD, IDC_EDIT_PASSWORD2);
PValidator pValidator;
Form()->AddValidator(IDC_EDIT_PASSWORD, ID_PasswordValidator, pMessage, &pValidator);
PStaticText pPassword2;
GetControlWrapper(View(), IDC_EDIT_PASSWORD2, CONTROL_STATIC_TEXT, &pPassword2);
pValidator->SetProperty(0, pPassword2);

首先，您將 [確認密碼 ] 控制項定義為 [密碼 ] 控制項的「子系」。 如此一來，如果表單控制器停用 [密碼 ] 控制項，也會停用 [ 確認密碼 ] 控制項。 接下來，將密碼驗證程式新增至表單。 最後，為密碼驗證器提供 [確認密碼 ] 控制項的介面。

由於需要兩個控制項，您必須使用程式碼來設定此驗證程式，而不是 .config XML 檔案。

RegExValidator 元件

這是一種可以包含在頁面上的驗證器類型。 識別碼 ID_RegExValidator ( IValidator.h) 中定義，其文字值為「Microsoft.Wizard.Validation.RegEx」。

此驗證工具會將支援 IStaticText) 的文字控制項的內容 (與規則運算式進行比較，如果文字不符合規則運算式，則會失敗。

或者，您可以將此驗證器與預定義的命名模式一起使用。 若要使用規則運算式，XML 必須包含名為 Pattern 的 setter 屬性。 如果您想要改用具名模式，請使用名為 NamedPattern 的 setter，該 setter 設定為表 7 中的其中一個值。

表格 7 具名模式設定者

FactoryRegistry 元件

此元件會追蹤所有類別 Factory 和服務。 它會實作 IFactoryRegistry 介面，並可透過頁面的 Container 方法間接取得。 此外，登錄會載入擴充功能 DLL。 載入 DLL 之後，登錄會尋找名為 RegisterFactoryies 的匯出函式。 您必須實作此函數，並在其中註冊頁面、任務和驗證程式的類別工廠， (以及您想要註冊) 的任何其他類別工廠。 以下是範例專案的範例：

extern "C" __declspec(dllexport) void RegisterFactories(IFactoryRegistry *factories)
{
Register<LocationPageFactory>(ID_LocationPage, factories);
}

記錄器元件

您可以透過 WizardPageImpl) 實作的 Logger 方法 (頁面使用此元件。 您可以使用此方法將項目寫入記錄檔。 記錄檔的內容對於診斷使用者在執行 UDI 精靈時可能遇到的問題很有用。

PropertyBag 元件

屬性包是記憶體變數的容器。 可從您的頁面使用 容器 () -Properties> () 取得。 記憶體變數對於在不同頁面之間傳遞暫存資料非常有用。

TSVariableBag 和 TSRepository 元件

TSVariableBag 元件可讓您讀取和寫入工作順序變數。 它會將值保留在記憶體中，直到使用者預設選取 [ 完成 (]) 。 您可以透過頁面的 TSVariables 方法存取 TSVariables 包 (由 WizardPageImpl 基底類別) 實作。 這些元件會記錄工作順序變數的所有讀取和寫入。

WmiRepository 元件

此元件提供使用 WMI 查詢的外觀。 您可以使用 ID_WmiRepository 呼叫 CreateInstance 協助程式函式，以取得此元件的執行個體，其支援 IWmiRepository 介面。 此元件會透過 IWmiIterator 介面傳回結果記錄。

精靈頁面協助程式類別

您可以使用 UDI SDK 隨附的內建協助程式類別建立自訂 UDI 精靈頁面。 表 8 列出可用來建立自訂精靈頁面的協助程式類別。

表格 8 協助程式類別

ClassFactoryImpl 類別

這是建立類別 factory 的實用基底類別，之後您可以向 Factory 登錄註冊。

以下是範例專案中定義 ClassFactoryImpl 類別的 LocationPage.h 檔案的摘錄。

#pragma once

#include "ClassFactoryImpl.h"

class LocationPageFactory :public ClassFactoryImpl
{
protected:
    IUnknown *CreateNewInstance();
};

以下是範例精靈頁面中 LocationPage.cpp 檔案的摘錄，用來定義頁面的類別處理站。

IUnknown *LocationPageFactory::CreateNewInstance()
{
    return static_cast<IWizardPage *>(new LocationPage);
}

介面範本類別

當您想要建置實作多個介面的元件時，請使用此範本類別，例如：

classLocationPage :public Interface<IFieldCallback, WizardPageImpl<IDD_LOCATION_PAGE>>

這段程式碼會建立基底類別鏈結，該鏈結同時支援 IFieldCalback 和 WizardPageImpl 支援的介面， (恰好是 IWizardPage) 。

路徑協助程式類別

此類別提供常見的檔案/目錄作業：

static inline std::wstring GetModulePath(HINSTANCE hModule)

它也會傳回 .exe 或 .dll 檔案的完整路徑，以及您提供給這個方法的實例控點：

static inline std::wstring GetModuleFilename(HINSTANCE hModule)

類別會傳回 .exe 的完整路徑和檔案名稱，以及您提供給這個方法的實例控點 .dll 檔案：

static inline std::wstring GetDirectoryName(LPCWSTR fullName)

. . . 或只選擇路徑，同時剝離檔案名稱：

static inline std::wstring GetFileName(LPCWSTR fullName)

給定具有檔案名稱的路徑，路徑協助程式類別只會傳回檔案名稱：

static inline std::wstring Combine(LPCWSTR path, LPCWSTR name)

最後，類別會傳回新字串，該字串是結合路徑和檔案名稱 (或另一個路徑) 。

指標範本類別

此類別是在 Pointer.h 中定義的。 因為 COM 元件使用參照計數來進行存留期管理，所以請務必在完成之後釋放介面。 Microsoft 提供可自動處理存留期的範本類別。 例如，如果您想要 XML 介面的智慧指標，您可以撰寫如下內容：

Pointer<IXMLDOMNode> pNewChild
pXmlDom->CreateNode(NODE_ELEMENT, L"MyElement", L"", &pNewChild);

第一行定義智慧指標。 第二行顯示透過另一個呼叫擷取智慧指標。 & 運算子一律會釋放現有的介面（如果它包含一個介面），並傳回內部指標的位址。 擷取像這樣的指標之後，當變數超出範圍時， 指標 實例就會為您呼叫 Release 。 Microsoft 建議您使用智慧指標，而不是手動呼叫 AddRef 和 Release 。

此外， Pointer 智慧指標類別會呼叫 QueryInterface 來為您擷取其他介面。 例如，當工廠登錄建立元件的新執行個體時，其程式碼會如下所示：

PWizardComponent pComp = pUnknown;
if (pComp != nullptr)
    pComp->SetContainer(m_pContainer);

第一行會在幕後呼叫 QueryInterface 來要求 IWizardComponent 介面。 如果元件不支援該介面，則產生的智慧指標會等於 nullptr 。

PUnknown 類別

這個類別是專門用於 IUnknown 介面的智慧指標。 針對所有其他介面，請使用 Pointer 範本類別。

StringUtil 協助程式類別

這個類別是在 Utilities.h 中定義，並提供協助程式方法，讓字串更容易處理：

static inline int CompareIgnore(LPCWSTR first, LPCWSTR second)

此方法會比較兩個字串，同時忽略大小寫 (請參閱表 9) 。

表格 9 StringUtil 協助程式類別

範例如下：

static inline std::wstring Format(LPCWSTR input, int index, LPCWSTR value)
static inline std::wstring Format(LPCWSTR input, int index, DWORD value)

這些方法有點類似 Microsoft .NET Format 方法，因為參數採用 的格式 {0}為 。 不過，它們不會執行任何輸入的格式設定，只會進行替換：

static inline std::wstring Printf(std::wstring format, I val)
static inline std::wstring Printf(std::wstring format, I val1, J val2)
static inline std::wstring Printf(std::wstring format, I val1, J val2, K val3)
static inline std::wstring Printf(std::wstring format, I val1, J val2, K val3, L val4)

這些是傳回 wstring 的 StringCchPrintf 周圍的包裝函式，因此您不需要自行為字串或緩衝區配置記憶體。

子介面範本類別

此基底類別可讓您更容易實作支援從另一個介面繼承之介面的元件。 例如， ICheckBox 介面繼承自 IControl。 以下是使用此類別來定義 CheckBoxWrapper 的方式：

classCheckBoxWrapper :public SubInterface<IControl, UnknownImpl<ICheckBox> >

基本介面是第一個參數，而衍生介面是第二個參數。

UnknownImpl 範本類別

這個類別是在 UnknownImpl.h 中定義，並處理建立 COM 元件的大部分詳細資料。 以下是使用此基底類別的範例：

classDirectory :public UnknownImpl<IDirectory>

此程式碼定義支援 IDirectory 介面的類別。

WizardComponent 範本類別

這個類別是在 IWizardComponent.h 中定義，是建立需要存取精靈服務的元件的實用基底類別，例如元件建立和記錄。

例如，以下是 CopyFilesTask 元件的定義方式：

classCopyFilesTask :public WizardComponent<ITask>
{
    ...

此範本類別的參數是您要用於元件的「主要」介面，在工作的情況下為 ITask。 使用 WizardComponent 表示您的元件支援您提供 (此範例 ) 中的 ITask 和 IWizardComponent 的介面。

每當您使用類別處理站登錄建立新元件時，登錄會呼叫元件的 IWizardComponent-SetContainer> 方法，以提供元件存取精靈服務。

WizardPageImpl 範本類別

使用此類別做為自訂頁面的基底類別，例如：

class LocationPage :public WizardPageImpl<IDD_LOCATION_PAGE>

參數是對話方塊範本的資源識別碼。

精靈頁面介面

UDI 精靈使用介面來存取頁面上的不同控制項。 在您的頁面中，您可以使用 GetControlWrapper 函數來擷取控制項包裝函式。 範例如下：

PStaticText pFormat;
GetControlWrapper(View(), IDC_CHECK_PARTITION, CONTROL_STATIC_TEXT, &pFormat);

在這裡， PStaticText 是指向 IStaticText 介面的智慧指標。 當智慧指標超出範圍或您將 pFormat) 等變數位址傳遞至方法時，它們會自動呼叫 COM Release () ( 方法&。

IADHelper 介面

__interfaceIADHelper : IUnknown
{
    HRESULT Init(ILogger *pLogger);
    HRESULT ValidLogon(LPCTSTR userName, LPCTSTR password, LPCTSTR domain);
    HRESULT HasAccess(LPCTSTR username, LPCTSTR password, LPCTSTR domain, LPCTSTR computerName, LPCTSTR accountDomain);
};

HRESULT 初始化 (ILogger *pLogger)

初始化此元件，將其傳遞給記錄器，以便它可以記錄資訊。

HRESULTValidLogon (LPCTSTR 使用者名稱、LPCTSTR 密碼、LPCTSTR 網域)

此方法會驗證一組認證是否有效，如表 10 所示。

表 10. HResultValidLogon

HRESULT HasAccess (LPCTSTR 使用者名稱， LPCTSTR 密碼， LPCTSTR 網域， LPCTSTR 電腦名稱， LPCTSTR accountDomain)

此方法會驗證一組認證是否具有 AD DS 中電腦物件的讀/寫存取權，如表 11 所示。

表 11. HResult HasAccess

IBackgroundTask 介面

__interface IBackgroundTask : IUnknown
{
    HRESULT Init(ITask *pTask, int id, IBackgroundCallback *pCallback);
    void Start(void);
    BOOL Running(void);
    HRESULT Wait(DWORD waitMilliseconds);
    HRESULT Terminate(DWORD exitCode);
    HRESULT GetExitCode(LPDWORD pCode, HRESULT *pHresult);
    HRESULT Close(void);
};

概觀

[ 進度] 頁面會使用此類別在個別執行緒上執行任務。 您也可以在想要在個別執行緒上執行作業時使用此類別。 工作 是支援 ITask 介面的任何類別。

此介面是由 IBackgroundTask.h 介面中定義的 ID_BackgroundTask (“Microsoft.Wizard.BackgroundTask”) 元件所實作。

HRESULT Init (ITask *pTask， int id， IBackgroundCallback *pCallback)

此介面會初始化元件，如表 12 所示。

表 12. HRESULT 初始化

void Start (void)

這個方法會在背景執行緒上啟動工作，並傳回表 13 中所示的元素。

表 13. 傳回背景對話

布林值執行 ()

如果背景工作目前正在執行中，這個方法會傳回 TRUE，如果未執行，則會傳回 FALSE。

HRESULT Wait (DWORD waitMilliseconds)

這個方法會一直等待執行緒停止執行或經過毫秒數。

HRESULT 終止 (DWORD exitCode)

此方法會終止執行中的執行緒 (請參閱表 14 和表 15) 。 此方法傳回之後，此程序可能需要很短的時間才能完成。

表 14. HRESULT 終止結束代碼

表 15. 終止碼

HRESULT GetExitCode (LPDWORD pCode， HRESULT *pHresult)

使用此方法可以取得在背景執行緒上執行工作的結果 (請參閱表 16) 。

表 16. 結果碼

HRESULT 關閉 (無效)

此方法會釋放背景執行緒。 如果執行緒目前正在執行，否則S_OK，它會傳回E_INVALIDARG。

ICheckBox 介面

__interface ICheckBox : IControl
{
    void Check(BOOL check);
    BOOL IsButtonChecked();
};

void 檢查 (BOOL 檢查)

設定核取方塊的核取狀態。 當方法為 TRUE 時，會選取核取方塊;當方法為 FALSE 時，則會清除核取方塊。

BOOL IsButtonChecked ()

此方法會報告核取方塊的目前核取狀態。

IComboBox 介面

__interface IComboBox : IControl
{
    HRESULT Bind([in] IBindableList *pList);
    HRESULT Select(int index);
    int Selected(void);
    void Add([in] LPCTSTR caption);
    HRESULT GetText([out, retval] LPBSTR pText);
    void Clear();
};

概觀

此介面是由 CheckBoxWrapper 元件實作。 您可以使用類型為 CONTROL_COMBO_BOX 的 GetControlWrapper 協助程式函式來擷取此元件的執行個體。

HRESULT 繫結 ([in] IBindableList *pList)

當您有實作 IBindableList 介面的資料來源時，請使用此方法。 清單方塊會使用此清單中的標題初始化內容。

HRESULT Select (int index)

在索引的下拉式方塊中選取項目。

int 已選取 (無效)

此方法會傳回所選項目的索引，如果未選取任何項目，則會傳回 -1 。

void Add ([in] LPCTSTR 標題)

手動將項目新增至下拉式方塊。

HRESULT GetText ([out， retval] LPBSTR pText)

擷取下拉式方塊中目前所選取項目的字串。

void 清除 ()

移除下拉式方塊中的所有項目。

IControl 介面

__interface IControl : IUnknown
{
    HRESULT SetEnable(BOOL enable);
    BOOL IsEnabled(void);
    HRESULT SetVisible(BOOL visible);
};

概觀

此介面是由 ControlWrapper 元件實作。 您可以使用類型為 CONTROL_GENERIC 的 GetControlWrapper 協助程式函式來擷取此元件的執行個體。

HRESULT SetEnable (BOOL 啟用)

啟用或停用控制項。

BOOL IsEnabled (void)

如果控制項已啟用，則傳回 TRUE，如果未啟用，則傳回 FALSE。

HRESULT SetVisible (BOOL 可見)

顯示或隱藏控制項。

ICpuInfo 介面

__interface ICpuInfo : IUnknown
{
    BOOL Is64Bit(void);
};

概觀

您可以建立新的 ID_CpuInfo 元件來取得此介面。 單一方法會回報 CPU 是 32 位元或 64 位元。 請注意，如果您的 64 位元電腦上有 32 位元作業系統，這個方法會傳回 TRUE，因為它只會回報 CPU 的寬度 (而非作業系統) 。

IDirectory 介面

__interface IDirectory : IUnknown
{
    BOOL FileExists(LPCWSTR name);
    BOOL FindFirst([in] LPCWSTR name);
    HRESULT FoundName([out, retval] LPBSTR name);
    DWORD FoundAttributes(void);
    BOOL FindNext(void);
    void FinishFind(void);
};

概觀

您使用 ID_Directory 建立的目錄元件，提供使用檔案系統中目錄的外觀。

BOOL FileExists (LPCWSTR 名稱)

如果您提供的名稱檔案存在，這個方法會傳回 TRUE。

BOOL FindFirst ([in] LPCWSTR 名稱)

此方法會尋找您提供的名稱的第一個相符項目。 它支援萬用字元，並傳回檔案和目錄名稱。 如果找到相符項目，則此方法傳回 TRUE，否則傳回 FALSE。

HRESULT FoundName ([out， retval] LPBSTR 名稱)

這個方法會擷取呼叫 FindFirst 或 FindNext 找到的檔案名稱。

DWORD FoundAttributes (void)

這個方法會傳回最近找到的檔案或目錄的屬性。 您可以使用如下所示的程式碼來測試是否為目錄：

pDirectory->FoundAttributes() & FILE_ATTRIBUTE_DIRECTORY

BOOL FindNext (void)

尋找下一個。 如果找到另一個相符項目，則此方法傳回 TRUE，否則傳回 FALSE。

void FinishFind (void)

這個方法會釋放用於 [尋找] 作業的資源。

IDomainJoinValidator 介面

__interface IDomainJoinValidator : IUnknown
{
    HRESULT Init(ILogger *pLogger, IWizardPageContainer *pContainer, IStaticText *pUsername, IStaticText *pPassword, IStaticText *pComputerName);
    HRESULT IsUsernameValid(LPCWSTR domainName);
    BOOL CanModifyComputerAdEntry(LPCWSTR domainName);
};

概觀

您可以使用 CreateInstance 範本函數的ID_DomainJoinValidator值來取得此介面的執行個體。

HRESULT Init (ILogger *pLogger， IWizardPageContainer *pContainer， IStaticText *pUsername， IStaticText *pPassword， IStaticText *pComputerName)

初始化執行個體，如表 17 所示。

表 17. HRESULT 初始化 - 執行個體初始化

HRESULT IsUsernameValid (LPCWSTR domainName)

此方法使用 IADHelper-ValidLogon> 方法來執行這項工作。 如需詳細資訊，請參閱該方法。

BOOL CanModifyComputerAdEntry (LPCWSTR domainName)

確認使用者是否有修改電腦項目的權限。 大部分工作是由 IADHelper-HasAccess> 完成。 如果這個方法傳回 FALSE，請檢查記錄檔以取得詳細資料。

IDriveList 介面

__interface IDriveList : IUnknown
{
    HRESULT Init(IWmiRepository *pWmi);
    HRESULT SetWhereClause(LPCTSTR whereClause);
    HRESULT SetMinimumDriveSize(__int64 size);
    HRESULT Update(void);
    HRESULT AddProperty(ENUM_DISK_QUERY_SECTION section, LPCTSTR propName, LPCTSTR propNameReturned);

    size_t Count(void);
    HRESULT GetProperty(size_t index, LPCTSTR propName,  LPVARIANT value);
    HRESULT GetCaption(size_t index,  LPBSTR pCaption);
}

HRESULT Init (IWmiRepository *pWmi)

在呼叫任何其他元件之前，先呼叫此方法。 呼叫此方法之前，您必須先建立新的 WmiRepository 。

HRESULT SetWhereClause (LPCTSTR whereClause)

這個方法可讓您新增在查詢中顯示為 “Where ”子句的文字。 例如，下列行只會傳回 USB 磁碟機：

pDrives->SetWhereClause(L"WHERE InterfaceType='USB'");

HRESULT SetMinimumDriveSize (__int64 size)

設定將從查詢傳回的磁碟機最小化磁碟機大小 （以位元組為單位）。

HRESULT 更新 (無效)

執行查詢。 呼叫這個方法後可用的磁碟機清單會依磁碟機代號排序。

HRESULT AddProperty (ENUM_DISK_QUERY_SECTION 區段， LPCTSTR propName， LPCTSTR propNameReturned)

這個方法會新增您想要在查詢結果中提供的其他屬性名稱。 在呼叫 Update 之前，請先呼叫這個方法。 表 18 顯示了三個有用的屬性。

表 18. HRESULT AddProperty：有用的屬性

size_t 無效) (計數

查詢傳回的記錄數目。 呼叫此方法之前，請先呼叫 Update 。

HRESULT GetProperty (size_t 索引、LPCTSTR propName、LPVARIANT 值)

這個方法會從查詢結果中擷取屬性的值，如表 19 所示。

表 19. HRESULT GetProperty

HRESULT GetCaption (size_t index， LPBSTR pCaption)

這個方法會擷取與 Caption 屬性相同的記錄標題。

IImageList 介面

__interface IImageList
{
    HRESULT CreateImageList(int width, int height, UINT flags);
    HImageList GetImageList(void);
    int AddImage(HInstance hInstance, int resourceId);
};

概觀

此介面是由 ImageList 元件實作。 您可以從 IListView 介面擷取此元件的執行個體。

HRESULT CreateImageList (int 寬度、int 高度、UINT 旗標)

建立由此元件管理的新影像清單。 請只呼叫這個方法一次。

HImageList GetImageList (void)

這個方法會傳回影像清單的控點，以防您需要對影像清單執行其他作業。

int AddImage (HInstance hInstance， int resourceId)

從資源將新影像新增至影像清單，如表 20 所示。

表 20. HRESULT IImageList 介面

IListView 介面

__interface IListView : IControl
{
    int AddItem([in] LPCTSTR text);
    int AddColumn(int width, [in] LPCTSTR text);
    HRESULT SetSubItem(int index, int column, [in] LPCTSTR text);
    int GetWidth(void);
    void SetExtendedStyle(DWORD style);
    int GetSelectedItem(void);
    HRESULT SelectItem(int index);
    BOOL IsItemChecked(int index);
    int GetItemCount(void);
    HRESULT CreateImageList(int width, int height, UINT flags);
    int AddImage(HINSTANCE hInstance, int resourceId);
    HRESULT SetImage(int index, int imageIndex);
    HRESULT Clear(void);
};

概觀

此介面是由 ControlWrapper 元件實作。 您可以使用類型為 CONTROL_LIST_VIEW 的 GetControlWrapper 協助程式函式來擷取此元件的執行個體。

int AddItem ([in] LPCTSTR 文字)

在清單方塊中新增資料列。 此方法會傳回剛新增之項目的索引。

int AddColumn (int width， [in] LPCTSTR text)

新增資料欄位至清單檢視。

HRESULT SetSubItem (int index， int column， [in] LPCTSTR text)

將文字設定在清單方塊第一欄以外的欄中，如表 21 所示。

表 21. HRESULT SetSubItem

int GetWidth (void)

這個方法會傳回整個文字方塊的寬度。

void SetExtendedStyle (DWORD 樣式)

這個方法可讓您在清單方塊上設定延伸樣式，例如：

m_pList->SetExtendedStyle(LVS_EX_FULLROWSELECT);

int GetSelectedItem (void)

這個方法會傳回目前選取之清單檢視項目的索引。

HRESULT SelectItem (int index)

將清單中選取的項目設定為此索引。

(int index) 的 BOOL IsItemChecked

如果已選取清單中的項目，這個方法會傳回 TRUE。 此方法需要您呼叫 SetExtendedStyle 來設定核取方塊樣式。

int GetItemCount (void)

這個方法會傳回清單檢視中的項目數。

HRESULT CreateImageList (int 寬度、int 高度、UINT 旗標)

建立新的影像清單，並將它附加到清單檢視。

int AddImage (HINSTANCE hInstance， int resourceId)

將影像新增至清單檢視的影像清單。 您必須先呼叫 CreateImageList。

HRESULT SetImage (int index， int imageIndex)

設定要在左側顯示的特定清單檢視項目影像。

HRESULT 清除 (無效)

移除清單檢視中的所有項目。

IProgressBar 介面

__interface IProgressBar : IControl
{
    HRESULT SetPercentage(int position);
    int GetPercentage(void);
};

概觀

此介面是由 ProgressBarWrapper 元件實作。 您可以使用類型為 CONTROL_PROGRESS_BAR 的 GetControlWrapper 協助程式函式來擷取此元件的執行個體。

HRESULT SetPercentage (int position)

使用介於 0 到 100 之間的數字來設定進度列的位置。 根據預設，新的 Win32® 進度列的範圍上限為 100。

int GetPercentage (void)

這個方法會傳回進度列的目前位置。

IRadioButton 介面

__interface IRadioButton : IControl
{
public:
    void SetGroup(int firstId, int lastId);
    void CheckRadio(int id);
    BOOL IsButtonChecked(int id);
    void EnableRadio(int id, BOOL enable);
};

概觀

此介面是由 RadioButtonWrapper 元件實作。 您可以使用類型為 CONTROL_RADIO_BUTTON 的 GetControlWrapper 協助程式函式來擷取此元件的執行個體。

void SetGroup (int firstId， int lastId)

為包裝函式提供應視為群組的選項按鈕範圍。 呼叫 CheckRadio 之前，請先呼叫此方法。

void CheckRadio (int id)

將特定選項按鈕設定為所選選項按鈕群組中的單一按鈕。 呼叫此方法之前，請先呼叫 SetGroup 。

BOOL IsButtonChecked (int id)

如果目前已選取選項按鈕，此方法會傳回 TRUE，否則會傳回 FALSE。

void EnableRadio (int id， BOOL enable)

這個方法會啟用或停用選項按鈕。

IStaticText 介面

__interface IStaticText : IControl
{
    HRESULT SetText([in] LPCTSTR pText);
    HRESULT GetText([out, retval] LPBSTR pText);
};

概觀

此介面是由 StaticTextWrapper 元件實作。 您可以使用類型為 CONTROL_STATIC_TEXT 的 GetControlWrapper 協助程式函式來擷取此元件的執行個體。

HRESULT SetText ([in] LPCTSTR pText)

設定控制項的文字。

HRESULT GetText ([out， retval] LPBSTR pText)

這個方法會傳回控制項文字的目前值。

ITask 介面

__interface IControl : IUnknown
{
    HRESULT Init(IStringProperties *pProperties, ISettingsProperties *pTaskSettings);
    HRESULT Execute(LPDWORD pReturnCode);
};

如果您想要元件在預檢頁面中做為工作，或想要使用 BackgroundTask 元件在背景執行緒上執行工作，請實作此介面。

以下是實作 ITask 介面的元件：

• ID_ShellExecuteTask， L“Microsoft.Wizard.ShellExecuteTask”

• ID_CopyFilesTask， L“Microsoft.Wizard.CopyFilesTask”

• ID_ACPowerTask， L“Microsoft.OSDRefresh.ACPowerTask”

• ID_WiredNetworkTask, L"Microsoft.SharedPages.WiredNetworkTask"

初始化

HRESULT Init(IStringProperties *pProperties, ISettingsProperties *pTaskSettings)

如果您正在為預檢頁面撰寫工作，請呼叫這個方法來初始化您的工作。 .config 檔案包含的 XML 格式可能如下：

<Task DisplayName="Check Windows Scripting Host" Type="Microsoft.Wizard.ShellExecuteTask">
  <Setter Property="filename">%windir%\system32\cscript.exe</Setter>
  <Setter Property="parameters">Preflight\OSDCheckWSH.vbs</Setter>
  <Setter Property="BitmapFilename">images\WinScriptHost.bmp</Setter>
  <ExitCodes>
    <ExitCode State="Success" Type="0" Value="0" Text="" />
    <ExitCode State="Error" Type="-1" Value="*" Text="Windows Scripting Host not installed." />
  </ExitCodes>
</Task>

pProperties 參數提供三個 setter 值的存取權，而 pTaskSettings 參數提供 Task 元素和子系的存取權。 大部分的工作只需要從 pProperties 參數讀取資料。

執行

HRESULT Execute(LPDWORD pReturnCode)

您可以在這裡撰寫執行工作的程式碼。 如果沒有錯誤，這個方法應該會傳回 S_OK ，如果工作執行時發生錯誤，這個方法可以傳回另一個 HRESULT 。 如果您使用預檢頁面，則此方法傳回的 S_OK 以外的值將與 ExitCodes> 區段中的<錯誤>元素進行<比對。

pReturnCode 參數必須更新為報告工作狀態的數字。 這些值由 ExitCode> 元素的<正式發行前檢查頁面相符。

ITreeView 介面

__interface ITreeView : IControl
{
    void EnableCheckboxes(void);
    HRESULT CreateImageList(int width, int height, UINT flags);
    int AddImage(HINSTANCE hInstance, int resourceId);

    HTREEITEM AddItem(LPCTSTR text, HTREEITEM hParent = NULL);
    void SetImage(HTREEITEM item, int image, int expandImage);

    void Clear(void);
    BOOL SetFirstVisible(HTREEITEM item);
    BOOL SelectItem(HTREEITEM item);
    void CheckItem(HTREEITEM item, UINT checkState);
    HTREEITEM SelectedItem(void);
    int SetItemHeight(SHORT height);
    HRESULT EnableItem(HTREEITEM item, BOOL enable);
    void Expand(HTREEITEM hItem, BOOL expand);

    HTREEITEM GetChild(HTREEITEM hParent);
    HTREEITEM GetParent(HTREEITEM hNode);
    HTREEITEM GetNextItem(HTREEITEM hPrevious);

    UINT IsChecked(HTREEITEM item);
    BOOL IsEnabled(HTREEITEM item);

    INT_PTR CommonControlEvent(WORD controlId, void* pInfo, BOOL *pCancel);
    HRESULT SetEventHandler(ITreeViewEvent *pEventHandler);

    void SetSelectedBackColor(COLORREF color);
};

概觀

此介面是由 TreeViewWrapper 元件實作。 您可以使用類型為 CONTROL_TREE_VIEW 的 GetControlWrapper 協助程式函式來擷取此元件的執行個體。

void EnableCheckboxes (void)

這個方法會透過設定 TVS_CHECKBOXES 樣式，開啟樹狀檢視控制項中的核取方塊。

HRESULT CreateImageList (int 寬度、int 高度、UINT 旗標)

新增影像清單至樹狀檢視控制項。 flags 參數會在呼叫 ImageList_Create Win32 函數時傳遞。

int AddImage (HINSTANCE hInstance， int resourceId)

在模組中使用執行個體控制碼 hInstance (resourceId) ，將影像新增至影像清單。

HTREEITEM AddItem (LPCTSTR 文字， HTREEITEM hParent = NULL)

新增節點至樹狀檢視。 如果 hParent 為 NULL，則會在最上層新增節點。 否則，請提供父項目的控點，以插入您要新增項目的位置。 這個方法會傳回新項目的控點。

void SetImage (HTREEITEM item， int image， int expandImage)

設定用於樹狀檢視項目的影像。 您可以設定標準和展開影像。

void 清除 (無效)

移除樹狀檢視中的所有項目。

BOOL SetFirstVisible (HTREEITEM 項目)

確定樹狀檢視項目可見。 樹狀檢視會視需要捲動，以顯示此項目。

BOOL SelectItem (HTREEITEM 項目)

將目前選取的項目設定為您提供的項目。 您可以在此之後呼叫 SetFirstVisible ，以確保新選取的項目可顯示。

void CheckItem (HTREEITEM 項目， UINT checkState)

此方法基本上會設定樹狀檢視中核取方塊所顯示的影像。 這些影像位於樹狀檢視管理的個別 ImageList 控制項中。 預設情況下，此影像清單包含三個影像，如表 22 所示。

表 22.void CheckItem 影像清單預設值

HTREEITEM SelectedItem (void)

這個方法會傳回目前選取的樹狀檢視項目控點。

int SetItemHeight (SHORT 高度)

這個方法會以像素為單位設定樹狀檢視控制項中所有項目的高度。 它會以像素為單位返回先前的高度。

HRESULT EnableItem (HTREEITEM 項目，BOOL 啟用)

這個方法會啟用或停用樹狀結構中的單一項目。 停用包含子女的項目並不會停用該子女。

void 展開 (HTREEITEM hItem， BOOL 展開)

此方法會展開或摺疊樹狀結構中的節點。

HTREEITEM GetChild (HTREEITEM hParent)

此方法會傳回樹狀檢視項目的第一個子系，如果沒有子系，則會傳回 NULL。

HTREEITEM GetParent (HTREEITEM hNode)

此方法會在樹狀檢視中傳回節點的父項控點，如果節點位於頂層，則會傳回 NULL。

HTREEITEM GetNextItem (HTREEITEM hPrevious)

您可以使用 GetChild 傳回的控點來呼叫此方法，以逐一查看節點的所有子系。 這個方法會傳回樹狀結構中共用相同父系的下一個同層級。

UINT IsChecked (HTREEITEM 項目)

如果未選取樹狀檢視節點，此方法會返回 0 ，如果已選取，則會返回 1 。

BOOL IsEnabled (HTREEITEM 項目)

如果樹狀檢視節點已啟用，此方法會傳回 TRUE，否則傳回 FALSE。

INT_PTR CommonControlEvent (WORD controlId， void* pInfo， BOOL *pCancel)

此方法僅供內部使用。

HRESULT SetEventHandler (ITreeViewEvent *pEventHandler)

如果您想要在選取的項目變更或使用者變更樹狀檢視項目的檢查狀態時收到通知，請呼叫此方法。 您必須在元件中實作 ITreeViewEvent 才能接收這些回呼。

void SetSelectedBackColor (COLORREF 色彩)

設定所選項目的背景色彩。

IWmiIteration 介面

__interface IWmiIterator : IUnknown
{
    HRESULT Next(void);
    HRESULT GetProperty(LPCTSTR propertyName, [out] LPVARIANT pValue);
};

概觀

在使用 WMI 呼叫時，通常會使用此介面與 IWmiRepository。 IWmiIteration 介面可讓您逐一查看查詢傳回的值。

HRESULT 下一個 (無效)

移至查詢結果中的下一個項目，如表 23 所示。

表 23. HRESULT 下一個 (無效) 查詢會傳回

HRESULT GetProperty (LPCTSTR propertyName， [out] LPVARIANT pValue)

此方法從目前結果記錄中擷取屬性的值，如表 24 和表 25 所示。

表 24. HRESULT GetProperty

表 25. HRESULT GetProperty 結果

IWmiRepository 介面

__interface IWmiRepository : IUnknown
{
    HRESULT SetNamespace(LPCWSTR namespaceName);
    HRESULT ExecQuery(LPCWSTR query, [out] IWmiIterator **ppIterator);
};

概觀

此介面是由 WmiRepository 元件 (ID_WmiRepository) 所實作。

HRESULT SetNamespace (LPCWSTR namespaceName)

這個方法會設定將用於查詢的 WMI 命名空間。 呼叫 ExecQuery 之前，請先呼叫此方法。 如果不呼叫這個方法，命名空間將會是 root\cimv2。 這個方法一律會傳回 S_OK。

HRESULT ExecQuery (LPCWSTR 查詢， [out] IWmiIterator **ppIterator)

對 WMI 命名空間執行查詢，並呼叫 SetNamespace，如表 26 和表 27 所示。

表 26. HRESULT ExecQuery

表 27. HRESULT 查詢結果

IFormController 介面

__interface IFormController : IUnknown
{
    Init(IWizardPageView *pView, IWizardPageContainer *pContainer);
    SetPageInfo(ISettingsProperties *pPageInfo);

    Validate(void);

    AddToGroup(int groupControlId, int controlId);
    UpdateCheckGroup(int groupControlId);
    AddValidator(int controlId, IValidator *pValidator, IControl *pCOntrol = 0);

    AddValidator(int controlId, LPCWSTR validatorId, LPCWSTR message, IValidator **ppValidator = nullptr);
    DisableValidation(int controlId, BOOL disable);

    AddField(LPCWSTR fieldName, int controlId, BOOL suppressLog, DialogControlTypes type);
    AddRadioGroup(LPCWSTR groupName, int radioControlId);
    EnableRadioGroup(LPCWSTR groupName, BOOL enable);
    InitFields(IFieldCallback *pFieldCallback = nullptr);
    SaveFields(IFieldCallback *pFieldCallback = nullptr);
    BOOL IsFieldDisabled(int controlId);

    InitSection(LPCWSTR key, LPCWSTR sectionCaption);
    AddSummaryItem(LPCWSTR first, LPCWSTR second);
    SuppressLogValue(LPCWSTR tsVariableName);
    SaveText(int controlId, LPCWSTR tsVariableName, LPCWSTR summaryCaption);
    LoadText(int controlId, LPCWSTR tsVariableName);

    void ControlEvent(WORD eventId, WORD controlId);
    BOOL IsValid(void);
 };

概觀

UDI 精靈中的每一個頁面都有自己的表單控制器，可實作此介面。 您可以使用此控制器將 .config XML 檔案中的欄位資料連線到頁面上的控制項。 然後，表單控制器會為您處理許多詳細資料。

設定表單

一般而言，請在頁面的 OnWindowCreated 方法中設定表單控制器。 這樣做通常涉及調用表 28 中所示的方法。

表 28. OnWindowCreated 方法

正在處理表單事件

將下列呼叫新增至 OnControlEvent 方法：

Form()->ControlEvent(eventId, controlId);

此呼叫會將事件傳遞至表單控制器，以便其處理表單相關事件。

儲存表單資料

在 OnNextSelected 方法中，呼叫表 29 中所示的表單方法。

表 29. OnNextSelected 方法

初始化

HRESULT Init(IWizardPageView *pView, IWizardPageContainer *pContainer)

您通常會在頁面的 OnWindowCreated 方法開頭附近呼叫此方法。 命令看起來應該像這樣：

Form()->Init(View(), Container());

SetPageInfo

HRESULT SetPageInfo(ISettingsProperties *pPageInfo)

這個方法是在內部呼叫的，您不應該自己呼叫它。 它會將頁面的 XML 提供給表單控制器。

驗證

HRESULT Validate(void)

此方法會執行所有附加至控制項的驗證工具。 如果驗證器未通過，表單控制器會顯示警告訊息並停用 「下一步 」按鈕，然後停止處理驗證器。 一般而言，您只需要在 OnWindowCreated 方法結尾呼叫此方法;它一律會傳回 S_OK。

AddToGroup

AddToGroup(int groupControlId, int controlId)

此方法會將控制項新增為核取方塊或單選按鈕的「子系」，如表 30 所示。 若未選取父系控制項，則所有這類子系控制項都會遭停用。 方法永遠會傳回 S_OK。

表 30. AddToGroup

UpdateCheckGroup

HRESULT UpdateCheckGroup(int groupControlId)

這個方法會根據父系控制項的狀態，更新群組子系控制項的啟用或停用狀態。 一般而言，您不需要自行呼叫這個方法，因為表單控制器會為您呼叫它。

AddValidator

HRESULT AddValidator(int controlId, IValidator *pValidator, IControl *pControl = 0)

只有在您有想要在程式碼中建立驗證程式，而不是使用 XML 建立驗證工具時，才呼叫此方法。 這個方法一律會傳回 S_OK。

AddValidator

HRESULT AddValidator(int controlId, LPCWSTR validatorId, LPCWSTR message, IValidator **ppValidator = nullptr)

只有在您有想要在程式碼中建立驗證程式，而不是使用 XML 建立驗證工具時，才呼叫此方法。

DisableValidation

HRESULT DisableValidation(int controlId, BOOL disable)

呼叫這個方法可明確停用控制項的驗證程式，或還原正常驗證，如表 31 所示。 例如，當您具有未包含在表單驗證中的控制項啟用/停用規則，且需要停用控制項的驗證時，此方法便十分有用。 換句話說，您通常不會呼叫這個方法。 這個方法一律會傳回 S_OK。

表 31. HRESULT DisableValidation

AddField

HRESULT AddField(LPCWSTR fieldName, int controlId, BOOL suppressLog, DialogControlTypes type)

在 .config XML 檔案的 Field 元素名稱與頁面對話方塊中的控制項識別碼之間新增控制項對應，如表 32 所示。 您必須在呼叫 InitFields 之前呼叫此方法，因為 InitFields 會使用此資訊。 這個方法一律會傳回 S_OK。

表 32. HRESULT AddField

AddRadioGroup

HRESULT AddRadioGroup(LPCWSTR groupName, int radioControlId)

這個方法會將控制項新增至具名的選項按鈕群組，如表 33 所示。 您必須在 InitFields 方法之前呼叫此方法，因為該方法會使用 RadioGroup 元素上的屬性來控制群組中所有選項按鈕控制項的設定。 例如，可以鎖定無線群組，以便停用所有選項按鈕，但只根據選取的選項按鈕來啟用或停用子控制項。 這個方法一律會傳回 S_OK。

表 33. HRESULT AddRadioGroup

EnableRadioGroup

HRESULT EnableRadioGroup(LPCWSTR groupName, BOOL enable)

此方法可讓您啟用或停用整個選項按鈕群組。 停用無線群組會停用群組中的所有選項按鈕控制項，以及使用 AddToGroup 新增之選項按鈕的任何子系。 見表 34 和表 35。

表 34. EnableRadioGroup

表 35. HRESULT EnableRadioGroup

InitFields

HRESULT InitFields(IFieldCallback *pFieldCallback = nullptr)

在呼叫這個方法之前，請針對 XML 可以控制的每個欄位呼叫 AddField 。 這個方法一律會傳回 S_OK。

pFieldCallback 參數為選用。 如果您提供，表單控制器會針對非CONTROL_STATIC_TEXT或非CONTROL_CHECK_BOX控制項呼叫 SetFieldDefault。 此行為可讓您從 XML 擷取預設值，然後自行在控制項中設定。

SaveFields

HRESULT SaveFields(IFieldCallback *pFieldCallback = nullptr)

這個方法會將欄位值儲存至工作順序變數及將顯示在 [摘要 ] 頁面上的摘要資料。 在 pFieldCallback 中提供指標，可讓您處理不支援 CONTROL_STATIC_TEXT之控制項的儲存值。

IsFieldDisabled

BOOL IsFieldDisabled(int controlId)

此方法可讓您判斷 XML 中是否已停用欄位。

InitSection

HRESULT InitSection(LPCWSTR key, LPCWSTR sectionCaption)

這個方法會初始化將顯示在 [摘要 ] 頁面上的摘要資料，如表 36 所示。 在呼叫 SaveFields 之前，請先在 OnNextSelected 方法中呼叫此方法。 這個方法一律會傳回 S_OK。

表 36. HRESULT InitSection

AddSummaryItem

HRESULT AddSummaryItem(LPCWSTR first, LPCWSTR second)

這個方法可讓您將摘要項目新增至 [ 摘要 ] 頁面，在使用 XML 設定的項目上方和項目之外。 見表 37。

表 37. HRESULT AddSummaryItem

SuppressLogValue

HRESULT SuppressLogValue(LPCWSTR tsVariableName)

針對您不希望將值寫入記錄檔的工作順序變數呼叫此方法。 針對儲存密碼、PIN 或使用者可能輸入的其他敏感性值的工作順序變數呼叫此方法。

儲存文字

HRESULT SaveText(int controlId, LPCWSTR tsVariableName, LPCWSTR summaryCaption)

這個方法會將文字控制項的值儲存至工作順序變數和摘要區段。 一般而言，您不需要自行呼叫這個方法，因為表單控制器會針對所有欄位執行此動作。 見表 38。

表 38. HRESULT 儲存文字

LoadText

HRESULT LoadText(int controlId, LPCWSTR tsVariableName)

這個方法會讀取工作順序變數的值，並將文字方塊設定為此值。

ControlEvent

void ControlEvent(WORD eventId, WORD controlId)

在 OnControlEvent 方法上呼叫這個方法，以確保表單控制器可以處理控制項事件，它必須這麼做才能正常運作。 您傳遞給這個方法的值與傳遞給 OnControlEvent 方法的值相同。

IsValid

BOOL IsValid(void)

這個方法會傳回最近一次表單驗證的狀態。 如果任何控制項驗證程式報告錯誤，這個方法會傳回 FALSE。 換句話說，只有在頁面上的所有控制項都有效時，才會傳回 TRUE。

IValidator 介面

__interface IValidator : IUnknown
{
    HRESULT Init(IControl *pControl, LPCTSTR message);
    HRESULT Init(IControl *pControl, IWizardPageContainer *pContainer, IStringProperties *pProperties);
    BOOL, IsValid(LPBSTR pMessage);
    HRESULT SetProperty(int propertyId, LPVARIANT pValue);
    HRESULT SetProperty(int propertyId, IUnknown *pUnknown);
    HRESULT SetProperty)(int propertyId, LPCTSTR pValue);
};

概觀

驗證程式 是可以驗證頁面上單一控制項的元件。 實作驗證程式最簡單的方法是讓它成為 BaseValidator 類別的子類別，該類別在 BaseValidator.h 頭檔中定義。

HRESULT Init (IControl *pControl， LPCTSTR 訊息)

如果您在程式碼中建立驗證器，則可以呼叫此方法來初始化驗證器。 見表 39。

表 39. HRESULT 初始化

HRESULT Init (IControl *pControl， IWizardPageContainer *pContainer， IStringProperties *pProperties)

表單控制器會呼叫這個方法，來初始化它根據頁面的 XML 所建立的驗證程式。 見表 40。

表 40. HRESULT 初始化方法

BOOL， IsValid (LPBSTR pMessage)

如果控制項有效，這個方法會傳回 TRUE，如果控制項無效，則會傳回 FALSE。 傳回時， pMessage 應該填入包含控制項無效時要顯示的訊息的新 BSTR 。

HRESULT SetProperty (int propertyId， LPVARIANT pValue)

如果您需要 XML 中未提供的額外值，您可以實作這個方法。

HRESULT SetProperty (int propertyId， IUnknown *pUnknown)

如果您需要 XML 中未提供的額外值，您可以實作這個方法。

HRESULT SetProperty) (int propertyId， LPCTSTR pValue)

如果您需要 XML 中未提供的額外值，您可以實作這個方法。

IRegEx 介面

__interface IRegEx : IUnknown
{
    BOOL MatchesRegex(LPCTSTR input, LPCTSTR regex);
    HRESULT GetMatch(size_t index, LPBSTR pValue);
};

這個方法由 ID_Regex 元件 (IRegex.h) 實作，並且支援規則運算式處理。

BOOL MatchesRegex (LPCTSTR 輸入， LPCTSTR Regex)

這個方法會針對輸入文字執行規則運算式。 它使用 C++ 標準程式庫的 regex_match 函數來執行實際工作。 如果有相符項目，則方法會傳回 TRUE，否則傳回 FALSE。

HRESULT GetMatch (size_t 索引， LPBSTR pValue)

此方法可讓您從最近的 MatchesRegex 呼叫中擷取相符項目。 請注意，這個方法中沒有錯誤處理，而且會傳回 S_OK 或擲回例外狀況。

ISummaryInfo 介面

__interface ISummaryInfo : IUnknown
{
    size_t Count(void);
    HRESULT Clear(void);
    HRESULT AddInfo(LPCTSTR pFirst, LPCTSTR pSecond);
    HRESULT GetInfo(size_t index, LPBSTR pFirst, LPBSTR pSecond);
    HRESULT GetCaption(LPBSTR pCaption);
    HRESULT SetCaption(LPCTSTR caption);
};

您不應該需要直接使用此介面。 請改用 IFormController。

ISummaryBag

__interface ISummaryBag : IUnknown
{
    size_t Count(void);
    HRESULT GetInfoByIndex(size_t index, [out] ISummaryInfo **ppSummary);
    HRESULT GetInfoByKey(LPCTSTR key, [out] ISummaryInfo **ppSummary);
};

您不應該需要直接使用此介面。 請改用 IFormController。

ITSVariableBag 介面

__interface ITSVariableBag : IUnknown
{
    void GetValue([in] LPCTSTR variableName, [out] LPBSTR pValue);
    void SetValue([in] LPCTSTR variableName, [in] LPCTSTR pValue);
    void Clear(void);
    HRESULT Remove([in] LPCTSTR variableName);
    HRESULT SuppressLogValue([in] LPCTSTR variableName);
    void Save(void);
};

此介面可讓您存取工作順序變數。 您可以使用頁面的 TSVariables () 方法存取此介面。

void GetValue ([in] LPCTSTR variableName， [out] LPBSTR pValue)

此方法會讀取工作順序變數的值。

void SetValue ([in] LPCTSTR variableName， [in] LPCTSTR pValue)

此方法會設定工作順序變數的值。 此值會儲存在記憶體中。 一旦您在 UDI 精靈中選取 [完成 ]，就會寫入工作順序值。

void 清除 (無效)

此方法會移除記憶體中儲存的所有工作順序值。

HRESULT Remove ([in] LPCTSTR variableName)

這個方法會從記憶體中移除特定的工作順序值。 下次您使用相同的工作順序名稱呼叫 GetValue 時，方法會嘗試從工作順序中擷取它。

HRESULT SuppressLogValue ([in] LPCTSTR variableName)

每當寫入工作順序變數時，例如當您在 UDI 精靈中選取 [完成 ] 時，名稱和值都會寫入記錄檔。 呼叫此方法以隱藏針對特定工作順序變數記錄敏感性值，例如密碼或 PIN。

void 儲存 (無效)

此方法會儲存所有已透過呼叫 SetValue 而設的任務順序值。

ITSVariableRepository 介面

__interface ITSVariableRepository : IUnknown
{
    void GetValue([in] LPCTSTR variableName, BOOL logValue, [out] LPBSTR pValue);
    void SetValue([in] LPCTSTR variableName, BOOL logValue, [in] LPCTSTR value);
};

此介面供 TSVariableBag 在內部使用，以讀取和寫入工作順序變數。

IWizardFinish 介面

__interface IWizardFinish : IUnknown
{
    HRESULT Canceled(void);
    HRESULT Finished(void);
};

在進階案例中，當您在 UDI 精靈中選取 [完成 ] 或 [ 取消 ] 時，此介面非常有用。 UDI 精靈包含 [ 完成 ] 工作，當您選取 [完成] 時，會儲存工作順序變數。 如果您取消精靈，工作只會將 OSDSetupWizCancelled 工作順序變數設定為 TRUE，而不會儲存任何其他工作順序變數的變更。

如果您建立自己的完成元件，則需要使用如下所示的程式碼來註冊它：

Register<MyFinishTaskFactory>(ID_MyFinishTask, pRegistry);

PWizardFinish pFinish;
CreateInstance(pRegistry, ID_MyFinishTask, &pFinish);

PWizardFinishService pService;
GetService<IWizardFinishService>(pRegistry, &pService);

pService->Register(pFinish);

IBindableList 介面

__interface IBindableList : IUnknown
{
    size_t Count(void);
    HRESULT GetCaption(size_t index, LPBSTR pCaption);
};

如果您有資料來源元件，且要透過呼叫其 Bind 方法繫結到下拉式方塊，請實作此介面。

size_t 無效) (計數

這個方法會傳回清單中的項目數。

HRESULT GetCaption (size_t index， LPBSTR pCaption)

這個方法會傳回特定索引處的項目標題。

IDataNodes 介面

__interface IDataNodes : IUnknown
{
    size_t Count();
    HRESULT SetCaptionProperty(LPCTSTR captionProperty);
    HRESULT GetProperty(size_t index, LPCTSTR propertyName, [out] LPBSTR propertyValue);
    HRESULT GetNode(size_t index, [out] ISettingsProperties **ppNode);
};

此介面可讓您存取可儲存在頁面中的階層式資料。 您可以透過 ISettingsProperties 介面上的方法取得此介面，您的頁面可透過 Settings 方法取得該介面。

頁面 XML 中的資料看起來可能像這樣

      <Data Name="Network">
        <DataItem>
          <Setter Property="DisplayName">Public</Setter>
          <Setter Property="Share">\\servername\Share</Setter>
        </DataItem>
        <DataItem>
          <Setter Property="DisplayName">Dev Team</Setter>
          <Setter Property="Share">\\servername\DevShare</Setter>
        </DataItem>
      </Data>

呼叫 設定 () -GetDataNode> (L“Network”，&pData) 提供具有兩個資料項目的 IDataNodes 實例 (每個項目又有兩個屬性) 。

size_t計數 ()

這個方法會傳回 DataItem 元素的數目。

HRESULT SetCaptionProperty (LPCTSTR captionProperty)

支援此介面的元件也支援 IBindableList，這可讓您輕鬆地使用頁面 XML 中的資料填入下拉式方塊。 這個方法會控制每個 DataItem 元素中的 setter) (將用於此繫結的屬性。 例如，您可以使用 DisplayName 呼叫這個方法，它就會使用該 setter 屬性進行資料繫結。 下拉式方塊接著會包含 [公用 ] 和 [開發人員團隊 ] 作為項目。

HRESULT GetProperty (size_t index， LPCTSTR propertyName， [out] LPBSTR propertyValue)

此方法會從其中一個 DataItem 元素取得屬性。 參見表 41 和表 42。

表 41. DataItem GetProperty

表 42. HRESULT GetProperty

HRESULT GetNode (size_t index， [out] ISettingsProperties **ppNode)

這個方法類似於 GetProperty，但它不是從 DataItem 傳回一個值，而是傳回包裝在 ISettingsProperties 介面中的整個 DataItem。 參見表 43 和表 44。

表 43. HRESULT GetNode

表 44. HRESULT GetNode 結果

IFactoryRegistry 介面

__interface IFactoryRegistry : IUnknown
{
    void Register(LPCTSTR type,  IClassFactory *pFactory);
    HRESULT LoadAndRegister(LPCTSTR dllName, ILogger *pLogger);
    BOOL Contains(LPCTSTR type);
    HRESULT GetFactory(LPCTSTR type,  IClassFactory **ppFactory);
    HRESULT CreateInstance(LPCTSTR type,  IUnknown **ppInstance);
    HRESULT SetContainer(IWizardPageContainer *pContainer);
    HRESULT RegisterService(REFGUID iid, IUnknown *pService);
    HRESULT GetService(REFGUID iid,  IUnknown **ppService);
};

概觀

當您建立新的自訂頁面時，您至少需要建立 頁面 Factory，也就是實作 IClassFactory 的類別。 (您可以使用 ClassFactoryImpl 作為 factory 的基底類別。)

void 暫存器 (LPCTSTR 類型，IClassFactory *pFactory)

這個方法會向登錄註冊類別處理站。 見表 45。

表 45. IClassFactory void Register

HRESULT LoadAndRegister (LPCTSTR dllName， ILogger *pLogger)

此方法僅供內部使用。

BOOL 包含 (LPCTSTR 類型)

此方法一般供內部使用。 它會檢查是否已為類型註冊類別處理站。

HRESULT GetFactory (LPCTSTR 類型，IClassFactory **ppFactory)

這個方法可讓您擷取類別處理站。 一般而言，您會呼叫 CreateInstance。 但是，如果您要建立大量相同的元件，則擷取 factory 會更有效率，然後要求它為您建立實例。

HRESULT CreateInstance (LPCTSTR 類型， IUnknown **ppInstance)

這個方法會給定元件類型，建立元件的新執行個體。 請改為使用 CreateInstance 範本方法，其允許建立類型安全的物件。

HRESULT SetContainer (IWizardPageContainer *pContainer)

此方法僅供內部使用。

HRESULT RegisterService (REFGUID iid， IUnknown *pService)

服務 是可在多個位置使用的元件單一執行個體。 您可以使用此方法在一個頁面上註冊服務，然後從另一個頁面擷取相同的執行個體。

HRESULT GetService (REFGUID iid， IUnknown **ppService)

這個方法會擷取先前透過呼叫 RegisterService 註冊的服務。

HRESULT SetLanguage (LANGID languageId)

這個方法會將 UDI 精靈的語言設定為您在 languageId 參數中提供的語言識別碼。

LANGID GetLanguage ()

這個方法會傳回您使用 UDI 精靈的 /locale 命令列參數提供的語言識別碼值。 此方法會傳回下列其中一個值：

• 使用 /locale 命令列參數提供的語言識別碼值

• 0，如果您沒有提供 /locale 命令列參數

ILogger 介面

__interface ILogger : IUnknown
{
    HRESULT Init(LPCWSTR logFilename);
    HRESULT MoveLog(LPCWSTR logFilename);
    HRESULT LogBase(EMessageType messageType, LPCTSTR component, SYSTEMTIME eventTime, LPCTSTR message);
    HRESULT Log(EMessageType messageType, LPCTSTR component, LPCTSTR message);
    HRESULT Error(HRESULT error, LPCTSTR component, LPCTSTR message);
    HRESULT Error2(HRESULT error, LPCTSTR component, LPCTSTR message, LPCTSTR message2);
    HRESULT Normal(LPCTSTR component, LPCTSTR message);
    HRESULT Normal2(LPCTSTR component, LPCTSTR message, LPCTSTR message2);
    HRESULT Verbose(LPCTSTR component, LPCTSTR message);
    HRESULT Verbose2(LPCTSTR component, LPCTSTR message, LPCTSTR message2);
    HRESULT Debug(LPCWSTR component, LPCWSTR message);
    HRESULT EnableDebug(BOOL debug);
    HRESULT Close(void);
    HRESULT GetLogFilename(LPBSTR pFilename);
};

概觀

UDI 精靈會將資訊記錄到記錄檔，以協助對欄位中發現的問題進行疑難排解。 讓您的頁面記錄資訊是個好主意。 您可以使用頁面的 Logger () 方法，從頁面內取得此介面的指標。 記錄檔中的行包含代表錯誤、正常、詳細資訊或偵錯訊息的「層級」數字。

<Setter Property="debug">true</Setter>

初始化

HRESULT Init(LPCWSTR logFilename)

此方法僅供內部使用。

MoveLog

HRESULT MoveLog(LPCWSTR logFilename)

此方法僅供內部使用。

LogBase

HRESULT LogBase(EMessageType messageType, LPCTSTR component, SYSTEMTIME eventTime, LPCTSTR message)

此方法僅供內部使用。

記錄

HRESULT Log(EMessageType messageType, LPCTSTR component, LPCTSTR message)

此方法僅供內部使用。

錯誤

HRESULT Error(HRESULT error, LPCTSTR component, LPCTSTR message)

呼叫這個方法以記錄錯誤的相關資訊。 見表 46。

表 46. HRESULT 錯誤

錯誤 2

HRESULT Error2(HRESULT error, LPCTSTR component, LPCTSTR message, LPCTSTR message2)

這個方法類似於 Error 方法，但可讓您提供由兩個部分組成的訊息。 最後一封郵件會在輸出檔案中出現 “message”，然後是 “message2”。 這只是一種方便的方法。

一般

HRESULT Normal(LPCTSTR component, LPCTSTR message)

此方法會記錄一般訊息。 請參閱參數的 錯誤 方法說明。

正常2

HRESULT Normal2(LPCTSTR component, LPCTSTR message, LPCTSTR message2)

此方法會記錄一般訊息。 請參閱 Error2 方法的參數描述。

詳細資訊

HRESULT Verbose(LPCTSTR component, LPCTSTR message)

這個方法會記錄詳細訊息。 請參閱參數的 錯誤 方法說明。

詳細資訊2

HRESULT Verbose2(LPCTSTR component, LPCTSTR message, LPCTSTR message2)

這個方法會記錄詳細訊息。 請參閱 Error2 方法的參數描述。

偵錯

HRESULT Debug(LPCWSTR component, LPCWSTR message)

此方法會記錄偵錯訊息。 請參閱參數的 錯誤 方法說明。 除非啟用，否則不會將偵錯訊息儲存到檔案。 如需詳細資料，請參閱概觀一節。

EnableDebug

HRESULT EnableDebug(BOOL debug)

此方法僅供內部使用。

關閉

HRESULT Close(void)

此方法僅供內部使用。

GetLogFilename

HRESULT GetLogFilename(LPBSTR pFilename)

這個方法會擷取記錄檔的名稱。

IOrientation 介面

__interface IOrientation : IUnknown
{
    void SetController(IWizardDialogController *pController);
    int AddPage(LPCTSTR name);
    void SelectPage(int index);
};

此介面僅供內部使用。

ISettings 介面

__interface ISettings : IUnknown
{
    int NumDlls();
    int NumPages();

    HRESULT SetStage(LPCWSTR stageName);
    HRESULT GetDllName(long index, __out LPBSTR pDllName);
    HRESULT GetPageInfo(long index, __out ISettingsProperties **ppPageInfo);
    HRESULT GetStyle(__out ISettingsProperties **ppStyleInfo);
};

此介面僅供內部使用。

ISettingsProperties 介面

__interface ISettingsProperties : IUnknown
{
    HRESULT GetAttribute(LPCTSTR attributeName, __out LPBSTR attributeValue);
    IStringProperties * Properties();
    HRESULT SelectNodes(LPCTSTR xPath, __out IXMLDOMNodeList **ppList);
    HRESULT SelectSingleNode(LPCTSTR xPath, __out IXMLDOMNode **ppNode);
    HRESULT GetDataNode(LPCTSTR name, __out ISettingsProperties **ppNode);
    HRESULT GetDataNodes(__out IDataNodes **ppNodes);
    HRESULT GetChildDataNodes(LPCTSTR childeName, __out IDataNodes **ppNodes);
};

概觀

此介面提供頁面資料的存取。 若要取得頁面資料的最上層，請使用頁面的 [設定] () 方法。

HRESULT GetAttribute (LPCTSTR attributeName， LPBSTR attributeValue)

此方法可讓您擷取主節點上的屬性值，當您使用頁面的設定 () 方法時，也就是頁面節點。

IStringProperties * Properties ()

此方法可讓您存取主節點下的 setter 屬性值。 若是頁面，這些是頂層屬性。

HRESULT、SelectNodes (LPCTSTR、xPath、IXMLDOMNodeList **ppList)

如果您想要使用 XPath 運算式直接取得 XML 節點的清單，請呼叫這個方法。 如果可以的話，最好使用其他方法之一。 只有在您無法以任何其他方式到達節點時才使用此方法。

HRESULT SelectSingleNode (LPCTSTR xPath， IXMLDOMNode **ppNode)

如果您想要使用 XPath 運算式直接取得單一 XML 節點，請呼叫此方法。 如果可以的話，最好使用其他方法之一。 只有在您無法以任何其他方式連線到節點時，才使用此方法。

HRESULT GetDataNode (LPCTSTR 名稱，ISettingsProperties **ppNode)

根據元素的 Name 屬性擷取 Data 元素。

HRESULT GetDataNodes (IDataNodes **ppNodes)

這個方法會擷取目前節點下的 DataItem 元素清單。 從頁面層級，呼叫 GetDataNode 以擷取資料的 ISettingsProperty 介面。 然後，在該執行個體上呼叫 GetDataNodes 以擷取記錄清單。 例如，假設有此 XML：

    <Page ...>
      <Data Name="Network">
        <DataItem>
          <Setter Property="DisplayName">Public</Setter>
          <Setter Property="Share">\\servername\Share</Setter>
        </DataItem>
        <DataItem>
          <Setter Property="DisplayName">Dev Team</Setter>
          <Setter Property="Share">\\servername\DevShare</Setter>
        </DataItem>
      </Data>

PSettingsProperties pData;
Settings()->GetDataNode(L"Network", &pData);
PDataNodes pNodes;
pData->GetDataNodes(&pNodes);

HRESULT， GetChildDataNodes (LPCTSTR， childeName， IDataNodes **ppNodes)

這個方法可讓您快速取得特定 Data 節點底下的 DataItem 節點集。 使用 GetDataNodes 範例中的 XML，下列程式碼會執行與 GetDataNodes 下範例中四行程式碼完全相同的動作，但會檢查錯誤：

ISimpleStringProperties Interface

ISimpleStringProperties 介面

__interface ISimpleStringProperties : IStringProperties
{
void Add(LPCTSTR propertyName, LPCTSTR value);
};

此介面本身可能沒有用處。 不過，它是由 ID_SimpleStringProperties 元件實作，該元件也會實作 IStringProperties 介面。 當您需要將一組屬性傳遞給另一個元件 （例如工作），但您想要以程式設計方式新增值而不是使用 XML 中的值時，可以使用此元件。 以下是使用此介面的範例：

PSimpleStringProperties *pProperties;
CreateInstance(Container(), ID_SimpleStringProperties, &pProperties);
pProperties->Add(L"filename", L"%windir%\\system32\\cscript.exe");
pTask->Init(pProperties, nullptr);
IStringProperties
__interface IStringProperties : IUnknown
{
    HRESULT Get(LPCTSTR propertyName, [out] LPBSTR pPropValue);
};

此介面可讓您簡單存取來自 XML 的一組 setter 元素。 此介面可用於使用 Settings () -Properties> () 的頁面屬性。

HRESULT Get (LPCTSTR propertyName， [out] LPBSTR pPropValue)

此方法會擷取單一屬性值。 參見表 47 和表 48。

表 47. IHRESULT 取得屬性值

表 48. IHRESULT 取得屬性值結果

ITaskManager 介面

__interface ITaskManager : IUnknown
{
    HRESULT Init(IWizardPageView *pPageView, int idListView, int idMessage, int idRetryButton, ISettingsProperties *pPageInfo, ITaskManagerCallback *pCallback);
    HRESULT SetFailMessage(LPCWSTR message);

    HRESULT Start(void);

    HRESULT GetTaskMessage(size_t index, LPBSTR message);
    HRESULT GetResultType)(size_t index, LPBSTR type);
    HRESULT GetProperty(size_t index, LPCTSTR propertyName, LPBSTR value);
    int GetSelectedIndex(void);
    HRESULT Wait(DWORD waitMilliseconds);
    size_t FailedCount(void);
    size_t WarningCount(void);
    size_t SucceedCount(void);
    size_t RunningCount(void);

    void OnCommonControlEvent(WORD controlId, LPNMHDR pInfo);
    void OnControlEvent(WORD eventId, WORD controlId);
    void EnableButtons(BOOL enable);
}

此介面是由 TaskManager 元件 (ITaskManager.h) 中的 ID_TaskManager 所實作，也就是在預檢頁面上執行工作的元件。 您可以直接使用預檢頁面（這是您大多數時候所做的），也可以建立自己的頁面，讓此元件完成大部分工作。

HRESULT 初始化 (IWizardPageView *pPageView， int idListView， int idMessage， int idRetryButton， ISettingsProperties *pPageInfo， ITaskManagerCallback *pCallback)

您必須先呼叫此方法，才能呼叫任何其他方法。 它會初始化 TaskManager 元件。 見表 49。

表 49. HRESULT 初始化

HRESULT SetFailMessage (LPCWSTR 訊息)

此方法會設定在一或多個工作失敗時所顯示的訊息。

HRESULT 啟動 (無效)

這個方法會啟動所有工作。 每項工作都是在個別執行緒上啟動。

HRESULT GetTaskMessage (size_t 索引，LPBSTR 訊息)

此方法僅供內部使用。 它根據工作清單中的索引來擷取工作的目前訊息。

HRESULT GetResultType) (size_t 索引，LPBSTR 類型)

這個方法會擷取工作的目前「類型」。 表 50 顯示可用的類型。

表 50. HRESULT GetResultType

透過查看工作的結束或錯誤碼，並在工作的 <ExitCodes> XML 元素中尋找相符項目來擷取類型。

HRESULT GetProperty (size_t 索引、LPCTSTR propertyName、LPBSTR 值)

進度和預檢頁面會使用此方法來擷取 BitmapFilename setter 屬性，讓它可以在您醒目提示之工作的訊息旁顯示影像。 換句話說，您可以將自訂 setter 新增至工作的 XML，然後使用此方法來擷取它。

int GetSelectedIndex (void)

這個方法會擷取目前所選工作的索引，如果您想要擷取有關工作的其他資訊， (請參閱 GetProperty 方法) 以顯示所選工作的索引，則此方法會很有用。 進度和預檢頁面使用此方法來顯示所選工作的影像。

HRESULT Wait (DWORD waitMilliseconds)

這個方法主要有助於單元測試，讓測試可以確保工作在單元測試結束之前完成。 您通常不會呼叫這個方法。 當所有工作都完成執行或等待時間已過時，它會傳回。

size_t FailedCount (void)

這個方法會傳回目前標示為失敗的工作數目。

size_t WarningCount (void)

這個方法會傳回目前標示為警告的工作數目。

size_t SucceedCount (void)

這個方法會傳回目前標示為成功的工作數目。

size_t RunningCount (void)

這個方法會傳回目前執行中的任務數目。

void OnCommonControlEvent (WORD controlId， LPNMHDR pInfo)

請從頁面的 OnCommonControlEvent 呼叫這個方法，讓 TaskManager 可以處理所需的事件。

void OnControlEvent (WORD eventId， WORD controlId)

從頁面的 OnControlEvent 呼叫這個方法，讓 TaskManager 可以處理所需的事件。

void EnableButtons (BOOL 啟用)

此方法僅供內部使用。

IWizardComponent 介面

__interface IWizardComponent : IUnknown
{
    HRESULT SetContainer(IWizardPageContainer *pContainer);
};

概觀

一般而言，您不會直接實作此介面，而是透過 WizardComponent 範本類別來實作。 如果您的元件實作此介面，而且已向登錄註冊類別處理站，則您的元件會在建立 IWizardPageContainer 實例時收到指向 IWizardPageContainer 實例的指標。 例如，這可協助您存取記錄器或登錄，以建立元件可能需要的其他元件。

IWizardDialogController 介面

__interface IWizardDialogController : IUnknown
{
    void Initialize(ISettings *pSettings);
    void InitPages(void);
    void Start();
    void Next();
    void Finish();
    void Previous();
    int NumPages();
    void Cancel();

    HRESULT Focus(WizardButtons button);
    HRESULT SetEnable(WizardButtons button, BOOL enable);
    void ShowWarningMessage(LPCTSTR message);
    void HideWarningMessage();

    void ChangePage(size_t newIndex);
    IUnknown *CurrentPage(void);
    HRESULT GetCurrentTitle([out, retval] LPBSTR pDisplayName);
};

此介面僅供內部使用。

IWizardDialogView 介面

__interface IWizardDialogView : IUnknown
{
    HRESULT LoadBannerImage(LPCTSTR bannerFilename);
    HRESULT LoadPage(LPCTSTR pageType, ISettingsProperties *pPageSettings, IWizardPageView **view);
    HRESULT SetEnable(WizardButtons button, BOOL enable);
    HRESULT Focus(WizardButtons button);
    void EnableFinish(BOOL isFinish);
    void Exit(int exitCode);
    void ShowWarningMessage(LPCTSTR message);
    void HideWarningMessage(void);
    void SetTitle(LPCTSTR title);
    void SetPageTitle(LPCTSTR title);
    int ShowMessageBox(LPCTSTR message, LPCTSTR lpCaption, UINT uType);
    HWND GetHwnd(void);
    void UpdateFocus(void);
};

此介面僅供內部使用。

IWizardPage 介面

__interface IWizardPage : IUnknown
{
    HRESULT SetPageSettings(ISettingsProperties *pPageSettings);
    HINSTANCE GetInstanceHandle(void);
    int GetDialogResourceId(void);
    void WindowCreated(IWizardPageView *pView, IWizardPageContainer *pContainer);
    void WindowShown(void);
    void WindowHidden(void);

    HRESULT NextSelected(void);
    void ControlEvent(WORD eventId, WORD controlId);
    void CommonControlEvent(WORD controlId, LPNMHDR pInfo, LPBOOL pCancel);
    void UnhandledEvent(HWND hwnd, UINT message, WPARAM wParam, LPARAM lParam);
};

概觀

此介面由 WizardPageImpl 實作，因此您通常不需要自己實作。 精靈與您的自訂頁面互動時，會為您呼叫所有這些方法。

IWizardPageContainer 介面

__interface IWizardPageContainer : IUnknown
{
    ILogger * Logger(void);
    IPropertyBag * Properties(void);
    HRESULT CreateInstance(LPCTSTR type, [out] IUnknown **ppInstance);
    HRESULT GetService(REFIID iid, [out] IUnknown **ppInstance);
    HRESULT ReplaceVariables(LPCTSTR source, [out] LPBSTR pDest);
    HRESULT GotoPage(LPCTSTR pageName);
    int ShowMessageBox(LPCTSTR message, LPCTSTR lpCaption, UINT uType);
    BOOL InPreview(void);
    HWND GetHwnd(void);
};

概觀

此介面可透過 WizardPageImpl) 實作 (Container 方法供頁面使用，並可讓您存取精靈的各種服務。

ILogger * Logger (void)

使用此方法可將訊息寫入記錄檔，例如：

Logger()->Verbose(s_component, L"Message for log file");

IPropertyBag * 無效) (屬性

這個方法可讓您存取「記憶體」變數，這些變數是僅在 UDI 精靈執行時才會在記憶體中的屬性。 這些屬性可供其他頁面使用程式碼或使用 $memoryVarName$ 語法的 XML 使用。

HRESULT CreateInstance (LPCTSTR 類型， [out] IUnknown **ppInstance)

這個方法可讓您建立已登錄之任何元件的新執行個體。 不過，最好使用範本函數 CreateInstance，因為它是強型別。

HRESULT GetService (REFIID iid， [out] IUnknown **ppInstance)

這個方法可讓您擷取已登錄的服務。 不過，最好是呼叫 GetService 範本函式，其為強型別 (，而不是使用 IUnknown) 。

HRESULT ReplaceVariables (LPCTSTR source， [out] LPBSTR pDest)

此方法處理字串值內的變數。 它支援表 51 和表 52 中所示的格式。

表 51. HRESULT ReplaceVariables

表 52. HRESULT 參數

HRESULT GotoPage (LPCTSTR pageName)

這個方法尚未經過完整測試。 這個概念是您可以根據 .config XML 檔案中定義的頁面名稱直接切換至特定頁面。 呼叫此方法會略過頁面上的 OnNextSelected 。 此外，此方法的行為可能會發生變化，因此請自行承擔使用風險。

int ShowMessageBox (LPCTSTR 訊息、LPCTSTR lpCaption、UINT uType)

這個方法會顯示包含您提供的文字和標題的訊息方塊。 uType 參數是您可以提供給 MessageBox Win32 函式的任何值。

BOOL InPreview (void)

如果您透過提供 /preview 參數在「預覽」模式下啟動精靈，此方法會傳回 TRUE。 在預覽模式中， [下一步 ] 按鈕永不會停用。 這個方法可讓您在預覽模式下略過程式碼，例如當您的頁面上沒有有效資料時，可能會導致問題。

HWND GetHwnd (void)

這個方法會傳回主對話方塊的 HWND 。 請謹慎使用此方法。 一般而言，UDI 精靈應用程式開發介面的設計是您絕不會直接使用視窗控制碼。

IWizardPageView 介面

__interface IWizardPageView : IUnknown
{
    HRESULT GetControlWrapper(int itemId, DialogControlTypes controlType, IUnknown **ppControl);
    HWND GetHwnd(void);
    HWND GetControl(int itemId);
    HRESULT Show (void);
    HRESULT Hide(void);
    HRESULT Focus(int itemId);
    IWizardPage * Page(void);
    IFormController * Form(void);

    HRESULT FocusWizardButton(WizardButtons button);
    HRESULT SetEnable(WizardButtons button, BOOL enable);
    void ShowWarningMessage(LPCTSTR message);
    void HideWarningMessage(void);
};

您可以透過 WizardPageImpl) 所實作的 View 方法 (頁面中的程式碼使用此介面。

HRESULT GetControlWrapper (int itemId， DialogControlTypes controlType， IUnknown *ppControl)

UDI 精靈使用 包裝函式，也就是與頁面上的控制項互動的實際外觀。 使用這些外觀而不是實際控件可以更輕鬆地為頁面編寫測試，因為您可以從測試中提供模擬外觀。

最好是使用強型別的 GetControlWrapper 範本方法，而不是直接使用此方法，例如：

PComboBox m_pLanguagePackCombo;
GetControlWrapper(View(), IDC_MY_COMBO, CONTROL_COMBO_BOX, &m_pCombo);

HWND GetHwnd (void)

這個方法會傳回頁面的視窗控制碼。 一般而言，您不應該需要存取此視窗控制碼。

HWND GetControl (int itemId)

如有必要，可以呼叫這個方法來取得頁面上某個控制項的視窗控制碼。 (最好) 呼叫 GetControlWrapper 範本函數。

HRESULT 顯示 (無效)

此方法僅供內部使用。

HRESULT 隱藏 (無效)

此方法僅供內部使用。

HRESULT Focus (int itemId)

將輸入焦點設定為特定控制項。

IWizardPage * 頁面 (無效)

此方法僅供內部使用。

IFormController * Form (void)

此方法僅供內部使用。

HRESULT FocusWizardButton (WizardButtons 按鈕)

將焦點設定在其中一個精靈按鈕。WizardButtons 有兩個值： BackButton 和 NextButton。

HRESULT SetEnable (WizardButtons 按鈕，BOOL 啟用)

要求啟用或停用其中一個精靈按鈕。 按鈕可能與您要求的狀態不相符。 例如，如果您使用 /preview 參數執行 UDI 精靈，則按鈕一律會啟用。 WizardButtons 有兩個值： BackButton 和 NextButton。

void ShowWarningMessage (LPCTSTR 訊息)

這個方法會在頁面內容區域底部顯示警告訊息。 此訊息可以是您想要的任何文字。

void HideWarningMessage (void)

隱藏您在呼叫 ShowWarningMessage 時顯示的警告訊息。

IXmlDocument 介面

__interface IXmlDocument : IUnknown
    HRESULT Load(LPCTSTR filename);
    HRESULT LoadXml(LPCTSTR xml);
    HRESULT Save(LPCWSTR filename);
    HRESULT GetParseErrorMessage(LPBSTR pMessage);
    HRESULT SelectNodes(LPCTSTR xpath, IXMLDOMNodeList **ppNodes);
    HRESULT SelectSingleNode(LPCTSTR xpath, IXMLDOMNode **ppNode);
    HRESULT AddSchema(LPCTSTR filename, LPCTSTR ns);
    HRESULT AddAttribute(IXMLDOMNode *pNode, LPCWSTR name, LPCWSTR value);
    HRESULT CreateNode(DOMNodeType type, LPCWSTR name, LPCWSTR ns, IXMLDOMNode **ppNode);
};

概觀

此介面由 ID_IXmlDocument 元件實現，該元件是一個外觀，旨在使 C++ 中的 XML 文件更容易處理。

HRESULT 載入 (LPCTSTR 檔案名稱)

這個方法會從外部檔案載入 XML 文件。 如果檔案載入時沒有發生錯誤，它會傳回 S_OK 或 S_FALSE 是否發生錯誤。 發生錯誤時，您可以呼叫 GetParseErrorMessage 來取得錯誤訊息。

HRESULT LoadXml (LPCTSTR xml)

這個方法會從字串載入 XML 文件，而不是從外部檔案。 除了讀取 XML 的來源以外，行為與 Load 方法相同。

HRESULT 儲存 (LPCWSTR 檔案名稱)

這個方法會將記憶體中的 XML 文件儲存至外部檔案。

HRESULT GetParseErrorMessage (LPBSTR pMessage)

如果有的話，這個方法會傳回一個新字串，其中包含載入 XML 文件的錯誤訊息。 它總是傳回 S_OK。

HRESULT、SelectNodes (LPCTSTR、xpath、IXMLDOMNodeList **ppNodes)

這個方法可讓您使用 XPath 運算式從文件擷取節點集合。 它總是傳回 S_OK。

HRESULT， SelectSingleNode (LPCTSTR， xpath， IXMLDOMNode **ppNode)

這個方法可讓您使用 XPath 運算式從文件中擷取一個節點。 它總是傳回 S_OK。

HRESULT AddSchema (LPCTSTR 檔案名稱，LPCTSTR ns)

這個方法會新增外部結構描述檔案的名稱，當載入 XML 文件時，該檔案會用來驗證 XML 文件的結構描述。 您提供的命名空間是您可以在 XPath 查詢中使用的字串，雖然尚未經過測試。

HRESULT AddAttribute (IXMLDOMNode *pNode， LPCWSTR 名稱， LPCWSTR 值)

這個方法會將新屬性新增至 XML 文件中的現有節點。 見表 53。

表 53. HRESULT AddAttribute

HRESULT CreateNode (DOMNodeType 類型、LPCWSTR 名稱、LPCWSTR ns、IXMLDOMNode **ppNode)

呼叫這個方法以建立新節點：

Pointer<IXMLDOMNode> pNewChild
pXmlDom->CreateNode(NODE_ELEMENT, L"MyElement", L"", &pNewChild);

建立新節點後，您可以呼叫父節點的 appendChild 方法，將其作為子節點新增至另一個節點。

協助程式函數

CreateInstance 範本函數

HRESULT CreateInstance(IWizardPageContainer *pContainer, LPCTSTR type, I **ppObject)

此函式是在 IWizardPageContainer.h 中定義，並透過 IWizardPageContainer-CreateInstance> 方法提供類型安全包裝函式，例如：

CreateInstance<IDirectory>(Container(), ID_Directory, &pDirectory);

這段程式碼會建立新的 ID_Directory 元件來擷取該元件的 IDirectory 介面。

GetService 範本函數

void GetService(IWizardPageContainer *pContainer, I **ppService)

此函式是在 IWizardPageContainer.h 中定義，並透過 IWizardPageContainer-GetService> 方法提供類型安全包裝函式，例如：

GetService<ITSVariableBag>(Container(), &pTsBag);

此函式會擷取支援 ITSVariableBag 介面的工作順序元件。 (針對 ITSVariableBag，您可以改為使用 WizardPageImpl 類別的 TSVariables 方法。)

UDI 精靈 Designer 組態檔案結構描述參考

此檔案是由 UDI 精靈 Designer 取用。 系統會為每個自訂 .dll 檔案建立個別檔案，其中可以包含自訂精靈頁面編輯器、自訂工作或自訂驗證程式。 檔案必須以 .config 結尾，並位於 installation_folder\Bin\Config 資料夾中， (installation_folder 是您安裝 MDT) 的資料夾。

表 54 列出 UDI 精靈 Designer 組態檔中的元素及其說明。 DesignerConfig 元素是此參照的根節點。

表 54. UDI 精靈 Designer 組態檔中的元素及其描述

DesignerConfig

此元素會指定所有其他元素的根。

項目資訊

表 55 提供 DesignerConfig 元素的相關資訊。

表 55. DesignerConfig 元素資訊

元素屬性

此元素沒有屬性。

註解

無。

範例

<DesignerConfig>
   + <TaskLibrary>
   + <ValidatorLibrary>
   + <DesignerMappings>
</DesignerConfig>

DesignerMappings

此元素將一組 Page 元素組成群組。

項目資訊

表 56 提供 DesignerMappings 元素的相關資訊。

表 56. DesignerMappings 元素資訊

元素屬性

此元素沒有屬性。

註解

無。

範例

<DesignerConfig>
   + <TaskLibrary>
   + <ValidatorLibrary>
   - <DesignerMappings>
        <Page DLL="SharedPages.dll"
           Description="Used to display text that describes the current stagegroup"
           Type="Microsoft.SharedPages.WelcomePage"
           DisplayName="Welcome"
           Image="Welcome_188.png"
           DesignerType="Microsoft.Enterprise.UDIDesigner.CoreModules.Views.WelcomePageView"
           DesignerAssembly="Microsoft.Enterprise.UDIDesigner.CoreModules.dll"/>
        <Page DLL="OSDRefreshWizard.dll"
           Description="Captures or restores user state data"
           Type="Microsoft.OSDRefresh.UserStatePage"
           DisplayName="User Data"
           Image="UserState_188.png"
           DesignerType="Microsoft.Enterprise.UDIDesigner.CoreModules.Views.UserStatePageView"
           DesignerAssembly="Microsoft.Enterprise.UDIDesigner.CoreModules.dll"/>
        <Page DLL="OSDRefreshWizard.dll"
           Description="Allows selecting the image to install, target drive, and whether to format"
           Type="Microsoft.OSDRefresh.VolumePage"
           DisplayName="Volume"
           Image="Volume_188.png"
           DesignerType="Microsoft.Enterprise.UDIDesigner.CoreModules.Views.VolumePageView"
           DesignerAssembly="Microsoft.Enterprise.UDIDesigner.CoreModules.dll"/>
     </DesignerMappings>
</DesignerConfig>

頁面

此元素會指定要在 UDI 精靈 Designer 中載入的精靈頁面編輯器，而 UDI 精靈頁面編輯器又會用來編輯精靈頁面的組態設定。

項目資訊

表 57 提供有關 Page 元素的資訊。

表 57. 頁面元素資訊

元素屬性

表 58 列出了 Page 元素的屬性以及每個元素的描述。

表 58. 頁面元素的屬性和對應值

註解

UDI 精靈 Designer 會像使用範本一樣使用 Page 元素來建立新精靈的初始 XML。 UDI 精靈 Designer 會執行結構描述驗證，以確保 Page 和子元素具有有效的格式。 此元素提供 UDI 精靈頁面類型與 UDI 精靈 Designer 使用自訂頁面編輯器編輯和建立此類型頁面所需的資訊之間的對應。

範例

無。

參數

這個元素會指定傳遞至父項 Task 或 Validator 元素的參數，並對應至 UDI 精靈設定檔中的 Setter 元素。

項目資訊

表 59 提供 Param 元素的相關資訊。

表 59. 參數元素資訊

元素屬性

表 60 列出了 Param 元素的屬性，並提供了每個元素的描述。

表 60. 參數元素的屬性和對應值

註解

無。

範例

無。

工作

此元素指定工作程式庫內的工作。

項目資訊

表 61 提供 Task 元素的相關資訊。

表 61. 工作元素資訊

元素屬性

表 62 列出了 Task 元素的屬性，並提供了每個元素的描述。

表 62. 任務元素的屬性和對應值

註解

無。

範例

無。

TaskItem

此元素會指定傳遞至工作的一組參數。

項目資訊

表 63 提供 TaskItem 元素的相關資訊。

表 63. TaskItem 元素資訊

元素屬性

表 64 列出了 TaskItem 元素的屬性，並提供每個元素的描述。

表 64. TaskItem 元素的屬性和對應值

註解

無。

範例

無。

TaskLibrary

此元素會將 一組工作 元素組成群組。

項目資訊

表 65 提供 TaskLibrary 元素的相關資訊。

表 65. TaskLibrary 元素資訊

元素屬性

此元素沒有屬性。

註解

無。

範例

<DesignerConfig>
   - <TaskLibrary>
        +<Task DLL="" Description="Executes a process with the given command line." Type="Microsoft.Wizard.ShellExecuteTask" Name="Shell Execute Task">
        +<Task DLL="OSDRefreshWizard.dll" Description="Discovers supported applications for install." Type="Microsoft.OSDRefresh.AppDiscoveryTask" Name="Application Discovery">
        +<Task DLL="SharedPages.dll" Description="Check to ensure a wired network connection is available." Type="Microsoft.SharedPages.WiredNetworkTask" Name="Wired Network Check">
        +<Task DLL="OSDRefreshWizard.dll" Description="Check to ensure power source is AC (not battery)." Type="Microsoft.OSDRefresh.ACPowerTask" Name="AC Power Check">
        +<Task DLL="" Description="Check to ensure power source is AC (not battery)." Type="Microsoft.Wizard.CopyFilesTask" Name="Copy Files Task">
     </TaskLibrary>
   + <ValidatorLibrary>
   + <DesignerMappings>
</DesignerConfig>

驗證程式

此元素指定驗證程式庫中的驗證程式。

項目資訊

表 66 提供 Validator 元素的相關資訊。

表 66. 驗證程式元素資訊

元素屬性

表 67 列出了 Validator 元素的屬性，並提供了每個元素的描述。

表 67. 驗證器元素的屬性和對應值

註解

無。

範例

無。

ValidatorLibrary

此元素會將一組 驗證程式 元素組成群組。

項目資訊

表 68 提供 ValidatorLibrary 元素的相關資訊。

表 68. ValidatorLibrary 元素資訊

元素屬性

此元素沒有屬性。

註解

無。

範例

<DesignerConfig> + <TaskLibrary> - <ValidatorLibrary> +<Validator DLL=“” description=“欄位中需要文字” Type=“Microsoft.Wizard.Validation.NonEmpty” Name=“NonEmpty”> +<Validator DLL=“” description=“不允許欄位中包含特定字元” Type=“Microsoft.Wizard.Validation.InvalidChars” Name=“InvalidChars”> +<Validator DLL=“” description=“必須遵循預先定義的模式” Type=“Microsoft.Wizard.Validation.RegEx” Name=”NamedPattern“> +<Validator DLL=”“ Description=”要求內容符合規則運算式“ Type=”Microsoft.Wizard.Validation.RegEx“ Name=”RegEx“></ValidatorLibrary> + <DesignerMappings></DesignerConfig>

UDI 精靈 Designer 參考

控制項

用來建立自訂精靈頁面編輯器以供 UDI 精靈 Designer 使用的控制項是 WPF UserControl 執行個體。 表 69 列出可用來建立自訂精靈頁面編輯器的控制項。

表 69. 可用於建立自訂精靈頁面編輯器的控制項

CollectionTControl

這個控制項提供許多編輯資料的功能。 了解如何使用此控制項的最佳方式是查看範例，其中顯示如何在頁面的 Data 元素下編輯資料。 特別是，此範例會示範如何在此控制項中新增、移除及編輯項目。

FieldElementControl

使用此控制項來編輯欄位，該欄位通常連結到 .xaml 頁面上的 TextBox 控制項。

範例

下列從 .xaml 檔案摘錄，說明如何使用 FieldElementControl 使用子 TextBox 控制項來設定精靈頁面上的欄位預設值：

<Controls:FieldElementControl
Width="450"
Margin="0,5"
FieldData="{Binding DataContext.Location, ElementName=ControlRoot}"
HeaderText="Location Combo Box"
InstructionText="Here you can configure the behavior of the location combo box."
HideValidationTab="True">

<TextBox Text="{Binding FieldData.DefaultValue,
 UpdateSourceTrigger=PropertyChanged,
 Mode=TwoWay}"/>
</Controls:FieldElementControl>

屬性

FieldData

此字串屬性包含將 FieldElementControl 連線至欄位基礎 XML 的資訊。 連線會與頁面編輯器介面的屬性建立。 下列摘錄自 .xaml 檔案，說明 FieldData 屬性的用法：

FieldData="{Binding DataContext.Location, ElementName=ControlRoot}"

在此摘錄中，頁面編輯器介面稱為 ControlRoot ，並在 ElementName 參數中指定。 繫結會執行至 ControlRoot 頁面編輯器介面的 DataContext.Location 屬性。 DataContext 是一個檢視模型，指向 UDI 精靈設定檔中的 Page 元素。 位置 是檢視的屬性，會傳回可能的位置清單，並由 UDI 精靈設定檔 內的資料元素 定義。 每個位置都由 UDI 精靈設定檔內的 DataItem 元素定義。

HeaderText

此字串屬性可讓您指定 FieldElementControl 控制項的標題。 標題可做為控制項的標題，並以粗體橘色文字格式顯示在控制項正上方。

InstructionText

此字串屬性可讓您指定 FieldElementControl 控制項的資訊文字。 一般而言，文字是用來提供欄位的簡短描述，並說明設定欄位如何影響對應的精靈頁面。

HideEnableButton

此布林值屬性可讓您控制在 [已解除鎖定 ] 與 [ 已鎖定 ] 之間變更狀態之按鈕的可見度 (啟用或停用) 。 如果設為：

• 為 True，則看不到按鈕

• False，則可見按鈕 (這是預設值。)

HideDefaultTab

此布林值屬性可讓您控制包含用來設定預設值之控制項的區段可見度。 雖然屬性是參照索引標籤，但 FieldElementControl 上沒有索引標籤，而是可以隱藏的區段。 如果設為：

• 為 True，則看不到該區段

• False，則顯示區段 (這是預設值。)

HideBorder

此布林值屬性可讓您控制欄位控制項周圍框線的可見度。 如果設為：

• 為 True，看不到框線

• False，則框線可見 (這是預設值。)

隱藏圖片

此布林值屬性可讓您控制 FieldImageSource 屬性設定之影像的可見度。 如果設為：

• 沒錯，影像不可見

• False，則可見影像 (這是預設值。)

HideValidationTab

此布林值屬性可讓您控制管理驗證器清單的區段的可見性。 雖然屬性是參照索引標籤，但 FieldElementControl 上沒有索引標籤，而是可以隱藏的區段。 如果設為：

• 為 True，則看不到該區段

• False，則顯示區段 (這是預設值。)

HideSummaryTab

此布林值屬性可讓您控制設定欄位摘要標題之區段的可見度。 欄位中的標題和對應值會顯示在階段流程中的 SummaryPage 精靈頁面類型上。 雖然屬性是參照索引標籤，但 FieldElementControl 上沒有索引標籤，而是可以隱藏的區段。 如果設為：

• 為 True，則看不到該區段

• False，則顯示區段 (這是預設值。)

HideTaskSequenceTab

此布林值屬性可讓您控制區段的可見度，在其中設定對應至欄位的工作順序變數。 雖然屬性是參照索引標籤，但 FieldElementControl 上沒有索引標籤，而是可以隱藏的區段。 如果設為：

• 為 True，則看不到該區段

• False，則顯示區段 (這是預設值。)

SetterControl

使用此控制項來修改 UDI 精靈設定檔中 Setter 元素的值。 這個控制項包含用來修改 setter 元素值的子控制項。

範例

下列從 .xaml 檔案摘錄，示範如何使用 SetterControl 使用子 TextBox 控制項來修改名為 KeyLocationSetter 的 Setter 元素。

<Controls:SetterControl Margin="5"
        Width="450"
        HeaderText="Title text"
        SetterData="{Binding KeyLocationSetter}"
        InstructionText="What this means..."
        HorizontalAlignment="Left">

    <TextBox
                   Margin="0,3"
                   Text="{Binding SetterData.SetterValue, Mode=TwoWay, UpdateSourceTrigger=PropertyChanged}"
    />

</Controls:SetterControl>

屬性

SetterData

您需要將此參數繫結至連接到 setter 的視圖或視圖模型屬性。 這類似於繫結至欄位的方式，如 FieldElementControl 所述。

HeaderText

這個屬性可讓您設定要出現在控制項標頭中的文字。 將此屬性視為控制項的標題;根據預設，它會顯示為粗體橘色文字。

InstructionText

將此屬性設定為您要顯示在標題下方的文字，通常是指示文字，會告訴自訂編輯器的使用者何時及為何要修改欄位的行為。

介面

表 70 列出可用來建立自訂精靈頁面編輯器的介面。

表 70. 可用於建立自訂精靈頁面編輯器的介面

IDataService

此介面包含數個屬性和方法，但您只需要一個屬性。 該屬性是此處記錄的唯一屬性。

您可以使用類別中如下所示的程式碼，使用相依性插入來取得此介面的指標：

[Dependency]
public IDataService DataService { get; set; }

屬性

表 71 列出 IDataService 介面的屬性。

表 71. IDataService 介面的屬性

CurrentPage

XElement CurrentPage { get; set; }

此屬性可讓您存取目前頁面的 XML。 您永遠不應該設定此屬性，但您可以隨意修改頁面的 XML。 範例頁面編輯器會顯示修改 XML 的範例。 此屬性主要在有自訂資料時使用。 針對欄位和屬性 (setter) ，您可以使用預先建立的控制項來處理所有詳細資料。

IMessageBoxService

此介面可讓您存取可用來顯示訊息方塊的方法。 您可能想知道為什麼需要一個界面來顯示消息框。 事實上，您不會： Microsoft 在程式碼中使用此介面，因為它可協助撰寫設計工具頁面的自動化測試。

不過，使用這些方法確實有一個有用的好處：對話方塊一律將 [擁有者] 設定為 UDI 精靈，這可確保對話方塊與主視窗正確分組。

您可以使用類別中如下所示的程式碼，使用相依性插入來取得此介面的指標：

[Dependency]
public IMessageBoxService MessageBoxes { get; set; }

方法

表 72 列出 IMessageBoxService 介面的方法。

表 72. IMessageBoxService 介面的方法

ShowMessageBox

這個方法會顯示一個訊息方塊，它是自訂精靈頁面編輯器的子系。 此成員已超載：表 73 包含成員清單和每個成員的簡要描述。 如需每個成員 (的完整資訊，包括語法、用法和範例) ，請參閱每個成員對應的章節。

表 73. ShowMessagBox 方法的超載成員

ShowMessageBox (字串訊息、字串標題、MessageBoxImage 圖示)

void ShowMessageBox(String message, String caption, MessageBoxImage icon);

這個方法會顯示含有 [確定] 按鈕的訊息方塊。 見表 74。

表 74. ShowMessageBox (字串訊息、字串標題、MessageBoxImage 圖示) 方法的參數

ShowMessageBox (字串訊息、字串標題、MessageBoxButton 按鈕、MessageBoxImage 圖示)

MessageBoxResult ShowMessageBox(string message, string caption, MessageBoxButton button, MessageBoxImage icon);

這個方法會顯示一個訊息方塊，其中包含您想要顯示的按鈕集，並報告您選取了哪個按鈕。 見表 75。

表 75. ShowMessageBox 的參數 (字串訊息、字串標題、MessageBoxButton 按鈕、MessageBoxImage 圖示) 方法

ShowMessageBox (例外狀況)

void ShowMessageBox(Exception exception);

這個方法會顯示訊息方塊，報告例外狀況的相關資訊。 此訊息方塊只有一個 [確定] 按鈕。 見表 76。

表 76. ShowMessageBox (例外狀況) 方法的參數

ShowDialogWindow

void ShowDialogWindow(Type viewType, DialogInteraction dialogPayload);

這個方法會建立新的對話方塊，其內容就是您在 viewType 參數中提供的文字。 UDI Designer 會建立這類的新執行個體，並將其包裝在具有 [確定] 和 [取消] 按鈕的對話方塊中。

您可以使用 dialogPayload 參數將資料傳遞至控制項。 SDK 目錄中的 SampleEditor 解決方案提供如何使用此功能的範例。

ShowWizardWindow

void ShowWizardWindow(Type viewType, DialogInteraction dialogPayload);

此方法可讓您在對話方塊內顯示自訂編輯器，其中包括用於瀏覽的 [ 下一步 ] 和 [上一步 ] 按鈕。 Microsoft 尚未提供如何使用此方法的範例。

UDI 精靈組態檔案結構描述參考

此檔案由 UDI 精靈取用，並由 UDI 精靈 Designer 設定。 此檔案可用來設定：

• UDI 精靈中顯示的精靈頁面

• UDI 精靈中精靈頁面的順序

• 每個精靈頁面上的欄位設定

• UDI 精靈 Designer 中可用的 StageGroups

• UDI 精靈 Designer 中每個部署精靈內的可用階段

  圖 77 列出 UDI 精靈設定檔中的元素及其描述。 精靈元素是此參照的根節點。

表 77. UDI 精靈設定檔中的元素及其描述

資料

此元素會將 Page 元素中的個別 DataItem 元素分組，並以 Name 屬性命名。

項目資訊

表 78 提供 資料 元素的相關資訊。

表 78. 資料元素資訊

元素屬性

表 79 列出 Data 元素的屬性，並提供每個元素的說明。

表 79. 資料元素的屬性和對應值

註解

Name 屬性可讓程式碼擷取一組特定的資料。

範例

無。

DataItem

此元素將 Page 元素中的個別 Setter 元素分組。 您可以在 DataItem 元素中包含一或多個 Data 元素，以建立階層式資料。 每個 DataItem 元素代表個別項目。 例如，可用磁碟機清單可能有一個用於顯示名稱的 DataItem ，以及另一個用於對應磁碟機代號的 DataItem 元素。

項目資訊

表 80 提供了 DataItem 元素的相關資訊。

表 80. DataItem 元素資訊

元素屬性

此元素沒有屬性。

註解

無。

範例

無。

預設

此元素會為父 Field 或 RadioGroup 元素中指定的欄位指定預設值。 預設值會設定為此元素括住的值。

項目資訊

表 81 提供 預設 元素的相關資訊。

表 81. 預設元素資訊

元素屬性

此元素沒有屬性。

註解

無。

範例

在下列範例中，時區欄位的預設值設定為 “Pacific Standard Time”：

<Field Name="TimeZone" Enabled="true" VarName="OSDTimeZone" Summary="Time Zone:">
  <Default>Pacific Standard Time</Default>

DLL

此元素會指定 UDI 精靈和 UDI 精靈 Designer 要載入和參考的 DLL。

項目資訊

表 82 提供 DLL 元素的相關資訊。

表 82. DLL 元素資訊

元素屬性

表 83 列出 DLL 元素的屬性，並提供每個元素的說明。

表 83. DLL 元素的屬性和對應值

註解

無。

範例

<DLLs>
  <DLL Name="OSDRefreshWizard.dll" />
  <DLL Name="SharedPages.dll" />
</DLLs>

DLL

此元素會將個別 DLL 元素組成群組。

項目資訊

表 84 提供 DLL 元素的 相關資訊。

表 84. DLL 元素資訊

元素屬性

此元素沒有屬性。

註解

無。

範例

<DLLs>
   <DLL Name="OSDRefreshWizard.dll" />
   <DLL Name="SharedPages.dll" />
</DLLs>

錯誤

此元素會指定工作可以傳回的可能錯誤碼。 工作 HRESULT 會傳回錯誤碼的值並進行陷印，以提供更具體的錯誤資訊。

項目資訊

表 85 提供 Error 元素的相關資訊。

表 85. 錯誤元素資訊

元素屬性

表 86 列出了 Error 元素的屬性，並提供了每個元素的描述。

表 86. 錯誤元素資訊

註解

無。

範例

無。

ExitCode

此元素會指定工作的可能結束代碼。 結束碼是工作預期的傳回碼。 為每個可能的結束代碼建立 ExitCode 元素。 否則，您可以在 Value 屬性中指定星號 (*) ，以處理未列在其他 ExitCode 元素中的傳回碼。

項目資訊

表 87 提供 ExitCode 元素的相關資訊。

表 87. ExitCode 元素資訊

元素屬性

表 88 列出 ExitCode 元素的屬性，並提供每個元素的說明。

表 88. ExitCode 元素的屬性和對應值

註解

無。

範例

無。

ExitCodes

此元素會針對 Task 或 Error 元素將一組 ExitCode 和 Error 元素分組。

項目資訊

表 89 提供 ExitCodes 元素的相關資訊。

表 89. ExitCodes 元素資訊

元素屬性

此元素沒有屬性。

註解

無。

範例

無。

欄位

這個元素會指定 Page 元素中控制項的執行個體，用來提供 XML 的自訂。 並非所有控制項都允許使用 XML 進行自訂——僅允許使用 Field 元素的控制項。

項目資訊

表 90 提供 Field 元素的相關資訊。

表 90. 欄位元素資訊

元素屬性

表 91 列出了 Field 元素的屬性，並提供每個元素的說明。

表 91. 欄位元素的屬性和對應值

註解

此元素可以包含零或多個 預設 元素，以及零或多個驗證 器 元素。

範例

無。

Fields

此元素會將 Page 元素中的個別 Field 元素分組。

項目資訊

表 92 提供 Fields 元素的相關資訊。

表 92. 欄位元素資訊

元素屬性

此元素沒有屬性。

註解

無。

範例

無。

檔案

此元素會使用 Microsoft.Wizard.CopyFilesTask 工作類型指定檔案複製作業的來源和目的地。 您可以包含個別的 File 元素，以便在單一工作中複製多個檔案。

項目資訊

表 93 提供 File 元素的相關資訊。

表 93. 檔案元素資訊

元素屬性

表 94 列出了 File 元素的屬性，並提供了每個元素的描述。

表 94. 檔案元素的屬性和對應值

註解

無。

範例

無。

頁面

此元素會指定頁面的執行個體，並包含頁面的所有組態設定。

項目資訊

表 95 提供 Page 元素的相關資訊。

表 95. 頁面元素資訊

元素屬性

表 96 列出了 Page 元素的屬性，並提供每個元素的描述。

表 96. 頁面元素的屬性和對應值

註解

無。

範例

無。

PageRef

此元素會指定 StageGroup內階段內頁面執行個體的參考。

項目資訊

表 97 提供 PageRef 元素的相關資訊。

表 97. PageRef 元素資訊

元素屬性

表 98 列出了 PageRef 元素的屬性並提供其描述。

表 98. PageRef 元素的屬性和對應值

註解

無。

範例

無。

頁數

此元素會將個別 頁面 元素分組。

項目資訊

表 99 提供 Pages 元素的相關資訊。

表 99. 頁面元素資訊

元素屬性

此元素沒有屬性。

註解

無。

範例

<Pages>
   + <Page Name="WelcomePage" DisplayName="Welcome" Type="Microsoft.SharedPages.WelcomePage">
   + <Page Name="ConfigScanPage" DisplayName="Deployment Readiness" Type="Microsoft.OSDRefresh.ConfigScanPage">
   + <Page Name="ConfigScanBareMetal" DisplayName="Deployment Readiness" Type="Microsoft.OSDRefresh.ConfigScanPage">
   + <Page Name="RebootPage" DisplayName="Reboot" Type="Microsoft.OSDRefresh.RebootPage">
   + <Page Name="WelcomePageReplace" DisplayName="Welcome" Type="Microsoft.SharedPages.WelcomePage">
   + <Page Name="VolumePage" DisplayName="Volume" Type="Microsoft.OSDRefresh.VolumePage">
   + <Page Name="UserRestorePage" DisplayName="Select Target" Type="Microsoft.OSDRefresh.UserStatePage">
   + <Page Name="ComputerPage" DisplayName="New Computer Details" Type="Microsoft.OSDRefresh.ComputerPage">
   + <Page Name="AdminAccounts" DisplayName="Administrator Password" Type="Microsoft.SharedPages.AdminAccountsPage">
   + <Page Name="UDAPage" DisplayName="User Device Affinity" Type="Microsoft.OSDRefresh.UDAPage">
   + <Page Name="LanguagePage" DisplayName="Language" Type="Microsoft.OSDRefresh.LanguagePage">
   + <Page Name="ApplicationPage" DisplayName="Install Programs" Type="Microsoft.OSDRefresh.ApplicationPage">
     <Page Name="SummaryPage" DisplayName="Summary" Type="Microsoft.Shared.SummaryPage" />
   + <Page Name="UserCapturePageOldPC" DisplayName="Select Target" Type="Microsoft.OSDRefresh.UserStatePage">
   + <Page Name="ProgressPage" DisplayName="Capture Data" Type="Microsoft.OSDRefresh.ProgressPage">
   + <Page Name="RebootAfterCapture" DisplayName="Reboot" Type="Microsoft.OSDRefresh.RebootPage">
</Pages>

RadioGroup

此元素會指定一組在 Field 元素中具有的選項按鈕。

項目資訊

表 100 提供了有關 RadioGroup 元素的資訊。

表 100. RadioGroup 元素資訊

元素屬性

表 101 列出了 RadioGroup 元素的屬性，並提供了每個元素的描述。

表 101. RadioGroup 元素的屬性和對應值

註解

無。

範例

無。

StageGroup

此元素指定部署階段群組。

項目資訊

表 102 提供了有關 StageGroup 元素的資訊。

表 102. StageGroup 元素資訊

元素屬性

表 103 列出了 StageGroup 元素的屬性和屬性描述。

表 103. StageGroup 元素的屬性和對應值

註解

無。

範例

無。

StageGroups

此元素會將 UDI 精靈設定檔中的一組階段群組分組。

項目資訊

表 104 提供了有關 StageGroups 元素的資訊。

表 104. StageGroups 元素資訊

元素屬性

此元素沒有屬性。

註解

無。

範例

無。

Setter

此元素會為 在 [屬性 ] 屬性中命名的屬性值指定屬性設定。

項目資訊

表 105 提供了有關 Setter 元素的資訊。

表 105. Setter 元素資訊

元素屬性

表 106 列出了 Setter 元素的屬性並提供其描述。

表 106. Setter 元素的屬性和對應值

註解

無。

範例

無。

階段

此元素指定 StageGroup 中的階段，並包含一或多個 PageRef 元素。

項目資訊

表 107 提供了有關 階段 元素的資訊。

表 107. 舞台元素資訊

元素屬性

表 108 列出了 階段 元素的屬性，並提供了每個元素的描述。

表 108. 舞台元素的屬性和對應值

註解

無。

範例

無。

Style

此元素會將設定 UDI 精靈外觀與風格的個別 Setter 元素進行分組，包括顯示在精靈頂端的標題，以及 UDI 精靈上顯示的橫幅影像。

項目資訊

表 109 提供了有關 Style 元素的資訊。

表 109. 樣式元素資訊

元素屬性

此元素沒有屬性。

註解

無。

範例

<Style>
  <Setter Property="bannerFilename">UDI_Wizard_Banner.bmp</Setter>
  <Setter Property="title">Operating System Deployment (OSD) Refresh Wizard</Setter>
</Style>

工作

這個元素會指定要在父 Page 元素中指定的頁面上執行的工作。

項目資訊

表 110 提供了 有關任務 元素的資訊。

表 110. 工作元素資訊

元素屬性

表 111 列出了 任務 元素的屬性，並提供了每個元素的描述。

表 111. 任務元素的屬性和對應值

註解

無。

範例

無。

工作

此元素會針對 Page 元素將一組工作分組。

項目資訊

表 112 提供 Tasks 元素的相關資訊。

表 112. 任務元素資訊

元素屬性

表 113 列出了 Tasks 元素的屬性，並提供每個元素的描述。

表 113. tasks 元素的屬性和對應值

註解

無。

範例

無。

驗證程式

此元素會為父項 Field 元素中指定的欄位控制項指定驗證程式。

項目資訊

表 114 提供 Validator 元素的相關資訊。

表 114. 驗證程式元素資訊

元素屬性

表 115 列出了 Validator 元素的屬性並提供其描述。

表 115. 驗證器元素的屬性和對應值

註解

無。

範例

無。

Wizard

此元素會指定所有其他元素的根。

項目資訊

表 116 提供 精靈 元素的相關資訊。

表 116. 精靈元素資訊

元素屬性

此元素沒有屬性。

註解

無。

範例

<Wizard>
   + <DLLs>
   + <Style>
   + <Pages>
   + <StageGroups>
</Wizard>