針對在外部位置進行封裝或未封裝的應用程式，使用 Windows 應用程式 SDK 執行階段 (機器翻譯)

發行項
04/03/2024

注意

如果您的應用程式是使用 MSIX 技術安裝，請參閱架構相依封裝應用程式的 Windows 應用程式 SDK 部署指南。

如果您的應用程式並未使用 MSIX 安裝 (也就是說，它封裝時含有外部位置的或未封裝)，您必須先初始化 Windows 應用程式 SDK，才能呼叫 WinUI 3、應用程式生命週期、MRT Core 和 DWriteCore 等 Windows 應用程式 SDK 功能。您的應用程式必須先初始化 Windows 應用程式 SDK 執行階段，才能使用 Windows 應用程式 SDK 的任何其他功能。

從 Windows 應用程式 SDK 1.0 起，如果您的應用程式是從自動初始化 (設定專案屬性 <WindowsPackageType>None</WindowsPackageType>) 開始建立，就能自動完成此作業。如需示範，請參閱建立您的第一個 WinUI 3 專案。
但是，如果您有進階需求 (例如透過顯示自己的自訂 UI 或記錄來處理錯誤，或如果您需要載入的 Windows 應用程式 SDK 版本與您組建的版本不同)，請繼續閱讀本主題。在這些情境中，您可以明確呼叫啟動程序載入程式 API，不必自動初始化。

上述兩種技術都可讓不使用 MSIX 的應用程式在執行階段對 Windows 應用程式 SDK 產生動態相依性。

如需動態相依性的背景資訊，請參閱 MSIX 架構套件和動態相依性。

在幕後，並選擇退出自動模組初始化

上述 WindowsPackageType 屬性所產生的程式碼會利用模組初始化表達式來呼叫啟動程序載入程式 API。啟動程序載入程式會執行繁重的工作，找出 Windows 應用程式 SDK，並讓目前的程序使用。產生的程式碼會同時處理初始化和關機。您可以使用下列專案屬性來控制初始化的行為：

<WindowsAppSDKBootstrapAutoInitializeOptions_Default>true</WindowsAppSDKBootstrapAutoInitializeOptions_Default>
- 使用預設選項。
<WindowsAppSDKBootstrapAutoInitializeOptions_None>true</WindowsAppSDKBootstrapAutoInitializeOptions_None>
- 不使用任何選項。
<WindowsAppSDKBootstrapAutoInitializeOptions_OnError_DebugBreak>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnError_DebugBreak>
- 如果發生錯誤，請呼叫 DebugBreak()。
<WindowsAppSDKBootstrapAutoInitializeOptions_OnError_DebugBreak_IfDebuggerAttached>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnError_DebugBreak_IfDebuggerAttached>
- 因發生錯誤而呼叫 DebugBreak() 的條件，必須是偵錯工具已附加到程序時。
<WindowsAppSDKBootstrapAutoInitializeOptions_OnError_FailFast>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnError_FailFast>
- 如果發生錯誤，請執行快速檢錯。
<WindowsAppSDKBootstrapAutoInitializeOptions_OnNoMatch_ShowUI>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnNoMatch_ShowUI>
- 如果找不到相符的 Windows 應用程式 SDK 執行階段，請提示使用者主動取得。
<WindowsAppSDKBootstrapAutoInitializeOptions_OnPackageIdentity_NoOp>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnPackageIdentity_NoOp>
- 如果呼叫了含有套件身分識別的程序，就是成功 (否則失敗並傳回錯誤)。

如果您想讓應用程式擁有明確的控制權，可以在應用程式的啟動初期直接呼叫啟動程序呼叫程式 API。在此情況下，專案檔中不需要 WindowsPackageType。

注意

除了自動初始化和啟動程序載入程式 API 之外，Windows 應用程式 SDK 也會提供動態相依性 API 的實作。此 API 可讓您的未封裝應用程式與任何架構套件相依 (而不只是 Windows 應用程式 SDK 架構套件)，且會由啟動程序載入程式 API 在內部使用。如需動態相依性 API 的詳細資訊，請參閱使用動態相依性 API 在執行階段參照 MSIX 套件。

退出 (或加入) 自動模組初始化

專案屬性 <WindowsAppSdkBootstrapInitialize>false</WindowsAppSdkBootstrapInitialize> 會停用上述的自動模組初始化 (未呼叫啟動程序載入程式 API)。這可讓您的應用程式採取動作，直接呼叫啟動程序載入程式 API。

從 Windows 應用程式 SDK 1.2 版 (穩定通道) 起，自動模組初始化僅適用於會產生可執行檔的專案 (也就是 OutputType 專案屬性設為 Exe 或 WinExe)。這是為了避免預設將自動初始化設定式新增至類別庫 DLL 和其他非可執行檔。如果您的非可執行檔 (例如由不會初始化啟動程序載入程式的主機處理序所載入的測試 DLL) 需要自動初始化設定式，您可以使用 <WindowsAppSdkBootstrapInitialize>true</WindowsAppSdkBootstrapInitialize> 在專案中明確啟用自動初始化設定式。

使用啟動程序載入程式 API

重要

從 1.1 版起，您已可使用下述的 MddBootstrapInitialize2 函式。

