共用方式為

Windows 應用程式 SDK 1.0 的穩定通道版本資訊

  • 發行項

穩定通道提供的 Windows 應用程式 SDK 版本可支援生產環境的應用程式使用。 使用穩定版 Windows 應用程式 SDK 的應用程式也可以發布至 Microsoft Store。

重要連結：

最新穩定通道版本：

Windows 應用程式 SDK 的下載項目

注意

Windows 應用程式 SDK Visual Studio 延伸模組 (VSIX) 不再以獨立下載的形式發布。 它們改在 Visual Studio 內 的Visual Studio Marketplace 提供。

1.0.4 版

這是 Windows 應用程式 SDK 的維修版本，其中包含 1.0 版的重要錯誤修正。

錯誤修正 (1.0.4)

  • 已修正 AppBars 當做 Page.TopAppBar 或 Page.BottomAppBar 使用時無法在螢幕上轉譯的問題。
  • 已修正應用程式的套件名稱字元為 12 個或以下時，如果使用來自 MUXControls.dll 的 WinUI 控制項就會立即當機的問題。 如需詳細資訊，請參閱 GitHub 的問題 6360。
  • 已修正會造成鍵盤捷徑和其他情境發生問題的觸控輸入問題。 如需詳細資訊，請參閱 GitHub 的問題 6291。
  • 已修正以 MSIX 封裝或獨立部署的應用程式無法部署的問題。
  • 已修正應用程式有時會在拖放操作中當機的問題。 如需詳細資訊，請參閱 GitHub 上的問題 7002。

1\.0.3 版

這是 Windows 應用程式 SDK 的維修版本，其中包含 1.0 版的重要錯誤修正。

錯誤修正 (1.0.3)

  • 已修正 C/C++ 執行階段 (CRT) 未安裝時，內含 WebView2 的 C# 應用程式會在啟動時當機的問題。
  • 已修正會造成鍵盤捷徑和其他情境發生問題的觸控輸入問題。 如需詳細資訊，請參閱 GitHub 的問題 6291。

備註：我們通常不會在維修版本新增功能，但此版本的 WebView2 修正必須更新至最新版的 WebView2 SDK (1020.46 至 1185.39)。 如需 WebView2 1.0.1185.39 的詳細資訊，請參閱 WebView2 SDK 版本資訊，WebView2 Runtime的其他資訊則請參閱發布應用程式和 WebViewView2 執行階段。

1\.0.2 版

這是 Windows 應用程式 SDK 的維修版本，其中包含 1.0 版的重要錯誤修正。

錯誤修正 (1.0.2)

  • 已修正捲動至 ListView 尾端會導致應用程式當機的版面配置循環問題。 如需詳細資訊，請參閱 GitHub 上的問題 6218。
  • 已修正 C/C++ 執行階段 (CRT) 未安裝時，C# 應用程式會在啟動時當機的問題。 不過，使用 WebView2 的 C# 應用程式仍需要 CRT。 如需詳細資訊，請參閱 GitHub 上的問題 2117。
  • 已修正採用單一專案 MSIX 的應用程式未產生 .appinstaller 檔案的問題。 如需詳細資訊，請參閱 GitHub 上的問題 1821。
  • 已修正 WinUI 應用程式不支援 .NET 6 dotnet build 的問題。

1\.0.1 版

這是 Windows 應用程式 SDK 的維修版本，其中包含 1.0 版的重大錯誤修正，並支援多視窗。

