發佈一個未封裝的 WinUI 3 應用程式

未封裝發行版讓你能在沒有 MSIX 的情況下發佈 WinUI 3 應用程式——對於無法部署 MSIX 的企業場景，或偏好傳統資料夾式安裝的開發者來說非常實用。

這很重要

開始前請先檢視這些限制。 未封裝的 WinUI 3 應用程式有限制，會影響你的發佈策略：

  • 單檔 EXE — 未封裝、自包含的 WinUI 3 應用程式支援PublishSingleFile（Windows 應用程式 SDK 1.5 及更新版本）。 此過程產生單一可散發的 EXE;相依關係會在首次啟動時擷取到暫存目錄。 需要特定的 MSBuild 屬性——詳見下方 的單檔案 EXE 。 依賴框架的應用程式和打包式應用程式不支援 PublishSingleFile。
  • Runtime dependency — Windows 應用程式 SDK 執行時必須存在於使用者的機器上。 你必須將執行時安裝程式與應用程式捆綁，或使用自包含部署（這會大幅增加輸出大小）。 請參見下方的 部署Windows 應用程式 SDK執行時。
  • 無套件身份 — 沒有套件清單，您的應用程式無法使用基於清單的Windows功能：無法透過 App Installer 或 Store 自動更新，無法在背景工作註冊，也無法透過套件清單進行檔案類型關聯或開始選單磁貼自訂。 （傳統的 Win32 機制，如安裝程式撰寫的登錄表條目與捷徑仍然有效。）
  • No MSIX/package-identity Store submission — 此分發模型不具備套件識別碼，因此不符合作為 Microsoft Store 的 MSIX 提交資格。 （你可以透過 MSI 或 EXE 安裝程式提交路徑提交傳統安裝程式到商店，但那是與本文描述的不同工作流程。）

如果這些限制是你的疑慮，可以考慮<打包你的應用程式>，這是大多數應用程式的建議，或者<將打包與外部位置結合>，這樣可以增加套件識別，而不需要完整轉換 MSIX。

關於所有打包選項的詳細資訊，請參閱「打包與部署 Windows 應用程式」總覽。

如果你選擇拆包新的或現有的 WinUI 應用程式，請依照以下步驟進行：

在你的 .csproj 檔案中，找到第一個現有的 PropertyGroup 元素，該元素同時包含 OutputType、 TargetFramework、 及其他屬性。

  • 在這個 WindowsPackageType 元素中加入 project 屬性。 將其值設定為 None。
<Project ...>
  ...
  <PropertyGroup>
    <WindowsPackageType>None</WindowsPackageType><!-- add this -->
    <OutputType>WinExe</OutputType>
    <TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>
    ...
  </PropertyGroup> 
  ...
</Project>

要從 Visual Studio 啟動應用程式（Debugging或 Without Debugging），從 Start 下拉選單選擇 Unpackaged啟動設定檔。 如果選擇了 Package 設定檔，你會在 Visual Studio 看到部署錯誤。 如果你是從命令行或Windows檔案總管啟動應用程式（.exe），則不需要執行此步驟。

Visual Studio - 開始下拉選單，C# 應用程式的未封裝啟動設定檔被選取並高亮顯示。

啟動管理器 API

設定 專案屬性會讓 auto-initializer 找到並載入最適合你應用程式的 Windows 應用程式 SDK版本。

如果你有進階需求（例如自訂錯誤處理，或載入特定版本的 Windows 應用程式 SDK），那你可以直接呼叫啟動器 API。 更多資訊請參見使用 Windows 應用程式 SDK 執行階段來處理封裝於外部位置或未封裝的應用程式，以及 教學：使用 Windows 應用程式 SDK 的應用程式中，如何在封裝於外部位置或未封裝的情況下使用 bootstrapper API。

欲了解更多關於啟動工具的資訊，請參閱部署 架構與框架依賴應用程式的概述。

部署 Windows 應用程式 SDK 執行環境

未封裝的 WinUI 3 應用程式依賴於使用者機器上安裝 Windows 應用程式 SDK 執行環境。 你有兩種方式可以確保執行環境的存在：

選項1：Windows 應用程式 SDK 執行時安裝程式（.exe）（推薦）

請將 Windows 應用程式 SDK 執行安裝程式與應用程式一併附上。 執行時安裝程式是一個可重新分發的 .exe，負責安裝所需的Windows 應用程式 SDK執行時套件。 從 Windows 應用程式 SDK releases 頁面下載，並搭配你自己的安裝程式或設定腳本一起綁定。 完整指引請參見 使用Windows 應用程式 SDK執行環境，適用於有外部位置或未封裝 的應用程式。

