共用方式為

Windows App SDK 部署指南適用於需框架支援的封裝應用程式

本文提供使用 Windows App SDK 部署架構相依封裝應用程式的指引（請參閱 什麼是 MSIX？）。 其他架構相依封裝選項的等同主題是 Windows App SDK 部署指南，適用於以外部位置進行封裝或未封裝的架構相依應用程式。

Overview

根據預設，當您在 Visual Studio中使用 WinUI 3 範本建立專案時，您的專案會被設定為透過單一專案 MSIX 將應用程式建置為 MSIX 套件（請參閱 使用單一專案 MSIX封裝應用程式），或者透過 Windows 應用程式封裝專案（請參閱 在 Visual Studio中設定 MSIX 封裝傳統型應用程式）。 接著，您可以根據 在 Visual Studio 中對桌面或 UWP 應用程式進行封裝的指示，為您的應用程式建置 MSIX 套件。 為應用程式建置 MSIX 套件之後，您有數個選項可 管理 MSIX 部署。

若要深入瞭解已封裝應用程式在使用 Windows App SDK 時可能需要的套件，請參閱 Windows App SDK 的部署架構。 這些套件包括 Framework、 Main 和 Singleton 套件;這些文件皆由 Microsoft 簽署並發行。 部署已封裝應用程式有兩個主要需求：

  1. 部署 Windows App SDK 架構套件。
  2. 呼叫部署 API。

Prerequisites

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

部署 Windows App SDK 架構套件

Windows App SDK 架構套件包含運行時間所使用的 Windows App SDK 二進位檔，並隨您的應用程式一起安裝。 架構對於 Windows App SDK 的不同通道有不同的部署需求。

穩定版

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

然而，如果你手動使用獨立的 Windows 應用程式封裝專案來建置你的應用程式套件，那麼你必須在檔案中宣告一個 Application (package).wapproj，例如以下內容：

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

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

預覽版本

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

呼叫部署 API

請參閱 初始化 Windows App SDK。

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

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

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

Important

在 Windows App SDK 1.0 版本中，只有完全信任或具備 packageManagement 限制功能的打包的應用程式，才有權限使用 Deployment API 來安裝 Main 和 Singleton 套件依賴。 部分信任封裝應用程式的支援將會在更新版本中推出。

您應該在應用程式程序初始化後調用部署 API，但在您的應用程式使用依賴 Singleton 套件的 Windows App SDK 執行期間功能之前（例如推播通知）。 部署 API 的主要方法是 DeploymentManager 類別的靜態 GetStatus 和 Initialize 方法。

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

Important

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

部署 API 範例應用程式

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

探索部署 API 範例應用

解決安裝錯誤

如果部署 API 在安裝 Windows App SDK 執行時間套件期間發生錯誤，則會傳回描述問題的錯誤碼。

例如，如果你的應用程式不是完全信任，或沒有 packageManagement 的限制功能，那你就會收到 ACCESS_DENIED 錯誤代碼。 若要檢閱您可能會遇到的其他錯誤碼及其可能的原因，請參閱 Windows 應用程式的封裝、部署及查詢的疑難排解。

如果錯誤碼未提供足夠的資訊，您可以在詳細的事件記錄檔中找到更多診斷資訊（請參閱 取得診斷資訊）。

如果您遇到無法診斷的錯誤，請在 WindowsAppSDK GitHub 存放庫中 提出錯誤碼和事件記錄檔的問題，以便我們可以調查問題。

  • Last updated on