通过

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

  • 项目

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

重要链接：

稳定通道发行说明存档：

下载 Windows App SDK

注意

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

版本 1.6.5 （1.6.250205002）

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

  • 修复了多个内存泄漏问题。

版本 1.6.4 （1.6.250108002）

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

  • 修复了多行 TextBox 中突出显示文本选择的问题。 有关详细信息，请参阅 GitHub 问题 #9965。
  • 修复了 DDLM 包有时不会安装、阻止启动未打包的应用的问题。 有关详细信息，请参阅 GitHub 问题 #3855。
  • 修复了在某些情况下 Detours 中可能出现的崩溃。 有关详细信息，请参阅 GitHub 问题 #4937。
  • 修复了当 CommandBar 位于窗口底部时，命令栏外的菜单可能会错误地打开而不是向下打开的另一个潜在问题。
  • 修复了在较旧图形硬件上运行时可能出现的崩溃。
  • 修复了关闭窗口时指针事件处理中潜在的崩溃。
  • 修复了因 CUIAWindow::InitIds 有时触发重入而导致的潜在崩溃。
  • 修复了使用 CompositionCapabilities.Changed 事件时可能发生的崩溃。
  • 修复了一些 Unicode 字符在 TextBox/RichEditBox 中显示为正方形的问题。
  • 修复了 options.RegisterNewerIfAvailable 的 PackageDeploymentManager.EnsurePackage*Async() 处理。 有关详细信息，请参阅 GitHub 问题 #4864。

版本 1.6.3 (1.6.241114003)

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

  • 修复了读取 AppWindow.ExtendsContentIntoTitleBar 属性时会打开自定义标题栏呈现的问题。 有关详细信息，请参阅 GitHub 问题 #9988。
  • 修复了在销毁 TextBox/RichEditBox 时可能发生的崩溃。 有关详细信息，请参阅 GitHub 问题 #9070。
  • 修复了 PackageDeploymentManager.IsPackageReadyOrNewerAvailable() 失败的问题。 有关详细信息，请参阅 GitHub 问题 #4817。
  • 修复了 ScrollViewer 泄漏的问题。
  • 添加了对罕见场景的检测，即应用停止呈现并且永远不会恢复。
  • 修复了一个问题，即 PackageDeploymentManager.RegisterPackageSetAsync() 需要 URI，而通过 PackageFamilyName 注册时应该是可选的。
  • 修复了阻止安装或卸载应用的问题。 有关详细信息，请参阅 GitHub 问题 #4881。

此版本包括以下新 API，允许小组件提供程序将 Web 内容合并到他们的小组件中：

Microsoft.Windows.Widgets.Providers 
  IWidgetManager2 
  IWidgetProviderMessage 
  IWidgetResourceProvider 
  WidgetManager 
     SendMessageToContent 

  WidgetMessageReceivedArgs 
  WidgetResourceRequest 
  WidgetResourceRequestedArgs 
  WidgetResourceResponse

版本 1.6.1 (1.6.240923002)

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

  • 修复了使用 FocusVisualKind.Reveal() 时的崩溃问题。 有关详细信息，请参阅 GitHub 问题 #9966。
  • 修复了 Bcp47Langs.dll 中的嘈杂 C++ 异常。 有关详细信息，请参阅 GitHub 问题 #4691。 请注意，此修补程序将删除与 Windows.Globalization.ApplicationLanguages.PrimaryLanguageOverride 的同步。
  • 修复了显示 ContentDialog 后立即引发额外 Unloaded 事件的问题。 有关详细信息，请参阅 GitHub 问题 #8402。
  • 修复了即使有打开空间，CommandBar 菜单也可能错误打开的问题。
  • 修复了顶级窗口在从右向左模式下运行时，对 InputNonClientPointerSource 区域的输入处理不正确的一些问题。
  • 修复了 Windows SDK 框架版本的编译时检查，以处理用于 .NET 9 的略有不同的框架名称。

版本 1.6

以下部分描述了版本 1.6 的新功能和已更新功能，以及已知问题。

在现有的 Windows 应用 SDK 1.5 应用中，可以将 Nuget 包更新为 1.6.240829007（请参阅使用 NuGet 包管理器在 Visual Studio 中安装和管理包中的更新包部分）。

有关已更新的运行时和 MSIX，请参阅 Windows 应用 SDK 下载。

1.6 所需的项目更改

C++ 项目更改

将 C++ 项目更新为 1.6 时，需要向 Microsoft.Web.WebView2 包添加项目引用。 如果在 Visual Studio 中通过 NuGet 包管理器进行更新，则会为你添加此依赖项。

