Windows 應用程式 SDK 的預覽通道版本資訊

  • 發行項

重要

預覽通道已經不支援使用在生產環境，且使用預覽版本的應用程式無法發布到 Microsoft Store。

預覽通道可針對下一個穩定版本提供預覽。 指定的預覽通道版本與下一個穩定版本之間可能會有重大 API 變更。 預覽通道的版本不包括實驗版 API。

重要連結：

1.5 版 Preview 1 (1.5.0-preview1)

這是預覽通道為 1.5 版發布的最新版本。

在現有的 Windows 應用程式 SDK 1.4 版 (來自穩定通道) 應用程式中，您可以將 Nuget 套件更新為 1.5.0-preview1 (請參閱在 Visual Studio 使用 NuGet 套件管理員安裝與管理套件中的更新套件一節)。

如需更新的執行階段和 MSIX，請參閱 Windows 應用程式 SDK 的下載項目。

XAML Islands 執行階段和關閉更新

  • 以 XAML Islands 為基礎的 WinAppSDK 1.4 和 WinAppSDK 1.5 應用程式在關閉任何執行緒的最後一個 XAML 視窗時，會有不同的行為。
    • 在 WinAppSDK 1.4，執行緒的最後一個 XAML 視窗關閉時，XAML 執行階段一律會退出執行緒的事件迴圈。
    • 而在 WinAppSDK 1.5：
      • 如果是 WinUI 桌面應用程式，預設行為仍然和 WinAppSDK 1.4 一樣。
      • 如果您將 XAML 用於 DesktopWindowXamlSource (「XAML Islands」) API，現在的預設行為是 XAML 不會自動退出執行緒的事件迴圈。
      • 在兩種模式，您都可以設定 Application.DispatcherShutdownMode 屬性來變更行為。
    • 如需更多資訊，請在文件仍提供期間參閱文件了解 Application.DispatcherShutdownMode 屬性。
  • 以 XAML Islands 為基礎的 WinAppSDK 1.4 和 WinAppSDK 1.5 應用程式在 XAML 執行階段的存留期方面，有不同的行為。
    • 在 WinAppSDK 1.4，如果特定執行緒的所有 WindowsXamlManager 和 DesktopWindowXamlSource 物件都已關閉，或在執行緒上執行的 DispatcherQueue 已關閉 (XAML 執行階段在 DispatcherQueue.FrameworkShutdownStarting 階段關閉)，執行緒的 XAML 執行階段就會關閉。
    • 在 WinAppSDK 1.5，在執行緒上執行的 DispatcherQueue 關閉 (XAML 執行階段在 DispatcherQueue.FrameworkShutdownStarting 階段關閉)，執行緒的 XAML 執行階段才會關閉。
    • 如需更多資訊，請在文件仍提供期間參閱文件了解 WindowsXamlManager 類別。

WinUI 地圖控制項

WinUI Maps 控制項的初始版本已經發布了！ 此控制項由 WebView2 和 Azure Maps 驅動，可提供下列功能：

  • 以地圖按鈕或觸控方式移動與縮放。
  • 將地圖樣式變更為衛星、地形或街道檢視。
  • 以程式設計方式將開發人員可自訂圖示的互動式圖釘新增到地圖。
  • 開發人員可自訂地圖初次載入時的置中位置。
  • 開發人員可控制要隱藏或顯示移動、縮放和地圖樣式的按鈕。

注意

若要使用 Maps 控制項，您需要 Azure 地圖金鑰。 如要建立金鑰，請參閱 Azure 地圖文件中建立 Web 應用程式的頁面。

Maps 控制項是全新功能，如有意見，歡迎告知我們，以便評估日後調整方向！

WinAppSDK 提供的其他新功能

  • 已新增 PublishSingleFile 部署模型的支援功能。 如需 PublishSingleFile 詳細資訊，請參閱單一檔案部署文件。

錯誤修正

  • 已修正 1.5-experimental2 版本中投影 DLL 無法產生的問題。 關於更多資訊，請參閱 GitHub 問題 #4152。
  • 已修正 RichEditBox 文字格式化快顯示窗的省略符號按鈕無法正確顯示動作清單的問題。 關於更多資訊，請參閱 GitHub 問題 #9140。
  • 已修正 ListView 無法正確處理鍵盤加速器的問題。 關於更多資訊，請參閱 GitHub 問題 #8063。
  • 已修正使用 AccessKey 關閉視窗時的存取違規問題。 關於更多資訊，請參閱 GitHub 問題 #8648。
  • 已修正 MenuBar 中的 MenuFlyoutItem 文字對齊受到影響的問題。 關於更多資訊，請參閱 GitHub 問題 #8755。
  • 已修正反白文字無法在按右鍵時維持反白的問題。 關於更多資訊，請參閱 GitHub 問題 #1801。
  • 已修正閒置視窗關閉時造成應用程式當機的問題。 關於更多資訊，請參閱 GitHub 問題 #8913。
  • 已修正以滑鼠中鍵滑動並隨後立即按左鍵時導致應用程式停格的問題。 關於更多資訊，請參閱 GitHub 問題 #9233。

1.5.0-Preview1 的新 API

1.5-preview1 版與 Stable 1.4 版本相比，多了以下新 API：

Microsoft.Graphics.DirectX
 
    DirectXPixelFormat
        A4B4G4R4

Microsoft.UI.Input
 
    FocusNavigationReason
    FocusNavigationRequest
    FocusNavigationRequestEventArgs
    FocusNavigationResult
    InputFocusController
        DepartFocus
        NavigateFocusRequested
 
    InputFocusNavigationHost

Microsoft.UI.Xaml
 
    Application
        DispatcherShutdownMode

    DebugSettings
        LayoutCycleDebugBreakLevel
        LayoutCycleTracingLevel

    DispatcherShutdownMode
    LayoutCycleDebugBreakLevel
    LayoutCycleTracingLevel

Microsoft.UI.Xaml.Controls
 
    MapControl
    MapControlMapServiceErrorOccurredEventArgs
    MapElement
    MapElementClickEventArgs
    MapElementsLayer
    MapIcon
    MapLayer
    SelectorBar
    SelectorBarItem
    SelectorBarSelectionChangedEventArgs
    WebView2
        EnsureCoreWebView2Async
        EnsureCoreWebView2Async

Microsoft.UI.Xaml.Hosting
 
    WindowsXamlManager
        GetForCurrentThread
        XamlShutdownCompletedOnThread
 
    XamlShutdownCompletedOnThreadEventArgs

Microsoft.Web.WebView2.Core
 
    CoreWebView2
        FrameId

    CoreWebView2AcceleratorKeyPressedEventArgs
        IsBrowserAcceleratorKeyEnabled

    CoreWebView2BrowserExtension
    CoreWebView2BrowsingDataKinds
        ServiceWorkers

    CoreWebView2CustomSchemeRegistration
        CoreWebView2CustomSchemeRegistration (String)
        AllowedOrigins
        SchemeName

    CoreWebView2Environment
        GetProcessExtendedInfosAsync

    CoreWebView2EnvironmentOptions
        AreBrowserExtensionsEnabled
        CustomSchemeRegistrations

    CoreWebView2Frame
        FrameId

    CoreWebView2FrameInfo
        FrameId
        FrameKind
        ParentFrameInfo

    CoreWebView2FrameKind
    CoreWebView2MouseEventKind
        NonClientRightButtonDown
        NonClientRightButtonUp

    CoreWebView2NavigationKind
    CoreWebView2NavigationStartingEventArgs
        NavigationKind

    CoreWebView2NewWindowRequestedEventArgs
        OriginalSourceFrameInfo

    CoreWebView2ProcessExtendedInfo
    CoreWebView2Profile
        AddBrowserExtensionAsync
        Delete
        Deleted

Microsoft.Windows.Management.Deployment
 
    AddPackageOptions
    EnsureReadyOptions
    PackageDeploymentContract
    PackageDeploymentManager
    PackageDeploymentProgress
    PackageDeploymentProgressStatus
    PackageDeploymentResult
    PackageDeploymentStatus
    PackageRuntimeManager
    PackageSet
    PackageSetItem
    PackageSetItemRuntimeDisposition
    PackageSetRuntimeDisposition
    PackageVolume
    ProvisionPackageOptions
    RegisterPackageOptions
    RemovePackageOptions
    StagePackageOptions
    StubPackageOption

Microsoft.Windows.Widgets.Feeds.Providers
 
    CustomQueryParametersRequestedArgs
    CustomQueryParametersUpdateOptions
    FeedDisabledArgs
    FeedEnabledArgs
    FeedManager
    FeedProviderDisabledArgs
    FeedProviderEnabledArgs
    FeedProviderInfo
    IFeedManager
    IFeedProvider

1.4 版 Preview 2 (1.4.0-preview2)

這是預覽通道為 1.4 版發布的最新版本。

在現有的 Windows 應用程式 SDK 1.3 版 (來自穩定通道) 應用程式中，您可以將 Nuget 套件更新為 1.4.0-preview2 (請參閱在 Visual Studio 使用 NuGet 套件管理員安裝與管理套件中的更新套件一節)。

