Windows 应用 SDK 1.2 的稳定通道发行说明

项目
07/05/2024

稳定通道提供支持在生产环境中供应用使用的 Windows App SDK 版本。使用 Windows App SDK 稳定版本的应用还可以发布到 Microsoft Store。

重要链接：

如果要将现有应用从较旧版本的 Windows App SDK 升级到较新版本，请参阅将现有项目更新到 Windows App SDK 的最新版本。

最新稳定通道版本：

Windows App SDK 的最新稳定通道发行说明

下载 Windows App SDK

注意

Windows App SDK Visual Studio 扩展 (VSIX) 已不再作为单独的下载进行分发。它们可在 Visual Studio 内的 Visual Studio Marketplace 中使用。

版本 1.2.5 (1.2.230313.1)

这是 Windows 应用 SDK 的服务版本，其中包含针对版本 1.2 的关键 bug 修复。

修复了在组合功能关闭期间导致应用崩溃的问题。
修复了即使在屏幕关闭的情况下，也会导致应用继续运行动画的问题。
修复了当鼠标和键盘输入同时发生时，导致 WebView2 中鼠标和触摸输入失败的问题。有关详细信息，请参阅 GitHub 问题 #3266。

版本 1.2.4 (1.2.230217.4)

这是 Windows 应用 SDK 的服务版本，其中包含针对版本 1.2 的关键 bug 修复。

修复了导致独立应用无法配置 UAC 设置的问题。有关详细信息，请参阅 GitHub 问题 #3376。
修复了导致推送通知通过 PushNotificationChannel::ExpirationTime 返回不准确过期时间的问题。有关详细信息，请参阅 GitHub 问题 #3300。
修复了将双精度数作为参数传递给 x:Bind 函数时导致将负数视为“无效”的问题。
用于更新 WinUI VSIX 的多个修复。这些更新包括简化 app.manifest 中的项目模板 dipAwareness、删除 UWP 模板、更新本地化资源文件、添加电话 ID 以取消阻止 Store 提交，以及删除版权声明和许可证。有关详细信息，请参阅 GitHub 问题 #5659、#3205、#3323、#3322、#3143。

版本 1.2.3 (1.2.230118.102)

这是 Windows 应用 SDK 的服务版本，其中包含针对版本 1.2 的关键 bug 修复。

修复了关闭多个窗口时导致 WinUI 3 应用崩溃的问题。
修复了在调用 ThreadPoolTimer 接口的两个或更多个引用时，导致应用在关闭时崩溃的问题。有关详细信息，请参阅 GitHub 问题 #7260 和 #7239。
修复了导致所有单项目 MSIX 应用以完全信任方式运行的问题。有关详细信息，请参阅 GitHub 问题 #7766。

版本 1.2.2 (1.2.221209.1)

这是 Windows 应用 SDK 的服务版本，其中包含针对版本 1.2 的关键 bug 修复。

修复了在已安装 Store 和旁加载包中的一个时，无法安装另一个（例从安装程序、NuGet 和引导程序安装）的问题。有关详细信息，请参阅 GitHub 问题 #3168。
修复了在使用触摸板滚动时导致缺少弹性效果和动画曲线的问题。有关详细信息，请参阅 GitHub 问题 #7874。
修复了 ListView 中导致内存泄漏的问题。
修复了在鼠标悬停后导致 Button 模板不遵循 Foreground 属性的问题。有关详细信息，请参阅 GitHub 问题 #7208。
修复了当 MediaElement 中没有 MediaPlaybackItem 时导致意外异常的问题。
修复了在内容转换时导致 MediaPlayerElement 中出现白框的问题。
修复了导致 App.UnhandledException 无法从其他线程捕获异常的其他问题。有关详细信息，请参阅 GitHub 问题 #1259 和 #5221。

版本 1.2.1 (1.2.221116.1)

这是 Windows 应用 SDK 的服务版本，其中包含针对版本 1.2 的关键 bug 修复。

修复了在添加 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，并将“目标 OS 版本”更改为相应的值（例如 net6.0-windows10.0.19041.0）。

Windows 中的第三方小组件

小组件面板最初是在 Windows 11 中引入的，仅限于显示内置小组件。小组件是在小组件面板上显示文本和图形的小型 UI 容器，与设备上安装的应用相关联。使用 Windows 应用 SDK，第三方开发人员现在可为打包的 Win32 应用创建小组件，并在 Windows 11 小组件面板上本地测试这些小组件。

有关小组件的详细信息，请查看小组件概述。

若要开始为应用开发小组件，请查看小组件服务提供商开发文档和小组件设计基础，以了解先决条件、指导和最佳做法。

此版本的先决条件包括：

在开发计算机上启用开发人员模式。
开发计算机正在运行 Windows Insider Preview (WIP) 开发频道中大于或等于 25217 的 Windows 版本，小组件面板为 521.20060.1205.0 或更高版本。

开发小组件时的已知限制：

只能在已在 WIP 中注册此预览版的设备上本地测试第三方小组件。
只能为打包的 Win32 应用创建小组件。渐进式 Web 应用 (PWA) 的小组件已计划作为 Microsoft Edge 108 的一部分提供支持。

DisplayInformation

Windows 桌面应用现在可以通过 WinAppSDK 中的 DisplayInformation 类支持高动态范围 (HDR) 和自动颜色管理 (ACM)。使用 DisplayInformation 类可以监视应用程序视图的显示相关信息。这包括一些事件，客户端可以通过这些事件监视应用程序视图中影响该视图所在的显示画面的更改，以及监视显示画面中可能影响应用程序视图的更改。

WinUI 3