C# 项目更改

在 1.6 中，Windows 应用 SDK 托管应用需要 Microsoft.Windows.SDK.NET.Ref*.*.*.38 或更高版本，这可以通过 csproj 文件中的 WindowsSdkPackageVersion 指定。 例如：

<Project Sdk="Microsoft.NET.Sdk">
   <PropertyGroup>
       <OutputType>WinExe</OutputType>
       <TargetFramework>net8.0-windows10.0.22621.0</TargetFramework>
       <TargetPlatformMinVersion>10.0.17763.0</TargetPlatformMinVersion>
       <WindowsSdkPackageVersion>10.0.22621.38</WindowsSdkPackageVersion>
   <PropertyGroup>
   ...

此外，Windows 应用 SDK 托管应用应更新为 Microsoft.Windows.CsWinRT2.1.1（或更高版本）。

注意

发布下一个 .NET SDK 服务更新后，不再需要这些手动引用。

本机 AOT 支持

1.6 中的原生 AOT 支持

.NET PublishAot 项目属性现在支持本机预先编译。 有关本机 AOT 的详细信息，请参阅本机 AOT 部署。 由于 AOT 基于剪裁支持而构建，因此以下与剪裁相关的大部分指导也适用于 AOT。

对于 PublishAot 支持和剪裁支持，除了上一节中所述的 C# 项目更改之外，还需要对 Microsoft.Windows.CsWinRT2.1.1（更高版本）的包引用，才能从该包启用源生成器，直到不再需要下一个 .NET SDK 服务更新发布。

有关详细信息，请参阅 CsWinRT 剪裁/AOT 支持文档和 CsWinRT 2.1.1 发行说明。

由于Windows 应用 SDK 在 F5 部署时调用发布目标，因此我们建议在 NuGet 还原时通过将以下内容添加到 csproj 文件中来启用 PublishAot：

<PublishAot>true</PublishAot>

解决 AOT 问题

在此版本中，开发人员负责确保所有类型都有正确的根，以避免剪裁（例如基于反射的 {Binding} 目标）。 后续版本将增强 C#/WinRT 和 XAML 编译器，使其在可能的情况下自动生根，提醒开发人员降低剪裁风险，并提供解决机制。

分部类

C#/WinRT 在 2.1.1 版本中也包含了对 PublishAot 的支持。 若要使用 C#/WinRT 启用 AOT 发布类，必须首先将其标记为 partial。 这允许 C#/WinRT AOT 源代码分析器为静态分析的类赋予属性。 只有类（包含方法，剪裁的目标）才需要此属性。

不安全代码错误

CsWinRT 源生成器可能会生成使用 unsafe 的代码。 如果在编译过程中遇到此类错误或出现诊断警告（CS0227 表示“不安全代码只会在使用 /unsafe 编译的情况下出现”），则应将 EnableUnsafeBlocks 设置为 true。 有关详细信息，请参阅 GitHub 问题 CsWinRT #1721。

WebView2 尚不兼容 AOT

Microsoft.Web.WebView2 包版本 1.0.2651.64 中的 WebView2 投影尚不兼容 AOT。 这将在即将发布的 Microsoft.Web.WebView2 包中得到修复，然后你可以在项目中引用它。

无反射技术

若要启用 AOT 兼容性，应将基于反射的技术替换为静态类型化序列化、AppContext.BaseDirectory、typeof() 等。有关详细信息，请参阅剪裁警告简介。

Root 类型

在实现对 {Binding} 的完全支持之前，可以按如下方式保留类型不进行剪裁：

给定项目 P 在命名空间 N 中使用类型 T 的程序集 A，该程序集仅被动态引用（因此通常被剪裁），可以通过以下方式保留 T：

P.csproj：

<ItemGroup>
    <TrimmerRootDescriptor Include="ILLink.Descriptors.xml" />
</ItemGroup>

ILLink.Descriptors.xml：

<?xml version="1.0" encoding="utf-8"?>
<linker>
    <assembly fullname="A">
        <type fullname="N.T" preserve="all" />
    </assembly>
</linker>

有关完整的根描述符 XML 表达式语法，请参阅根描述符。

注意

尚未采用 AOT 支持的依赖项包可能会显示运行时问题。

分离的 WebView2 版本控制

Windows 应用 SDK 现在使用 Edge WebView2 SDK 作为 NuGet 引用，而不是嵌入 Edge WebView2 SDK 的硬编码版本。 新模型允许应用选择较新版本的 Microsoft.Web.WebView2 包，而不是仅限于生成 Windows 应用 SDK 的版本。 新模型还允许应用引用也引用 Edge WebView2 SDK 的 NuGet 包。 有关详细信息，请参阅 GitHub 问题 #5689。

