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

2025-04-30

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

重要链接：

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

最新的稳定频道版本：

Windows 应用 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 修复。

修复了导致应用在 Composition 功能关闭期间崩溃的问题。
修复了导致应用即使在屏幕关闭时继续运行动画的问题。
修复了当同时发生鼠标和键盘输入时，导致 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 以取消阻止应用商店提交以及删除版权声明和许可证。有关详细信息，请参阅 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 修复。

修复了以下问题：如果已安装其他包，则会导致应用商店和旁加载包（例如安装程序、NuGet 和引导程序）无法安装。有关详细信息，请参阅 GitHub 问题 #3168。
修复了在使用触摸板滚动时导致缺少弹性效果和动画曲线的问题。有关详细信息，请参阅 GitHub 问题 #7874。
修复了 ListView 中导致内存泄漏的问题。
修复了导致按钮模板在鼠标悬停后不遵循前景色属性的问题。有关详细信息，请参阅 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”更改为“目标 OS 版本”，并将其 net6.0 更改为适当的值（例如 net6.0-windows10.0.19041.0）。

Windows 中的第三方小组件

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

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

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

此版本的先决条件包括：

在开发计算机上启用开发人员模式。
开发计算机正在运行来自 Windows 预览体验计划（WIP）开发通道的 Windows 版本，该版本号大于或等于 25217，同时小工具面板的版本为 521.20060.1205.0 或更高。

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

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

显示信息

Windows 桌面应用现在可以通过 WinAppSDK 中的 DisplayInformation 类支持高动态范围（HDR）和自动颜色管理（ACM）。 DisplayInformation 类可用于监视应用程序视图的显示相关信息。这包括一些事件，以便于客户端监控应用程序视图中的变化，这些变化会影响视图所在的显示器，以及显示器中的变化，这些变化可能会影响应用程序视图。

WinUI 3

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

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

修复了以下问题：

Windows 10 应用中现在支持带 DesktopAcrylicController 的亚克力背景材料。有关详细信息，请查看 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 应用 SDK 中的应用通知，了解如何创建发送和接收本地应用通知的桌面 Windows 应用程序的示例。

重大变更：

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

修复了以下问题：

PushNotificationManager.IsSupported 将执行提升模式检查。如果该应用具有提升权限，系统将返回 false。

已知限制（通知）：

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

窗口

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

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

已知限制（开窗）：

Windows 10 不支持基本标题栏自定义。其中包括 BackgroundColor、 InactiveBackgroundColor、 ForegroundColor、 InactiveForegroundColor 和 IconShowOptions。如果您调用这些属性，它们将被静默忽略。所有其他 AppWindowTitleBar API 在 Windows 10 版本 1809 及更高版本中工作。对于标题按钮颜色 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。
Bootstrapper 和 Undocked RegFree WinRT 的自动初始化默认值现在仅为生成可执行文件（OutputType=Exe 或 WinExe）的项目设置。这可以防止默认将自动初始化器添加到类库 DLL 及其他不可执行文件中。
- 如果您需要在非可执行文件中启用自动初始化器（例如，由未初始化 Bootstrapper 的泛型可执行文件加载的测试 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" 或使用自动初始化。