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

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

目前有下列穩定通道版本可供使用:

如果您想要將現有應用程式從舊版的 Windows 應用程式 SDK 升級為較新版本,請參閱將現有專案更新為最新版的 Windows 應用程式 SDK

下載 Windows 應用程式 SDK

注意

Windows App Visual Studio 延伸模組 (VSIX) 不再以個別下載的形式散發。 它們可在Visual Studio內的Visual Studio Marketplace 中使用。

1.5 版

版本 1.5.1 (1.5.240311000)

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

  • 已修正因為無法複製「map.html」而無法建置獨立應用程式的問題。
  • 已修正因為拒絕有效令牌而無法初始化的問題 MapControl 。 如需詳細資訊,請參閱 GitHub #9324
  • 已修正使用藍色背景載入的問題 MapControl 。 如需詳細資訊,請參閱 GitHub #9377
  • 已修正按兩下的形箭號 NavigationViewItem 未在按一下時正確展開或折疊的問題。 這也會導致功能表在模式中 PaneDisplayMode="Top" 按兩下箭號時顯示為空白。 如需詳細資訊,請參閱 GitHub #9423#9426
  • 修正使用觸控或手寫筆點選 NavigationViewItem 會導致專案無法回應任何未來輸入的問題。 如需詳細資訊,請參閱 GitHub #9429
  • 修正按兩下區域中的項目 NavigationView.PaneFooter 時發生當機的問題。 如需詳細資訊,請參閱 GitHub #9396
  • 修正了功能表中的圖示有時會在錯誤的地方顯示的問題。 如需詳細資訊,請參閱 GitHub #9409
  • 修正了在離開視窗和返回之前,壓克力不會在功能表上顯示的問題。 如需詳細資訊,請參閱 GitHub #9406
  • 已修正初始化期間可能發生的 TextBox/RichEditBox 當機。 如需詳細資訊,請參閱 GitHub #9216
  • 修正了一些嘈雜的例外狀況, NavigationView 這些例外狀況會擲回並攔截到破壞。
  • 已修正「捏合縮放」手勢有時會顯示為平移或點選的問題,因為訊息引發不正確 PointerCaptureLost

1.5 版

下列各節說明 1.5 版的新功能和更新的功能和已知問題。

在現有的 Windows 應用程式 SDK 1.4 應用程式中,您可以將 Nuget 套件更新為 1.5.240227000 (請參閱使用 NuGet 封裝管理員 在 Visual Studio 中安裝和管理套件一節)。

如需更新的運行時間和 MSIX,請參閱下載 Windows 應用程式 SDK

XAML Islands 運行時間和關機更新

當任何線程上的最後一個 XAML 視窗關閉時,以 XAML Islands 為基礎的應用程式,WinAppSDK 1.4 和 WinAppSDK 1.5 之間有行為差異。

  • 在 WinAppSDK 1.4 中,當線程的最後一個 XAML 視窗關閉時,XAML 運行時間一律會結束線程的事件迴圈。
  • 在 WinAppSDK 1.5 中:
    • 如果您的應用程式是 WinUI Desktop 應用程式,預設行為仍然與 WinAppSDK 1.4 中的相同。
    • 如果您使用 XAML 做為 DesktopWindowXamlSource (“XAML Islands”) API,則預設行為現在是 XAML 不會自動結束線程的事件迴圈。
    • 在這兩種模式中,您可以藉由設定 Application.DispatcherShutdownMode 屬性來變更此行為。

如需詳細資訊,請參閱可用屬性的檔 Application.DispatcherShutdownMode 。 這會完成 GitHub 提案 #8492

在 XAML 執行時間的存留期內,以 XAML Islands 為基礎的應用程式,WinAppSDK 1.4 和 WinAppSDK 1.5 的行為差異:

  • 在 WinAppSDK 1.4 中,如果給定線程上的所有 WindowsXamlManagerDesktopWindowXamlSource 物件都已關閉或關閉,或 DispatcherQueue 在該線程上執行 ,XAML 運行時間會在階段關閉 DispatcherQueue.FrameworkShutdownStarting 時關閉,則 XAML 執行時間會在線程上關閉。
  • 在 WinAppSDK 1.5 中,XAML 執行時間只有在該線程上執行的 DispatcherQueue 關閉時,才會在線程上關閉 (Xaml 運行時間一律在 DispatcherQueue.FrameworkShutdownStarting 階段期間關閉)。

如需詳細資訊,請參閱可用時 類別 WindowsXamlManager 的檔。

的行為 WindowsXamlManager.InitializeForCurrentThread()差異如下:

  • 在 WinAppSDK 1.4 中, WindowsXamlManager.InitializeForCurrentThread() 傳回具有每個呼叫之物件的唯一 WindowsXamlManager 實例。
  • 在 WinAppSDK 1.5 中, WindowsXamlManager.InitializeForCurrentThread() 如果線程上已經存在,則會傳回現有的實例。 Close/Dispose() 現在會忽略 。

WinUI 地圖 控件

WinUI Maps 控制件現已推出! 此控制項由 WebView2 和 Azure 地圖服務 提供,並提供下列功能:

  • 使用地圖按鈕或觸控來移動瀏覽和縮放。
  • 將地圖的樣式變更為衛星、地形或街道檢視。
  • 以程式設計方式將可互動釘選與開發人員可自定義的圖示新增至地圖。
  • 地圖以初始載入為中心位置的開發人員自定義。
  • 控制開發人員隱藏或顯示移動瀏覽、縮放和地圖樣式的按鈕。

WinUI 3 Maps Control

注意

若要使用 Maps 控件,您需要 Azure 地圖服務 鍵。 若要建立金鑰,請參閱建立 Web 應用程式的 Azure 地圖服務 檔頁面。

控件 Maps 是完全新的,歡迎您的意見反應評估其未來方向!

新增 SelectorBar 控件

在 1.5 中,我們已新增 SelectorBar 控件,讓用戶能夠在多個數據檢視之間切換。 此控件先前在我們的 1.5 藍圖上稱為“SegmentedControl”。

WinUI 3 SelectorBar Control

CommandBarFlyout 主要命令中的標籤

如果 Label 已在上AppBarButton設定 屬性,則 已更新的CommandBarFlyout視覺效果,以顯示主要命令區域中專案的文字標籤。 先前,區域中的主要命令 CommandBarFlyout 只會顯示圖示,但現在它們可以同時顯示圖示和標籤,以改善可用性。

WinUI 3 CommandBarFlyout Labels

自定義環境/選項的 WebView2 支援

WinUI WebView2 控制項現在會公開使用自訂 CoreWebView2EnvironmentCoreWebView2ControllerOptions來自定義基礎CoreWebView2物件的能力。 這可讓應用程式作者指定要載入 WebView2Runtime 的替代路徑、選擇使用不同的 UserDataFolder,或設定 IsPrivateModeEnabledScriptLocale選項。

適用於 .NET 8 的 Suppport

我們在最近的 1.4 服務版本中新增了 .NET 8 的支援,但仍會保留使用平臺特定 RID 的警告。 在 1.5 中,我們已完成這項工作,使警告不再存在。

改善偵錯和來源可用性

我們現在會將 Microsoft-ui-xaml 存放庫中程式代碼的 Github 來源伺服器資訊插入公用符號中,讓調試程式自動下載原始程式碼。 我們也對整個 WinAppSDK 中的符號進行其他修正和改善,以改善偵錯體驗。

改善偵錯版面配置週期的功能

在 WinUI 應用程式中偵錯版面配置週期可能是一項挑戰,因此在 1.5 中, DebugSettings 對象現在會公開選項,讓版面配置程式能夠更輕鬆地偵錯和修正應用程式中的配置週期。

來自 WinAppSDK 的其他新功能

  • 已新增 PublishSingleFile 部署模型的支援。 如需 PublishSingleFile 的詳細資訊,請參閱 單一檔案部署檔
  • 已新增螢幕助讀程式支援、文字縮放支援和其他輔助功能功能的改善。
  • 根據我們排定優先順序的 GitHub Bug 待辦專案,各種穩定性和效能改善。

個別發行的新功能

適用於 C# 和 C++ 的 WinAppSDK Visual Studio 範本新版本正透過 Visual Studio Marketplace 發行,且會在 1.5 版之後幾周出現。 使用新版本時,範本現在可以獨立於 WinAppSDK 版本發行,讓我們在取得客戶更新方面更有彈性。

其他先前規劃的功能

在 1.5 中,我們已在藍圖上宣佈的下列功能上取得進展,但未完成這些功能。 它們將繼續進入1.6時間範圍。

  • 索引標籤視窗
  • WebView2 的拖放支援
  • 數據表檢視和筆跡控件的調查

動態光源已從藍圖中移除。目前為止。

已知問題

  • 使用包含 .xaml 檔案等資源的連結庫時,您可能會在運行時間遇到錯誤訊息,指出找不到這些資源。 在此情況下,可能需要插入 <ShouldComputeInputPris>true</ShouldComputeInputPris> 項目檔,以確保包含這些資源。
  • 按兩下的箭號 NavigationViewItem 不再正確展開或折疊在按兩下時。 按兩下仍可運作,如同按兩下上的 NavigationViewItem其他地方一樣。

