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

项目
03/03/2023

重要

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

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

重要链接：

如果要将现有应用从较旧版本的 Windows 应用 SDK 升级到较新版本，请参阅将现有项目更新到 Windows 应用 SDK 的最新版本。
有关实验版的文档，请参阅安装Windows 应用 SDK预览版和实验通道的工具。

试验通道发行说明：

版本 1.3 实验
版本 1.2 实验版
试验版本 1.0
预览版本 0.8

版本 1.3 实验 (1.3.0-experimental1)

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

XAML 背景 API

借助内置于 XAML 窗口的属性，Mica & 背景亚克力背景现在更易于在 WinUI 3 应用中使用。有关 Window.SystemBackdrop 属性的详细信息，请参阅 GitHub 上的 Xaml 背景 API 规范。

请注意，在此版本中，只能在代码隐藏中设置背景，如下所示。在标记中设置 <Window.SystemBackdrop> 会导致编译错误。此外，Xaml 背景 API 当前缺少“实验性”标记，因为它们正在积极开发中。

public MainWindow()
{
    this.InitializeComponent();

    this.SystemBackdrop = new MicaBackdrop();
}

Window.AppWindow

替换多行样本代码后，现在可以通过直接从 WindowWindow.AppWindow使用 AppWindow API。有关其他背景和使用情况信息，请参阅 GitHub 上的 Window.AppWindow API 规范。

WinAppSDK 中的新功能

ApplicationModel.DynamicDependency： PackageDependency.PackageGraphRevisionId 替换已弃用的 MddGetGenerationId。
环境管理器： EnvironmentManager.AreChangesTracked 告知你是否能够在应用程序中跟踪环境管理器的更改。有关详细信息，请参阅 GitHub 上的环境管理器 API 规范。
MRT 核心：一个新事件， Application.ResourceManagerInitializing 允许应用提供其自己的接口实现 IResourceManager ，并允许你访问 WinUI 用于解析资源 URI 的 ResourceManager。
借助最新的实验性 VSIX，现在可以通过 Visual Studio 菜单（而不是在项目文件中）在未打包和打包之间转换应用。
当无法解析引用的 Static/ThemeResource 查找时， DebugSettings.XamlResourceReferenceFailed 将引发一个新事件。此事件提供对跟踪的访问权限，该跟踪详细说明框架搜索该键的位置，以便更好地调试静态 & ThemeResource 查找失败。有关详细信息，请参阅 GitHub 上的问题 4972、 2350 和 6073 。

Bug 修复

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

其他实验性 API

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

下面的列表详细介绍了此实验性版本中引入的 API，我们不打算在 1.3.0 稳定版本中提供这些 API。

**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 中的所有实验频道功能和功能。

To download, retarget your WinAppSDK NuGet version to 1.2.220909.2-experimental2.

修复的问题

在即将到来的Windows Insider Preview版本中，使用 Windows 应用 SDK 的应用程序将无法启动。

版本 1.2 实验 (1.2.0-experimental1)

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

To download, retarget your WinAppSDK NuGet version to 1.2.220727.1-experimental1.

输入 & 组合

Windows 应用 SDK 0.8 中首次引入，Microsoft.UI.Input.Experimental Microsoft.UI.Composition.Experimental命名空间中有几个实验类。&

此版本的新增功能：

InputPointerSource 具有新的静态工厂 GetforWindowId。

Content

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

值得注意的 API：

ContentIsland - 将输出、输入和辅助功能汇集在一起，并提供交互式内容的抽象。可以构造自定义可视化树，并使用这些 API 进行交互。
DesktopChildSiteBridge - 使 ContentIsland 连接到基于 HWND 的层次结构。

有关详细信息，请查看 GitHub 上的示例。

调度

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

通知

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

WinUI 3

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

其他限制和已知问题

由于 ABI 中引入了中断性变更，更新到 Windows 应用 SDK 1.2-experimental1 后，需要重新生成应用。
引用依赖于 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，该 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 应用程序或组件时，必须指定所需的体系结构：x86、x64 或 arm64。
.NET 应用必须面向内部版本 18362 或更高版本：TFM 必须设置为 net6.0-windows10.0.18362 或更高版本，并且打包项目的 <TargetPlatformVersion> 必须设置为 18362 或更高版本。有关详细信息，请参阅 GitHub 上的已知问题。
使用试验版本 1.0 的 C# 应用必须使用以下 .NET SDK 之一：
- .NET 6 SDK 或更高版本 (请参阅下载 .NET 和 .NET 5 将于 2022 年 5 月 10 日终止支持) 。

预览版本 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 生成配置。 The WinUI 3 templates in Visual Studio only allow architecture-specific builds. 添加 Windows 应用 SDK 到支持任何 CPU 的现有 .NET 应用程序或组件时，必须指定所需的体系结构：x86、x64 或 arm64。
.NET apps must target build 18362 or later: Your TFM must be set to net6.0-windows10.0.18362 or later, and your packaging project's <TargetPlatformVersion> must be set to 18362 or later. 有关详细信息，请参阅 GitHub 上的已知问题。

示例

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

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

版本 1.3 实验 (1.3.0-experimental1)

XAML 背景 API

Window.AppWindow

WinAppSDK 中的新功能

Bug 修复

其他实验性 API

版本 1.2 实验 (1.2.0-experimental2)

修复的问题

版本 1.2 实验 (1.2.0-experimental1)

输入 & 组合

Content

调度

通知

WinUI 3

其他限制和已知问题

试验版本 1.0 (1.0.0-experimental1)

WinUI 3

推送通知（试验功能）

窗口化

适用于未打包应用的部署

其他限制和已知问题

预览版本 0.8 (0.8.0-preview)

WinUI 3

应用生命周期（试验功能）

未打包应用的部署（试验功能）

DWriteCore

MRT 核心

限制和已知问题

示例

其他资源

其他资源

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

版本 1.3 实验 (1.3.0-experimental1)

XAML 背景 API

Window.AppWindow

WinAppSDK 中的新功能

Bug 修复

其他实验性 API

版本 1.2 实验 (1.2.0-experimental2)

修复的问题

版本 1.2 实验 (1.2.0-experimental1)

输入 & 组合

Content

调度

通知

WinUI 3

其他限制和已知问题

试验版本 1.0 (1.0.0-experimental1)

WinUI 3

推送通知（试验功能）

窗口化

适用于未打包应用的部署

其他限制和已知问题

预览版本 0.8 (0.8.0-preview)

WinUI 3

应用生命周期（试验功能）

未打包应用的部署（试验功能）

DWriteCore

MRT 核心

限制和已知问题

示例

相关主题

其他资源

其他资源