如需更新的執行階段和 MSIX，請參閱 Windows 應用程式 SDK 的下載項目。

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 的基礎支援，或可在沒有 XAML 時使用此 ContentIslands 功能。
  • 新的 DragDropManager (加上相關類型) 已新增到 Microsoft.UI.Input.DragDrop 命名空間供 Island 情境使用。

ItemsView 更新

1.4-preview1 板新推出的 ItemsView 類別已大幅更新，加上新的屬性和支援類別。

  • 新的 ItemsView 控制項會顯示資料集合。 ItemsView 類似於 ListView 和 GridView 控制項，但在組建時使用的是 ItemsRepeater、ScrollView、ItemContainer 和 ItemCollectionTransitionProvider 元件。 它提供的獨特功能可用於插入自訂 Layout 或 ItemCollectionTransitionProvider 實作。 其他關鍵優勢還有即時切換版面配置，同時保留項目選擇的功能。 內部的 ScrollView 控制項還具備 ListView/GridView 的 ScrollViewer 控制項不提供的功能，例如在程式設計的捲動中控制動畫。
    • ItemsRepeater 新的 ItemTransitionProvider 屬性 (和新的 ItemsView 控制項) 可讓您針對該控制項，指定讓 ItemCollectionTransitionProvider 物件控制轉場動畫。 CreateDefaultItemTransitionProvider 方法已新增到 Layout，可讓版面配置物件提供隨附的遞補轉換，以備您沒有針對 ItemsView 控制項提供明確設定時之需。
    • 使用 Layout 新的 IndexBasedLayoutOrientation 屬性時，如有設定項目的版面配置方向，該方向會以項目在來源集合中的索引為依據。 預設值是 IndexBasedLayoutOrientation.None。 自訂版面配置是以呼叫新的 (受保護的) SetIndexBasedLayoutOrientation 方法來設定此屬性。
    • VirtualizingLayoutContext 新的 VisibleRect 屬性會在與 Layout 有關聯的 FrameworkElement 中取得可見的檢視區矩形。 受保護的虛擬 VirtualizingLayoutContext.VisibleRectCore 方法可以覆寫，藉此提供會從 VisibleRect 屬性傳回的值。
  • 新的 LinedFlowLayout 類別通常用於配置 ItemsView 集合控制項的項目。 它在顯示一系列相片時特別實用。 它會將相片由左至右與由上至下排列，每行都是八張。 相片會在填滿水平線後換到下一行。 為了與行貼合，相片的左右邊緣可能會經過裁切。 相片也可能會在部署延展模式時水平延伸，並在上下邊緣經過裁切，藉此將行填滿。

WinAppSDK 的新功能和更新

  • Popup/FlyoutBase.IsConstrainedToRootBounds = false已受支援，可讓快顯視窗/飛出視窗延伸到父視窗的邊界之外。 這些類型已新增 SystemBackdrop 屬性，藉此支援在這類不受限的快顯視窗使用壓克力。 功能表會按照預設，使用此屬性來加上壓克力。
  • Closed、FrameworkClosed 和 IsClosed 已新增到 DesktopAcrylicController 和 MicaController，藉此改善物件/執行緒關閉時的處理方式。
  • DesktopAcrylicController.Kind現在已可設為可在幾種標準壓克力外觀中做選擇。
  • DispatcherQueue有幾種新的事件和協助程式可加強讓關閉更井然有序，且可讓使用 Islands 的應用程式輕鬆執行標準的受支援事件迴圈。
  • InputNonClientPointerSource在 Microsoft.UI.Input 命名空間中可用於自訂標題列情境，藉此定義非用戶端區域的地區。 程式碼可註冊對應事件，例如在這些地區的懸停和點擊事件。
  • AppWindow 有幾種新的協助程式可取得 DispatcherQueue 並與之建立關聯。
  • 新的 TreeView.SelectionChanged 事件可讓開發人員在使用者或程式碼後置變更了 TreeView 控制項的所選節點組合時作出回應。
  • 新的 ScrollView 控制項提供 ScrollViewer 的新替代方案。 這個新的控制項在行為和 API 方面與現有的 ScrollViewer 控制項高度重疊，但卻是以 InteractionTracker 為基礎，具備動畫驅動的檢視變更等功能，且也是為了確保 ItemsRepeater 的完整功能而設計。 請參閱更有彈性的 ScrollViewer · 問題編號 108 · microsoft/microsoft-ui-xaml (github.com) 了解詳情。 完整的 ScrollView 模型已加入各種新類型，包括 ScrollPresenter。
  • 新的 AnnotatedScrollBar 控制項擴充了一般的捲動桿功能，提供可輕鬆瀏覽大量項目集合的方法。 藉由可點擊的滑軌，加上可當作標記使用的標籤，上述方法得以實現。 它也會在懸停於可點擊的滑軌上方時顯示工具提示，藉此讓使用者更了解可捲動內容的細部。

1.4.0-Preview2 的新 API

1.4-preview2 版與之前的 1.4-preview1 版本相比，多了以下新 API：

Microsoft.UI
 
    ClosableNotifierHandler
    IClosableNotifier

Microsoft.UI.Composition.SystemBackdrops
 
    DesktopAcrylicController
        Closed
        FrameworkClosed
        IsClosed
        Kind
 
    DesktopAcrylicKind
    MicaController
        Closed
        FrameworkClosed
        IsClosed

Microsoft.UI.Content
 
    ContentCoordinateConverter
    ContentCoordinateRoundingMode
    ContentDeferral
    ContentEnvironmentSettingChangedEventArgs
    ContentEnvironmentStateChangedEventArgs
    ContentIsland
    ContentIslandAutomationProviderRequestedEventArgs
    ContentIslandEnvironment
    ContentIslandStateChangedEventArgs
    ContentLayoutDirection
    ContentSite
    ContentSiteEnvironment
    ContentSiteEnvironmentView
    ContentSiteRequestedStateChangedEventArgs
    ContentSiteView
    ContentSizePolicy
    DesktopChildSiteBridge
    DesktopSiteBridge
    IContentSiteBridge

Microsoft.UI.Dispatching
 
    DispatcherExitDeferral
    DispatcherQueue
        EnqueueEventLoopExit
        EnsureSystemDispatcherQueue
        FrameworkShutdownCompleted
        FrameworkShutdownStarting
        RunEventLoop
        RunEventLoop
 
    DispatcherQueueController
        ShutdownQueue
 
    DispatcherRunOptions

Microsoft.UI.Input
 
    CharacterReceivedEventArgs
    ContextMenuKeyEventArgs
    FocusChangedEventArgs
    InputActivationListener
        GetForIsland
 
    InputFocusChangedEventArgs
    InputFocusController
    InputKeyboardSource
        CharacterReceived
        ContextMenuKey
        GetCurrentKeyState
        GetForIsland
        GetKeyState
        KeyDown
        KeyUp
        SystemKeyDown
        SystemKeyUp
 
    InputNonClientPointerSource
    InputPointerSource
        GetForIsland
 
    InputPreTranslateKeyboardSource
    KeyEventArgs
    NonClientCaptionTappedEventArgs
    NonClientPointerEventArgs
    NonClientRegionKind
    NonClientRegionsChangedEventArgs
    PhysicalKeyStatus
    VirtualKeyStates

Microsoft.UI.Input.DragDrop
 
    DragDropManager
    DragDropModifiers
    DragInfo
    DragOperation
    DragUIContentMode
    DragUIOverride
    DropOperationTargetRequestedEventArgs
    IDropOperationTarget

Microsoft.UI.Windowing
 
    AppWindow
        AssociateWithDispatcherQueue
        Create
        DispatcherQueue

Microsoft.UI.Xaml
 
    XamlRoot
        ContentIslandEnvironment

Microsoft.UI.Xaml.Automation.Peers
 
    ItemsViewAutomationPeer

Microsoft.UI.Xaml.Controls
 
    AnnotatedScrollBar
    AnnotatedScrollBarDetailLabelRequestedEventArgs
    AnnotatedScrollBarLabel
    AnnotatedScrollBarScrollingEventArgs
    AnnotatedScrollBarScrollingEventKind
    IndexBasedLayoutOrientation
    ItemCollectionTransition
    ItemCollectionTransitionCompletedEventArgs
    ItemCollectionTransitionOperation
    ItemCollectionTransitionProgress
    ItemCollectionTransitionProvider
    ItemCollectionTransitionTriggers
    ItemsRepeater
        ItemTransitionProvider
        ItemTransitionProviderProperty
 
    ItemsView
    ItemsViewItemInvokedEventArgs
    ItemsViewSelectionChangedEventArgs
    ItemsViewSelectionMode
    Layout
        CreateDefaultItemTransitionProvider
        IndexBasedLayoutOrientation
        SetIndexBasedLayoutOrientation
 
    LinedFlowLayout
    LinedFlowLayoutItemCollectionTransitionProvider
    LinedFlowLayoutItemsInfoRequestedEventArgs
    LinedFlowLayoutItemsJustification
    LinedFlowLayoutItemsStretch
    ScrollingAnchorRequestedEventArgs
    ScrollingAnimationMode
    ScrollingBringingIntoViewEventArgs
    ScrollingChainMode
    ScrollingContentOrientation
    ScrollingInputKinds
    ScrollingInteractionState
    ScrollingRailMode
    ScrollingScrollAnimationStartingEventArgs
    ScrollingScrollBarVisibility
    ScrollingScrollCompletedEventArgs
    ScrollingScrollMode
    ScrollingScrollOptions
    ScrollingSnapPointsMode
    ScrollingZoomAnimationStartingEventArgs
    ScrollingZoomCompletedEventArgs
    ScrollingZoomMode
    ScrollingZoomOptions
    ScrollView
    TreeView
        SelectionChanged
 
    TreeViewSelectionChangedEventArgs
    VirtualizingLayoutContext
        VisibleRect
        VisibleRectCore