WinUI 3 应用可以使用 MediaPlayerElement 和 MediaTransportControls 媒体播放控件来播放音频和视频。有关如何以及何时使用媒体控件的详细信息，请参阅媒体播放器。

已使用 WinUI 2.8 中的最新控件、样式和行为更新了 WinUI 3。这些更新包括添加了 InfoBadge 控件、改进了辅助功能和高对比度模式，以及控件的 bug 修复。有关详细信息，请参阅 WinUI 2.7 和 WinUI 2.8 的发行说明。

已解决的问题：

Windows 10 应用现在支持带有 DesktopAcrylicController 的 Acrylic 背景材料。有关详细信息，请查看 GitHub 上的问题 7112。
修复了导致 App.UnhandledException 路由失败的各种问题。有关详细信息，请查看 GitHub 上的问题 5221。有关其余问题，解决方法记录在以下 GitHub 问题中，这些问题在将来的版本 1.2 中将予以解决：
- App_UnhandledException 的 UnhandledExceptionEventArgs.Exception 只能提取一次 - 应缓存
- Do_Abi _* 事件/回调处理程序应使用 RoReportUnhandledError 包装调用
修复了导致 ListView 样式从 WinAppSDK 1.1 回归和更改的问题。有关详细信息，请查看 GitHub 上的问题 7666。
修复了当应用处于非活动状态时，导致出现错误的 Mica 回退背景色的问题。有关详细信息，请查看 GitHub 上的问题 7801。

已知限制：

使用 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 预览版 2 开始，可以在 Arm64 设备上使用 WinAppSDK 开发本机应用程序。

若要开始在 Arm64 设备上进行开发，请参阅基于 Arm 的 Windows 和 Arm64 Visual Studio。

通知

AppNotificationBuilder 作为 XML 有效负载的替代方案引入，用于创建和定义应用通知。

有关使用信息，请参阅 GitHub 上的 AppNotificationBuilder 规范。

另请参阅快速入门：Windows App SDK 中的应用通知，以获取有关如何创建发送和接收本地应用通知的 Windows 桌面应用程序的示例。

中断性变更：

对于推送通知，在发出通道请求调用时，应用需要使用 Azure 对象 ID 而不是 Azure 应用 ID。有关查找 Azure 对象 ID 的详细信息，请参阅快速入门：Windows App SDK 中的推送通知。

修复的问题：

PushNotificationManager.IsSupported 将执行提升模式检查。如果应用已提升，它将返回 false。

已知限制（通知）：

在 AppNotificationScenario 中，Urgent 仅支持 Windows 版本 19041 及更高版本。可以使用 AppNotificationBuilder.IsUrgentScenarioSupported 检查该功能在运行时是否可用。
在 AppNotificationButton 中，hint-toolTip 和 hint-buttonStyle 仅支持版本 19041 及更高版本。可以使用 IsButtonStyleSupported 和 IsToolTipSupported 检查该功能在运行时是否可用。
在 MediaPlayerElement 中，在未打包应用的 XAML 标记中使用 Source 属性时，无法使用 ms-appx 或 ms-resource URI 设置该属性。替代做法是使用文件 URI 设置 Source，或者从代码设置。

窗口化

现在，可以通过 AppWindowTitleBar 类在 Windows 10 版本 1809 及更高版本中使用完整的标题栏自定义。可以将 AppWindowTitleBar.ExtendsContentIntoTitleBar 设置为 true 以将内容扩展到标题栏区域，并设置 SetDragRectangles 以定义拖动区域（此外还可以设置其他自定义选项）。

如果你一直在使用 AppWindowTitleBar.IsCustomizationSupported 属性来检查是否可以调用 AppWindowTitleBar API，它现在会在支持的 Windows App SDK Windows 10 版本（1809 及更高版本）上返回 true。

已知限制（窗口化）：

Windows 10 不支持基本标题栏自定义。这些属性包括 BackgroundColor、InactiveBackgroundColor、ForegroundColor、InactiveForegroundColor 和 IconShowOptions。如果你调用这些属性，将以静默方式忽略它们。所有其他 AppWindowTitleBar API 都可以在 Windows 10 版本 1809 及更高版本中使用。对于标题按钮颜色 API（及其他 API）和 Height，ExtendsContentIntoTitleBar 必须设置为 true，否则也会以静默方式将其忽略。

访问控制

引入了 security.accesscontrol.h 和 GetSecurityDescriptorForAppContainerNames 函数，以简化和条理化打包进程与常规 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。
现在，仅为生成可执行文件（OutputType=Exe 或 WinExe）的项目设置引导程序和未停靠 RegFree WinRT 自动初始化表达式默认值。这可以防止在默认情况下将自动初始化表达式添加到类库 DLL 和其他不可执行文件中。
- 如果需要在不可执行文件（例如，由不初始化引导程序的通用可执行文件加载的测试 DLL）中使用自动初始化表达式，可以通过 <WindowsAppSdkBootstrapInitialize>true</WindowsAppSdkBootstrapInitialize> 或 <WindowsAppSdkUndockedRegFreeWinRTInitialize>true</WindowsAppSdkUndockedRegFreeWinRTInitialize> 在项目中显式启用自动初始化表达式。
Microsoft.WindowsAppRuntime.Release.Net.dll 始终是 Arm64 二进制文件，不适用于 x86 和 x64 应用。显式调用 Bootstrap API 时，不要使用 Microsoft.WindowsAppRuntime.Release.Net.dll 程序集。作为解决方法，可以在随 NuGet 包一起分发的以下源文件中包含版本常数：'..\include\WindowsAppSDK-VersionInfo.cs'，或使用自动初始化表达式。