新建包部署 API

包管理 API 已收到多项增强功能，包括 Is*ReadyOrNewerAvailable*()、EnsureReadyOptions.RegisterNewerIfAvailable、Is*Provisioned*()、IsPackageRegistrationPending() 和多个 bug 修复。 有关更多详细信息，请参阅 PackageManagement.md 和 拉取请求 #4453。

改进了 TabView 选项卡分离

改进了 1.6 中的 TabView 选项卡分离

TabView 支持新的 CanTearOutTabs 模式，该模式为拖动选项卡和拖动到新窗口提供了增强的体验。 启用此新选项后，选项卡拖动非常类似于 Edge 和 Chrome 中的选项卡拖动体验，在拖动过程中会立即创建一个新窗口，允许用户将其拖动到屏幕边缘，以平滑的动作最大化或捕获窗口。 此实现也不使用拖放 API，因此不受这些 API 中的任何限制的影响。 值得注意的是，在以管理员身份提升的进程中，支持选项卡分离。

其他值得注意的更改

  • 添加了一个新的 ColorHelper.ToDisplayName() API，填补了 UWP 的空白。
  • 添加了一个新 Microsoft.Windows.Globalization.ApplicationLanguages 类，其中特别包括一个新 PrimaryLanguageOverride 功能。 有关详细信息，请参阅 GitHub 问题 #4523。
  • 未密封 ItemsWrapGrid。 这是向后兼容的更改。
  • PipsPager 支持一种新模式，可以在第一个项目和最后一个项目之间换行。

1.6 中新增的 PipsPager 换行模式

  • RatingControl 现在通过将一些硬编码样式属性移动到主题资源，更易于进行自定义设置。 这允许应用覆盖这些值，以更好地自定义 RatingControl 的外观。
1.6 中新增的 RatingControl 自定义
  • WinUI 3 已更改为字体选择的排版模型，而不是传统的粗细/拉伸/样式模型。 某些较新的字体（包括 Segoe UI 变量）需要排版模型，并支持增强的字体功能。 一些依赖于粗细/拉伸/样式模型进行选择的旧字体可能无法在排版模型中找到。

已知问题

  • 如果调试器设置为在所有 C++ 异常时中断，则它将在 BCP47（Windows 全球化）代码中启动时在一些嘈杂的异常时中断。 有关详细信息，请参阅 GitHub 问题 #4691。
  • 引用 WinAppSDK 1.6 包的组件库包无法正确获取引用的 WebView2 包内容。 有关详细信息，请参阅 WebView2Feedback #4743。 一种解决方法是在需要的地方添加对 Microsoft.Web.WebView2 包的直接引用。
  • 由于 .NET 运行时的 GC 线程中的争用条件，使用本机 AOT 编译的应用在页面导航后有时可能会遇到挂起问题。 有关详细信息，请参阅 .NET 问题 #104582。
  • 1.6.0 的初始版本引入了一个与我们的一个依赖项有关的问题，我们希望在即将发布的 .NET SDK 中解决这个问题。 如果遇到 Microsoft.Windows.SDK.NET 引用版本错误，则需要显式引用错误消息指定的 .NET SDK 版本。 例如，如果错误提示你需要版本 10.0.19041.38，请将以下内容添加到 .csproj 文件中：
    • <WindowsSdkPackageVersion>10.0.19041.38</WindowsSdkPackageVersion>。