Microsoft.UI.Xaml.Controls.Primitives
 
    FlyoutBase
        SystemBackdrop
        SystemBackdropProperty
 
    IScrollController
    IScrollControllerPanningInfo
    Popup
        SystemBackdrop
        SystemBackdropProperty
 
    RepeatedScrollSnapPoint
    RepeatedZoomSnapPoint
    ScrollControllerAddScrollVelocityRequestedEventArgs
    ScrollControllerPanRequestedEventArgs
    ScrollControllerScrollByRequestedEventArgs
    ScrollControllerScrollToRequestedEventArgs
    ScrollPresenter
    ScrollSnapPoint
    ScrollSnapPointBase
    ScrollSnapPointsAlignment
    SnapPointBase
    ZoomSnapPoint
    ZoomSnapPointBase

Microsoft.UI.Xaml.Hosting
 
    DesktopWindowXamlSource
    DesktopWindowXamlSourceGotFocusEventArgs
    DesktopWindowXamlSourceTakeFocusRequestedEventArgs
    WindowsXamlManager
    XamlSourceFocusNavigationReason
    XamlSourceFocusNavigationRequest
    XamlSourceFocusNavigationResult

1.4 版 Preview 1 (1.4.0-preview1)

這是預覽通道為 1.4 版發布的最新版本。

在現有的 Windows 應用程式 SDK 1.3 版 (來自穩定通道) 應用程式中，您可以將 Nuget 套件更新為 1.4.0-preview1 (請參閱在 Visual Studio 使用 NuGet 套件管理員安裝與管理套件中的更新套件一節)。

如需更新的執行階段和 MSIX，請參閱 Windows 應用程式 SDK 的下載項目。

小工具更新

新增三種新介面，可供小工具提供者實作：IWidgetProvider2、IWidgetProviderAnalytics 和 IWidgetProviderErrors。 IWidgetProvider2 可讓提供者回應使用者叫用的自訂動作，等同於第一方小工具可提供的功能。 提供者可使用 IWidgetProviderAnalytics 和 IWidgetProviderErrors 為小工具收集遙測資料；小工具的分析和失敗事件都會通知對應的小工具提供者。 WidgetCustomizationRequestedArgs、WidgetAnalyticsInfoReportedArgs 和 WidgetErrorInfoReportedArgs 類別會用於通知相關資訊，以便支援新功能。

WinAppSDK 提供的新功能

  • 新的 ThemeSettings 類別可讓 Win32 WinRT 應用程式偵測到系統的高對比設定發生變更，此功能類似 UWP 的 AccessibilitySettings 類別。 請參閱 GitHub 的 ThemeSettings API 規格了解詳情。
  • Popup/FlyoutBase.ShouldConstrainToRootBounds已受支援，可讓工具提示、功能表和其他快顯視窗延伸到主視窗的邊界之外。 Preview 1 尚未完全支援在快顯視窗/飛出視窗使用壓克力或其他 SystemBackdrops；下個 1.4 版本將會納入其他 API 和這項實作功能。
  • AccessKeyManager.EnterDisplayMode是針對既有根目錄目前的焦點元素顯示存取金鑰的新方法。 顯示叫用命令的按鍵提示時，存取金鑰會處於「顯示模式」，例如在小畫家按下 Alt 鍵可顯示各個按鍵對應的控制項。 這種方法可讓使用者以程式設計方式進入顯示模式。
  • Application.ResourceManagerRequested 透過一套機制來提供不同的 IResourceManager，以便在預設 ResourceManager 無法運作時解析資源 URI。 請參閱 GitHub 的 Application.ResourceManagerRequested API 規格了解詳情。
  • 我們即將推出名稱為 ItemsView 的新清單控制項，以及對應的實體 ItemContainer 類別。 ItemContainer 是一種輕量的容器，內建選取狀態和視覺，可輕易包覆所需內容，並搭配 ItemsView 使用於集合控制項情境。 ItemsView在 Preview 1 仍然標示為實驗版，但會納入下個 1.4 版本。
  • WebView2 SDK 版本已從 1661.34 更新為 1823.32。

1.4.0-Preview1 的新 API

1.4-preview1 版與 Stable 1.3 版本相比，多了以下新 API：

Microsoft.UI.System
 
    ThemeSettings

Microsoft.UI.Xaml
 
    Application
        ResourceManagerRequested
 
    ResourceManagerRequestedEventArgs

Microsoft.UI.Xaml.Automation.Peers
 
    ItemContainerAutomationPeer

Microsoft.UI.Xaml.Controls
 
    ItemContainer

Microsoft.UI.Xaml.Controls.Primitives
 
    CommandBarFlyoutCommandBar
        SystemBackdrop
        SystemBackdropProperty

Microsoft.UI.Xaml.Input
 
    AccessKeyManager
        EnterDisplayMode

Microsoft.Web.WebView2.Core
 
    CoreWebView2
        LaunchingExternalUriScheme
        MemoryUsageTargetLevel
 
    CoreWebView2File
    CoreWebView2LaunchingExternalUriSchemeEventArgs
    CoreWebView2MemoryUsageTargetLevel
    CoreWebView2PermissionKind
        WindowManagement
 
    CoreWebView2Profile
        CookieManager
        IsGeneralAutofillEnabled
        IsPasswordAutosaveEnabled
 
    CoreWebView2Settings
        IsReputationCheckingRequired
 
    CoreWebView2WebMessageReceivedEventArgs
        AdditionalObjects

Microsoft.Windows.Widgets.Providers
 
    IWidgetProvider2
    IWidgetProviderAnalytics
    IWidgetProviderErrors
    WidgetAnalyticsInfoReportedArgs
    WidgetCustomizationRequestedArgs
    WidgetErrorInfoReportedArgs

1.3 版 Preview 1 (1.3.0-preview1)

這是預覽通道為 1.3 版發布的最新版本。 此版本收錄了 WinAppSDK 各項新功能的預覽版本，以及數種效能、安全性、協助工具和可靠性的錯誤修正。

在現有的 Windows 應用程式 SDK 1.2 版 (來自穩定通道) 應用程式中，您可以將 Nuget 套件更新為 1.3.0-preview1 (請參閱在 Visual Studio 使用 NuGet 套件管理員安裝與管理套件中的更新套件一節)。

如需更新的執行階段和 MSIX，請參閱 Windows 應用程式 SDK 的下載項目。

XAML 底圖 API

透過 XAML 視窗中內建的屬性，Mica & Background Acrylic 背景現在可以更輕鬆地在 WinUI 3 應用程式中使用。 有關 Window.SystemBackdrop 屬性的詳細信息，請參閱 GitHub 上的 Xaml Backdrop API 規範。

public MainWindow()
{
    this.InitializeComponent();

    this.SystemBackdrop = new MicaBackdrop();
}

Window.AppWindow

透過替換幾行樣板程式碼，您現在可以直接從 Window 通過 Window.AppWindow。 有關其他背景和使用信息，請參閱 GitHub 上的 Window.AppWindow API 規格。

來自 WinAppSDK 的新功能

  • ApplicationModel.DynamicDependency：PackageDependency.PackageGraphRevisionId 替換已棄用的 MddGetGenerationId。
  • 環境管理員：EnvironmentManager.AreChangesTracked 告知您是否能夠在應用程式中追蹤環境管理員的變更。 如需詳細資訊，請參閱 GitHub 上的環境管理員 API 規格。
  • MRT Core：一個新事件，Application.ResourceManagerInitializing 允許您的應用程式提供自己的 IResourceManager 介面實現，並允許您存取 WinUI 用於解析資源 URI 的 ResourceManager。 請參閱 GitHub 的 IResourceManager API 規格了解詳情。
  • 在加入最新的實驗版 VSIX 後，您現在已可透過 Visual Studio 功能表將應用程式轉換成封裝與未封裝，無需使用專案檔案。
  • 現在，當 DebugSettings.XamlResourceReferenceFailed 無法解析引用的 Static/ThemeResource 查找時，會引發一個新事件。 此事件允許存取詳細說明架構在何處搜尋該金鑰的追蹤，以便您更好地調試 Static & ThemeResource 查找失敗。 如需詳細資訊，請參閱 API 規格 和 GitHub 的問題 4972、2350 和 6073。
  • 部署：DeploymentManager 中現在已可提供 DeploymentRepairOptions，以便管理與修復 Windows 應用程式執行階段。 請參閱 GitHub 的 Deployment API 規格的「修復」一節了解詳情。