錯誤修正

  • 已修正套用間距至折疊項目的問題 StackPanel 。 如需詳細資訊,請參閱 GitHub 問題 #916
  • 已修正在關閉另一個應用程式窗口之後,捲動控件無法再運作的問題。 如需詳細資訊,請參閱 GitHub 問題 #9292#9355
  • 已修正在第一個畫面呈現之前將 設定 DebugSettings.EnableFrameRateCountertrue 時的當機。 如需詳細資訊,請參閱 GitHub 問題 #2835
  • 已修正 C++ 的潛在編譯錯誤,其中某些標頭不包含必要的相依性。 請注意,順序變更 #include 可能會影響某些應用程式,例如,如果應用程式使用 2023 之前的 C++/WinRT 版本,可能會造成編譯錯誤 IInspectable 。 如需詳細資訊,請參閱 GitHub 問題 #9014
  • 已修正系結無法在 內ItemsRepeaterDataTemplate運作的問題ElementName。 如需詳細資訊,請參閱 GitHub 問題 #560
  • 已修正在已啟用應用程式內工具列的Visual Studio下執行應用程式時當機。 需要 Visual Studio 17.8 Preview 2 或更新版本,才能完整取得修正程式。 如需詳細資訊,請參閱 GitHub 問題 #8806
  • 已修正快速捲動時有時可能會當機的問題 AnnotatedScrollbar
  • 已修正功能表文字有時會遭到截斷的問題。
  • 已修正教學提示未收到適當焦點的問題。 如需詳細資訊,請參閱 GitHub 問題 #3257
  • 已修正在啟動時將 的 設定TailVisibilityTeachingTipCollapsed 時,當應用程式當機的問題。 如需詳細資訊,請參閱 GitHub 問題 #8731
  • 已修正使用連結庫時 PRI 檔案處理方式的問題。 如需詳細資訊,請參閱 GitHub 問題 #8857
  • 已修正 1.5-experimental2 版本未產生投影 DLL 的問題。 如需詳細資訊,請參閱 GitHub 問題 #4152
  • 修正了 文字格式快顯 RichEditBox 上的省略號按鈕未正確顯示動作清單的問題。 如需詳細資訊,請參閱 GitHub 問題 #9140
  • 已修正無法正確處理鍵盤快捷鍵的問題 ListView 。 如需詳細資訊,請參閱 GitHub 問題 #8063
  • 已修正使用 AccessKey 關閉視窗的存取違規問題。 如需詳細資訊,請參閱 GitHub 問題 #8648
  • 已修正使用 AccessKey 關閉視窗時的當機。 如需詳細資訊,請參閱 GitHub 問題 #9002
  • 已修正在內MenuFlyoutItemMenuBar影響 文字對齊的問題。 如需詳細資訊,請參閱 GitHub 問題 #8755
  • 已修正在按下滑鼠右鍵時,醒目提示的文字不會保持醒目提示的問題。 如需詳細資訊,請參閱 GitHub 問題 #1801
  • 已修正導致非使用中視窗在關閉時當機應用程式的問題。 如需詳細資訊,請參閱 GitHub 問題 #8913
  • 已修正使用滑鼠中間按鈕捲動時可能會停止回應應用程式的問題,並在之後立即按下滑鼠左鍵。 如需詳細資訊,請參閱 GitHub 問題 #9233
  • 已修正在使用自定義 NavigationViewItem時,導致應用程式在啟動時當機的問題。 如需詳細資訊,請參閱 GitHub 問題 #8814
  • NavigationView已修正省略號按鈕錯誤產生錯誤的問題。 如需詳細資訊,請參閱 GitHub 問題 #8380
  • 已修正無法在多視窗應用程式中正確轉譯的問題 SystemBackdrop 。 如需詳細資訊,請參閱 GitHub 問題 #8423
  • 修正了插入 到 開頭 ObservableCollection時的重複問題。 如需詳細資訊,請參閱 GitHub 問題 #8370

1\.4 版

版本 1.4.5 (1.4.240211001)

這是 Windows 應用程式 SDK的服務版本,其中包含1.4版的重要錯誤修正。

  • 已修正在使用滑鼠滾輪捲動時按下滑鼠按鈕時,可能會停止應用程式的問題。 如需詳細資訊,請參閱 GitHub 問題 #9233
  • 修正參考 NuGet 套件鏈結時重複資產的問題。 如需詳細資訊,請參閱 GitHub 問題 #8857
  • 已修正數 BreadcrumbBar 個問題,包括記憶體流失、省略號功能表空白時當機,以及視窗內錯誤限制的省略號功能表。
  • 已修正釋放圖形資源時關機的潛在當機問題。

版本 1.4.4 (1.4.231219000)

這是 Windows 應用程式 SDK的服務版本,其中包含1.4版的重要錯誤修正。

  • 已修正 WinUI 3 診斷安全性問題。
  • 修正了透過觸控啟用時,密碼方塊未顯示螢幕鍵盤的輸入問題。 如需詳細資訊,請參閱 GitHub 問題 #8946
  • 已修正導致 Microsoft.UI.Xaml.Controls.dll 檔案大小意外成長的問題。
  • CommandBarFlyout已修正設定焦點時可能導致當機的問題。
  • 已更新 .NET 8 RID 特定資產處理的 Windows 應用程式 SDK 支援。
  • 已修正導致某些交換鏈被定位或伸展不正確的問題。

版本 1.4.3 (1.4.231115000)

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

  • 已修正一個問題:功能表可能會在短時間內沒有背景出現。
  • 已修正在特定多監視器案例中可能發生的當機問題。
  • 已修正操作功能表可能出現在螢幕外的問題。
  • 已修正窗口樣式和最大化行為的問題。 如需詳細資訊,請參閱 GitHub 問題 #8996
  • 修正了Islands的問題,其中焦點可能會意外從另一個控件抓取。
  • 已修正 上的 NavigationView定位順序問題。
  • 修正了在標題欄頂端可能會顯示白色列的轉譯問題。 如需詳細資訊,請參閱 GitHub 問題 #8947
  • 各種效能修正。

版本 1.4.2 (1.4.231008000)

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

  • 已修正因記憶體和物件配置過多而造成explorer.exe損毀問題。
  • 已修正防止返回按鈕正常運作的標題列互動問題。
  • 已修正導致針對包含來源檔案多次產生警告的問題。
  • 已修正影響操作功能表效能的問題。
  • 已修正.lnk快捷方式問題,讓目標.exe一律指向 WindowsApps 資料夾中套件的相同位置。
  • 已修正影響特定字型中索引文字正確轉譯的 DWriteCore 問題。
  • 已修正清單檢視中防止使用 Tab/Shift + Tab 對巢狀選取項目進行適當鍵盤瀏覽的問題。
  • 修正在第二次展開 ComboBox 之後,觸控中斷卷動 ComboBox 項目的問題。 如需詳細資訊,請參閱 GitHub 問題 #8831
  • 已修正 WinAppSDK 套件未包含某些語言的 WinUI 當地語系化資源的問題。
  • 已修正 檔案總管 與 XAML 如何顯示使用者慣用語言之間的不一致。
  • 已修正 檔案總管 導致使用中索引標籤下顯示細線的工藝問題。
  • 已修正某些架構提供的鍵盤快捷鍵未正確當地語系化的問題。 如需詳細資訊,請參閱 GitHub 問題 #2023
  • 已修正點選時重複捲動的 RepeatButton 控件問題。
  • 已修正 WinAppSDK 安裝程式.exe,以取得適當的資源版本資訊。

版本 1.4.1 (1.4.230913002)

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

  • 已修正效能問題,以改善第一個畫面的時間。
  • 已修正功能表未遵守 RequestedTheme的問題。 例如,此問題可能會導致白色背景上的白色文字。 如需詳細資訊,請參閱 GitHub 問題 #8756
  • 修正會導致壓克力背景在某些功能表中變成完全透明的問題。
  • 已修正 XAML 有時會造成 Windows 不必要地重新貼上桌面桌布的問題。
  • 已修正 和 TabNavigation = CycleListViewGridView的支持TabNavigation = Local,現在除了箭頭鍵之外,還能夠使用 TAB 在標頭和項目之間巡覽。
  • 已修正關閉工具提示時的一些嘈雜例外狀況。 如需詳細資訊,請參閱 GitHub 問題 #8699

1\.4 版

下列各節說明 1.4 版的新功能和更新的功能和已知問題。

在現有的 Windows 應用程式 SDK 1.3 應用程式中,您可以將 Nuget 套件更新為 1.4.230822000 (請參閱使用 NuGet 封裝管理員 在 Visual Studio 中安裝和管理套件一節)。

如需更新的運行時間和 MSIX,請參閱 Windows 應用程式 SDK 的下載。

自定義標題列 + AppWindow 標題列合併

WinUI 3 自定義標題欄會使用 AppWindow 標題欄實作,以及 NonClientInputPointerSource API,在 Windows 應用程式 SDK 1.4 中。 因此,這兩個標題欄實作現在的行為方式都與相同的功能和限制相同。 在所有支援的案例中,這完全回溯相容 - 任何具有自定義定義標題欄的應用程式都會像以前一樣運作。 但是,現在對於可能不熟悉自定義標題列的 WinUI 3 開發人員來說,現在更容易利用這些新功能來瞭解和使用它們:

  • 較佳的預設案例,開發人員不會特別定義標題欄元素(取代 WinUI 2 的後援標題列)
  • 標題欄中的不同拖曳區域,可讓您建立多個拖曳區域,並在非工作區的任何部分放置可點選的控件(標題欄區域)
  • 應用程式範圍的可拖曳區域,可放置於應用程式中的任何位置,或讓整個應用程式可拖曳
  • 更好的主題支援,可取代以資源為基礎的主題
    • 由於拖曳區域是透明的,所以每次都會遵循應用程序主題
  • 更多自定義:隱藏最小、最大值和關閉按鈕;將系統圖示放在標題欄中;或具有不同區域作為接收 NCHITTEST 回應的 標題 按鈕
  • 更多開發人員自由,可讓您混合和比對 AppWindow 標題欄 API,例如針對大部分案例使用較高層級的 WinUI 3 API,但搭配 AppWindow API 混合在較低層級的控制

Widget 更新

已為小工具提供者新增三個新介面,以實作: IWidgetProvider2IWidgetProviderAnalyticsIWidgetProviderErrorsIWidgetProvider2 可讓提供者回應使用者叫用的 自定義 動作,這與第一方小工具可用的動作相同。 IWidgetProviderAnalyticsIWidgetProviderErrors 介面由提供者用來收集小工具的遙測;與小工具的相關分析和失敗事件會傳達給個別的小工具提供者。 WidgetCustomizationRequestedArgsWidgetAnalyticsInfoReportedArgsWidgetErrorInfoReportedArgs 類別可用來傳達相關信息以支援新功能。

XAML Islands 不再實驗性

XAML Islands 和基礎 ContentIslands 平臺已不再是實驗性平臺。

  • 目前 XAML Islands 只會測試在 C++ 應用程式中使用。 此版本不包含任何方便的包裝函式元素,可用於 WPF 或 WinForms。
  • DesktopWindowXamlSource 和相關的類型已新增在適用於 XAML Islands 的 Microsoft.UI.Xaml.Hosting 命名空間中。 XamlRoot.ContentIslandEnvironment 已新增 ,以協助存取元素的基礎 Island 資訊。
  • 許多新類型已在 Microsoft.UI.Content 命名空間和 Microsoft.UI.Input 命名空間中引進,作為 XAML Islands 的基礎支援,或是使用此 ContentIslands 功能而不使用 XAML。
  • 在Island案例的 Microsoft.UI.Input.DragDrop 命名空間中新增了新的 DragDropManager (加號相關類型)。

ItemsView