錯誤修正 (1.0.1)

  • 已修正 MddBootstrapAutoinitializer 在啟用 ImplicitUsings 時無法編譯的問題。 如需詳細資訊，請參閱 GitHub 上的問題 1686。
  • 已修正 WebView2 的焦點意外遺失導致輸入和選取問題的問題。 如需詳細資訊，請參閱 GitHub 的問題 5615 & 問題 5570。
  • 已修正在 WinUI 3 應用程式使用自訂標題列時，Visual Studio 的應用程式內工具列無法點擊的問題。
  • 已修正在 WinUI 3 應用程式使用自訂標題列時，貼齊式版面配置無法顯示的問題。 如需詳細資訊，請參閱 GitHub 的問題 6333 & 問題 6246。
  • 已修正以仍在載入的 UIElement 呼叫 Window.SetTitlebar 時，如果設定 Window.ExtendsContentIntoTitleBar 屬性會造成例外狀況的問題。
  • 已修正單一專案 MSIX 應用程式不支援 dotnet build 的問題。
  • 已修正安裝封裝應用程式後，未封裝的應用程式無法安裝的問題。 如需詳細資訊，請參閱 GitHub 的問題 1871。
  • 已修正滑鼠拖曳作業過程中效能會降低的問題。
  • 已修正在未封裝應用程式呼叫 GetWindowIdFromWindow() 時當機的問題。 如需詳細資訊，請參閱 GitHub 討論 1891。

1.0 版的限制和已知問題也適用於1.0.1版。

此外，針對有自訂標題列的應用程式，我們在此版本進行了變更 (並修正許多問題)，其中包括修正用於拖&放作業的玻璃視窗。 建議您使用預設值和預設行為 (請試用看看！)。 如果您的標題列使用邊界，藉此讓預設標題按鈕可互動，建議您將標題欄的背景設定為紅色，然後調整邊界，將拖曳區域延伸至標題控制項，藉此將拖曳區域視覺化。

新功能

在 WinUI 3 應用程式的相同執行緒上建立多個視窗的功能已經穩定並啟用。 如需詳細資訊，請參閱 GitHub.com 的 問題 5918。

1.0 版

下列各節說明 1.0 版的新功能、更新功能、限制和已知問題。

WinUI 3

WinUI 3 是 Windows 應用程式 SDK 適用的原生使用者體驗 (UX) 架構。 在此版本中，我們已新增多個 Windows 應用程式 SDK 0.8 的新功能，並緩解了 1.0 Preview 版本的問題。

新增和更新功能：

  • 我們已新增控制項 (PipsPager、Expander、BreadcrumbBar) 並更新現有控制項，藉此反映 WinUI 2.6 的最新 Windows 樣式。
  • WinUI 已支援單一專案 MSIX 封裝，方法是使用「已封裝的空白應用程式...」範本建立新應用程式。
  • 我們現在已支援部署未封裝在 Windows 版本 1809 和更高版本的 WinUI 3 應用程式。 如需詳細資訊，請參閱建立您的第一個 WinUI 3 (Windows 應用程式 SDK) 專案。
  • WinUI 3 專案現在已可將目標版本設為 Windows 10 版本 1809。 之前只能設為 1903 版。
  • Visual Studio 2022 Preview 5 和 GA 已支援應用程式內工具列、熱重新載入& WinUI 封裝應用程式的即時視覺化樹狀結構。

重要限制：

  • 已封裝與未封裝 WinUI 應用程式共有的已知問題：

    • 參照 C++ Windows 執行階段元件的 C++ 或 C# 應用程式發生的執行階段錯誤：

      • 若要解決，請將下列目標新增到 Windows 執行階段元件的 .vcxproj 結尾：
      <Target Name="GetPriIndexName">
<PropertyGroup>
    <!-- Winmd library targets use the default root namespace of the project for the App package name -->
    <PriIndexName Condition="'$(RootNamespace)' != ''">$(RootNamespace)</PriIndexName>
    <!-- If RootNamespace is empty fall back to TargetName -->
    <PriIndexName Condition="$(PriIndexName) == ''">$(TargetName)</PriIndexName>