已知問題

  • 樞紐控制項會造成當機，產生 XAML 剖析錯誤。 如需詳細資訊，請參閱 GitHub 的問題 #8160。
  • DatePicker 或 TimePicker 飛出視窗開啟時，應用程式會當機。
  • 1.3 版推出的 WindowsAppRuntime.ReleaseInfo 和 WindowsAppRuntime.RuntimeInfo API 內含重大錯誤，因此尚不受支援。

1.2 版 Preview 2 (1.2.0-preview2)

這是預覽通道為 1.2 版發布的最新版本。

在現有的 Windows 應用程式 SDK 1.1 版 (來自穩定通道) 應用程式中，您可以將 Nuget 套件更新為 1.2.0-preview2 (請參閱在 Visual Studio 使用 NuGet 套件管理員安裝與管理套件中的更新套件一節)。

如需更新的執行階段和 MSIX，請參閱 Windows 應用程式 SDK 的下載項目。

重要

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。

若要更新 .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，「目標 OS 版本」則變更為適用的值 (例如 net6.0-windows10.0.19041.0)。

Windows 的第三方小工具

小工具面板最初是在 Windows 11 推出，但僅限於顯示第一方小工具。 小工具是小型的 UI 容器，可在小工具面板顯示文字和圖形，且與裝置上安裝的應用程式相關聯。 透過 Windows 應用程式 SDK，第三方開發人員如今已可為封裝的 Win32 應用程式建立小工具，並在 Windows 11 小工具面板進行本機測試。

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

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

此版本的先決條件包括：

  • 在開發機器啟用開發人員模式。
  • 開發機器執行的 Windows 版本來自 Windows 測試人員計畫 (WIP) 的開發人員通道，其中小工具面板的版本為 521.20060.1205.0 或以上。

開發小工具時的已知限制

  • 第三方小工具只能在已於 WIP 註冊此預覽版本的裝置進行本機測試。 在 Windows 應用程式 SDK 1.2.0，使用 Windows 零售版本的使用者已經可以透過應用程式在 Microsoft Store 的上架版本取得第三方小工具。
  • 小工具只能在封裝的 Win32 應用程式建立。 漸進式 Web 應用程式 (PWA) 的小工具預計將在 Microsoft Edge 108 中獲得支援。

精簡以 .NET 開發的應用程式

.NET 開發人員現在已可發布精簡過的 WinAppSDK 應用程式。 有了 CsWinRT 2.0，以 WinAppSDK 發布的 C#/WinRT 投射現在已可精簡。 發布精簡過的應用程式可減少應用程式在硬碟占用的空間，因為可精簡的二進位碼中未使用的程式碼都已移除。 應用程式的啟動效能可能會改善。 在發布精簡的基本 Hello World 應用程式後，我們發現硬碟佔用空間減少將近 80%，且啟動效能改善了約 7%。 精簡的 WinUI 程式庫則節省了近 45% 的硬碟空間。

如需詳細了解精簡功能的起用方式、精簡的限制 (例如可精簡類型產生的反射)，以及精簡警告，請參閱精簡獨立部署和可執行檔。 開發人員在精簡後，應徹底測試應用程式，確保所有功能皆如期運作。 如需詳細資訊，請參閱 GitHub 問題 2478。

DisplayInformation

Win32 應用程式現在已可透過 WinAppSDK 的 DisplayInformation 類別支援高動態範圍 (HDR)。 DisplayInformation 類別可讓您監控應用程式檢視的顯示器相關資訊。 其中包含的事件可讓用戶端監控對應用程式檢視的所在顯示器有影響的檢視變更，以及對應用程式檢視可能有影響的顯示器變更。

已修正 WinUI 3 的問題

  • Windows 10 應用程式已可支援從 DesktopAcrylicController 取得壓克力底圖材質。 如需詳細資訊，請參閱 GitHub 問題 7112。
  • 已修正 App.UnhandledException 路由到應用程式時失敗的問題。 如需詳細資訊，請參閱 GitHub 問題 5221。
  • 已修正 WinAppSDK 1.1 的 ListView 樣式迴歸予變更的問題。 如需詳細資訊，請參閱 GitHub 問題 7666。

其他限制和已知問題

重要

當您從專案參照 WinAppSDK 1.2 時，您可能會看到類似如下的錯誤：「偵測到套件降級：Microsoft.Windows.SDK.BuildTools 從 10.0.22621.1 降級為 10.0.22000.194」，原因是應用程式專案和 WinAppSDK 套件的套件參照不相容。 若要解決此問題，您可以將專案的參照更新到較新且相容的 Microsoft.Windows.SDK.BuildTools 版本，或移除專案中的參照。 移除專案的參照後，WinAppSDK 套件就會隱含地參照相容的版本。

  • 目前不支援以 Arm64 Visual Studio 進行組建。
  • 啟動程序載入程式和 Undocked RegFree WinRT 自動初始設定式的預設值 (現在) 僅供會產生可執行檔 (OutputType=Exe 或 WinExe) 的專案使用。 這可以避免類別庫 DLL 和其他非可執行檔依預設新增自動初始設定式。
    • 如果您的非可執行檔 (例如不會初始化啟動程序載入程式的一般可執行檔所載入的測試 DLL)，您可以經由 <WindowsAppSdkBootstrapInitialize>true</WindowsAppSdkBootstrapInitialize> 或 <WindowsAppSdkUndockedRegFreeWinRTInitialize>true</WindowsAppSdkUndockedRegFreeWinRTInitialize> 在專案明確啟用自動初始設定式。
  • 您可以呼叫版本資訊 API (ReleaseInfo 和 RuntimeInfo)，但會傳回版本 0 (並非實際版本資訊)。

1.2 版 Preview 1 (1.2.0-preview1)

在現有的 Windows 應用程式 SDK 1.1 版 (來自穩定通道) 應用程式中，您可以將 Nuget 套件更新為 1.2.0-preview1 (請參閱在 Visual Studio 使用 NuGet 套件管理員安裝與管理套件中的更新套件一節)。

如需更新的執行階段和 MSIX，請參閱 Windows 應用程式 SDK 的下載項目。

WinUI 3

WinUI 3 應用程式可透過 MediaPlayerElement 和 MediaTransportControls 媒體播放控制項播放影音。 如需詳細了解使用媒體控制項的方式和時機，請參閱媒體播放器。

WinUI 3 已經更新，最新的控制項、樣式和行為已與 WinUI 2.8 不同。 這些更新包含新增了 InfoBadge 控制項、改善了協助工具和高對比模式，以及修正控制項的錯誤。 如需詳細資訊，請參閱 WinUI 2.7 和 WinUI 2.8 的版本資訊。

已知問題

WinAppSDK 1.1 的 ListView 樣式會迴歸和變更。

通知

AppNotificationBuilder 推出了 XML 承載的替代方案，可供建立與定義應用程式通知。

請參閱 GitHub 的 AppNotificationBuilder 規格了解使用資訊。

另請參閱快速入門：Windows 應用程式 SDK 的應用程式通知，以便參考如何建立桌面 Windows 應用程式來傳送和接收本機應用程式通知的範例。

重大變更

如果是推播通知，在進行通道請求呼叫時，應用程式需要使用 Azure 物件 ID，而不是 Azure 應用程式 ID。 如需詳細了解如何尋找 Azure 物件識別碼，請參閱快速入門：Windows 應用程式 SDK 的推播通知。

已修正的問題

PushNotificationManager.IsSupported 會針對高權限模式執行檢查。 如果應用程式的權限升高，就會傳回 false。

已知限制 (通知)

視窗化

Windows 10 的 1809 和之後的版本可透過 AppWindowTitleBar 類別完整自訂標題列。 您可以將 AppWindowTitleBar.ExtendsContentIntoTitleBar 設為 true，藉此將內容擴充到標題列區域；設為 SetDragRectangles 則可定義拖曳區域 (除了其他自訂選項之外)。

如果您以前都是使用 AppWindowTitleBar.IsCustomizationSupported 屬性來確認您是否可以呼叫 AppWindowTitleBar API，它現在會在支援的 Windows 應用程式 SDK Windows 10 版本 (1809 及之後的版本) 傳回 true。

已知限制 (視窗化)

Windows 10 不支援簡單的標題列自訂。 這些自訂項目包括 BackgroundColor、InactiveBackgroundColor、ForegroundColor、InactiveForegroundColor 和 IconShowOptions。 如果您呼叫這些屬性，系統會忽略它們且不傳送通知。 其他 AppWindowTitleBar API 都能在 Windows 10 版本 1809 和之後版本運作。 如要自訂隱藏式輔助字幕按鈕顏色的 API 等屬性和 Height，ExtendsContentIntoTitleBar 必須設為 true，否則系統也會忽略它們且不傳送通知。