我們引進了名為 ItemsView 的新清單控件,以及對應的具體 ItemContainer 類別。 ItemContainer 是具有內建選取狀態和視覺效果的輕量型容器,可輕易包裝所需的內容,並用於 ItemsView 集合控件案例。

  • 新的 ItemsView 控制件會顯示數據收集。 ItemsView類似於 ListViewGridView 控件,但使用ItemsRepeaterScrollViewItemContainerItemCollectionTransitionProvider 元件來建置。 它提供插入自定義 LayoutItemCollectionTransitionProvider 實作的獨特功能。 另一個主要優點是能夠即時切換版面配置,同時保留專案選取範圍。 內部ScrollView控制元件也提供控制件中GridViewListView/ScrollViewer無法使用的功能,例如能夠在程式設計卷動期間控制動畫。
    • ItemTransitionProvider上的新屬性ItemsRepeater(和新ItemsView控件)可讓您指定ItemCollectionTransitionProvider物件來控制該控件上的轉換動畫。 CreateDefaultItemTransitionProvider方法也已新增至 Layout,如果控件上ItemsView未明確提供後援轉換,則配置物件可提供後援轉換。
    • 在來源集合中,如果有任何配置方向的專案是以其索引為基礎的新 IndexBasedLayoutOrientation 屬性 Layout 。 預設值是 IndexBasedLayoutOrientation.None。 自訂版面配置會藉由呼叫 new (protected) SetIndexBasedLayoutOrientation 方法來設定此屬性。
    • 上的VirtualizingLayoutContextVisibleRect屬性會取得與Layout相關聯之 內FrameworkElement可見的檢視區矩形。 您可以覆寫受保護的虛擬 VirtualizingLayoutContext.VisibleRectCore 方法,以提供將從 屬性傳 VisibleRect 回的值。
  • LinedFlowLayout 類別通常用來配置集合控件的專案 ItemsView 。 它特別適合用來顯示圖片的集合。 它這樣做的方式是從左到右,從上到下,以同等高度的行。 圖片會填滿水平線,然後換行至下一行。 圖片可能裁剪在左邊緣和右邊緣,以放入線條。 當採用延展模式時,它們也可以水平展開,並在頂端和下邊緣裁剪以填滿線條。

來自 WinAppSDK 的新功能

  • 新的ThemeSettings類別,可讓 Win32 WinRT 應用程式偵測系統的高對比度設定何時變更,類似於 UWP 的輔助功能 設定 類別。 如需詳細資訊,請參閱 GitHub 上的主題 設定 API 規格
  • AccessKeyManager.EnterDisplayMode 是顯示所提供根目錄目前焦點元素之訪問鍵的新方法。 存取鍵在顯示叫用命令的按鍵提示時處於「顯示模式」,例如按下 小畫家 中的 Alt 鍵以顯示哪些按鍵對應至哪些控制件。 這個方法允許以程式設計方式進入顯示模式。
  • Application.ResourceManagerRequested會提供一個機制,以針對預設ResourceManager無法運作的案例,提供不同的IResourceManager資源 URI。 如需詳細資訊,請參閱 GitHub 上的 Application.ResourceManagerRequested API 規格
  • WebView2 SDK 的版本已從 1661.34 更新為 1823.32
  • Popup/FlyoutBase.IsConstrainedToRootBounds = false 現在支援,允許彈出視窗/飛出視窗延伸至父視窗界限之外。 SystemBackdrop屬性已新增至這些類型,以支援在這些不受限制的彈出視窗中擁有壓克力。 功能表預設會使用此項目來擁有壓克力。
  • ClosedFrameworkClosedIsClosed 已新增至 DesktopAcrylicControllerMicaController ,以改善物件/線程關機期間的處理。
  • DesktopAcrylicController.Kind 現在可以設定為在一些標準壓克力外觀之間進行選擇。
  • DispatcherQueue 有一些新事件和協助程式,可協助更妥善組織的關機,以及使用Islands的應用程式輕鬆執行標準支援的事件迴圈。
  • InputNonClientPointerSource 在 Microsoft.UI.Input 命名空間中,可用於自定義標題欄案例,以定義非工作區區域。 程式代碼可以註冊對應的事件,例如暫留和按兩下這些區域上的事件。
  • AppWindow 有一些新的協助程式可取得與 建立關聯 DispatcherQueue
  • 新的 TreeView.SelectionChanged 事件可讓開發人員在使用者或程式代碼後置變更 控件中 TreeView 選取的節點集時回應。
  • 新的 ScrollView 控制項提供 的新替代方案 ScrollViewer。 這個新控件與現有 ScrollViewer 控件的行為和 API 高度一致,但以 InteractionTracker為基礎,具有動畫驅動檢視變更等新功能,也設計為確保的完整功能 ItemsRepeater。 請參閱 更有彈性的 ScrollViewer ·問題 #108 •microsoft/microsoft-ui-xaml (github.com) 以取得詳細數據。 包括的各種新類型 ScrollPresenter是整體 ScrollView 模型的一部分。
  • 新的 AnnotatedScrollBar 控件會藉由提供簡單的方法來巡覽大型專案集合,來擴充一般滾動條的功能。 這是透過具有標籤作為標記的可點選滑軌來達成。 它也允許更細微地瞭解可捲動的內容,方法是在可點選滑軌上停留時顯示工具提示。

已知問題

錯誤修正

  • 已修正呼叫 Microsoft.Windows.AppLifecycle.AppInstance.Restart("") API 會導致未封裝的應用程式當機的問題。 如需詳細資訊,請參閱 GitHub 問題 #2792
  • 已修正 1.4-experimental1 中引進的安裝程序當機問題。 如需詳細資訊,請參閱 GitHub 問題 #3760
  • 已修正 TextBlock 中未正確移除文字刪除線的問題。 如需詳細資訊,請參閱 GitHub 問題 #1093
  • 已修正在 TabFocusNavigation 設定為 「一次」的面板中,導致 Shift + Tab 導覽不正確的問題。如需詳細資訊,請參閱 GitHub 問題 #1363
  • 修正了 C++/WinRT 中防止 {x:Bind} 使用具名 XAML 控件的 屬性正常運作的問題。 如需詳細資訊,請參閱 GitHub 問題 #2721
  • 已修正設定 所造成 WinUI Desktop 應用程式中的 DebugSettings.EnableFrameRateCounter = true運行時間 AccessViolation 問題。 如需詳細資訊,請參閱 GitHub 問題 #2835
  • 已修正未包含所需標頭的問題 XamlTypeInfo.g.cpp 。 如需詳細資訊,請參閱 GitHub 問題 #4907
  • 已修正同時多點觸控和滑鼠輸入所造成的當機問題。 如需詳細資訊,請參閱 GitHub 問題 #7622
  • 已修正當系統設定停用滑鼠上方非使用中視窗捲動時,導致作用中 WinUI 3 應用程式視窗無法捲動的問題。 如需詳細資訊,請參閱 GitHub 問題 #8764
  • 修正嘗試子類別 MediaPlayerElement時發生當機的問題。
  • 已修正 中的 TreeView某些損毀和記憶體流失問題。
  • 已修正使用鍵盤在 中 RadioButtons巡覽時可能發生的應用程式停止響應問題。
  • 已修正使用鍵盤在 中 PipsPager巡覽時當機的問題。
  • 已修正 WebView2 內容,以 設定 應用程式中的「文字大小」輔助功能設定來調整。
  • 已修正當顯示關閉時動畫執行時可能發生的當機。
  • 已修正在 1.3 中引進的效能問題,該問題會將 ~10% 的額外負荷新增至第一個版面配置/轉譯。

1.3 版

版本 1.3.3 (1.3.230724000)

這是 Windows 應用程式 SDK的服務版本,其中包含1.3版的重要錯誤修正。

  • 已修正當對話框關閉時,滑鼠有時會停止運作的問題。
  • 已修正因為系統上套件版本不符而導致應用程式無法安裝的部署問題。 如需詳細資訊,請參閱 GitHub 問題 #3740
  • 已修正在 1.3 Windows 應用程式 SDK 影響操作功能表定位的問題。
  • 已修正會導致某些 WinUI3 應用程式在某些情況下當應用程式關閉時當機的問題,因為 XAML 自行關閉太早。
  • 已修正字型圖示未以從右至左語言正確鏡像的問題。 如需詳細資訊,請參閱 GitHub 問題 #7661
  • 已修正當資源以不正確的順序損毀時,導致應用程式在關機時當機的問題。 如需詳細資訊,請參閱 GitHub 問題 #7924

版本 1.3.2 (1.3.230602002)

這是 Windows 應用程式 SDK的服務版本,其中包含1.3版的重要錯誤修正。

  • 已修正設定受保護的數據指標時當機。
  • 已修正在應用程式啟動期間 XamlMetadataProvider 中的效能問題。 如需詳細資訊,請參閱 GitHub 問題 #8281
  • 已修正 RichTextBlock 中超鏈接和觸控的問題。 如需詳細資訊,請參閱 GitHub 問題 #6513
  • 已修正 WebView2 中捲動和觸控板的問題。 如需詳細資訊,請參閱 GitHub 問題 #7772
  • 已修正更新 Windows 應用程式 SDK 有時需要重新啟動Visual Studio的問題。 如需詳細資訊,請參閱 GitHub 問題 #3554
  • 修正在調試程式中執行時關機時的嘈雜例外狀況。

版本 1.3.1 (1.3.230502000)

這是 Windows 應用程式 SDK的服務版本,其中包含1.3版的重要錯誤修正。

  • 已修正在設定 Content 為 Null 時,導致應用程式當機的問題。 如需詳細資訊,請參閱 GitHub 問題 #8416
  • 已修正在 XAML 中設定視窗標題時導致應用程式當機的問題,這是 1.3.0 中新增的新功能。 如需詳細資訊,請參閱 GitHub 問題 #3689
  • 已修正視窗在內容變更時不正確地取得焦點的問題。
  • 已修正使用 WinAppSDK 1.3 專案範本建立 C++ 項目的問題。
  • Visual Studio Marketplace 上更新的範本

1.3 版

下列各節說明 1.3 版的新功能和更新功能和已知問題。

在現有的 Windows 應用程式 SDK 1.2 應用程式中,您可以將 Nuget 套件更新為 1.3.230331000 (請參閱使用 NuGet 封裝管理員 在 Visual Studio 中安裝和管理套件一節)。

如需更新的運行時間和 MSIX,請參閱下載 Windows 應用程式 SDK

XAML 背景 API

透過 XAML 視窗內建的屬性,Mica 和 Background Acrylic 背景現在更容易在 WinUI 3 應用程式中使用。 如需 Xaml 背景屬性的詳細資訊,請參閱系統背景Mica 背景 API 檔。

public MainWindow()
{
    this.InitializeComponent();

    this.SystemBackdrop = new MicaBackdrop();
}

Window.AppWindow

取代數行未定案程序代碼,您現在可以直接從 Window 透過 Window.AppWindow使用 AppWindow API。

來自 WinAppSDK 的新功能

  • ApplicationModel.DynamicDependencyPackageDependency.PackageGraphRevisionId 取代已被取代的 MddGetGenerationId。
  • 環境管理員: EnvironmentManager.AreChangesTracked 告知您是否能夠在應用程式中追蹤環境管理員的變更。
  • 新的事件偵錯 設定。當無法解析參考的 Static/ThemeResource 查閱時,現在會引發 XamlResourceReferenceFailed。 此事件可讓您存取追蹤,該追蹤會詳細說明搜尋該索引鍵的架構,以便讓您偵錯 Static 和 ThemeResource 查閱失敗。 如需詳細資訊,請參閱 GitHub 上的追蹤 XAML 資源參考查閱失敗 API 規格。

其他更新

已知問題

由於 xaml 編譯程式最近的變更,升級至 1.3 的現有專案可能會遇到類似 Visual Studio 中的建置錯誤:

> C:\Users\user\\.nuget\packages\microsoft.windowsappsdk\\**1.3.230331000**\buildTransitive\Microsoft.UI.Xaml.Markup.Compiler.interop.targets(537,17): error MSB4064: The "PrecompiledHeaderFile" parameter is not supported by the "CompileXaml" task loaded from assembly: Microsoft.UI.Xaml.Markup.Compiler, Version=1.0.0.0, Culture=neutral, PublicKeyToken=de31ebe4ad15742b from the path: C:\Users\user\\.nuget\packages\microsoft.windowsappsdk\\**1.2.230118.102**\tools\net472\Microsoft.UI.Xaml.Markup.Compiler.dll. Verify that the parameter exists on the task, the <UsingTask> points to the correct assembly, and it is a settable public instance property.

這是由 Visual Studio 使用來自 1.2 的快取 xaml 編譯程式工作 dll 所造成,但從 1.3 使用不相容的 MSBuild 邏輯加以驅動,如上述錯誤文字所示。 因應措施是關閉 Visual Studio、重新啟動它,然後重載解決方案。

1.2 版

版本 1.2.5 (1.2.230313.1)

這是 Windows 應用程式 SDK的服務版本,其中包含1.2版的重要錯誤修正。

  • 已修正導致應用程式在組合關機期間當機的問題。
  • 已修正即使螢幕關閉,仍會導致應用程式繼續執行動畫的問題。
  • 已修正當滑鼠和鍵盤輸入同時發生時,導致 WebView2 中的滑鼠和觸控輸入失敗的問題。 如需詳細資訊,請參閱 GitHub 問題 #3266

版本 1.2.4 (1.2.230217.4)

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

  • 已修正導致獨立應用程式無法設定UAC設定的問題。 如需詳細資訊,請參閱 GitHub 問題 #3376
  • 已修正導致推播通知使用 PushNotificationChannel::ExpirationTime傳回不正確的到期時間的問題。 如需詳細資訊,請參閱 GitHub 問題 #3300
  • 已修正將雙精度浮點數當做參數傳遞至 x:Bind 函式時,導致負數被視為「無效」的問題。
  • 更新 WinUI VSIX 的數個修正程式。 這些更新包括簡化 app.manifest 中的專案範本 dipAwareness、移除 UWP 範本、更新本地化的資源檔、新增手機標識碼以解除封鎖市集提交,以及移除著作權聲明和授權。 如需詳細資訊,請參閱 GitHub 問題 #5659#3205#3323#3322#3143

版本 1.2.3 (1.2.230118.102)

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

  • 已修正當多個視窗關閉時,導致 WinUI 3 應用程式當機的問題。
  • 已修正呼叫 ThreadPoolTimer 介面的兩個或多個參考時,導致應用程式關閉當機的問題。 如需詳細資訊,請參閱 GitHub 問題 #7260#7239
  • 已修正導致所有單一專案 MSIX 應用程式以完全信任執行的問題。 如需詳細資訊,請參閱 GitHub 問題 #7766

版本 1.2.2 (1.2.221209.1)

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

  • 已修正導致市集和側載套件(例如從安裝程式、NuGet 和啟動載入器)在已安裝其他套件時無法安裝的問題。 如需詳細資訊,請參閱 GitHub 問題 #3168
  • 已修正使用觸控板捲動時造成遺失彈性效果和動畫曲線的問題。 如需詳細資訊,請參閱 GitHub 問題 #7874
  • 已修正 ListView 造成記憶體流失的問題。
  • 已修正在滑鼠暫留之後,按鈕範本不會遵守 Foreground 屬性的問題。 如需詳細資訊,請參閱 GitHub 問題 #7208
  • 已修正當 MediaElement 中沒有 MediaPlaybackItem 時,造成不必要的例外狀況的問題。
  • 已修正在內容轉換時導致 MediaPlayerElement 中出現白色畫面的問題。
  • 已修正導致 App.UnhandledException 無法攔截其他線程的例外狀況的其他問題。 如需詳細資訊,請參閱 GitHub 問題 #1259#5221

版本 1.2.1 (1.2.221116.1)

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

已修正在新增 WebView2 或 TextBox 控制件時,在 C++ WinUI 3 應用程式中啟動時導致當機的問題。 如需詳細資訊,請參閱 GitHub 問題 #7911#3117

1.2 版

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

注意

Visual Studio 2019 和 .NET 5 不再支援建置 C# 應用程式(請參閱 Windows 應用程式 SDK 1.2 移至 C# WinRT 2.0)。 您將需要 Visual Studio 2022 和下列其中一個 .NET SDK 版本:6.0.401 (或更新版本)、6.0.304、6.0.109。 發行時,WinAppSDK 1.2 也會支援 .NET 7。

若要更新 .NET SDK 版本,請安裝最新版的Visual Studio 2022,或流覽 .NET 下載。 在沒有必要 .NET SDK 版本的情況下更新 NuGet 套件時,您會看到如下的錯誤:「此版本的 WindowsAppSDK 需要 .NET 6+ 和WinRT.Runtime.dll 2.0 版或更新版本。」 若要將專案從 .NET 5.0 更新為 .NET 6.0,請開啟項目檔,並將 “TargetFramework” net6.0 變更為 ,並將 “Target OS version” 變更為適當的值 (例如 net6.0-windows10.0.19041.0)。

Windows 中的第三方小工具

小工具面板最初是在 Windows 11 中引進,而且僅限於顯示內建小工具。 小工具是小型UI容器,可顯示小工具面板上的文字和圖形,並與安裝在裝置上的應用程式相關聯。 使用 Windows 應用程式 SDK,身為第三方開發人員,您現在可以為已封裝的 Win32 應用程式建立小工具,並在 Windows 11 小工具面板本機進行測試。

如需小工具的詳細資訊,請參閱 小工具概觀

若要開始為您的應用程式開發小工具,請參閱 小工具服務提供者 開發檔和 Widget 設計必要條件、指引和最佳做法的基本概 念。

此版本的必要條件包括:

  • 在開發電腦上啟用開發人員模式。
  • 開發計算機正在執行 Windows Insider Preview 開發通道的 Windows 版本,其大於或等於 25217,且小工具面板版本為 521.20060.1205.0 或更新版本。

開發 Widget 時的已知限制

  • 第三方小工具只能在在此預覽版本中註冊的裝置上本機測試。
  • 小工具只能針對已封裝的 Win32 應用程式建立。 漸進式 Web Apps 的 Widget 計劃支援 Microsoft Edge 108

DisplayInformation

Windows 傳統型應用程式現在可以透過 WinAppSDK 中的 DisplayInformation 類別支援高動態範圍 (HDR) 和 自動色彩管理 (ACM)。 DisplayInformation 類別可讓您監視應用程式檢視的顯示相關信息。 這包括事件,可讓用戶端監視應用程式檢視中會影響檢視所在的顯示項目變更,以及可能會影響應用程式檢視的顯示變更。

WinUI 3

WinUI 3 應用程式可以使用 MediaPlayerElement 和 MediaTransportControls 媒體播放控件播放音訊和視訊 如需如何使用媒體控件和時機的詳細資訊,請參閱 媒體播放機

WinUI 3 已更新 WinUI 2.8 的最新控件、樣式和行為。 這些更新包括新增 InfoBadge 控制件、輔助功能和高對比度模式的改善,以及跨控件的錯誤修正。 如需詳細資訊,請參閱 WinUI 2.7 和 WinUI 2.8 的版本資訊

已修正問題

已知限制

  • 使用 Visual Studio 2022 17.4.0 建立新的 WinUI 3 專案時,將會參考 WinAppSDK 的預覽版本。 使用 NuGet 封裝管理員 更新此版本的參考。
  • 將 MediaPlayerElement.Source 設定為相對 URI (ms-appx/ms-resource) 會在未封裝的應用程式中失敗。 建議的因應措施是將相對 ms-appx:/// URI 轉換為完全解析的 file:/// URI。

針對使用 .NET 開發的應用程式進行修剪

.NET 開發人員現在可以發佈已修剪的 WinAppSDK 應用程式。 使用 CsWinRT 2.0 時,在 WinAppSDK 中散發的 C#/WinRT 投影現在可調整。 發佈已修剪的應用程式可藉由從可修剪的二進位檔中移除任何未使用的程式代碼,以減少應用程式的磁碟使用量。 應用程式也可能看到啟動效能改善。 使用基本的 Hello World 應用程式時,我們已看到 ~80% 的磁碟使用量改善,以及發佈修剪時的 ~7% 啟動效能改善。 使用 WinUI 資源庫時,我們看到了 ~45% 的磁碟使用量改善。

如需如何啟用修剪、修剪限制(例如可修剪類型的反映)和修剪警告的詳細資訊,請參閱 修剪獨立部署和可執行檔。 開發人員應該在修剪之後徹底測試其應用程式,以確保一切如預期般運作。 如需詳細資訊,請參閱 GitHub 上的問題 2478

Visual Studio Arm64 的支援

早在 Project Reunion (現在 WinAppSDK) 0.5,使用 WinAppSDK 開發的應用程式就能夠在 Arm64 上執行。 從 Visual Studio 17.3 Preview 2 開始,您可以在 Arm64 裝置上使用 WinAppSDK 開發原生應用程式。

若要開始在 Arm64 裝置上進行開發,請參閱 Arm 上的 Windows 和 Arm64 Visual Studio

通知

AppNotificationBuilder 引進為 XML 承載的替代方案,可用來建立和定義應用程式通知。

如需使用資訊,請參閱 GitHub 上的 AppNotificationBuilder 規格

另請參閱快速入門:Windows 應用程式 SDK 中的應用程式通知,以取得如何建立傳送和接收本機應用程式通知的桌面 Windows 應用程式範例。

重大變更

針對推播通知,發出通道要求呼叫時,應用程式必須使用 Azure 對象識別碼,而不是 Azure 應用程式識別碼。 如需尋找 Azure 物件識別碼的詳細資訊,請參閱 Windows 應用程式 SDK 中的推播通知。

已修正問題

PushNotificationManager.IsSupported 會執行提高許可權模式的檢查。 如果提高應用程式權限,則會傳回 false

已知限制 (通知)

視窗化

Windows 10 版本 1809 和更新版本現在可透過 AppWindowTitleBar 類別取得完整標題列自定義。 您可以將AppWindowTitleBar.ExtendsContentIntoTitleBar 設定true ,以將內容延伸至標題欄區域,以及SetDragRectangles 來定義拖曳區域(以及其他自定義選項)。

如果您已使用 AppWindowTitleBar.IsCustomizationSupported 屬性來檢查您是否可以呼叫 AppWindowTitleBar API,它現在會在 true Windows 應用程式 SDK 支援的 Windows 10 版本 (1809 和更新版本) 上傳回 。

已知限制 (視窗化)

Windows 10 不支援基本標題列自定義。 其中包括 BackgroundColorInactiveBackgroundColorForegroundColorInactiveForegroundColor IconShowOptions。 如果您呼叫這些屬性,則會以無訊息方式忽略這些屬性。 所有其他 AppWindowTitleBar API 都適用於 Windows 10 版本 1809 和更新版本。 針對 標題 按鈕色彩 API(以及其他)和 Height,ExtendsContentIntoTitleBar 必須設定為 true,否則它們也會以無訊息方式忽略。

