Windows 应用 SDK 的试验通道发行说明

重要

不支持在生产环境中使用试验通道,并且无法将使用试验版本的应用发布到 Microsoft Store

试验通道提供 Windows 应用 SDK 的版本,其中包括开发早期阶段的试验通道功能。 用于试验功能的 API 具有试验特性。 如果在代码中调用试验 API,会收到生成时警告。 试验通道中的所有 API 在将来的版本中可能会有重大更改,但试验 API 特别容易更改。 试验功能可能会从下一版本中删除,也可能永远不会发布。

重要链接

试验通道发行说明

试验版本 1.5 (1.5.0-experimental2)

这是试验通道的最新版本。 若要下载,请将 WinAppSDK NuGet 版本重新定目标到 1.5.240124002-experimental2

缺陷修复

此版本中包含以下 bug 修复:

  • 修复了当使用自定义 NavigationViewItem 时导致应用程序启动时崩溃的问题。 有关详细信息,请参阅 GitHub 问题 #8814
  • 修复了省略号按钮会不正确地生成错误的 NavigationView 问题。 有关详细信息,请参阅 GitHub 问题 #8380
  • 修复了在多窗口应用中 SystemBackdrop 无法正确渲染的问题。 有关详细信息,请参阅 GitHub 问题 #8423
  • 修复了当插入到 ObservableCollection 开头时的重复问题。 有关详细信息,请参阅 GitHub 问题 #8370

新 API

1.5-experimental1 包括以下新 API。 这些 API 不是实验性的,但尚未包含在 WinAppSDK 的稳定版本中。

Microsoft.Graphics.DirectX
 
    DirectXPixelFormat
        A4B4G4R4
Microsoft.UI.Xaml
 
    DebugSettings
        LayoutCycleDebugBreakLevel
        LayoutCycleTracingLevel
 
    LayoutCycleDebugBreakLevel
    LayoutCycleTracingLevel
Microsoft.UI.Xaml.Automation.Peers
 
    SelectorBarItemAutomationPeer
Microsoft.UI.Xaml.Controls
 
    MapControl
    MapControlMapServiceErrorOccurredEventArgs
    MapElement
    MapElementClickEventArgs
    MapElementsLayer
    MapIcon
    MapLayer
    SelectorBar
    SelectorBarItem
    SelectorBarSelectionChangedEventArgs
    WebView2
        EnsureCoreWebView2Async
        EnsureCoreWebView2Async
Microsoft.Windows.Management.Deployment
 
    EnsureReadyOptions
    PackageDeploymentManager
        AddPackageSetAsync
        DeprovisionPackageAsync
        DeprovisionPackageByUriAsync
        DeprovisionPackageSetAsync
        EnsurePackageReadyAsync
        EnsurePackageReadyByUriAsync
        EnsurePackageSetReadyAsync
        IsPackageReady
        IsPackageReadyByUri
        IsPackageRegistrationPending
        IsPackageRegistrationPendingForUser
        ProvisionPackageAsync
        ProvisionPackageByUriAsync
        ProvisionPackageSetAsync
        RegisterPackageAsync
        RegisterPackageByUriAsync
        RegisterPackageSetAsync
        RemovePackageByUriAsync
        RepairPackageAsync
        RepairPackageByUriAsync
        RepairPackageSetAsync
        ResetPackageAsync
        ResetPackageByUriAsync
        ResetPackageSetAsync
        StagePackageAsync
        StagePackageByUriAsync
        StagePackageSetAsync
 
    PackageDeploymentProgress
    PackageDeploymentResult
        Error
        ErrorText
 
    PackageSet
        Items
        PackageUri
 
    PackageVolume
        FindPackageVolumeByName
        FindPackageVolumeByPath
        FindPackageVolumes
        IsRepairNeeded
        Repair
 
    ProvisionPackageOptions
    RegisterPackageOptions
        DependencyPackageFamilyNames
 
    RemovePackageOptions
        FailIfNotFound

其他实验 API

此版本包括以下新的和经过修改的实验 API:

Microsoft.UI.Xaml
 
    Application
        DispatcherShutdownMode
 
    DispatcherShutdownMode
    XamlIsland
        SystemBackdrop
Microsoft.UI.Xaml.Hosting
 
    WindowsXamlManager
        IsXamlRunningOnCurrentThread
        XamlShutdownCompletedOnThread
 
    XamlShutdownCompletedOnThreadEventArgs
Microsoft.Windows.System.Workloads
 
    IWorkloadHandler
    Workload
    WorkloadManager
    WorkloadProgress
    WorkloadProgressStatus
    WorkloadResult
    WorkloadsContract
    WorkloadStatus

试验版本 1.5 (1.5.0-experimental1)

这是试验通道的最新版本。 若要下载,请将 WinAppSDK NuGet 版本重新定目标到 1.5.231202003-experimental1

新 API

1.5-experimental1 包括以下新 API。 这些 API 不是实验性的,但尚未包含在 WinAppSDK 的稳定版本中。

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

其他实验 API

此版本包括以下新的和经过修改的实验 API:

Microsoft.UI.Content
 
    ContentIsland
        ConnectionInfo
        ConnectRemoteEndpoint
        IsRemoteEndpointConnected
 
    ContentIslandEnvironment
        CurrentOrientation
        DisplayScale
        NativeOrientation
        ThemeChanged
 
    ContentSiteEnvironment
        CurrentOrientation
        DisplayScale
        NativeOrientation
        NotifyThemeChanged
 
    DesktopChildSiteBridge
        AcceptRemoteEndpoint
        ConnectionInfo
        IsRemoteEndpointConnected
        RemoteEndpointConnecting
        RemoteEndpointDisconnected
        RemoteEndpointRequestedStateChanged
 
    EndpointConnectionEventArgs
    EndpointRequestedStateChangedEventArgs
    IContentIslandEndpointConnectionPrivate
    IContentSiteBridgeEndpointConnectionPrivate
    ProcessStarter
    SystemVisualSiteBridge
        IsClosed
Microsoft.UI.Input
 
    FocusNavigationReason
    FocusNavigationRequest
    FocusNavigationRequestEventArgs
    FocusNavigationResult
    InputFocusController
        DepartFocus
        NavigateFocusRequested
 
    InputFocusNavigationHost
Microsoft.UI.Xaml
 
    DebugSettings
        LayoutCycleDebugBreaks
        LayoutCycleTracing
 
    LayoutCycleDebugBreakLevel
    LayoutCycleTracingLevel
    XamlIsland
Microsoft.UI.Xaml.Controls
 
    SelectionModel
        SelectAllFlat
Microsoft.UI.Xaml.Core.Direct
 
    XamlPropertyIndex
        FlyoutBase_SystemBackdrop
        Popup_SystemBackdrop
Microsoft.Windows.Management.Deployment
 
    AddPackageOptions
    AddPackageSetOptions
    DeploymentPriority
    DeploymentProcessingModel
    EnsureIsReadyOptions
    FindPackageSetOptions
    PackageDeploymentContract
    PackageDeploymentManager
    PackageDeploymentProgress
    PackageDeploymentProgressStatus
    PackageDeploymentResult
    PackageDeploymentStatus
    PackageRuntimeManager
    PackageSet
    PackageSetItem
    PackageSetItemRuntimeDisposition
    PackageSetManager
    PackageSetRuntimeDisposition
    PackageVolume
    PackageVolumeManager
    PackageVolumeStatus
    RegisterPackageOptions
    RemovePackageOptions
    StagePackageOptions
    StubPackageOption

试验版本 1.4 (1.4.0-experimental1)

这是试验通道的最新版本。 若要下载,请将 WinAppSDK NuGet 版本重新定目标到 1.4.230518007-experimental1

缺陷修复

此版本包含其他修补程序,包括:

  • 修复了在新的 WinUI 桌面应用程序中启用调试设置帧速率计数器导致访问冲突的问题。 有关详细信息,请参阅 GitHub 上的问题 2835
  • 修复了在触摸板上水平滚动在 WebView2 网页中不起作用的问题。 有关详细信息,请参阅 GitHub 上的问题 7772