存取控制

已在 GetSecurityDescriptorForAppContainerNames 功能推出 security.accesscontrol.h，使封裝程序和一般 Win32 API 之間的命名物件共用更簡單流暢。 此方法會擷取套件系列名稱 (PFN) 清單並存取遮罩，然後傳回安全性描述項。 請參閱 GitHub 的 GetSecurityDescriptorForAppContainerNames 規格了解詳情。

其他限制和已知問題

  • .NET PublishSingleFile 不受支援。

1.1 版 Preview 3 (1.1.0-preview3)

這是預覽通道為 1.1 版發布的最新版本。 它支援所有預覽通道的功能 (請參閱各別發布通道提供的功能)。

在現有的 Windows 應用程式 SDK 1.0 版應用程式中，您可以將 Nuget 套件更新為 1.1.0-preview3 (請參閱在 Visual Studio 使用 NuGet 套件管理員安裝與管理套件中的更新套件一節)。 此外，請查看 Windows 應用程式 SDK 的下載項目取得更新的執行階段和 MSIX。

注意

如果您是 C# 開發人員，您需要下列其中一個 .NET SDK 版本：5.0.213、5.0.407、6.0.104、6.0.202 (或之後的版本)。 若要更新 .NET SDK 版本，請前往 .NET 下載項目或更新至 Visual Studio 最新版。 在沒有所需 .NET SDK 版本的情況下更新 NuGet 套件時，您會看到如下的錯誤：「此版本的 WindowsAppSDK 需要 .NET 6+ 和 WinRT.Runtime.dll 1.6 版或更高的版本。」

除了 Preview 2 的全部功能，下列章節還說明此版本的新增與更新功能、限制和已知問題。

WinUI 3

WinUI 3 應用程式現在已支援雲母和背景壓克力。

如需詳細了解這些材質，請參閱 Windows 11 的材質。 請在以 WinUI 3 XAML 使用 SystemBackdropController，以及在 GitHub 的 WinUI 控制項程式庫中，分別取得在 C++ 應用程式和 C# 應用程式套用雲母的範例程式碼。

通知

修正的問題：

  • 在 1.1.0-preview1 和 1.1.0-preview2，有些未封裝應用程式的圖示會錯誤複製到 AppData\LocalMicrosoftWindowsAppSDK。 在此版本，這些圖示會改複製到 AppData\Local\Microsoft\WindowsAppSDK。 為避免圖示外流，請在更新到 1.1.0-preview3 後手動刪除錯誤路徑的應用程式圖示。
  • 現在已支援透過捷徑擷取應用程式通知中的應用程式圖示和顯示名稱。 此應用程式圖示的優先權會高於資源檔案中指定的任何圖示。
  • 未封裝應用程式推播通知的支援功能已復原 (請參閱限制了解已備註的例外)。 我們推出的 PushNotificationManager::IsSupported API 可檢查您的應用程式是否支援推播通知。

限制：

  • 目前不支援高權限的未封裝應用程式通知。 PushNotificationManager::IsSupported 不會針對高權限模式執行檢查。 不過，我們正在嘗試於日後的版本支援此功能。

MSIX 封裝

我們強化了 MSIX，讓它透過以下擴充功能類別來新增與擴充現有功能：

  • windows.appExecutionAlias
  • windows.customDesktopEventLog
  • windows.dataShortcuts
  • windows.fileTypeAssociation
  • windows.fileTypeAssociation.iconHandler
  • windows.folder
  • windows.shortcut

這些類別都需要安裝 Windows 應用程式 SDK 架構套件。 請參閱 Windows 應用程式 SDK 的下載項目安裝執行階段。

環境管理員

可讓開發人員新增、移除與修改環境變數的 API 設定，無需直接使用登錄 API。

1.1 Preview 1 澄清：使用環境管理員的應用程式在解除安裝後會使任何環境變數變更都一併自動移除的功能僅適用於封裝應用程式。 此外，擷取環境變數變更需要安裝 Windows 應用程式 SDK 架構套件，請查看 Windows 應用程式 SDK 下載項目下載執行階段。

其他已知限制

1.1 版 Preview 2 的迴歸：

  • 使用 MRT Core API 的 .NET 應用程式和不會部署單一專案 MSIX 的 WinUI 應用程式：
    • 已新增到專案成為現有項目及之前分別自動加入 PRIResource 及 Content ItemGroups 的 RESW 和影像檔案將不會加入上述 ItemGroups。 因此，這些資源在 PRI 產生過程不會加到索引，所以在執行階段無法使用。
      • 解決辦法：手動將這些資源加入專案檔案，然後從 None ItemGroup 移除。
      • 替代的因應措施：可用時，請將應用程式的 .NET SDK 升級至 6.0.300。 請參閱 .NET SDK 的版本需求了解額外資訊。
  • 如果是不會部署單一專案 MSIX 的 .NET 應用程式：
    • 如果檔案已新增到 Content ItemGroup 兩次以上，就會發生組建錯誤。
      • 解決辦法：刪除重複的新增項目，或將專案檔案的 EnableDefaultContentItems 設為 false。

兩者的迴歸都會復原為下個穩定版本。

1.1 版 Preview 2 (1.1.0-preview2)

這是預覽通道為 1.1 版發布的第二版。 它支援所有預覽通道的功能 (請參閱各別發布通道提供的功能)。

在現有的 Windows 應用程式 SDK 1.0 版應用程式中，您可以將 Nuget 套件更新為 1.1.0-preview2 (請參閱在 Visual Studio 使用 NuGet 套件管理員安裝與管理套件中的更新套件一節)。 此外，請查看 Windows 應用程式 SDK 的下載項目取得更新的執行階段和 MSIX。

注意

如果您是 C# 開發人員，您需要下列其中一個 .NET SDK 版本：5.0.213、5.0.407、6.0.104、6.0.202 (或之後的版本)。 若要更新 .NET SDK 版本，請前往 .NET 下載項目或更新至 Visual Studio 最新版。 在沒有所需 .NET SDK 版本的情況下更新 NuGet 套件時，您會看到如下的錯誤：「此版本的 WindowsAppSDK 需要 .NET 6+ 和 WinRT.Runtime.dll 1.6 版或更高的版本。」

除了 Preview 1 的全部功能，下列章節還說明此版本的新增與更新功能、限制和已知問題。

通知

修正的問題：

  • 應用程式如沒有套件身分識別，在傳送通知後，如果應用程式圖示屬於應用程式的資源，圖示就會顯示在通知中。 如果應用程式資源不含圖示，系統就會使用 Windows 預設應用程式圖示。
  • 未在執行中的 WinUI 3 應用程式，現在已可透過通知在背景啟動。

1.1 Preview 1 的迴歸： 未封裝應用程式的推播通知支援。 預計在下個版本復原。

已知限制：

  • 我們推出的 PushNotificationManager::IsSupported API 可檢查獨立應用程式是否支援推播通知。 不過，此 API 仍無法按照預期運作，我們會在下個預覽版本完整支援 IsSupported API，請靜候佳音。
  • 有些未封裝應用程式的圖示會錯誤複製到 AppData\LocalMicrosoftWindowsAppSDK。 在下個版本，這些圖示會改複製到 AppData\Local\Microsoft\WindowsAppSDK。 為避免圖示外流，開發人員必須在升級到下個版本後手動刪除錯誤路徑的應用程式圖示。
  • 不支援透過捷徑擷取通知中的應用程式圖示和顯示名稱。 不過，我們正在嘗試於日後的版本支援此功能。

部署

新功能：

已知限制：

  • 只有 Windows 10 的 1903 和之後版本支援獨立部署。

視窗化

如需更輕鬆以程式設計方式存取在 USER32.dll 實作的功能 (請參閱 Windows 與訊息)，此版本在 AppWindow 本身呈現更多該類功能。

新功能：

  • 應用程式在開啟視窗後，如果呼叫 AppWindow.ShowOnceWithRequestedStartupState (等同於 ShowWindow(SW_SHOWDEFAULT))，對視窗的顯示方式有更多的控制權。
  • 應用程式可顯示、最小化或復原視窗，並指定視窗是否要在接收到呼叫時啟動。
  • 應用程式現在可設定視窗在 Win32 座標的用戶端區域大小。
  • 我們已新增 API 來支援管理 Z 軸方向的視窗。
  • 以 AppWindowTitleBar.ExtendsContentIntoTitleBar 繪製自訂標題列的應用程式，可設定 PreferredTitleBarHeight 選項。 您可以選擇標準高度標題列，或選擇長標題列來加大空間放入互動式內容。 請參閱 Fluent 設計指導方針的標題列，了解使用長標題列的建議時機。

已知限制：

  • 只有 Windows 11 支援長標題列。 我們正在致力將此功能連同其他自訂標題列 API 往下支援。

WinUI 3

