Windows 應用程式 SDK 框架依賴封包應用程式部署指南

本文提供有關部署使用 Windows 應用程式 SDK 的依賴框架的套件化應用程式的指引（參見 什麼是 MSIX？）。 其他框架依賴型打包選項的相關主題為 Windows 應用程式 SDK 部署指南，針對以外部位置打包或未打包的框架依賴應用程式。

Overview

預設情況下，當你在 Visual Studio 中使用 WinUI 3 範本建立專案時，專案會設定為將應用程式建置成 MSIX 套件，使用單一專案 MSIX（參見「使用單專案 MSIX 打包你的應用程式」）或 Windows 應用程式封裝專案（參見「在 Visual Studio 設定你的桌面應用程式以 MSIX 打包）。 接著，您可以依照 使用 Visual Studio 將桌面或 UWP 應用程式封裝 的指示，來建立您的應用程式的 MSIX 套件。 為應用程式建置 MSIX 套件之後，您有數個選項可 管理 MSIX 部署。

想了解更多關於你的封裝應用程式在使用 Windows 應用程式 SDK 時可能需要的套件，請參閱 Deployment 架構中的 Windows 應用程式 SDK。 這些套件包括 Framework、 Main 和 Singleton 套件;這些文件皆由 Microsoft 簽署並發行。 部署已封裝應用程式有兩個主要需求：

  1. 部署Windows 應用程式 SDK框架套件。
  2. 呼叫部署 API。

Prerequisites

  • 對於已封裝的應用程式，VCLibs 架構套件相依性是需求。 如需詳細資訊，請參閱 Desktop Bridge 的 C++ 執行階段框架套件。
  • C#。 需要 .NET 6 或更新版本。 更多資訊請參見 .NET Downloads。

部署 Windows 應用程式 SDK 框架套件

Windows 應用程式 SDK 框架套件包含執行時使用的 Windows 應用程式 SDK 二進位檔，並隨你的應用程式安裝。 該框架對不同 Windows 應用程式 SDK 通道有不同的部署要求。

穩定版

當你在開發電腦上安裝穩定版的 Windows 應用程式 SDK NuGet 套件，並使用提供的 WinUI 專案範本建立專案時，產生的套件清單會包含一個 PackageDependency 元素，指定對框架套件的依賴。

然而，如果你用獨立的 Windows 應用程式封裝專案手動建置應用程式套件，則必須在 檔案中宣告 Application (package).wapproj，如下：

<ItemGroup>
   <PackageReference Include="Microsoft.WindowsAppSDK" Version="1.8.260209005">
       <IncludeAssets>build</IncludeAssets>
   </PackageReference>
</ItemGroup>

該套件相依性可確保當您的應用程式部署至另一部計算機時，會安裝架構套件。

預覽版本

當你在開發電腦上安裝 Windows 應用程式 SDK NuGet 套件的預覽版時，Windows 應用程式 SDK 框架套件的預覽版本會在建置時部署，作為 NuGet 套件的相依。

呼叫部署 API

另見 初始化 Windows 應用程式 SDK。

部署 API 由 Windows 應用程式 SDK 框架套件提供，並可在 Microsoft.Windows 中取得。ApplicationModel.WindowsAppRuntime namespace. Windows 應用程式模型不支援宣告對 Main 和 Singleton 套件的依賴。 因此，基於下列原因，需要部署 API：

  1. 若要針對不在 Framework 套件中的功能部署 Singleton 套件（例如推播通知）。
  2. 若要部署Main套件，以便能透過Microsoft Store為架構套件啟用自動更新。

對於 非 透過商店發行的套件應用程式，作為開發者，你負責分發 Framework 套件。 我們建議您呼叫部署 API，以便將任何關鍵的服務更新送達。 請注意，若要在 Framework 套件之外使用功能（例如推播通知），必須部署 Singleton 套件（這可以使用部署 API 來完成，或使用您自己的安裝方法轉散發 MSIX 套件）。