</PropertyGroup>
</Target>
      • 預期會發生類似 WinRT 來源錯誤 - 0x80004005：「無法從 'ms-appx:///BlankPage.xaml'.' 找到資源」的錯誤。

  • 使用單一專案 MSIX 的 WinUI 應用程式 (已封裝的空白應用程式範本) 的已知問題：

    • 除非重新啟動 Visual Studio，否則缺少 [封裝&發佈] 功能表項目：在 Visual Studio 2019 和 Visual Studio 2022 使用已封裝的空白應用程式 (桌面版 WinUI 3) 專案範本建立具有單一專案 MSIX 的新應用程式時，除非您關閉並重新開啟 Visual Studio，否則發布專案的命令不會顯示在功能表中。
    • 若未安裝選用的「C++ (v14x) 通用 Windows 平台工具」元件，則具有單一專案 MSIX 的 C# 應用程式無法編譯。 如需詳細資訊，請參閱安裝 Windows 應用程式 SDK 的工具。
    • 在具有單一專案 MSIX 的應用程式中，使用參照的 Windows 執行階段元件所定義的類型時可能發生執行階段錯誤：若要解決，請將可啟動的類別項目手動新增至 appxmanifest.xml。
      • C# 應用程式預期會發生「COMException：類別未註冊 (0x80040154 (REGDB_E_CLASSNOTREG))」的錯誤。
      • C++/WinRT 應用程式預期會發生「winrt::hresult_class_not_registered」的錯誤。

  • 未封裝的 WinUI 3 應用程式 (未封裝的應用程式) 的已知問題：

  • 封裝和部署 WinUI 應用程式時的已知問題：

    • 具有單一專案 MSIX 的 WinUI 應用程式 (已封裝的空白應用程式範本) 不支援 Package 命令。 請改用 Package & Publish 命令來建立 MSIX 套件。
    • 若要使用 Pack 命令從 C# 類別庫建立 NuGet 套件，請確認運作中的 Configuration 是 Release。
    • C++ Windows 執行階段元件不支援使用 Pack 命令來建立 NuGet 套件。

如需詳細資訊或開始使用 WinUI 進行開發，請參閱：

視窗化

Windows 應用程式 SDK 提供 AppWindow 類別，它可讓過去容易使用的 Windows.UI.WindowManagement.AppWindow 預覽類別演進，使它可供所有 Windows 應用程式使用，包括 Win32、WPF 和 WinForms。

新功能：

  • AppWindow 是一種高層級視窗化 API，可讓視窗化情境變得容易操作，與 Windows 使用者體驗及其他應用程式良好整合。 代表應用程式內容的系統管理容器中的高層級抽象層。 這個容器是您裝載內容的位置，且代表使用者在螢幕上調整應用程式大小與移動時所互動的實體。 如果您是熟悉 Win32 的開發人員，可將 AppWindow 視為 HWND 的高層級抽象層。
  • DisplayArea 代表 HMONITOR 的高層級抽象層，與 AppWindow 的原則相同。
  • DisplayAreaWatcher 可讓開發人員觀察顯示器拓撲的變更，並列舉系統目前定義的 DisplayAreas。

如需詳細資訊，請參閱管理應用程式視窗 (Windows 應用程式 SDK)。

輸入

這些輸入 API 支援 WinUI，並為開發人員提供較低層級的 API 介面，以便達成更進階的輸入互動。

新功能：

重要限制：

  • 所有 PointerPoint 靜態 factory 函式皆已移除：GetCurrentPoint、GetCurrentPointTransformed、GetIntermediatePoints 和 GetIntermediatePointsTransformed。
  • Windows 應用程式 SDK 不支援使用指標識別碼擷取 PointerPoint 物件。 不過，您可以改用 PointerPoint 成員函式 GetTransformedPoint 擷取現有 PointerPoint 物件的轉變版本。 針對中繼點，您可以使用 PointerEventArgs 成員函式 GetIntermediatePoints 和 GetTransformedIntermediatePoints。
  • 直接使用平台 SDK API Windows.UI.Core.CoreDragOperation 對於 WinUI 應用程式不適用。
  • PointerPoint 屬性 RawPosition 和 ContactRectRaw 已移除，因為它們參照非預測值，這些值與 OS 的正常值相同。 請改用 Position 和 ContactRect。 指標預測功能現在是由 Microsoft.UI.Input.PointerPredictor API 物件來處理。