修正的問題：

  • 已修正沒有藉由將 WebView2 SDK 從 1020.46 升級到 1185.39 來安裝 C/C++ 執行階段 (CRT) 時，含有 WebView2 的 C# 應用程式會在啟動時當機的問題。
  • 已修正有些圓角在理應顯示單色時卻顯示漸層的問題。 如需詳細資訊，請參閱 GitHub 的問題 6076 & 問題 6194。
  • 已修正更新的樣式在 generic.xaml 遺失的問題。
  • 已修正捲動至 ListView 尾端會導致應用程式當機的版面配置循環問題。 如需詳細資訊，請參閱 GitHub 上的問題 6218。

效能

C# 應用程式有多項效能改良。 如需了解詳情，請參閱 C#/WinRT 1.6.1 版本資訊。

1.1 版 Preview 1 (1.1.0-preview1)

這是預覽通道為 1.1 版發布的第一版。 它支援所有預覽通道的功能 (請參閱各別發布通道提供的功能)。

在現有的 Windows 應用程式 SDK 1.0 版應用程式中，您可以將 Nuget 套件更新為 1.1.0-preview1 (請參閱在 Visual Studio 使用 NuGet 套件管理員安裝與管理套件中的更新套件一節)。 此外，請查看 Windows 應用程式 SDK 的下載項目取得更新的執行階段和 MSIX。

下列章節說明此版本的新增與更新功能、限制和已知問題。

WinUI 3

已知問題：已修正拖放功能啟用時使用者無法放下元素的問題。

高權限 (管理員) 支援

使用 Windows App SDK 1.1 Preview 1 時，應用程式 (包括 WinUI 3) 能以更高的權限運作。

重要限制

  • 目前僅適用於 Windows 11。 我們正在評估於之後的版本將此支援功能向下支援。

已知問題

  • WinUI 3 應用程式在拖放功能的互動中，會在拖曳元素時當機。

自封式部署

Windows 應用程式 SDK 1.1 將推出獨立式部署的支援功能。 我們的部署概覽詳述了架構相依式及獨立式部署的差異，以及操作方法。

已知問題：

  • 已封裝的 C++ 應用程式需要將下列項目新增到專案檔案的下方，才能解決獨立式 .targets 檔案移除 VCLibs 架構參照的問題：

    <PropertyGroup>
    <IncludeGetResolvedSDKReferences>true</IncludeGetResolvedSDKReferences>
</PropertyGroup>

<Target Name="_RemoveFrameworkReferences"
    BeforeTargets="_ConvertItems;_CalculateInputsForGenerateCurrentProjectAppxManifest">
    <ItemGroup>
        <FrameworkSdkReference Remove="@(FrameworkSdkReference)" Condition="'%(FrameworkSdkReference.SDKName)' == 'Microsoft.WindowsAppRuntime.1.1-preview1'" />
    </ItemGroup>
</Target>

  • 只有 Windows 10 的 1903 和之後版本提供支援。

通知

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

新功能：

  • 支援封裝與未封裝應用程式的應用程式通知。 GitHub 的完整詳情
    • 開發人員可以在本機或從自己的雲端服務傳送應用程式通知，也就是快顯通知。
  • 支援封裝與未封裝應用程式的推播通知。 GitHub 的完整詳情
    • 開發人員可從自己的雲端服務傳送原始通知或應用程式通知。

限制：

  • 獨立式發布的應用程式可能不支援推播通知。 下個預覽版本的 IsSupported API 將支援推播通知，請靜候佳音。
  • 未封裝的應用程式在傳送應用程式通知時，除非是主控台應用程式，否則應用程式通知不會顯示應用程式圖示。 未封裝的主控台應用程式應遵循 ToastNotificationsDemoApp 範例所式的模式。
  • 您必須安裝 Windows 應用程式 SDK 執行階段，才可支援推播通知，請查看 Windows 應用程式 SDK 的下載項目取得安裝程式。
  • 未在執行中的 WinUI 3 應用程式，無法透過通知在背景啟動。 不過，我們正在嘗試於日後的版本支援此功能。

環境管理員

可讓開發人員新增、移除與修改環境變數的 API 設定，無需直接使用登錄 API。

新功能

  • 使用環境管理員的應用程式在解除安裝後，任何環境變數變更都會自動移除。

限制

  • 目前不支援 C# 應用程式。 我們正在評估於之後的版本將此功能加入 C# 應用程式。

其他限制和已知問題

  • 如果您使用 C# 搭配 1.1.0 Preview 1，則必須至少使用下列其中一個 .NET SDK 版本：.NET SDK 6.0.201、6.0.103、5.0.212 或 5.0.406。 如要升級 .NET SDK，您可以更新為最新版的 Visual Studio，或前往下載 .NET。

1.0 版 Preview 3 (1.0.0-preview3)

Preview 3 是 Windows 應用程式 SDK 1.0 版的預覽通道最新版本。 Preview 3 支援所有預覽通道功能。

下載 1.0 Preview 3 Visual Studio 延伸模組 (VSIX)

注意

如果您已安裝 Windows 應用程式 SDK Visual Studio 延伸模組 (VSIX)，請先解除安裝再安裝新版。 如需指示，請參閱 管理 Visual Studio 的延伸模組。

您可在下表下載 1.0 版 Preview 3 的 Visual Studio 延伸模組 (VSIX)。 如需全部版本，請參閱 Windows 應用程式 SDK 下載項目。 如果您尚未下載，請先按照安裝 Windows 應用程式 SDK 的工具設定開發環境。

下方的延伸模組係為您的程式設計語言和 Visual Studio 版本量身打造。

1.0 版 Preview 3 下載項目 說明
C# Visual Studio 2019 擴充功能 以 Windows 應用程式 SDK Visual Studio 2019 延伸模組組建 C# 應用程式。
C++ Visual Studio 2019 擴充功能 以 Windows 應用程式 SDK Visual Studio 2019 延伸模組組建 C++ 應用程式。
C# Visual Studio 2022 擴充功能 以 Windows 應用程式 SDK Visual Studio 2022 延伸模組組建 C# 應用程式。
C++ Visual Studio 2022 擴充功能 以 Windows 應用程式 SDK Visual Studio 2022 延伸模組組建 C++ 應用程式。
.exe 安裝程式和 MSIX 套件 使用 .exe 安裝程式和 MSIX 套件對應用程式部署 Windows 應用程式 SDK。

下列章節說明 1.0 版 Preview 3 的新增與更新功能、限制和已知問題。

WinUI 3

我們現在已支援不需 MSIX 套件即可部署 WinUI 3 應用程式。 請參閱建立您的第一個 WinUI 3 專案，以便設定 WinUI 3 應用程式來支援未封裝部署。

重要限制

  • 只有 Windows 1909 和之後的版本支援未封裝的 WinUI 3 應用程式。
  • x86 和 x64 支援未封裝的 WinUI 3 應用程式；arm64 將會在下個穩定版本加入支援。
  • 未封裝應用程式需要 Visual Studio 2019 或 Visual Studio 2022 的單一專案 MSIX 封裝工具。
  • 在未封裝的應用程式，您可能會收到提示要求您安裝 .NET 3.5；如有收到，您可以忽略提示。
  • 未封裝應用程式目前不支援部分 API。 我們預計在下個穩定版本修正這個情況。 下方為幾個例子：
  • ListView、CalendarView 和 GridView 控制項目前使用錯誤的樣式，但我們預計在下個穩定版本修正這個情況。

如需詳情，或要開始以 WinUI 3 進行開發，請參閱：

其他限制和已知問題

  • Windows 10 1809 版不支援未封裝應用程式。 我們預計在下個穩定通道的版本修正這個情況。

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

  • 此版推出了適用於 C# and C++ 的已封裝的空白應用程式 (桌面版 WinUI) 專案範本。 這類範本可讓您在 MSIX 套件中組建應用程式，無需另外使用封裝專案 (請參閱使用單一專案 MSIX 封裝應用程式)。 這些範本在此版本有以下已知問題：

    • 除非重新啟動 Visual Studio，否則缺少「發布」功能表。 在 Visual Studio 2019 和 Visual Studio 2022 使用已封裝的空白應用程式已封裝 (桌面版 WinUI) 專案範本建立新應用程式時，除非您關閉 Visual Studio 在重新開啟，否則發布專案的命令不會顯示在功能表。

    • 使用單一專案 MSIX 封裝新增 C++ 靜態/動態程式庫專案參照到 C++ 應用程式時會發生錯誤。 Visual Studio 會顯示錯誤，告知專案無法新增為參照，因為專案類型不相容。

    • 參照類別庫專案中的自訂使用者控制項時會發生錯誤。 由於發生系統找不到指定路徑的錯誤，應用程式會當機。

    • Visual Studio 2019 的 C# 或 C++ 範本。 嘗試組建專案時，會出現錯誤「專案不知道如何執行設定檔專案名稱」。 若要解決此問題，請安裝單一專案 MSIX 封裝工具延伸模組。

    • Visual Studio 2019 和 Visual Studio 2022 的 C# 範本。 在 Visual Studio 開始偵錯或開始但不偵錯時，如果應用程式並未部署與執行 (且 Visual Studio 沒有回饋)，請按一下以選取方案總管中的專案節點，並再試一次。

    • Visual Studio 2019 和 Visual Studio 2022 的 C# 範本。 當您嘗試在開發電腦上執行或偵錯專案時，會發生下列錯誤：「必須先部署專案，才能進行偵錯。 請在組態管理員啟用『部署』」。若要解決此問題，請在組態管理員為專案啟用部署。 如需詳細操作指示，請參閱建立您的第一個 WinUI 3 專案。

    • Visual Studio 2022 版 17.0 C++ 範本已達 Preview 4。 第一次嘗試執行專案時，您會遇到下列錯誤：「發生部署錯誤」。 若要解決此問題，請再次執行或部署專案。 此問題將在 Visual Studio 2022 版 17.0 Preview 7 修正。

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

  • 使用 1.0 Preview 3 的 C# 專案必須使用下列 .NET SDK：.NET 6 SDK 或之後的版本 (請參閱下載 .NET 和 .NET 5 將於 2022 年 5 月 10 日終止支援）。

  • 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);。