Important

只有完全信任或具備 packageManagement 限制能力的套件應用程式，才有權限使用 Deployment API 安裝 Main 和 Singleton 套件相依。

在你的應用程式進程初始化後，但在應用程式使用 Windows 應用程式 SDK 執行時的功能（例如推送通知）之前，應該呼叫部署 API。 部署 API 的主要方法是 DeploymentManager 類別的靜態 GetStatus 和 Initialize 方法。

  • GetStatus 方法會回傳目前載入的 Windows 應用程式 SDK 執行時的部署狀態。 使用此方法判斷是否需要先安裝 Windows 應用程式 SDK 執行套件，才能讓現有應用程式使用 Windows 應用程式 SDK 功能。
  • Initialize 方法會驗證所有所需的套件是否已達到目前載入的Windows 應用程式 SDK執行時所需的最低版本。 如果遺漏任何套件相依性，則方法會嘗試註冊那些遺漏的套件。 從 Windows 應用程式 SDK 1.1 開始，Initialize 方法也支援強制部署 Windows 應用程式 SDK 執行時套件的選項。 這會關閉 主 執行時和 單例 執行時套件的所有程序，進而中斷它們的服務（例如，推播通知在此期間不會發送通知）。 你應該只呼叫一次 初始化 。 對於透過 Start Without Debugging 和 Start Debugging Visual Studio指令部署的應用程式，你不需要呼叫 Initialize 來部署。

Important

Visual Studio屬性<WindowsAppSdkDeploymentManagerInitialize>的預設值為true。 所以如果你想明確呼叫 DeploymentManager.Initialize，請在你的 Visual Studio 專案檔案中設定 <WindowsAppSdkDeploymentManagerInitialize>false</WindowsAppSdkDeploymentManagerInitialize>。

部署 API 範例應用程式

如需更多關於如何使用 DeploymentManager 類別中的 GetStatus 與 Initialize 方法的指引，請瀏覽可用的範例應用程式。

探索部署 API 範例應用

解決安裝錯誤

如果部署 API 在安裝 Windows 應用程式 SDK 執行時套件時遇到錯誤，會回傳描述問題的錯誤代碼。

下表列出部署 API 常見的錯誤代碼及其典型原因：

錯誤代碼 Name 常見原因
0x80070005 ACCESS_DENIED 此應用程式未獲得完整信任，或未具備 packageManagement 受限制功能。 以提升的權限執行，或新增所需的權限。
0x80073CF0 ERROR_INSTALL_OPEN_PACKAGE_FAILED MSIX 套件損壞或無法存取。 確認套件檔案是否完整且路徑正確。
0x80073CF3 ERROR_INSTALL_PREREQUISITE_FAILED 必要的相依性套件遺失或不相容。 確保已安裝 VCLibs 框架套件及其他任何前置需求。
0x80073D06 使用中的錯誤封包 一個或多個套件正在使用中，無法更新。 關閉所有使用 Windows 應用程式 SDK 執行環境的應用程式，然後再嘗試。
0x80073CFB ERROR_PACKAGE_ALREADY_EXISTS 套件版本已經註冊完成。 這只是通知資訊，你的應用程式可以繼續執行。
0x80073CF9 安裝失敗錯誤 一般性安裝失敗。 詳情請參考活動記錄（見下文）。

小提示

關於完整的 MSIX 套件安裝錯誤代碼清單，請參閱 Windows 應用程式的故障排除、部署與查詢。

如果錯誤碼未提供足夠的資訊，您可以在詳細的事件記錄檔中找到更多診斷資訊（請參閱 取得診斷資訊）。 事件日誌位於事件檢視器中的 應用程式與服務記錄>Microsoft>Windows>AppxDeployment-Server 下。

如果你遇到無法診斷的錯誤，請在 WindowsAppSDK GitHub repo 中提交錯誤代碼和事件日誌，讓我們能調查問題。

  • Last updated on