其他实验 API

此版本包括以下新的和经过修改的实验 API:

Microsoft.UI

   IClosableNotifier
Microsoft.UI.Composition.SystemBackdrops

   DesktopAcrylicController
       Closed
       FrameworkClosed
       Kind

   DesktopAcrylicKind
   MicaController
       Closed
       FrameworkClosed
Microsoft.UI.Content

   ContentAppWindowBridge
       SettingChanged

   ContentEnvironmentSettingChangedEventArgs
   ContentExternalBackdropLink
   ContentExternalOutputLink
       ExternalOutputBorderMode

   ContentIsland
       FrameworkClosed

   ContentIslandWindow
       SettingChanged

   ContentSite
       FrameworkClosed

   ContentSiteWindow
       NotifySettingChanged
       SettingChanged

   CoreWindowTopLevelWindowBridge
       SettingChanged

   DesktopSiteBridge
       Closed
       FrameworkClosed

   IContentWindow
       SettingChanged

   SystemVisualSiteBridge
       Closed
       FrameworkClosed
Microsoft.UI.Input

   InputLayoutPolicy
   InputNonClientPointerSource
       ConfigurationChanged
       GetForWindowId

   NonClientRegionConfigurationChangedEventArgs
Microsoft.UI.System

   ThemeSettings
Microsoft.UI.Windowing

   DisplayArea
       GetMetricsFromWindowId
Microsoft.UI.Xaml

   XamlRoot
       ContentWindow
Microsoft.UI.Xaml.Controls

   ItemContainer
       Child
       ChildProperty

   ItemContainerMultiSelectMode
       Extended

   ItemsView
       Animator
       AnimatorProperty

   MenuFlyoutPresenter
       SystemBackdrop
       SystemBackdropProperty

   RiverFlowLayout
       InvalidateItemsInfo
       RequestedRangeCount
       RequestedRangeStartIndex

   RiverFlowLayoutElementAnimator
Microsoft.UI.Xaml.Controls.Primitives

   CommandBarFlyoutCommandBar
       SystemBackdrop
       SystemBackdropProperty
Microsoft.UI.Xaml.Input

   AccessKeyManager
       EnterDisplayMode

试验版本 1.3 (1.3.0-experimental1)

这是试验通道的最新版本。 若要下载,请将 WinAppSDK NuGet 版本重新定目标到 1.3.230202101-experimental1

XAML 背景 API

借助 XAML 窗口中的内置属性,现在可以更轻松地在 WinUI 3 应用中使用 Mica & Background Acrylic 背景。 请参阅 GitHub 上的 Xaml Backdrop API 规范,详细了解 Window.SystemBackdrop 属性。

在此版本中需要注意的是,你只能在代码隐藏中设置背景,如下所示。 在标记中设置 <Window.SystemBackdrop> 会导致编译错误。 此外,Xaml Backdrop API 当前缺少一个“实验”标记,因为开发团队正在积极开发中。

public MainWindow()
{
    this.InitializeComponent();

    this.SystemBackdrop = new MicaBackdrop();
}

Window.AppWindow

现在,只需替换几行样板代码,就可以直接通过 Window.AppWindow 从“窗口”使用 AppWindow API。 请参阅 GibHub 上的 Window.AppWindow API 规范,了解其他背景和使用信息。

WinAppSDK 中的新功能

  • ApplicationModel.DynamicDependency:取代已弃用的 MddGetGenerationId 的 PackageDependency.PackageGraphRevisionId
  • 环境管理器:EnvironmentManager.AreChangesTracked 告知你是否可在应用程序中跟踪对环境管理器的更改。 请参阅 GitHub 上的环境管理员 API 规范了解详细信息。
  • MRT 核心:新事件 Application.ResourceManagerInitializing 允许应用提供 IResourceManager 接口其自己的实施,并为应用提供对 Win UI 用于解析安全 URI 的 ResourceManager 访问权限。
  • 现在,使用最新的试验性 VSIX,可以通过 Visual Studio 菜单在未打包和打包之间转换应用,而无需在项目文件中执行此操作。
  • 当无法解析引用的 Static/ThemeResource 查找时,现在会引发新事件 DebugSettings.XamlResourceReferenceFailed。 使用此事件可以访问某个跟踪,该跟踪详细说明了在框架中的哪个位置搜索该键,以便更好地调试 Static 和 ThemeResource 查找失败。 有关详细信息,请参阅 GitHub 上的问题 497223506073