存取控制

引進 security.accesscontrol.hGetSecurityDescriptorForAppContainerNames 函 式,以簡化封裝進程與一般 Win32 API 之間的具名對象共用。 此方法會取得套件系列名稱 (PFN) 和存取掩碼的清單,並傳回安全性描述元。 如需詳細資訊,請參閱 GitHub 上的 GetSecurityDescriptorForAppContainerNames 規格

其他限制和已知問題

重要

當您從專案參考 WinAppSDK 1.2 時,您可能會看到類似:「偵測到的套件降級:Microsoft.Windows.SDK.BuildTools 從 10.0.22621.1 降級為 10.0.22000.194」的錯誤,原因是應用程式專案和 WinAppSDK 套件的套件參考不相容。 若要解決此問題,您可以將專案中的參考更新為較新且相容的 Microsoft.Windows.SDK.BuildTools 版本。

  • 單元測試可能會失敗,並在 Visual Studio 的 [測試輸出] 窗格中發生 REGDB_E_CLASSNOTREG 錯誤。 因應措施是,您可以將 新增 <WindowsAppContainer>true</WindowsAppContainer> 至項目檔。
  • 不支援 .NET PublishSingleFile。
  • Bootstrapper 和 Undocked RegFree WinRT 自動初始化表達式預設值僅針對產生可執行檔的項目設定 (OutputType=Exe 或 WinExe)。 這可防止將自動初始化表達式新增至類別庫 DLL 和其他非可執行檔。
    • 如果您需要非可執行檔中的自動初始化運算式(例如未初始化 Bootstrapper 的泛型可執行檔所載入的測試 DLL),您可以透過 或 <WindowsAppSdkUndockedRegFreeWinRTInitialize>true</WindowsAppSdkUndockedRegFreeWinRTInitialize>在專案中<WindowsAppSdkBootstrapInitialize>true</WindowsAppSdkBootstrapInitialize>明確啟用自動初始化表達式。
  • Microsoft.WindowsAppRuntime.Release.Net.dll一律是 Arm64 二進位檔,不適用於 x86 和 x64 應用程式。 明確呼叫 Bootstrap API 時,請勿使用Microsoft.WindowsAppRuntime.Release.Net.dll元件。 作為因應措施,您可以在以 NuGet 套件散發的這個原始程式檔中包含版本常數:『.。\include\WindowsAppSDK-VersionInfo.cs' 或使用自動初始化表達式。

1.1 版

Windows 應用程式 SDK 穩定通道 1.1.x 譜系的最新可用版本是 1.1.5 版。 1.1.x 支援所有穩定的通道功能(請參閱 Windows 應用程式 SDK 發行通道版本通道所提供的功能一節)。

1.1.5 版

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

錯誤修正

  • 已修正已啟用Mica時壓克力無法運作的問題。 如需詳細資訊,請參閱 GitHub 上的問題 7200
  • 已修正導致相依於 WindowsAppRuntime 安裝程式的應用程式(例如未封裝的應用程式)無法在 Windows 10 ARM64 計算機上執行的問題。 如需詳細資訊,請參閱 GitHub 上的問題 2564

1.1.4 版

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

錯誤修正

  • 已修正從 1.0.x 回歸,導致 ListView、TreeView 和其他 'List' 控件在捲動時與許多專案捲動時當機。 如需詳細資訊,請參閱 GitHub 上的問題 7230
  • 已修正 DispatcherQueue 導致不再叫用加入佇列回呼的問題。
  • 已修正在相同應用程式會話中呼叫 DeploymentManager.Initialize 多次時導致應用程式當機的問題。
  • 已修正導致 C# 應用程式無法在 Arm64 Visual Studio 上建置的問題。 如需詳細資訊,請參閱 GitHub 上的問題 7140
  • 已修正 XAML 映像處理程式代碼因錯誤處理而發生間歇性當機的問題。
  • 已修正在 ItemsRepeater 中附加具有父 UserControl 之事件處理程式時的記憶體流失問題。 如需詳細資訊,請參閱 GitHub 上的問題 6123
  • 已修正當應用程式項目設定為在側載時啟用套件自動更新時,Visual Studio 17.3 中的建置失敗問題(亦即 .appinstaller)。 如需詳細資訊,請參閱 問題 2773
  • 已修正導致呼叫 Initialize 的市集分散式封裝應用程式(例如 Push 的必要專案)重複呼叫它的問題,因為已安裝 main 和 singleton 套件時傳 Package Install Needed 回 DeploymentManager::GetStatus。 這會導致應用程式啟動時效能降低。
  • 已修正當無法開啟清除事件時,導致單一實例應用程式中發生例外狀況的問題。 如需詳細資訊,請參閱 GitHub 上的 PR

1.1.3 版

這是 Windows 應用程式 SDK的服務版本,其中包含1.1版的重要錯誤修正。

錯誤修正

  • 已修正在應用程式第一頁包含 ProgressBar、ProgressRing、PipsPager、PersonPicture 或 Expander 控件時 XAML 當機的相關問題集。 如需詳細資訊,請參閱 GitHub 上的問題 7164
  • 已修正導致 x64 安裝程式無法安裝 Windows 應用程式 SDK 執行時間的問題。 如需詳細資訊,請參閱 GitHub 上的問題 2713
  • 已修正安裝較高版本的運行時間時,導致 WindowsAppRuntime 無法安裝的問題。 如需詳細資訊,請參閱 GitHub 上的討論 2708

1.1.2 版

這是 Windows 應用程式 SDK的服務版本,其中包含1.1版的重要錯誤修正。

錯誤修正

  • 已修正在對話框開啟時關閉視窗時 XAML 當機的問題。 如需詳細資訊,請參閱 GitHub 上的問題 1032
  • 在 C# 檔案中新增 <auto-generated> 標籤,以防止 StyleCop 警告。 如需詳細資訊,請參閱 GitHub 上的問題 4526
  • 已修正在未安裝比對架構套件時呼叫 MddBootstrapInitialize 時發生存取違規錯誤和當機的問題。 如需詳細資訊,請參閱 GitHub 上的問題 2592
  • 已修正 Visual Studio 中遺漏 C# WinUI 3 專案範本的問題。 如需詳細資訊,請參閱 GitHub 上的問題 7148
  • 修正當以系統使用者身分執行時,WindowsAppRuntime 安裝程式失敗的問題。 如需詳細資訊,請參閱 GitHub 上的問題 2546

1.1.1 版

這是 Windows 應用程式 SDK的服務版本,其中包含1.1版的重要錯誤修正。

錯誤修正

  • 已修正在拖放作業期間,導致應用程式有時當機的問題。 如需詳細資訊,請參閱 GitHub 上的問題 7002
  • 已修正將AppWindowPresenterKind從 FullScreen 切換為預設值時,標題欄消失的問題。
  • 已修正啟動載入器 API 之類的 ApiInformation.IsPropertyPresent 問題,而且 ApiInformation.IsMethodPresent 會在未封裝的應用程式中造成未處理的例外狀況。 如需詳細資訊,請參閱 GitHub 上的問題 2382
  • 已修正使用手寫筆輸入將應用程式最大化時導致應用程式凍結的問題。

1.1 版

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

注意

針對 C# 開發人員,需要下列其中一個 .NET SDK 版本(或更新版本):6.0.202、6.0.104、5.0.407、5.0.213。 若要更新 .NET SDK 版本,請流覽 .NET 下載 或更新至最新版本的Visual Studio。 若沒有必要的 .NET SDK 版本,更新 NuGet 套件時,您會看到如下的錯誤:「此版本的 WindowsAppSDK 需要WinRT.Runtime.dll 1.6 版或更新版本“

應用程式生命週期和重新啟動

應用程式現在可以使用現有 RegisterApplicationRestart API 的特定自變數和狀態建置來起始明確的重新啟動,以向操作系統註冊,以在更新、停止回應和重新啟動案例中重新啟動。

新功能:

  • 任何已封裝或解壓縮的桌面應用程式都可以在命令上終止並重新啟動本身,並使用 API 存取重新啟動實例 AppInstance.Restart() 的任意命令行字串。
    • 這是 UWP RequestRestartAsync() API 的隨即解除和同步版本,可透過自變數重新啟動,並在重新啟動失敗時傳 AppRestartFailureReason 回 。
    • 如需使用方式和參考資訊,請參閱 GitHub 上的重新啟動 API 檔。

WinUI 3

WinUI 3 是適用於 Windows 應用程式 SDK 的原生用戶體驗 (UX) 架構。 此版本包含 WinAppSDK 1.0 的新功能,以及 1.0 和 1.1 預覽版本的數個穩定性改進。

新功能:

  • Mica 和 Background Acrylic 現在適用於 WinUI 3 應用程式。
  • 首先在 1.0.1 中引進,我們已穩定並啟用在 WinUI 3 應用程式中相同線程上建立多個視窗。 如需詳細資訊,請參閱 問題 5918

已修正的 Bug:

  • 已修正使用Mica時,當視窗平均除以兩個畫面時,應用程式會當機的問題。 如需詳細資訊,請參閱 GitHub 上的問題 7079
  • 已修正此問題:將 WebView2 SDK 從 1020.46 升級至 1185.39 時,當 C/C++ 運行時間 (CRT) 未安裝時,WebView2 應用程式在啟動時當機。
  • 已修正當部分圓角應該是純色時顯示漸層的問題。 如需詳細資訊,請參閱 GitHub 上的問題 6076問題 6194
  • 已修正泛型.xaml 遺漏更新樣式的問題。
  • 已修正在捲動至 ListView 結尾時導致應用程式當機的配置周期問題。 如需詳細資訊,請參閱 GitHub 上的問題 6218
  • 已修正啟用拖放功能時,用戶無法卸除項目的問題。 如需詳細資訊,請參閱 GitHub 上的問題 7008

已知限制:

  • 使用自定義標題列時,標題 控件不會變更主題變更的色彩。
  • 當使用者在對話框開啟時關閉視窗時,XAML 會當機。

部署

新功能:

已知限制:

  • 執行 Windows App 執行時間安裝程式 (WindowsAppRuntimeInstall.exe) 需要啟用側載。 如需詳細資訊,請參閱 GitHub 上的問題 2469
  • 在某些情況下,透過Visual Studio專案功能表建立 MSIX 套件可能會當機Visual Studio。 此問題將在Visual Studio 17.3版 Preview 2 中修正,並服務為17.2。 如果您遇到此問題,您可以從命令行產生 MSIX、切換至未封裝的專案,或還原回 Windows 應用程式 SDK 1.0 來解決此問題。
  • 在 1809 上不支援以 MSIX 封裝的獨立應用程式,導致應用程式在啟動時當機。

提升權限

應用程式現在能夠以更高的許可權執行。

已知限制:

環境變數管理員

環境變數管理員是 Windows 應用程式 SDK 1.1 中引進的新 API。 環境變數管理員可讓開發人員從一個 API 介面存取和修改程式中的環境變數、使用者和計算機範圍。