使用者必須執行一次執行時安裝程式。 後續的應用程式更新不需要重新安裝執行時，除非所需的 Windows 應用程式 SDK 版本改變。

選項二：自給自足部署

在專案檔案中設定 <WindowsAppSDKSelfContained>true</WindowsAppSDKSelfContained>，將 Windows 應用程式 SDK 執行時直接打包到應用程式的輸出資料夾。 這消除了執行時的依賴——使用者不需要另外安裝任何東西。

<PropertyGroup>
  <WindowsPackageType>None</WindowsPackageType>
  <WindowsAppSDKSelfContained>true</WindowsAppSDKSelfContained>
</PropertyGroup>

取捨是：你的輸出資料夾會大幅增加（包含完整執行時），而且每次應用程式更新都會承載完整的執行時負載。 這個選項用於簡單的發行情境，或是無法控制目標機器安裝內容時。

→ 部署使用Windows 應用程式 SDK的未封裝應用程式，提供完整的執行時部署參考。

單一檔案 EXE

從 Windows 應用程式 SDK 1.5 開始，未封裝、自包含的 WinUI 3 應用程式支援 .NET PublishSingleFile 部署模型。 這會產生一個可散布的 EXE 檔案——所有相依關係都會打包進 EXE，並在啟動時解壓到暫存目錄。

這很重要

PublishSingleFile 不支援已封裝的應用程式（MSIX 或採用外部位置封裝）或相依於架構的應用程式。 這兩種條件——既未包裝 又 自成一體——都是必須的。

MSBuild 必修屬性

Windows 應用程式 SDK 包含一個建置階段驗證目標（WindowsAppSDKSingleFileVerifyConfiguration），當 PublishSingleFile 已設定時，會檢查你的專案組態。 以下是必要的屬性：

<PropertyGroup>
  <WindowsPackageType>None</WindowsPackageType>
  <WindowsAppSDKSelfContained>true</WindowsAppSDKSelfContained>
  <SelfContained>true</SelfContained>
  <EnableMsixTooling>true</EnableMsixTooling>
  <IncludeAllContentForSelfExtract>true</IncludeAllContentForSelfExtract>
  <PublishSingleFile>true</PublishSingleFile>
</PropertyGroup>

建置程序會在缺少 EnableMsixTooling、WindowsPackageType=None 或 IncludeAllContentForSelfExtract 時發出 錯誤，並在缺少 SelfContained 或 時發出 WindowsAppSDKSelfContained。

Note

抽取行為：IncludeAllContentForSelfExtract=true 這表示相依關係會在首次啟動時解壓到使用者機器上的臨時目錄——該應用程式並非零解壓二進位檔。 單一 EXE 方便分發，但必須有擷取的檔案才能執行。 WindowsAppSdkUndockedRegFreeWinRTInitialize自動初始化器會負責找出已解壓縮的執行階段；如果您選擇不使用它，則必須在程式啟動前將 MICROSOFT_WINDOWSAPPRUNTIME_BASE_DIRECTORY 環境變數設為 AppContext.BaseDirectory。

若無法接受單一檔案擷取，替代方案

如果你需要無須解壓縮的單一二進位檔，或者你的部署環境無法接受解壓縮行為，請考慮：

  • 使用 MSIX 封包 ——使用者擁有單一安裝程式體驗（App Installer 處理所有檔案），同時擁有商店資格、套件識別碼及內建更新
  • 使用傳統安裝程式（WiX、Inno Setup） ——將輸出資料夾包裝成一個 EXE 安裝程式，透明解壓並安裝所有所需檔案
  • 使用不同的框架——WPF 和 WinForms 應用程式支援PublishSingleFile更廣泛的設定

未封裝應用程式的分發考量

未封裝的 WinUI 3 應用程式缺乏套件識別碼，這表示它們無法存取某些 Windows 功能：

  • 不會透過 App Installer 或 Microsoft Store 自動更新
  • 沒有透過套件清單進行背景任務註冊
  • 沒有透過套件清單建立檔案類型關聯或協定處理的處理器
  • 無法透過套件清單自訂開始功能表的磚塊

如果你需要這些功能，可以考慮將 外部位置封包 作為中間路徑，增加套件識別，且不需要完整 MSIX 轉換。

→ 發佈你的第一個Windows應用程式，完整了解 WinUI 3 及其他Windows應用框架的散布選項。

  • 上次更新時間：