應用程式生命週期

通常應用程式生命週期功能已經存在 UWP 平台，且已經納入 Windows 應用程式 SDK 供桌面應用程式類型使用，尤其未封裝的主控台應用程式、Win32 應用程式、Windows 表單應用程式和 WPF 應用程式。 Windows 應用程式 SDK 導入的這些功能無法使用在 UWP 應用程式，因為 UWP 平台本身已經有相同功能。

重要

如果您正在處理 UWP 應用程式，請參閱從 UWP 移轉至 Windows 應用程式 SDK (機器翻譯)。

非 UWP 應用程式也能封裝到 MSIX 套件。 雖然這些應用程式可使用部分 Windows 應用程式 SDK 的應用程式生命週期功能，但如有資訊清單方法，就必須使用這類方法。 舉例來說，它們無法使用 Windows 應用程式 SDK 的 RegisterForXXXActivation API，且必須改為透過資訊清單註冊大量啟用。

已封裝應用程式的所有限制也適用於已封裝的 WinUI 應用程式，此外亦請參考下述其他考量。

重要考量：

  • 豐富啟用： GetActivatedEventArgs

  • 註冊/取消註冊大量啟用

  • 單一/多實例

    • 未封裝的應用程式：完全可用。
    • 已封裝的應用程式：完全可用。
    • WinUI 應用程式：如果應用程式想要偵測其他執行個體並重新導向啟用，就必須儘早執行，並在初始化任何視窗等動作之前完成。若要達成此目的，應用程式必須定義 DISABLE_XAML_GENERATED_MAIN，並撰寫自訂的 Main (C#) 或 WinMain (C++)，以便讓它執行偵測和重新導向。
    • RedirectActivationToAsync 是非同步呼叫，如果您的應用程式正在執行 STA，請勿等候非同步呼叫。 如果是 Windows Forms 和 C# WinUI 應用程式，您可以視需要宣告 Main 為非同步。 如果是 C++ WinUI 和 C# WPF 應用程式，您無法將 Main 宣告為非同步，因此您必須將重新導向呼叫移至其他執行緒，確保不會封鎖 STA。
    • 如需詳細資訊，請參閱應用程式生命週期 API 的應用程式執行個體。

  • 電源/狀態通知

已知問題：

  • 檔案類型關聯性會錯誤將 %1 編碼為 %251 設定動詞處理常式的命令列範本時，使未封裝的 Win32 應用程式當機。 您的部份解決辦法是手動將登錄值手動邊即為 %1。 如果目標檔案路徑有空格，則此問題仍會失敗，且此情境沒有解決辦法。
  • 這些單一/多重執行個體錯誤將會在即將推出的維修修補程式中修正：
    • 編譯 x86 時，AppInstance 重新導向無法運作
    • 註冊金鑰、取消註冊金鑰，然後再重新註冊會導致應用程式當機

DWriteCore

DWriteCore 是 DirectWrite 的 Windows 應用程式 SDK 實作 (DirectWrite 是用於高品質文字渲染、與解析度無關的輪廓字體以及完整 Unicode 文字和佈局支援的 DirectX API)。 DWriteCore 是 DirectWrite 的一種形式，可在低至 Windows 10 版本 1809 (10.0，17763 版) 的 Windows 版本上執行，並讓您自由地跨平台使用。

功能：

DWriteCore 包含 DirectWrite 的所有功能，但存在一些例外。

重要限制：

  • DWriteCore 不包含以下 DirectWrite 功能：
    • 各工作階段字型
    • 使用者定義的字元 (EUDC) 字型
    • 字型串流 API
  • 低層級轉譯 API 僅提供部分支援。
  • DWriteCore 不與 Direct2D 互通，但您可以使用 IDWriteGlyphRunAnalysis 和 IDWriteBitmapRenderTarget。

如需詳細資訊，請參閱 DWriteCore 概觀。

MRT 核心

MRT Core 是新式 Windows 資源管理系統的簡化版本，會隨 Windows 應用程式 SDK 一起發布。

重要限制：

  • 在 .NET 專案中，如果應用程式已經組建，已複製並貼到專案資料夾的資源檔案就不會在按 F5 後加入索引。 重新組建應用程式即可解決問題。 如需更多資訊，請參閱問題 1503。

  • 在 .NET 專案中，如果使用 Visual Studio UI 將資源檔案新增至專案，預設可能不會將檔案加入索引。 如需更多資訊，請參閱問題 1786。 若要解決此問題，請移除 CSPROJ 檔案中的下列項目：

    <ItemGroup>
    <Content Remove="<image file name>" />
</ItemGroup>
<ItemGroup>
    <PRIResource Remove="<resw file name>" />
</ItemGroup>

  • 如果是未封裝的 C++ WinUI 應用程式，資源 URI 不會正確組建。 若要解決此問題，請在 vcxproj 新增下列項目：

    <!-- Add the following after <Import Project="$(VCTargetsPath)\Microsoft.Cpp.props" /> -->

<PropertyGroup>
    <AppxPriInitialPath></AppxPriInitialPath>   
</PropertyGroup>

有關更多信息，請參閱使用 MRT Core 管理資源。

部署

新增和更新功能：

重要限制：

  • 啟動程序載入程式 API 的 .NET 包裝函式僅供未封裝的 .NET 應用程式用於簡化 Windows 應用程式 SDK 的存取。
  • 只有完全信任或具備 packageManagement 受限功能的 MSIX 封裝應用程式有權限使用部署 API 來安裝主要且單一的套件相依性。 我們會在之後的版本支援部分信任的封裝應用程式。
  • 在 x64 系統對使用 DeploymentManager.Initialize 方法的 x86 應用程式執行 F5 測試時，請先執行 WindowsAppRuntimeInstall.exe，確保 x64 架構已經安裝。 否則，由於 Visual Studio 並未部署 x64 架構 (通常透過 Store 部署或側載而造成)，您會遇到 NOT_FOUND 錯誤。

其他限制和已知問題

  • 不支援任何 CPU 組建元件：新增 Windows 應用程式 SDK 至支援任何 CPU 的現有 .NET 應用程式或元件時，您必須指定所需的架構：x86、x64 或 arm64。

  • 從 .NET 5 升級至 .NET 6：在 Visual Studio UI 升級時，可能會遇到組建錯誤。 您可以手動將專案檔的 TargetFrameworkPackage 更新為下列項目來解決問題：

      <TargetFramework>net6.0-windows10.0.19041.0</TargetFramework>

  • 如未安裝 C++ UWP 工具，C# 單一專案 MSIX 應用程式就無法編譯。 如果您有 C# 單一專案 MSIX 的專案，就必須安裝 C++ (v14x) 通用 Windows 工具的選用元件。

  • 安裝多個 Visual Studio 2019 版本時，之後的語言 VSIX 無法安裝到 Visual Studio 2019。 如果您已安裝多個 Visual Studio 2019 版本 (例如發布版和預覽版)，接著安裝 C++ 和 C# 的 Windows 應用程式 SDK VSIX，則第二項安裝會失敗。 若要解決問題，請在安裝第一種語言 VSIX 之後解除安裝 Visual Studio 2019 的單一專案 MSIX 封裝工具。 如需詳細了解此問題，請參閱這項意見反應。

  • DispatcherQueue.TryEnqueue (恢復發送器佇列執行緒的執行) 的替代方案是使用 Windows 實作程式庫 (WIL) 的 resume_foreground 協助程式功能：

    1. 對專案新增 Microsoft.Windows.ImplementationLibrary NuGet 套件的參照。
    2. 新增 #include <wil/cppwinrt_helpers.h> 到 pch.h。
    3. 新增 #include <winrt/Microsoft.UI.Dispatching.h> 到 pch.h。
    4. 接著 co_await wil::resume_foreground(your_dispatcherqueue);。