缺陷修复

  • 修复了触摸输入导致软键盘不在文本框上出现的问题。 有关详细信息,请参阅 GitHub 上的问题 6291
  • 修复了导致将 IElementFactory 作为 ItemTemplate 引发 ArgumentException 的 ItemsRepeater 的问题。 有关详细信息,请参阅 GitHub 上的问题 4705

其他实验 API

此版本还包括早期开发的多个 API。

以下列表详细介绍了此实验版本中引入的 API,我们不打算在 1.3.0 稳定版本中交付。

**Microsoft.UI.Content**

    DesktopSiteBridge
        GetInputEnabledToRoot
        GetVisibleToRoot
        InputEnabled
**Microsoft.UI.Dispatching**

    DispatcherQueue
        FrameworkShutdownStarting
**Microsoft.UI.Input**

    InputLightDismissAction
        GetForIsland

    InputNonClientPointerSource
    InputPointerActivationBehavior
    InputPointerSource
        ActivationBehavior

    NonClientRegionCaptionTappedEventArgs
    NonClientRegionHoverEventArgs
    NonClientRegionKind
**Microsoft.UI.Input.DragDrop**

    DragDropManager
    DragDropModifiers
    DragInfo
    DragOperation
    DragUIContentMode
    DragUIOverride
    DropOperationTargetRequestedEventArgs
    IDropOperationTarget
**Microsoft.UI.Xaml.Automation.Peers**

    ItemContainerAutomationPeer
    ItemsViewAutomationPeer
**Microsoft.UI.Xaml.Controls**

    AnnotatedScrollBar
    AnnotatedScrollBarLabel
    AnnotatedScrollBarScrollEventArgs
    AnnotatedScrollBarScrollEventType
    AnnotatedScrollBarScrollOffsetRequestedEventArgs
    AnnotatedScrollBarSubLabelRequestedEventArgs
    AnnotatedScrollBarValueRequestedEventArgs
    ElementFactory
        GetElement
        GetElementCore
        RecycleElement
        RecycleElementCore

    IndexBasedLayoutOrientation
    ItemContainer
    ItemContainerInteractionTrigger
    ItemContainerInvokedEventArgs
    ItemContainerMultiSelectMode
    ItemContainerUserInvokeMode
    ItemContainerUserSelectMode
    ItemsView
    ItemsViewItemInvokedEventArgs
    ItemsViewItemInvokeMode
    ItemsViewSelectionMode
    Layout
        IndexBasedLayoutOrientation

    NonVirtualizingLayout
        IndexBasedLayoutOrientationCore

    RiverFlowLayout
    RiverFlowLayoutItemsInfoRequestedEventArgs
    RiverFlowLayoutItemsJustification
    RiverFlowLayoutItemsStretch
    VirtualizingLayout
        IndexBasedLayoutOrientationCore

    VirtualizingLayoutContext
        VisibleRect
        VisibleRectCore
**Microsoft.Graphics.Display**

    DisplayInformation
        AngularOffsetFromNativeOrientation
        DpiChanged
        OrientationChanged
        RawDpi
        RawPixelsPerViewPixel

    DisplayOrientation
**Microsoft.UI.Xaml.Hosting**

    DesktopWindowXamlSource
        CreateSiteBridge
        SiteBridge
        SystemBackdrop

试验版本 1.2 (1.2.0-experimental2)

这是试验通道的最新版本。 它支持所有试验频道功能以及 1.2.0-preview 1 中的所有功能。

若要下载,请将 WinAppSDK NuGet 版本重新定目标到 1.2.220909.2-experimental2

修复的问题