如果已封裝的應用程式使用環境變數管理員,則會記錄所有環境變數作業。 拿掉封裝時,會還原所有環境變數作業。

新功能:

  • 取得和設定進程中的環境變數、用戶和計算機範圍。
  • 拿掉使用環境變數管理員的套件時,自動環境變數會還原。
  • 包含PATH和PATHEXT的特定API。

已知限制:

  • 僅適用於 Windows 11

MRT 核心

MRT Core 是現代化 Windows 資源管理系統的簡化版本,會作為 Windows 應用程式 SDK 的一部分散發。

修正的問題:

  • 在 .NET SDK 6.0.300 中修正使用 VS UI 新增資源檔時,導致資源預設不會編製索引的問題。 如果使用較舊的 .NET SDK 版本,請繼續使用 1.0 版本資訊中所述的因應措施。 如需詳細資訊,請參閱 GitHub 上的問題 1786
  • Visual Studio 2022 17.2 已修正在未封裝的 C++ WinUI 3 應用程式中無法正確建置資源 URI 的問題。 如果使用較舊的Visual Studio版本,請將Visual Studio更新為17.2以接收此修正程式。

已知限制:

  • 在 .NET 專案中,如果應用程式已建置,則不會在 F5 上編製複製貼上至專案資料夾的資源檔案索引。 因應措施是重建應用程式。 如需詳細資訊,請參閱 GitHub 上的問題 1503

如需詳細資訊,請參閱 使用 MRT Core 管理資源。

通知

已封裝的開發人員(包括隨外部位置封裝)和未封裝的應用程式,現在可以傳送 Windows 通知。

新功能:

  • 支援已封裝和未封裝應用程式的應用程式通知。
    • 開發人員可以在本機或從自己的雲端服務傳送應用程式通知,也稱為快顯通知。 請參閱 應用程式通知概觀
  • 支援已封裝和未封裝應用程式的推播通知。
    • 開發人員可以從自己的雲端服務傳送原始通知和應用程式通知。 請參閱 推播通知概觀

已知限制:

  • 不支援從提升許可權的應用程式傳送通知。 PushNotificationManager::IsSupported() 不會執行提高許可權模式的檢查。

視窗化

為了更輕鬆地存取在 USER32.dll 中實作的功能(請參閱 Windows 和訊息),此版本本身會呈現更多該功能 AppWindow

新功能:

  • 透過呼叫 AppWindow.ShowOnceWithRequestedStartupState,具有現有視窗的應用程式可以更充分掌控視窗的顯示方式,相當於 ShowWindow(SW_SHOWDEFAULT)
  • 應用程式可以在指定呼叫時是否應該啟動窗口,同時顯示、最小化或還原視窗。
  • 應用程式現在可以在 Win32 座標中判斷其視窗工作區大小的特定維度,而不需要計算非工作區大小以取得特定工作區大小。
  • 根據 SetWindowPos 的 hWndInsertAfter 功能,其他 WinRT API 可支援 Windows 的 Z 順序管理。
  • 使用 繪製自定義標題列 AppWindowTitleBar.ExtendsContentIntoTitleBar 的應用程式可以設定 PreferredTitleBarHeight 選項。 您現在可以選擇標準高度標題欄,或高高的標題列,以提供更多互動內容的空間。 如需何時使用高標題欄的建議,請參閱 Fluent 設計指導方針中的標題列

修正的問題:

  • 第一次叫用全螢幕演示者時,視窗現在會正確容納整個畫面。 如需詳細資訊,請參閱 GitHub 上的問題 1853
  • 建立的 AppWindow::GetFromWindowId Windows 具有 OverlappedPresenter 作為預設演示者,但在來自其他 API 的視窗樣式變更方面沒有限制。 使用 AppWindow::Create 建立的 Windows 會從一開始就備妥預設的演示者護欄。 如需詳細資訊,請參閱 GitHub 上的問題 2049
  • OverlappedPresenter.SetBorderAndTitlebar使用 API 隱藏 標題 按鈕和框線會導致最大化時產生 1px 上框線。 此問題已解決。 如需詳細資訊,請參閱 GitHub 上的問題 1693

已知限制:

  • 使用 AppWindowTitlebar API 來自定義標準標題列的色彩時,相較於標準標題列,圖示和文字會不對齊。 如需詳細資訊,請參閱 GitHub 問題 2459

  • 解決 GitHub 問題 2049 時(如上所示),我們引進了下列 Bug:如果您將任何 AppWindowPresenter 套用至您從 GetFromWindowId 擷取的 AppWindow然後透過呼叫 USER32 API 變更該演示者所追蹤的窗口樣式,然後重新套用預設演示者,嘗試還原回視窗先前的狀態, 結果是沒有標題列的視窗。 如果您依賴應用程式中的任何演示者,並在套用非預設演示者時,使用對 USER32 的呼叫來變更視窗樣式,則您可能需要新增因應措施,以確保在處理這個 Bug 之前正確執行窗口行為。 您可以使用下列代碼段作為樣本,以解決此問題:

    AppWindow m_appWindow;
    OverlappedPresenter m_defaultPresenter;
    
    private void EnterFullScreen_Click(object sender, RoutedEventArgs e)
    {
        // Capture the default presenter.
        m_defaultPresenter = m_appWindow.Presenter as OverlappedPresenter;
    
        // Opt in the default overlapped presenter so it can control various aspects of the AppWindow.
        m_defaultPresenter.IsAlwaysOnTop = m_defaultPresenter.IsAlwaysOnTop;
        m_defaultPresenter.IsResizable = m_defaultPresenter.IsResizable;
        m_defaultPresenter.IsMinimizable = m_defaultPresenter.IsMinimizable;
        m_defaultPresenter.IsMaximizable = m_defaultPresenter.IsMaximizable;
        m_defaultPresenter.SetBorderAndTitleBar(m_defaultPresenter.HasBorder, m_defaultPresenter.HasTitleBar);
    
        m_appWindow.SetPresenter(AppWindowPresenterKind.FullScreen);
    }
    
    private void ExitFullScreen_Click(object sender, RoutedEventArgs e)
    {
        m_appWindow.SetPresenter(AppWindowPresenterKind.Default);
    }
    

C#/WinRT

現在支援 C# Windows 執行階段元件,包括 WinUI 自定義控件。 這可讓元件作者將 C#撰寫的運行時間元件發佈至任何 WinRT 相容語言(例如 C++/WinRT)。 請參閱逐步解說 — 使用 WinUI 3 控制項建立 C# 元件,並從使用 GitHub 上的 Windows 應用程式 SDK 和範例的 C++/WinRT 應用程式取用它。

其他限制和已知問題

  • 參考相依於 WebView2 套件的應用程式(例如 Microsoft.Identity.Client)無法建置。 這是因為在建置階段發生衝突的二進位檔所造成。 如需詳細資訊,請參閱 GitHub 上的問題 2492
  • 搭配 WinAppSDK C# 類別庫專案使用 dotnet build ,可能會看到建置錯誤「無法載入 Microsoft.Build.Packaging.Pri.Tasks.ExpandPriContent 工作」。 若要解決此問題,請在專案檔中設定 <EnableMsixTooling>true</EnableMsixTooling>
  • 默認 WinAppSDK 範本請注意,當 MaxVersionTested=“10.0.19041.0” 應該是 “10.0.22000.0”。 如需某些功能的完整支援,特別是 UnlockedDEHs,請將項目檔中的 MaxVersionTested 更新為 “10.0.22000.0”。

1.0 版

Windows 應用程式 SDK 穩定通道 1.0.x 譜系的最新可用版本是 1.0.4 版。 1.0.x 支援所有穩定的通道功能(請參閱 Windows 應用程式 SDK 發行通道中的可用功能一節)。

1.0.4 版

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

錯誤修正

  • 修正當做Page.TopAppBar或Page.BottomAppBar時,導致AppBars無法轉譯在螢幕上的問題。
  • 已修正使用來自 MUXControls.dll 之 WinUI 控制件的套件名稱為 12 個字元或更少的應用程式會立即當機的問題。 如需詳細資訊,請參閱 GitHub 上的問題 6360
  • 已修正觸控輸入問題,導致鍵盤快捷方式和其他案例發生問題。 如需詳細資訊,請參閱 GitHub 上的問題 6291
  • 已修正導致使用 MSIX 封裝或部署為獨立式應用程式無法部署的問題。
  • 已修正在拖放作業期間,導致應用程式有時當機的問題。 如需詳細資訊,請參閱 GitHub 上的問題 7002

1\.0.3 版

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

錯誤修正

  • 已修正當 C/C++ 執行時間 (CRT) 未安裝時,導致 WebView2 的 C# 應用程式在啟動時當機的問題。
  • 已修正觸控輸入問題,導致鍵盤快捷方式和其他案例發生問題。 如需詳細資訊,請參閱 GitHub 上的問題 6291

注意:我們通常不會在服務版本中新增功能,但此版本的WebView2修正程式需要我們更新至最新版本的WebView2 SDK (1020.46至1185.39)。 如需有關 WebView2 1.0.1185.39 的詳細資訊,請參閱 WebView2 SDK 的版本資訊和 散發您的應用程式和 WebView2 運行時間,以取得 WebView2 運行 時間的其他資訊。

1\.0.2 版

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

錯誤修正

  • 已修正在捲動至 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 版的重要錯誤修正和多窗口支援。

錯誤修正

  • 已修正導致 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 應用程式中相同線程上建立多個視窗。 如需詳細資訊,請參閱 問題 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 專案
  • WinUI 3 項目現在可以將其目標版本設定為 Windows 10 版本 1809。 之前,它們只能設定為1903版。
  • Visual Studio 2022 Preview 5 和 GA 支援應用程式內工具列、熱重新載入 和 WinUI 封裝應用程式的即時可視化樹狀結構。

重要限制

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

    • C++ 或 C# 應用程式中參考 C++ Windows 執行階段 元件的執行時錯誤:
      • 若要解決,請將下列目標新增至 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 in Desktop) 專案範本建立具有單一專案 MSIX 的新應用程式時,發行專案的命令才會出現在功能表中,直到您關閉並重新開啟 Visual Studio 為止。
    • 沒有安裝 「C++ (v14x) 通用 Windows 平台 Tools」 選用元件,具有單一專案 MSIX 的 C# 應用程式將不會編譯。 如需詳細資訊,請參閱安裝 Windows 應用程式 SDK 工具。
    • 在具有單一專案 MSIX 的應用程式中,使用參考 Windows 執行階段元件中定義的類型時可能發生運行時錯誤:若要解決,請將可啟動的類別專案手動新增至appxmanifest.xml。
      • C# 應用程式中的預期錯誤是 「COMException: 類別未註冊 (0x80040154 (REGDB_E_CLASSNOTREG)]。
      • C++/WinRT 應用程式中的預期錯誤是 “winrt::hresult_class_not_registered”。
  • 未封裝的 WinUI 3 應用程式的已知問題(未封裝的應用程式):

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

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

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