缺陷修复

  • 修复了在 .xaml 中设置 InfoBar.IsOpen 时发生的崩溃。 有关详细信息，请参阅 GitHub 问题 #8391。
  • 修复了当鼠标移动到 WebView2 边界之外时，HTML 元素将丢失指针捕获的问题。 有关详细信息，请参阅 GitHub 问题 #8677。
  • 修复了拖放到带有 ShouldConstrainToRootBounds=false 的弹出按钮中不起作用的问题。 有关详细信息，请参阅 GitHub 问题 #9276。
  • 修复了启用 PublishSingleFile 时 ms-appx:// 引用不起作用的问题。 有关详细信息，请参阅 GitHub 问题 #9468。
  • 修复了调试器符号在某些二进制文件中无法正常工作的问题。 有关详细信息，请参阅 GitHub 问题 #4633。
  • 修正了当子类化 NavigationView 时可能崩溃的问题。
  • 修复了滚动或减小表格大小时 RichEditBox 中的表格边框无法正确擦除的问题。
  • 修复了 MediaTransportControls 中浮出控件具有完全透明背景的问题。
  • 修复了一个问题，即拖动到 WebView2 会失败，或者在显示比例系数不是 100% 的情况下或启用系统文本缩放时掉落在错误的位置。
  • 修复了 TextBox/RichEditBox 当输入因 MaxLength 限制而受阻时不会向辅助功能工具宣布的问题。
  • 修复了一些关于处理自定义标题栏方案的问题。 有关详细信息，请参阅 GitHub 问题 #7629、#9670、#9709 和 #8431。
  • 修复了 InfoBadge 图标不可见的问题。 有关详细信息，请参阅 GitHub 问题 #8176。
  • 修复了图标在 CommandBarFlyout 中有时显示在错误位置的问题。 有关详细信息，请参阅 GitHub 问题 #9409。
  • 修复了打开或关闭子菜单时菜单中键盘焦点的问题。 有关详细信息，请参阅 GitHub 问题 #9519。
  • 修复了在回收项目时 TreeView 使用错误 IsExpanded 状态的问题。 有关详细信息，请参阅 GitHub 问题 #9549。
  • 修复了在 ItemsRepeater.ItemTemplate 中使用 ElementName 绑定时出现的问题。 有关详细信息，请参阅 GitHub 问题 #9715。
  • 修复了 ItemsRepeater 中的第一个项目有时位置不正确的问题。 有关详细信息，请参阅 GitHub 问题 #9743。
  • 修复了 InputNonClientPointerSource 有时中断最小/最大/关闭按钮输入的问题。 有关详细信息，请参阅 GitHub 问题 #9749。
  • 修复了将 Microsoft.UI.Interop.h 与 clang-cl 配合使用时的编译错误。 有关详细信息，请参阅 GitHub 问题 #9771。
  • 修复了 CharacterReceived 事件在 ComboBox/TextBox 中不起作用的问题。 有关详细信息，请参阅 GitHub 问题 #9786。
  • 修复了箭头键和选项卡键引发重复 KeyUp 事件的问题。 有关详细信息，请参阅 GitHub 问题 #9399。
  • 修复了 PowerManager.SystemSuspendStatusChanged 事件无法获取 SystemSuspendStatus 的问题。 有关详细信息，请参阅 GitHub 问题 #2833。
  • 修复了当窗口中唯一的控件为 WebView2 时，初始键盘焦点不能正确给定的问题。
  • 修复了当使用 ExtendsContentIntoTitleBar=true 时，最小/最大/关闭按钮没有正确出现在 UI 自动化中，从而阻止语音访问显示这些按钮的数字的问题。
  • 修复了应用可能在锁定检查中由于意外重入而崩溃的问题。
  • 修复了切换到高对比度主题时 Hyperlink 颜色无法正确更新的问题。
  • 修复了更改背景窗口中 ListView 的集合可能会错误地将该窗口移动到前景并聚焦的问题。
  • 修复了调用 ItemsRepeater.StartBringIntoView 有时会导致项目消失的问题。
  • 修复了在 ScrollViewer 中触摸和拖动 Button 会使其处于按下状态的问题。
  • 更新了 IntelliSense，但缺少许多较新类型和成员的信息。
  • 修复了一个问题，即在 ScrollViewer 的空白区域单击总是会将焦点移动到 ScrollViewer 中的第一个可聚焦控件，并将该控件滚动到视图中。 有关详细信息，请参阅 GitHub 问题 #597。
  • 修复了 Window.Activated 事件有时会多次触发的问题。 有关详细信息，请参阅 GitHub 问题 #7343。
  • 修复了将 NavigationViewItem.IsSelected 属性设置为 true 会阻止其子项在展开时显示的问题。 有关详细信息，请参阅 GitHub 问题 #7930。
  • 修复了 MediaPlayerElement 无法正确显示带有 None 或 DropShadow 边缘效果的字幕的问题。 有关详细信息，请参阅 GitHub 问题 #7981。
  • 修复了显示浮出控件时未使用 Flyout.ShowMode 属性的问题。 有关详细信息，请参阅 GitHub 问题 #7987。
  • 修复了 NumberBox 有时会出现舍入错误的问题。 有关详细信息，请参阅 GitHub 问题 #8780。
  • 修复了使用针对旧版本 WinAppSDK 编译的库在尝试查找类型或属性时出错的问题。 有关详细信息，请参阅 GitHub 问题 #8810。
  • 修复了启动窗口时未设置初始键盘焦点的问题。 有关详细信息，请参阅 GitHub 问题 #8816。
  • 修复了 FlyoutShowMode.TransientWithDismissOnPointerMoveAway 首次显示后不起作用的问题。 有关详细信息，请参阅 GitHub 问题 #8896。
  • 修复了某些控件无法正确绑定模板 Foreground 和 Background 属性的问题。 有关详细信息，请参阅 GitHub 问题 #7070、#9020、#9029、#9083 和 #9102。
  • 修复了 VisualStateManager setter 中使用的 ThemeResource 不会在主题更改时更新的问题。 这通常会影响浮出控件中的控件。 有关详细信息，请参阅 GitHub 问题 #9198。
  • 修复了 WebView 将失去关键焦点，导致额外模糊/焦点事件和其他问题的问题。 有关详细信息，请参阅 GitHub 问题 #9288。
  • 修复了 NavigationView 可能在调试输出中显示绑定错误的问题。 有关详细信息，请参阅 GitHub 问题 #9384。
  • 修复了定义负视区的 SVG 文件不再呈现的问题。 有关详细信息，请参阅 GitHub 问题 #9415。
  • 修复了更改 ItemsView.Layout 方向导致项目被删除的问题。 有关详细信息，请参阅 GitHub 问题 #9422。
  • 修复了滚动 ScrollView 生成大量调试输出的问题。 有关详细信息，请参阅 GitHub 问题 #9434。
  • 修复了 MapContorl.InteractiveControlsVisible 不能正常工作的问题。 有关详细信息，请参阅 GitHub 问题 #9486。
  • 修复了 MapControl.MapElementClick 事件未正确触发的问题。 有关详细信息，请参阅 GitHub 问题 #9487。
  • 修复了 x:Bind 在使用弱引用之前没有检查 null 的问题，这可能会导致崩溃。 有关详细信息，请参阅 GitHub 问题 #9551。
  • 修复了更改 TeachingTip.Target 属性不能正确更新其位置的问题。 有关详细信息，请参阅 GitHub 问题 #9553。
  • 修复了 WebView2 中下拉菜单没有响应的问题。 有关详细信息，请参阅 GitHub 问题 #9566。
  • 修复了使用 GeometryGroup 时内存泄漏问题。 有关详细信息，请参阅 GitHub 问题 #9578。
  • 修复了从 ScrollView 中的 ItemRepeater 滚动浏览大量项目可能导致空白呈现帧的问题。 有关详细信息，请参阅 GitHub 问题 #9643。
  • 修复了 SceneVisual 不起作用的问题。