影響 1.0 Preview 1 和 Preview 2 的重大問題

Windows 應用程式 SDK 的 Version 1.0 Preview 1 和 Preview 2 採納一套機制，可在應用程式解除安裝時，將封裝應用程式產生的任何環境變數變更都清除。 此功能仍處在實驗階段，且第一版存在已知錯誤，可能會使系統的 PATH 環境變數損毀。

Preview 1 和 Preview 2 會使含有擴充字元 % 的任何 PATH 環境變數損毀。 每次有封裝應用程式解除安裝都會發生這種情況，無論應用程式是否使用 Windows 應用程式 SDK。

另請參閱 PATH 環境變數損毀問題。

詳細資料

系統的 PATH 項目以 Path 值存放在下列 Windows 登錄的金鑰中：

Computer\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Environment

如果您啟動登錄編輯器 (regedit.exe)，就能將上方路徑複製並貼到階層連結列 (功能表列下方)，然後按下 Enter 就能找到金鑰。

金鑰的 Path 值應屬 REG_EXPAND_SZ 類型，但會因錯誤而變更為 REG_SZ。 如果當中包含變數擴充字元 %，系統的 PATH 環境變數就會變得不可用。

受影響的版本

風險降低

若要讓機器復原到良好狀態，請按照下列步驟操作：

  1. 檢查登錄中的 PATH 是否損毀，如果是，請執行下方指令碼重設。

    您可以使用下列 Windows PowerShell 指令碼完成步驟 1 (PowerShell Core 無效)。 執行時請提高權限。

    # This script must be run from an elevated Windows PowerShell
# window (right-click Windows PowerShell in the Start menu,
# and select Run as Administrator).

# If the PATH in the Registry has been set to REG_SZ, then delete
# it, and recreate it as REG_EXPAND_SZ.

$EnvPath = 'Registry::HKLM\System\CurrentControlSet\Control\Session Manager\Environment'
$Environment=Get-Item $EnvPath
$PathKind = $Environment.GetValueKind('Path')

if ($PathKind -ne 'ExpandString') {
  $Path = $Environment.GetValue('Path')
  Remove-ItemProperty $EnvPath -Name Path
  New-ItemProperty $EnvPath -Name Path -PropertyType ExpandString -Value $Path
}

  2. 解除安裝所有使用 Windows 應用程式 SDK 1.0 Preview1 或 Preview2 的應用程式 (請見下方指令碼)。

  3. 解除安裝 Windows 應用程式 SDK 1.0 Preview1/Preview2 套件，包括內含錯誤的套件 (請見下方指令碼)。

    您可以使用下列 Windows PowerShell 指令碼完成步驟 2 和 3 (PowerShell Core 無效)。 執行時請提高權限。

    # This script must be run from an elevated Windows PowerShell
# window (right-click Windows PowerShell in the Start menu,
# and select Run as Administrator).

# Remove the Windows App SDK 1.0 Preview1/2, and all apps that use it.

$winappsdk = "Microsoft.WindowsAppRuntime.1.0-preview*"
Get-AppxPackage | Where-Object { $_.Dependencies -like $winappsdk } | Remove-AppxPackage
Get-AppxPackage $winappsdk | Remove-AppxPackage

Windows 應用程式 SDK 1.0 Preview 3 的修正

造成 PATH 環境變數損毀的功能將在即將推出的 Windows 應用程式 SDK 1.0 Preview 3 版本移除。 在所有錯誤都已修正並經過完整測試後，日後它仍可能重新推出。

建議您使用 1.0 Preview 3 版。

1.0 版 Preview 2 (1.0.0-preview2)

重要

1.0 版 Preview 1 和 Preview 2 包含重大錯誤。 如果您已安裝其中一個預覽版，請參閱如何解決問題。 建議您改用 1.0 Preview 3 版。

這是預覽通道為 1.0 版發布的最新版本。 它支援所有預覽通道功能。

下列章節說明此版本的新增與更新功能、限制和已知問題。

WinUI 3

更新項目：

  • 控制項已經更新，可反映 WinUI 2.6 的 Windows 樣式。
  • 可支援單一專案 MSIX。
  • WinUI 3 套件現在已可鎖定 17763 及之後的版本。 如需更多資訊，請參閱問題 ＃921。
  • 可支援應用程式內工具列。 不過，若要支援應用程式內工具列和現有的熱重新載入/即時視覺化樹狀結構，需要即將在 10 月推出的 Visual Studio 17.0 Preview 5 版。

已修正錯誤：WebView2Runtime 文字現在已當地語系化。

如需詳情，或要開始以 WinUI 3 進行開發，請參閱：

視窗化

此版本推出 AppWindow 類別的更新。 此版本並沒有新增重大更新，但方法名稱和屬性有變更，且部分傳回值已經移除。 請參閱文件和範本了解詳細更新。 如果您在 1.0 Experimental 或 1.0 Preview 1 版本使用 AppWindow，可能會發現程式碼有變更。

更新項目：

  • AppWindowConfiguration 類別已經移除。 此類別的屬性現在已可在 AppWindow 本身使用，或在 Presenter 類別使用。
  • WinRT API 方法在這個空間的多數 bool 傳回值已經移除，且由於這類方法現在一律會成功，因此已經改為 void。
  • GetWindowIdFromWindow 和 GetWindowFromWindowId 已不再需要呼叫 C# ImportDll。 請改用 Microsoft.UI.Win32Interop 類別提供的 .NET 包裝函式方法。

重要限制：

  • Windows 應用程式 SDK 目前不提供方法讓 UI 架構內容附加到 AppWindow；您無法使用 HWND interop 存取方法。
  • 視窗標題列自訂僅適用於 Windows 11。 請使用 IsCustomizationSupported 方法確認列自訂功能是否有支援。 我們預計會讓此功能向下支援。

如需更多資訊，請參閱管理應用程式視窗。

輸入

更新項目：

  • 已加強支援，使觸控板輸入更精準。

重要限制：

  • 所有 PointerPoint 靜態 factory 函式皆已移除：GetCurrentPoint、GetCurrentPointTransformed、GetIntermediatePoints 和 GetIntermediatePointsTransformed。
  • Windows 應用程式 SDK 不支援擷取含有 指標 ID 的 PointerPoint 物件。 不過，您可以改用 PointerPoint 成員函式 GetTransformedPoint 擷取現有 PointerPoint 物件的轉變版本。 針對中繼點，您可以使用 PointerEventArgs 成員函式 GetIntermediatePoints 和 GetTransformedIntermediatePoints。 請參閱文件了解其他詳情。

MRT 核心

更新項目：

  • 應用程式開發人員現在可以選擇不讓影像檔案或 RESW 檔案加入 .NET 專案的 PRI 檔案。 如需更多資訊，請參閱問題 980。

重要限制：

  • 在 .NET 專案中，如果應用程式已經組建，已複製並貼到專案資料夾的資源檔案就不會在按 F5 後加入索引。 重新組建應用程式即可解決問題。 如需更多資訊，請參閱問題 1503。
  • 在 .NET 專案中，從外部資料夾新增的現有資源檔案如果沒有手動設定組建動作，就不會加入索引。 若要解決此問題，請在 Visual Studio 中設定組建動作： 影像檔案為 Content，RESW 檔案則為 PRIResource。 如需更多資訊，請參閱問題 1504。

部署未封裝應用程式

新功能：

  • Windows 應用程式 SDK 1.0 Preview 2 推出了啟動程序載入程式 API 的 .NET 包裝函式 (請參閱將 Windows 應用程式 SDK 執行階段用於含有外部位置的封裝應用程式或未封裝應用程式)。 啟動程序載入程式 API 是一組原生 C/C++ 功能，未封裝應用程式需要它才能在執行階段與 Windows 應用程式 SDK 架構套件動態相依。 .NET 提供更簡單的方式呼叫 .NET 應用程式的啟動程序載入程式 API，包括 表單和 WPF 應用程式。 啟動程序載入程式 API 的 .NET 包裝函式可在 Microsoft.WindowsAppRuntime.Bootstrap.Net.dll 組件取得，它就位在本機應用程式專案。 如需 .NET 包裝函式的詳細資訊，請參閱 .NET 包裝函式庫。
  • 封裝應用程式現在已可使用部署 API 取得安裝在機器的主要和單一 MSIX 套件。 主要且單一的套件包含在架構套件中，會隨應用程式一同安裝，但由於 Windows 應用程式模型的限制，封裝應用程式需要採取此額外步驟才能安裝這類套件。 如需詳細了解部署 API 的運作方式，請參閱架構相依的封裝應用程式適用的 Windows 應用程式 SDK 部署指南。