視窗化

Windows 應用程式 SDK 提供 AppWindow 類別,可演進先前容易使用的 Windows.UI.WindowManagement.AppWindow 預覽類別,並讓其可供所有 Windows 應用程式使用,包括 Win32、WPF 和 WinForms。

新功能

  • AppWindow 是一種高階視窗化 API,可讓您輕鬆使用視窗化案例,與 Windows 用戶體驗與其他應用程式整合。 表示應用程式內容系統管理容器的高階抽象概念。 這是您內容裝載所在的容器,並代表使用者在調整應用程式大小並在螢幕上移動時與其互動的實體。 對於熟悉 Win32 的開發人員,AppWindow 可視為 HWND 的高階抽象概念。
  • DisplayArea 代表 HMONITOR 的高階抽象概念,遵循與 AppWindow 相同的原則。
  • DisplayAreaWatcher 可讓開發人員觀察顯示拓撲中的變更,並列舉系統中目前定義的 DisplayAreas。

如需詳細資訊,請參閱 管理應用程式視窗

輸入

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

新功能

重要限制

應用程式生命週期

大部分的應用程式生命週期功能已存在於UWP平臺中,並已帶入 Windows 應用程式 SDK,以供傳統型應用程式類型使用,特別是未封裝的控制台應用程式、Win32 應用程式、Windows Forms 應用程式和 WPF 應用程式。 這些功能的 Windows 應用程式 SDK 實作無法在 UWP app 中使用,因為 UWP 平臺本身有對等的功能。

重要

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

非 UWP 應用程式也可以封裝成 MSIX 套件。 雖然這些應用程式可以使用某些 Windows 應用程式 SDK 應用程式生命週期功能,但它們必須使用可用的指令清單方法。 例如,它們無法使用 Windows 應用程式 SDK RegisterForXXXActivation API,而必須改為透過指令清單註冊豐富啟用。

已封裝應用程式的所有條件約束也適用於已封裝的 WinUI 應用程式,而且還有其他考慮,如下所述。

重要考慮

  • 豐富啟用: GetActivatedEventArgs

  • 註冊/取消註冊豐富啟用

    • 解壓縮的應用程式:完全可用。
    • 已封裝的應用程式:無法使用應用程式的 MSIX 指令清單。
    • 如需詳細資訊,請參閱 豐富啟用
  • 單一/多重實例

    • 解壓縮的應用程式:完全可用。
    • 已封裝的應用程式:完全可用。
    • WinUI 應用程式:如果應用程式想要偵測其他實例並重新導向啟用,則必須儘早這麼做,以及初始化任何視窗之前等等。若要啟用此功能,應用程式必須定義DISABLE_XAML_GENERATED_MAIN,並撰寫自定義Main (C#) 或 WinMain (C++),以在其中執行偵測和重新導向。
    • RedirectActivationToAsync 是異步呼叫,如果您的應用程式是在 STA 中執行,則不應該在異步呼叫上等候。 針對 Windows Forms 和 C# WinUI 應用程式,您可以視需要宣告 Main 為異步。 針對 C++ WinUI 和 C# WPF 應用程式,您無法將 Main 宣告為異步,因此您必須將重新導向呼叫移至另一個線程,以確保您不會封鎖 STA。
    • 如需詳細資訊,請參閱 應用程式實例
  • Power/State 通知

    • 解壓縮的應用程式:完全可用。
    • 已封裝的應用程式:完全可用。
    • 如需詳細資訊,請參閱 電源管理

已知問題

  • 設定動詞處理程式的命令行範本時,檔案類型關聯錯誤地將 %1 編碼為 %251,這會損毀解壓縮的 Win32 應用程式。 您可以手動將登錄值編輯為 %1,以做為部分因應措施。 如果目標檔案路徑中有一個空格,它仍然會失敗,而且該案例沒有因應措施。
  • 這些單一/多重實例錯誤將會在即將推出的維護修補程式中修正:
    • 針對 x86 編譯時,AppInstance 重新導向無法運作
    • 註冊金鑰、取消註冊金鑰,然後重新註冊它會導致應用程式當機

DWriteCore

DWriteCore 是 DirectWrite 的 Windows 應用程式 SDK 實作,它是適用於高品質文字轉譯的 DirectX API、與解析度無關的外框字型,以及完整的 Unicode 文字和版面配置支援。 DWriteCore 是一種 DirectWrite 形式,可在 Windows 版本下執行到 Windows 10 版本 1809 (10.0;建置 17763),並開啟大門讓您跨平臺使用。

功能 DWriteCore 包含 DirectWrite 的所有功能,但有一些例外。

重要限制

  • DWriteCore 不包含下列 DirectWrite 功能:
    • 每一會話字型
    • 使用者定義字元 (EUDC) 字型
    • 字型串流 API
  • 低階轉譯 API 支援部分。
  • DWriteCore 不會與 Direct2D 互通,但您可以使用 IDWriteGlyphRunAnalysisIDWriteBitmapRenderTarget

如需詳細資訊,請參閱 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 管理資源。

部署

新功能和更新

  • 您可以透過 WindowsPackageType project 屬性自動初始化 Windows 應用程式 SDK,以載入 Windows 應用程式 SDK 運行時間,並呼叫 Windows 應用程式 SDK API。 如需相關指示,請參閱 建立您的第一個 WinUI 3 專案
  • 解除封裝的應用程式可以藉由將獨立 Windows 應用程式 SDK .exe 安裝程式整合到現有的 MSI 或安裝程式中,來部署 Windows 應用程式 SDK。 如需詳細資訊,請參閱 Windows 應用程式 SDK 與外部位置或解除封裝之架構相依應用程式的部署指南。
  • 解除封裝的 .NET 應用程式也可以使用 .NET 包裝函式,讓啟動載入器 API 在運行時間動態相依於 Windows 應用程式 SDK 架構套件。 如需 .NET 包裝函式的詳細資訊,請參閱 .NET 包裝函式連結庫
  • 已封裝的應用程式可以使用部署 API 來確認並確認電腦上已安裝所有必要的套件。 如需部署 API 運作方式的詳細資訊,請參閱架構相依封裝應用程式的 Windows 應用程式 SDK 部署指南。

重要限制

  • 啟動載入器 API 的 .NET 包裝函式僅供解壓縮的 .NET 應用程式使用,以簡化對 Windows 應用程式 SDK 的存取。
  • 只有完全信任或具有 packageManagement 受限制功能的 MSIX 封裝應用程式有權使用部署 API 來安裝主要和單一套件相依性。 部分信任封裝應用程式的支援將會在更新版本中推出。
  • 當 F5 測試使用 x64 系統上 DeploymentManager.Initialize 方法的 x86 應用程式時,請執行 WindowsAppRuntimeInstall.exe,確定會先安裝 x64 架構。 否則,由於Visual Studio未部署 x64 架構,因此您將會遇到 NOT_FOUND 錯誤,這通常是透過市集部署或側載發生。

其他限制和已知問題

  • 不支援任何 CPU 組建元件:將 Windows 應用程式 SDK 新增至支援任何 CPU 的現有 .NET 應用程式或元件時,您必須指定所需的架構:x86x64arm64

  • 從 .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 平台 Tools 選用元件。

  • 安裝多個 Visual Studio 2019 版本時,後續語言 VSIX 無法安裝到 Visual Studio 2019。 如果您已安裝多個版本的 Visual Studio 2019(例如 Release 和 Preview),然後安裝 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);

0.8 版

Windows 應用程式 SDK 穩定通道0.8.x譜系的最新可用版本是0.8.12版。

注意

Windows 應用程式 SDK 先前是程式代碼名稱 Project Reunion 所知道。 0.8 版和更早版本中的某些 SDK 資產仍會使用程式代碼名稱。 在參考現有資產或指定舊版時,檔的某些區域仍會使用 Project Reunion

版本 0.8.12

這是 Windows 應用程式 SDK 的服務版本,其中包含 0.8.0 版本的重要錯誤修正。

注意

對於 C# 開發人員,需要下列其中一個 .NET SDK 版本:5.0.213、5.0.407、6.0.104、6.0.202(或更新版本)。 若要更新 .NET SDK 版本,請流覽 .NET 下載 或更新至最新版本的Visual Studio。 若沒有必要的 .NET SDK 版本,更新 NuGet 套件時,您會看到如下的錯誤:「此版本的 WindowsAppSDK 需要WinRT.Runtime.dll 1.6 版或更新版本“

更新:

0.8.11 版

這是 Windows 應用程式 SDK 的服務版本,其中包含 0.8.0 版本的重要錯誤修正。

注意

對於 C# 開發人員,需要下列其中一個 .NET SDK 版本:5.0.213、5.0.407、6.0.104、6.0.202(或更新版本)。 若要更新 .NET SDK 版本,請流覽 .NET 下載 或更新至最新版本的Visual Studio。 若沒有必要的 .NET SDK 版本,更新 NuGet 套件時,您會看到如下的錯誤:「此版本的 WindowsAppSDK 需要WinRT.Runtime.dll 1.6 版或更新版本“

更新:

  • 已修正使用滑鼠選取文字時,導致失去焦點事件引發的回歸。

0.8.10 版

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

注意

對於 C# 開發人員,需要下列其中一個 .NET SDK 版本:5.0.213、5.0.407、6.0.104、6.0.202(或更新版本)。 若要更新 .NET SDK 版本,請流覽 .NET 下載 或更新至最新版本的Visual Studio。 若沒有必要的 .NET SDK 版本,更新 NuGet 套件時,您會看到如下的錯誤:「此版本的 WindowsAppSDK 需要WinRT.Runtime.dll 1.6 版或更新版本“

更新:

  • 已修正在拖放作業期間導致應用程式有時當機的問題。

注意

Windows 應用程式 SDK 0.8.9 未發行。 在 0.8.8 之後直接發行的版本是 0.8.10。

版本 0.8.8

這是 Windows 應用程式 SDK 的服務版本,其中包含 0.8.0 版本的重要錯誤修正。

注意

針對 C# 開發人員,需要下列其中一個 .NET SDK 版本(或更新版本):6.0.202、6.0.104、5.0.407、5.0.213。 若要更新 .NET SDK 版本,請流覽 .NET 下載 或更新至最新版本的Visual Studio。 若沒有必要的 .NET SDK 版本,更新 NuGet 套件時,您會看到如下的錯誤:「此版本的 WindowsAppSDK 需要WinRT.Runtime.dll 1.6 版或更新版本“

更新:

  • 已修正 TextBox 中關於軟式鍵盤和一般互動的觸控輸入問題。 這些問題也會影響鍵盤快捷方式。 如需詳細資訊,請參閱 GitHub 上的問題 6291
  • 已修正當使用中時,應用程式視窗有時會顯示為非使用中的問題。
  • 已修正 UIA (使用者介面自動化) 在外部進程中執行的效能問題。
  • 已修正手寫筆輸入的應用程式穩定性問題。
  • 已修正因為 UIA 而大幅延遲功能表中 png 圖示轉譯的問題。

版本 0.8.7