在即将推出的 Windows Insider Preview 版本中,使用 Windows 应用 SDK的应用程序将无法启动。

试验版本 1.2 (1.2.0-experimental1)

这是试验通道的最新版本。 它支持所有试验通道功能

若要下载,请将 WinAppSDK NuGet 版本重新定目标到 1.2.220727.1-experimental1

输入和组合

首先在 Windows 应用 SDK 0.8 中引入,Microsoft.UI.Input.ExperimentalMicrosoft.UI.Composition.Experimental 命名空间中有几个实验类。

此版本中的新增功能:

内容

在此版本中,Microsoft.UI.Content 命名空间中的实验类提供交互式内容的构建基块。 这些是低级别基元,可以组合到内容中,为最终用户提供交互式体验。 内容定义了以下结构:使用动画呈现输出、处理不同目标的输入、提供辅助功能表示形式以及处理主机状态更改。

值得注意的 API:

  • ContentIsland - 将输出、输入和辅助功能组合在一起,并为交互式内容提供抽象。 可以使用这些 API 构造和生成自定义可视化树。
  • DesktopChildSiteBridge - 允许 ContentIsland 连接到基于 HWND 的层次结构。

有关详细信息,请参阅 GitHub 上的示例

调度

DispatcherQueue 现在以重新进入的形式调度。 以前,单个 DispatcherQueueHandler 回调可能一次在单个线程上处于活动状态。 现在,如果处理程序启动嵌套消息泵,则其他回调将调度为重新进入。 这与窗口消息和嵌套消息泵的 Win32 行为匹配。

通知

现在支持注册应用通知的应用显示名称和图标。 请查看 GitHub 上的规范以了解其他信息。

WinUI 3

  • WinUI 2.8 版的控件和样式是最新的。
  • 实验版本中不再支持 UWP。

其他限制和已知问题

  • 更新到 Windows 应用 SDK 1.2-experimental1 后,需要重新生成应用,因为 ABI 中引入了中断性变更。
  • 引用依赖于 WebView2 的包(例如 Microsoft.Identity.Client)的应用无法生成。 此问题是因生成时二进制文件冲突而造成的。 有关详细信息,请参阅 GitHub 上的问题 2492
  • dotnet build 用于 WinAppSDK C# 类库项目可能会出现生成错误“无法加载 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 (1.0.0-experimental1)

此版本支持所有试验通道功能

以下部分介绍此版本的新功能、更新功能、限制和已知问题。

WinUI 3

此版本的 WinUI 3 侧重于为 1.0 稳定版构建新功能以及修复 bug。

  • 新功能:支持每个窗口显示 ContentDialog,而不是按线程显示
  • Bug:有关此版本中解决的 bug 的完整列表,请参阅我们的 GitHub 存储库
  • 示例:若要查看 WinUI 3 控件和功能的运行情况,可从 GitHub 克隆并生成 WinUI 3 控件库应用,或从 Microsoft Store 下载应用。

有关详细信息,或开始使用 WinUI 进行开发,请参阅:

推送通知(试验功能)

此版本引入了推送通知 API,可供打包的桌面应用与基于 Azure 应用注册的标识一起使用。 若要使用此功能,必须注册获取专用预览版

重要限制:

  • 只有在 Windows 10 版本 2004(内部版本 19041)或更高版本上运行的 MSIX 打包的应用才支持推送通知。
  • Microsoft 保留在使用个人预览版期间从推送通知禁用或撤销应用的权利。
  • Microsoft 不保证推送通知的可靠性或延迟。
  • 在使用个人预览版期间,推送通知数量限制为每月 100 万条。

有关详细信息,请参阅推送通知

窗口化

此版本包括对窗口化 API 的更新。 这些是一组基础的窗口化 API,它们以 AppWindow 类为中心,能够实现易于使用的窗口化方案,这些方案与 Windows 用户体验和其他应用能够很好地集成在一起。 这类似于 UWP AppWindow,但两者并不相同。