啟動程序載入程式 API 包含三個會在 Windows 應用程式 SDK 的 mddbootstrap.h 標頭檔案中宣告的 C/C++ 函式：MddBootstrapInitialize、MddBootstrapInitialize2 和 MddBootstrapShutdown。這些函式是由 Windows 應用程式 SDK 的啟動程序載入程式庫所提供。該程式庫是一個小型 DLL，必須與您的應用程式一起發布，它不屬於架構套件本身。

MddBootstrapInitialize2

此函式會初始化呼叫程序，它使用的 Windows 應用程式 SDK 架構套件版本會與您傳遞至函式參數的條件最相符。通常，這個程序參照的架構套件版本會與已安裝的 Windows 應用程式 SDK NuGet 套件相符。如果多個套件符合準則，則會選取最佳候選專案。此函式必須是應用程式啟動時第一批呼叫的函式之一，才能確保啟動程序載入程式元件可以正確地初始化 Windows 應用程式 SDK，並將執行階段參照新增至架構套件。

啟動程序載入程式 API 會使用動態相依性 API，將 Windows 應用程式 SDK 執行階段的架構套件新增至目前程序的套件圖形，並啟用套件的存取。

此函式也會初始化動態相依性存留期管理員 (DDLM)。該元件提供基礎結構，避免 OS 在由未封裝應用程式使用中時對 Windows 應用程式 SDK 架構套件提供維修服務。

MddBootstrapShutdown

此函式會將呼叫 MddBootstrapInitialize 後產生的目前程序所作出的變更移除。呼叫該函式之後，您的應用程式就無法再呼叫 Windows 應用程式 SDK API，包括動態相依性 API。

此函式也會關閉動態相依性存留期管理員 (DDLM)，讓 Windows 可以視需要維修架構套件。

啟動程序載入程式 API 的 .NET 包裝函式

雖然您可以直接從 .NET 應用程式呼叫 C/C++ 啟動程序載入程式 API，但需要透過平台叫用來呼叫函式。在 Windows 應用程式 SDK 1.0 和之後的版本中，啟動程序載入程式 API 的 .NET 包裝函式可在 Microsoft.WindowsAppRuntime.Bootstrap.Net.dll 組件取得。該組件為 .NET 開發人員提供更簡單且更自然的 API 來存取啟動程序載入程式的功能。 Bootstrap 類別提供靜態的 Initialize、TryInitialize 和 Shutdown 函式來包裝 MddBootstrapInitialize 和 MddBootstrapShutdown 函式的呼叫，用於最常見的情境。如需示範如何將 .NET 包裝函式用於啟動程序載入程式 API 的範例，請參閱教學課程：在使用 Windows 應用程式 SDK 的含外部位置封裝應用程式或未封裝應用程式中使用啟動程序載入程式 API中的 C# 操作指示。

如需啟動程序載入程式 API 的 .NET 包裝函式詳細資訊，請參閱下列資源：

啟動程序載入程式 C# API。
動態相依性規格第 6.1.4 節。
Bootstrap.cs：啟動程序載入程式 API 的 .NET 包裝函式開放原始碼實作。

啟動程序載入程式 API 的 C++ 包裝函式

從 Windows 應用程式 SDK 1.1 起，您可使用啟動程序載入程式 API 的 C++ 包裝函式。

請參閱啟動程序載入程式 C++ API。

在應用程式資訊清單中宣告 OS 相容性

若要宣告作業系統 (OS) 相容性，並避免 Windows 應用程式 SDK 預設為 Windows 8 的行為的 (以及潛在的當機)，您可以並排加入應用程式資訊清單到含有外部位置的封裝應用程式或未封裝應用程式。請參閱應用程式資訊清單 (這是宣告 DPI 感知之類的項目，並在建置期間內嵌至應用程式的 .exe 檔案)。如果您要將 Windows 應用程式 SDK 的支援新增到現有應用程式，而不是透過 Visual Studio 專案範本建立新應用程式，這麼做可能有問題。

如果您的專案還沒有並排的應用程式資訊清單，請將新的 XML 檔案加到專案中，並按照應用程式資訊清單的建議來命名。將以下範例所示的相容性元素和子元素加入檔案。這些值會控制應用程式程序中執行元件的 quirks 層級。

以您要指定的 Windows 版本編號 (必須是 10.0.17763.0 或之後的版本) 來取代 maxversiontested 元素的 Id 屬性。請注意，設定較高的值意味著舊版 Windows 無法正確執行應用程式，因為每個 Windows 版本都只認識更舊的版本。因此，如果您希望應用程式在 Windows 10 版本 1809 (10.0，版本 17763) 執行，則應將 10.0.17763.0 值保留不變，或者為應用程式支援的其他值新增多個 maxversiontested 元素。

<?xml version="1.0" encoding="UTF-8"?>
<assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0">
    <compatibility xmlns="urn:schemas-microsoft-com:compatibility.v1">
        <application>
            <!-- Windows 10, version 1809 (10.0; Build 17763) -->
            <maxversiontested Id="10.0.17763.0"/>
            <supportedOS Id="{8e0f7a12-bfb3-4fe8-b9a5-48fd50a15a9a}" />
        </application>
    </compatibility>
</assembly>

共用方式為