重要限制：

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

應用程式週期

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

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

封裝應用程式的所有限制也都會套用在封裝的 WinUI 3 應用程式，且另外也存在下述需考量的事項。

重要考量：

  • 豐富啟用： GetActivatedEventArgs

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

    • 未封裝的應用程式：完全可用。
    • 已封裝的應用程式：無法使用，請改用應用程式的 MSIX 指令清單。
    • 如需詳細資訊，請參閱大量啟用。

  • 單一/多實例

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

  • 電源/狀態通知

    • 未封裝的應用程式：完全可用。
    • 已封裝的應用程式：完全可用。
    • 如需更多資訊，請參閱電源管理。

已知問題：

檔案類型關聯性會錯誤將 %1 編碼為 %251 設定動詞處理常式的命令列範本時，使未封裝的 Win32 應用程式當機。 您的部份解決辦法是手動將登錄值手動邊即為 %1。 如果目標檔案路徑有空格，則此問題仍會失敗，且此情境沒有解決辦法。

其他限制和已知問題

  • 1.0 版 Preview 1 和 Preview 2 包含重大錯誤。 如果您已安裝其中一個預覽版，請參閱如何解決問題。 建議您改用 1.0 Preview 3 版。

  • 此版推出了適用於 C# and C++ 專案的已封裝的空白應用程式 (桌面版 WinUI 3) 範本。 這類範本可讓您在 MSIX 套件中組建應用程式，無需另外使用封裝專案。 這些範本在此版本有以下已知問題：

    • Visual Studio 2019 的 C# 範本。 嘗試組建專案時，會出現錯誤「專案不知道如何執行設定檔專案名稱」。 若要解決此問題，請安裝單一專案 MSIX 封裝工具延伸模組。

    • Visual Studio 2019 和 Visual Studio 2022 的 C# 範本。 當您嘗試在開發電腦上執行或偵錯專案時，會發生下列錯誤：「必須先部署專案，才能進行偵錯。 請在組態管理員啟用『部署』」。若要解決此問題，請在組態管理員為專案啟用部署。 如需詳細操作指示，請參閱建立您的第一個 WinUI 3 專案。

    • Visual Studio 2019 和 Visual Studio 2022 的 C# 範本。 在此版本，這些專案都無法呼叫 UWP 應用程式可以呼叫的 Win32 API 子集。 已封裝的空白應用程式，含 WAP (桌面版 WinUI 3) 範本不受此問題影響。

    • Visual Studio 2022 版 17.0 C++ 範本已達 Preview 4。 第一次嘗試執行專案時，您會遇到下列錯誤：「發生部署錯誤」。 若要解決此問題，請再次執行或部署專案。 此問題將在 Visual Studio 2022 版 17.0 Preview 5 修正。

  • 推播通知 API (Microsoft.Windows.PushNotifications namespace) 錯誤納入在 1.0 Preview 2 版本。 此功能仍然是實驗版，若要使用，您必改為須安裝 1.0 Experimental 版本。 即將推出的 1.0 將會移除版本此。

  • 應用程式生命週期 API (Microsoft.Windows.AppLifecycle namespace) 錯誤將 Experimental 屬性納入 1.0 Preview 2 版本。 下個版本將會從這個 API 移除 Experimental 屬性。

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

  • 使用 1.0 Preview 2 的 C# 專案必須使用下列 .NET SDK：.NET 6 SDK 或之後的版本 (請參閱下載 .NET 和 .NET 5 將於 2022 年 5 月 10 日終止支援）。

  • 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);。

1.0 版 Preview 1 (1.0.0-preview1)

重要

1.0 版 Preview 1 和 Preview 2 包含重大錯誤。 如果您已安裝其中一個預覽版，請參閱如何解決問題。 建議您改用 1.0 Preview 3 版。

這是預覽通道為 1.0 版發布的第一版。 它支援所有預覽通道功能。

下列章節說明此版本的新增與更新功能、限制和已知問題。

WinUI 3

此版本的 WinUI 3 將重點放在建造錯誤都修正的 1.0 版。

  • 新功能：Preview 1 沒有新功能。
  • 已修正的問題：如需此版本已解決的問題清單，請參閱我們的 GitHub 存放庫。

如需詳情，或要開始以 WinUI 3 進行開發，請參閱：

視窗化

此版本將我們在 Experimental 1 推出的視窗化 API 加入 Preview 版。 此版本的重點是修正錯誤、穩定性和 API 簽章的調整，因此沒有重大新功能領域。 值得注意的變更和新增則列於下方。

新功能：

重要限制：

  • 此版本的 AppWindow 目前僅適用於 Win32 應用程式 (封裝和未封裝皆可)。
  • Windows 應用程式 SDK 目前不提供方法讓 UI 架構內容附加到 AppWindow；您無法使用 HWND interop 存取方法。
  • 視窗標題列自訂僅適用於 Windows 11。 請使用 IsCustomizationSupported 方法確認列自訂功能是否有支援。 我們預計會讓此功能向下支援。

如需更多資訊，請參閱管理應用程式視窗。

輸入

此版本將部分新功能加到輸入 API。 值得注意的變更和新增則列於下方。

新增和更新功能：

  • PointerPredictor 讓筆跡應用程式這類延遲敏感應用程式能夠預測輸入點的位置達未來的 15 毫秒，藉此達成更優異的延遲性能和流暢的動畫。
  • PenDeviceInterop 可讓您使用 FromPointerPoint 方法取得 Windows.Devices.Input.PenDevice 的參照。
  • InputCursor 移除了 CoreCursor 中存在的「自訂」類型，並將 CoreCursor 物件分割成不同物件，藉此在預設系統游標類型和自訂游標類型之間做出明確區別。
  • InputCursor API 的更新。
  • GestureRecognizer 已從 Microsoft.UI.Input 實驗版移除。
  • PointerPoint 已從 Microsoft.UI.Input 實驗版移除。
  • WinUI 3 拖放功能已完全支援滑鼠、觸控和觸控筆的輸入。

重要限制：

  • 此版本的輸入 API 存在 Windows 1809 版的已知問題。
  • MRT Core 尚未接受任何 InputCursor 子類型的支援。
  • 平台 SDK API Windows.UI.Core.CoreDragOperation 的直接使用對於 WinUI 3 應用程式無效。
  • PointerPoint 屬性 RawPosition 和 ContactRectRaw 已移除，因為它們參照非預測值，這些值與 OS 的正常值相同。 請改用 Position 和 ContactRect。 指標預測功能現在是由 Microsoft.UI.Input.PointerPredictor API 物件來處理。

MRT 核心

自 1.0 Preview 1 版本起，MRT Core API 已從 Microsoft.ApplicationModel.Resources 命名空間移至 Microsoft.Windows.ApplicationModel.Resources 命名空間。

其他限制和已知問題

  • 1.0 版 Preview 1 和 Preview 2 包含重大錯誤。 如果您已安裝其中一個預覽版，請參閱如何解決問題。 建議您改用 1.0 Preview 3 版。

  • 使用 C++ 已封裝的空白應用程式，含 WAP (桌面版 WinUI 3) 專案範本建立的專案依預設會遇到下列組建錯誤：fatal error C1083: Cannot open include file: 'winrt/microsoft.ui.dispatching.co_await.h': No such file or directory。 若要解決此問題，請從 pch.h 檔案移除以下程式碼行。 下個版本將會修正此問題。

    #include <winrt/microsoft.ui.dispatching.co_await.h>

  • 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);。

  • 不支援任何 CPU 建置配置：Windows 應用程式 SDK 是用本機程式碼編寫的，因此不支援任何 CPU 建置配置。 Visual Studio 中的 WinUI 3 範本僅允許特定於體系結構的建置。 將 Windows 應用程式 SDK 新增至支援任何 CPU 的現有 .NET 應用程式或元件時，必須指定所需的架構：x86、x64 或 arm64。

  • .NET 應用程式必須面向內部版本 18362 或更高版本：您的 TFM 必須設定為 net6.0-windows10.0.18362 或更高版本，並且您的封包專案 <TargetPlatformVersion> 必須設定為 18362 或更高版本。 如需更多資訊，請參閱 GitHub 上的已知問題。

  • 使用 1.0 Preview 1 的 C# 專案必須使用下列 .NET SDK：.NET 6 SDK 或之後的版本 (請參閱下載 .NET 和 .NET 5 將於 2022 年 5 月 10 日終止支援）。

  • Windows 10 版本 1809 不支援未封裝的應用程式：這會在下一個版本中解決。