重要限制:

  • 此版本的 AppWindow 目前仅适用于(打包和未打包的)Win32 应用。
  • Windows 应用 SDK 当前不提供将 UI 框架内容附加到 AppWindow 的方法,只能使用 HWND 互操作访问方法。
  • 在适用于 AMD64 的 Windows 版本 1809 和 1903 中,窗口化 API 目前无法正常使用。

有关详细信息,请参阅管理应用窗口

适用于未打包应用的部署

此版本引入了对动态依赖项功能(包括引导程序 API)的更新

重要限制:

  • 仅对未打包的应用支持动态依赖项功能。
  • 不支持提升权限的调用方。

有关详细信息,请参阅以下文章:

其他限制和已知问题

  • 不支持任何 CPU 生成配置:Windows 应用 SDK 是用本机代码编写的,因此不支持任何 CPU 生成配置Visual Studio 中的 WinUI 3 模板只允许特定于体系结构的生成。 添加 Windows 应用 SDK 到支持任何 CPU 的现有 .NET 应用程序或组件时,必须指定所需的体系结构:x86x64arm64
  • .NET 应用必须面向内部版本 18362 或更高版本:TFM 必须设置为 net6.0-windows10.0.18362 或更高版本,并且打包项目的 <TargetPlatformVersion> 必须设置为 18362 或更高版本。 有关详细信息,请参阅 GitHub 上的已知问题
  • 使用试验版本 1.0 的 C# 应用必须使用以下 .NET SDK 之一

预览版本 0.8 (0.8.0-preview)

此版本支持所有试验通道功能

以下部分介绍此版本的新功能、更新功能、限制和已知问题。

WinUI 3

此版本引入了重要的 bug 修复(包括在0.5 服务版本中修复的问题)以及 WinUI 的其他更改。 若要获取完整列表,请参阅 WinUI 3 - Windows 应用 SDK 0.8 发行说明

应用生命周期(试验功能)

此版本引入了与管理应用应用生命周期相关的新试验功能。

  • 所有应用(打包和未打包的)均可使用 GetActivatedEventArgs(尽管打包的应用已可使用平台中的此实现)
  • 仅打包的应用可以使用 RegisterForXXXActivation 函数
  • 打包的桌面应用可以使用应用生命周期实例化。

有关详细信息,请参阅应用实例化富激活

未打包应用的部署(试验功能)

此版本为未打包的应用引入了新的实验性部署功能。 未打包的应用现在可以动态依赖于 Windows 应用 SDK 运行时包,因此,你可以继续使用现有的 MSI 或安装程序进行应用部署。 这是通过以下功能实现的:

  • Windows 应用 SDK 的独立安装程序。
  • 包含动态依赖项功能的 MSIX 包捆绑。

有关详细信息,请参阅依赖于框架的使用外部位置打包的应用或未打包应用的 Windows 应用 SDK 部署指南

DWriteCore

此版本添加了以下功能:

  • 文本修饰(文本布局 API 中的下划线和删除线)
  • 垂直文本布局
  • 字体字距调整 API
  • 未打包应用的试验支持

有关详细信息,请参阅使用 DWriteCore 渲染文本

MRT 核心

此版本添加了以下功能:

  • 现可自动设置资源的生成操作,从而减少了手动项目配置需求。
  • 未打包应用的试验支持。

有关详细信息,请参阅使用 MRT Core 管理资源

限制和已知问题

  • 不支持任何 CPU 生成配置:Windows 应用 SDK 是用本机代码编写的,因此不支持任何 CPU 生成配置Visual Studio 中的 WinUI 3 模板只允许特定于体系结构的生成。 添加 Windows 应用 SDK 到支持任何 CPU 的现有 .NET 应用程序或组件时,必须指定所需的体系结构:x86x64arm64
  • .NET 应用必须面向内部版本 18362 或更高版本:TFM 必须设置为 net6.0-windows10.0.18362 或更高版本,并且打包项目的 <TargetPlatformVersion> 必须设置为 18362 或更高版本。 有关详细信息,请参阅 GitHub 上的已知问题

示例

Windows 应用 SDK 示例不适用于此版本。 即将推出新的和更新的示例,包括演示新功能(例如未打包的应用部署)的示例。