通过

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

  • 项目

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

重要链接：

稳定通道发行说明存档：

下载 Windows App SDK

注意

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

版本 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.CsWinRT 2.1.1 （或更高版本）。

注意

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

本机 AOT 支持

1.6 中的本机 AOT 支持

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

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

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

由于Windows 应用 SDK在 F5 部署时调用发布目标，因此我们建议在 NuGet 还原时启用PublishAot，方法是将此项添加到csproj文件：

<PublishAot>true</PublishAot>

解决 AOT 问题

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

分部类

C#/WinRT 还包含 PublishAot 版本 2.1.1 中的支持。 若要使用 C#/WinRT 为 AOT 发布启用类，必须先标记 partial该类。 这样，C#/WinRT AOT 源分析器就可以将类特性化为静态分析。 只有类（包含方法，剪裁的目标）才需要此属性。

不安全代码错误

CsWinRT 源生成器可能会生成使用 unsafe的代码。 如果在编译期间遇到此类错误或针对它的诊断警告（CS0227 的“不安全代码可能仅在使用 /unsafe 进行编译时出现”），则应将 EnableUnsafeBlocks 设置为 true。 有关详细信息，请参阅 GitHub 问题 CsWinRT #1721。

WebView2 尚不兼容 AOT

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

无反射技术

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

根类型

在完全支持 {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 引用，而不是嵌入边缘 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 直接引用。
  • 使用本机 AOT 编译的应用有时可能会在页面导航后遇到挂起问题，因为 .NET 运行时的 GC 线程中的争用条件。 有关详细信息，请参阅 .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 完全透明背景的问题。
  • 修复了以下问题：在显示比例系数超过 100% 或启用系统文本缩放时，拖入 WebView2 会失败或下降到错误的位置。
  • 修复了当输入因限制而阻止输入时，无法向辅助功能工具报出的问题TextBoxRichEditBox/。MaxLength
  • 修复了处理自定义标题栏方案时出现的几个问题。 有关详细信息，请参阅 GitHub 问题 #7629、 #9670、 #9709 和 #8431。
  • 修复了图标不可见的问题 InfoBadge 。 有关详细信息，请参阅 GitHub 问题 #8176。
  • 修复了图标有时在错误位置上 CommandBarFlyout显示的问题。 有关详细信息，请参阅 GitHub 问题 #9409。
  • 修复了打开或关闭子菜单时菜单中键盘焦点的问题。 有关详细信息，请参阅 GitHub 问题 #9519。
  • 修复了在回收项目时使用错误IsExpanded状态的问题TreeView。 有关详细信息，请参阅 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。
  • 修复了无法获取SystemSuspendStatus事件的问题PowerManager.SystemSuspendStatusChanged。 有关详细信息，请参阅 GitHub 问题 #2833。
  • 修复了以下问题：初始键盘焦点未正确提供给窗口中唯一 WebView2 控件的时间。
  • 修复了在ExtendsContentIntoTitleBar=trueUI 自动化中未正确显示 Min/Max/Close 按钮的问题，这阻止了语音访问显示这些按钮的数字。
  • 修复了由于意外重新进入而导致应用在锁定检查中崩溃的问题。
  • 修复了切换为高对比度主题时颜色未正确更新的问题 Hyperlink 。
  • 修复了以下问题：更改后台窗口中的 ListView 集合可能会错误地将该窗口移动到前台并获取焦点。
  • 修复了调用 ItemsRepeater.StartBringIntoView 有时可能导致项目消失的问题。
  • 修复了触摸和拖动 Button 处于 ScrollViewer 按下状态的问题。
  • 更新了 IntelliSense，它缺少许多较新的类型和成员的信息。
  • 修复了以下问题：在空区域中 ScrollViewer 单击将焦点始终移动到该控件中的第一个可聚焦控件， ScrollViewer 并将该控件滚动到视图中。 有关详细信息，请参阅 GitHub 问题 #597。
  • 修复了事件有时多次触发的问题 Window.Activated 。 有关详细信息，请参阅 GitHub 问题 #7343。
  • 修复了设置 NavigationViewItem.IsSelected 属性以防止 true 其子级在展开时显示的问题。 有关详细信息，请参阅 GitHub 问题 #7930。
  • 修复了无法正确显示带有None或DropShadow边缘效果的标题的问题MediaPlayerElement。 有关详细信息，请参阅 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。
  • 修复了在 setter 中使用的VisualStateManager主题更改不会更新的问题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