1.6.0 中的新 API

版本 1.6.0 包括与稳定 1.5 版本相比的以下新 API：

Microsoft.UI

    ColorHelper
        ToDisplayName

Microsoft.UI.Input

    EnteredMoveSizeEventArgs
    EnteringMoveSizeEventArgs
    ExitedMoveSizeEventArgs
    InputNonClientPointerSource
        EnteredMoveSize
        EnteringMoveSize
        ExitedMoveSize
        WindowRectChanged
        WindowRectChanging

    MoveSizeOperation
    WindowRectChangedEventArgs
    WindowRectChangingEventArgs

Microsoft.UI.Xaml

    XamlRoot
        CoordinateConverter

Microsoft.UI.Xaml.Automation.Peers

    ScrollPresenterAutomationPeer

Microsoft.UI.Xaml.Controls

    PipsPager
        WrapMode
        WrapModeProperty

    PipsPagerWrapMode
    TabView
        CanTearOutTabs
        CanTearOutTabsProperty
        ExternalTornOutTabsDropped
        ExternalTornOutTabsDropping
        TabTearOutRequested
        TabTearOutWindowRequested

    TabViewExternalTornOutTabsDroppedEventArgs
    TabViewExternalTornOutTabsDroppingEventArgs
    TabViewTabTearOutRequestedEventArgs
    TabViewTabTearOutWindowRequestedEventArgs

Microsoft.Windows.Globalization

    ApplicationLanguages

Microsoft.Windows.Management.Deployment

    EnsureReadyOptions
        RegisterNewerIfAvailable

    PackageDeploymentFeature
    PackageDeploymentManager
        IsPackageDeploymentFeatureSupported
        IsPackageProvisioned
        IsPackageProvisionedByUri
        IsPackageReadyOrNewerAvailable
        IsPackageReadyOrNewerAvailableByUri
        IsPackageSetProvisioned
        IsPackageSetReadyOrNewerAvailable

    PackageReadyOrNewerAvailableStatus

Microsoft.Windows.Storage

    ApplicationData
    ApplicationDataContainer
    ApplicationDataContract
    ApplicationDataCreateDisposition
    ApplicationDataLocality