這是 Windows 應用程式 SDK的維護版本,其中包含 C#/.NET 應用程式的數個效能更新。 若要更新至此版本,您必須參考最新的 Windows SDK 套件版本。 若要這樣做,請使用應用程式的目標 TargetFramework SDK 版本,將屬性<WindowsSdkPackageVersion>10.0.<sdk_version>.24</WindowsSdkPackageVersion>新增至檔案.csproj。 例如:

<Project Sdk="Microsoft.NET.Sdk">
   <PropertyGroup>
       <OutputType>WinExe</OutputType>
       <TargetFramework>net6.0-windows10.0.19041.0</TargetFramework>
       <TargetPlatformMinVersion>10.0.17763.0</TargetPlatformMinVersion>
       <WindowsSdkPackageVersion>10.0.19041.24</WindowsSdkPackageVersion>
   <PropertyGroup>
   ...

這個版本的 Windows SDK 投影將在即將推出的 .NET 6 服務版本中提供。 在該 .NET SDK 更新可供使用之後,您應該從專案檔中移除 <WindowsSdkPackageVersion> 屬性。

如果您未設定此屬性,您會看到如下的錯誤: "Error: This version of Project Reunion requires WinRT.Runtime.dll version 1.6 or greater."

0.8.6 版

這是 Windows 應用程式 SDK的服務版本,其中包含 0.8.0 版 C#/.NET 應用程式的數個效能改善。

若要更新此版本的 Windows 應用程式 SDK,您必須安裝最新的 .NET SDK 12 月更新(請參閱下載 .NET.NET 5 將於 2022 年 5 月 10 日終止支援)。 如果您沒有安裝 .NET SDK 的最低必要版本,則會看到類似的錯誤 "Error: This version of Project Reunion requires WinRT.Runtime.dll version 1.4 or greater."

錯誤修正

如需效能改善的詳細清單,請參閱 C#/WinRT 1.4.1 版本資訊

0.8.5 版

這是 Windows 應用程式 SDK的服務版本,其中包含 0.8.0 版的更重大錯誤修正。

錯誤修正

  • 已修正導致 WinUI 應用程式使用 指標輸入 當機的問題。
  • 已修正導致 Windows 11 上沒有圓角標題列按鈕(最小值、最大值、關閉)的問題。
  • 已修正在 Windows 11 上將滑鼠停留在最大化/還原按鈕上方時,重設大小配置選項不會出現的問題。
  • 已修正在建立 PointCollection 物件時造成當機例外狀況的問題。 如需詳細資訊,請參閱 Github 上的問題 971

0.8 版的限制和已知問題也適用於 0.8.5 版,除非在下列章節中另有標示。

版本 0.8.4

這是 Windows 應用程式 SDK的維護版本,其中包含 0.8.0 版的更重大錯誤修正。

錯誤修正

  • 自定義標題列的修正,讓 ContentDialog 不會遮蓋它,而且標題欄按鈕會四捨五入。
  • 修正當顯示縮放比例變更時影像處理當機的問題。
  • 修正 UI 消失或裁剪錯誤的錯誤

0.8 版的限制和已知問題也適用於 0.8.4 版,除非在下列章節中另有標示。

版本 0.8.3

這是 Windows 應用程式 SDK的服務版本,其中包含 0.8.0 版的更重大錯誤修正。

錯誤修正

當視窗最小化,然後還原時,鍵盤焦點會遺失,需要按滑鼠以還原焦點。

0.8 版的限制和已知問題也適用於 0.8.3 版,除非在下列章節中另有標示。

0.8.2 版

這是 Windows 應用程式 SDK的服務版本,其中包含 0.8.0 版的更重大錯誤修正。

錯誤修正

  • Visual Studio 2022 Preview 2 和更新版本現在支援 Windows 應用程式 SDK 和 WinUI 3。
  • 針對 .NET 應用程式,在傳入列舉陣列時,您可能會收到下列錯誤: Object contains non-primitive or non-blittable data.
  • 使用文本框內的 HandWriting Panel 撰寫會導致當機
  • 圖示/影像一律會以 100% 的縮放值載入,而不是根據監視器縮放值
  • EventSource<T>垃圾收集會導致後續無法取消訂閱處理程式(如需詳細資訊,請參閱 GitHub 問題
  • 安全性修正 – 如需詳細資訊,請參閱 CVE-2021-34533
  • SwapChainPanel.CompositionScaleChanged 有時會在變更顯示縮放比例之後傳回不正確的 CompositionScale 值

0.8 版的限制和已知問題也適用於 0.8.2 版,除非在下列章節中另有標示。

0.8.1 版

這是 Windows 應用程式 SDK的服務版本,其中包含 0.8.0 版的一些重大錯誤修正。

錯誤修正

  • Windows 應用程式 SDK 無法在最新的 Windows 測試人員組建上執行
  • 輸入未出現在下拉式清單中的值時,在 EditableComboBox 中當機
  • WebView2 不允許使用者在收到焦點之後進行定位
  • 在 WinUI 產生的程式代碼中完整限定 Windows.Foundation.Metadata.DefaultOverload 命名空間,以避免命名空間模棱兩可
    • 這會修正錯誤 #5108
  • 安全性修正 – 如需詳細資訊,請參閱 CVE-2021-34489

0.8 版的限制和已知問題也適用於 0.8.1 版,除非在下列章節中另有標示。

0.8.0 版穩定

新功能和更新

此版本支援所有 穩定的通道功能

WinUI 3

此版本包含許多 Bug 修正,以及 WinUI 3 之間的改善穩定。 以下是 WinUI 3 - Project Reunion 0.5 發行后,WinUI 3 的所有新變更:

  • 樞紐控制項已新增回 ,現在可用於任何 WinUI 3 應用程式。

  • 此版本包含 Project Reunion v0.5.5、v0.5.6 和 v0.5.7 的所有 Bug 修正。

  • 新的錯誤修正,包括:

    • 在文字方塊中按滑鼠右鍵,會導致應用程式損毀
    • NavigationView 會導致 UWP、Reunion 0.5 預覽版當機
    • ProgressBar 不會顯示 Paused 與 Error 選項之間的差異
    • 複製/貼上/變更文字樣式時,在 RichEditBox 中當機
    • 未設定 SetTitleBar 或 Null 時,視窗 標題 按鈕錯位

    如需此版本所解決之 Bug 的完整清單,請參閱 我們的 GitHub 存放庫

  • ColorHelper.ToDisplayName API 已無法使用。

  • 已移除下列型態:

    • Microsoft.Graphics.IGeometrySource2D
    • Microsoft.Graphics.IGeometrySource2DInterop

    請改用 Windows.Graphics.IGeometrySource2DWindows.Graphics.IGeometrySource2DInterop

  • 命名空間中的所有 Microsoft.System 類型都已移至 Microsoft.UI.Dispatching 命名空間,包括 DispatcherQueue 類別

  • 已移除 屬性 AcrylicBrush.BackgroundSource ,因為 HostBackdrop WinUI 3 中不支援 BackgroundSource

如需 WinUI 的詳細資訊,請參閱 Windows UI 3 連結庫 (WinUI)

若要查看作用中的 WinUI 3 控制項和功能,您可以從 GitHub 複製和建置 WinUI 3 資源庫應用程式,或從 Microsoft Store 下載應用程式

若要開始使用 WinUI 進行開發,請參閱下列文章:

DWriteCore

此版本的 DWriteCore 包含下列新功能和更新的功能。 DWriteCore 會在 DWriteCore 概觀引進並說明。

注意

DWriteCoreCreateFactory 的功能與 DirectWrite 系統版本導出的 DWriteCreateFactory 函式功能相同 DWriteCore 函式具有不同的名稱,以避免您在連結 DWriteCore.libDWrite.lib時模棱兩可。

如需 DWriteCore 和 DirectWrite API 參考,請參閱 DWriteCore API 參考DirectWrite API 參考

MRTCore

  • 當您 將資源新增至專案時,會自動設定資源的建置動作 ,以減少手動項目設定的需求。

限制

  • Windows 測試人員計劃的開發通道目前不支援此版本。 這是在 0.8.1 版中修正的。

  • 傳統型應用程式 (C# 或 C++ 桌面):此版本僅支援在使用 MSIX 封裝的桌面應用程式 (C++ 或 C#) 中使用。 若要在未封裝的桌面應用程式中使用 Windows 應用程式 SDK,您必須使用實驗性發行通道

重要

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

已知問題

  • WinUI 3 工具,例如 Live Visual Tree、Live Property Explorer 和 0.8 版和更新版本中的 熱重新載入,需要 Visual Studio 2019 16.11 Preview 3 和更新版本。

  • 目前使用 WinUI 3 和 Windows 應用程式 SDK 0.8 的應用程式無法使用使用 Project Reunion 0.5 的類別庫。 更新類別庫以使用 Windows 應用程式 SDK 0.8。

  • .NET 應用程式必須以組建 18362 或更新版本為目標:您的 TFM 必須設定為 net6.0-windows10.0.18362 或更新版本,而封裝專案的 必須設定為 18362 或更新版本。 如需詳細資訊,請參閱 GitHub 問題 #921

  • 在淺色和深色模式之間經常切換時,您可能會遇到當機。

  • 針對 .NET 應用程式,您可能會在傳入列舉陣列時收到下列錯誤: Object contains non-primitive or non-blittable data.這是在 0.8.2 版中修正的。

  • 對於 .NET 應用程式,目前沒有辦法退出宣告使用Visual Studio UI 將影像編製索引為應用程式資源。 若要解決此問題,請將 Directory.Build.targets 新增至專案(請參閱 自定義您的組建 - Visual Studio 以取得指示),並移除映像,如下所示:

    • 若要移除特定影像(請注意需要相對路徑):

      <Project> 
      <ItemGroup> 
          <Content Remove="..\Bitmap1.bmp" />
      </ItemGroup>
      </Project>
      
    • 若要根據元資料移除影像:

      <Project>
      <ItemGroup>
          <Content Remove="@(None->WithMetadataValue('Pack','true'))" />
      </ItemGroup>
      </Project>
      

    此問題的修正計劃為即將推出的版本 ,此時不再需要上述因應措施。

0.5 版

Windows 應用程式 SDK 穩定通道 0.5.x 譜系的最新可用版本是 0.5.9 版。

新功能和更新

此版本支援所有 穩定的通道功能

已知問題與限制

此版本有下列限制和已知問題:

  • 傳統型應用程式 (C# 或 C++ 桌面版):此版本僅支援在使用 MSIX 封裝的桌面應用程式 (C++ 或 C#) 中使用。 若要在未封裝的桌面應用程式中使用 Windows 應用程式 SDK,您必須使用實驗性發行通道
  • .NET 應用程式必須以組建 18362 或更新版本為目標:您的 TFM 必須設定為 net6.0-windows10.0.18362 或更新版本,而且封裝專案的 <TargetPlatformVersion> 必須設定為 18362 或更新版本。 如需詳細資訊,請參閱 GitHub 上的已知問題。

重要

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