通过

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

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

重要链接：

最新的稳定频道版本：

下载 Windows App SDK

注释

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

版本 1.0.4

这是 Windows 应用 SDK 的服务版本，其中包含 1.0 版本的严重 bug 修复。

错误修复（1.0.4）

  • 修复了一个问题：当 AppBars 用作 Page.TopAppBar 或 Page.BottomAppBar 时，无法在屏幕上显示。
  • 修复了以下问题：使用来自 MUXControls.dll 的 WinUI 控件的包名称为 12 个字符或更少的应用将立即崩溃。 有关详细信息，请参阅 GitHub 上的 问题 6360 。
  • 修复了触摸输入问题，这些问题导致键盘快捷方式和其他场景无法正常使用。 有关详细信息，请参阅 GitHub 上的 问题 6291 。
  • 修复了导致使用 MSIX 打包或部署为自包含的应用无法部署的问题。
  • 修复了导致应用在拖放操作期间有时崩溃的问题。 有关详细信息，请参阅 GitHub 上的 问题 7002 。

版本 1.0.3

这是 Windows 应用 SDK 的服务版本，其中包含 1.0 版本的严重 bug 修复。

漏洞修复（1.0.3）

  • 修复了在未安装 C/C++ 运行时（CRT）时导致 WebView2 的 C# 应用在启动时崩溃的问题。
  • 修复了触摸输入问题，这些问题导致键盘快捷方式和其他场景无法正常使用。 有关详细信息，请参阅 GitHub 上的 问题 6291 。

注意：我们通常不会在服务版本中添加功能，但此版本的 WebView2 修补程序要求我们更新到最新版本的 WebView2 SDK（1020.46 到 1185.39）。 有关 WebView2 1.0.1185.39 的其他信息，请参阅 WebView2 SDK 发行说明；有关 WebView2 运行时的更多信息，请参阅分发应用和 WebView2 运行时 。

版本 1.0.2

这是 Windows 应用 SDK 的服务版本，其中包含 1.0 版本的严重 bug 修复。

漏洞修复（1.0.2）

  • 修复了在滚动到 ListView 末尾时导致应用崩溃的布局周期问题。 有关详细信息，请参阅 GitHub 上的 问题 6218 。
  • 修复了在未安装 C/C++ 运行时 （CRT） 时导致 C# 应用在启动时崩溃的问题。 但是，使用 WebView2 的 C# 应用仍需要 CRT。 有关详细信息，请参阅 GitHub 上的 问题 2117 。
  • 修复了具有单项目 MSIX 的应用程序未生成 .appinstaller 文件的问题。 有关详细信息，请参阅 GitHub 上的 问题 1821 。
  • 修复了 WinUI 应用程序不支持 .NET 6 dotnet build的问题。

版本 1.0.1

这是 Windows 应用 SDK 的服务版本，其中包括 1.0 版本的关键 bug 修复和多窗口支持。

漏洞修复（1.0.1）

  • 修复了因启用 ImplicitUsings 而导致 MddBootstrapAutoinitializer 无法编译的问题。 有关详细信息，请参阅 GitHub 上的 问题 1686 。
  • 修复了 WebView2 中的焦点意外丢失导致输入和选择问题的问题。 有关详细信息，请参阅 GitHub 上的 问题 5615 和 问题 5570 。
  • 修复了在 WinUI 3 应用中使用自定义标题栏时，导致 Visual Studio 中的应用内工具栏无法点击的问题。
  • 修复了在 WinUI 3 应用中使用自定义标题栏时，快照布局不显示的问题。 有关详细信息，请参阅 GitHub 上的 问题 6333 和 问题 6246 。
  • 修复了在使用仍在加载的 UIElement 调用 Window.SetTitlebar 时设置 Window.ExtendsContentIntoTitleBar 属性时导致异常的问题。
  • 修复了单项目 MSIX 应用不支持 dotnet build的问题。
  • 修复了导致未打包应用在安装打包应用后无法安装的问题。 有关详细信息，请参阅 GitHub 上的 问题 1871 。
  • 修复了在鼠标拖动作期间降低性能的问题。
  • 修复了在未打包的应用中调用 GetWindowIdFromWindow（） 时的崩溃。 有关详细信息，请参阅 GitHub 上的 1891 讨论 。

版本 1.0 的限制和已知问题 也适用于版本 1.0.1。

此外，对于具有自定义标题栏的应用，我们在此版本中进行了更改（并修复了许多问题），其中包括对用于拖放作的玻璃窗口的修复。 建议使用默认值和行为（试试看！） 如果你的标题栏使用了边距，以便默认标题按钮是交互式的，我们建议通过将标题栏的背景设置为红色，然后调整边距以将拖动区域扩展到标题控件来可视化拖动区域。

新功能

我们已稳定并启用了在 WinUI 3 应用程序中在同一线程 上创建 多个窗口。 有关详细信息 ，请参阅问题 5918 。

版本 1.0

以下部分介绍 1.0 的新功能和更新的功能、限制和已知问题。

WinUI 3

WinUI 3 是 Windows 应用 SDK 的本机用户体验 （UX） 框架。 在此版本中，我们添加了 Windows 应用 SDK 0.8 中的多个新功能，并稳定了 1.0 预览版中的问题。

新功能和更新：

  • 我们添加了新控件（PipsPager、Expander、BreadcrumbBar）和更新了现有控件，以反映 WinUI 2.6 的最新 Windows 样式。
  • WinUI 支持单项目 MSIX 打包，可以通过使用“Blank App, Packaged…”模板创建一个新的应用程序来实现。
  • 我们现在支持部署未打包在 Windows 版本 1809 及更高版本的 WinUI 3 应用。 有关其他信息，请查看 创建第一个 WinUI 3 （Windows 应用 SDK） 项目 。
  • WinUI 3 项目现在可以将其目标版本设置为 Windows 10 版本 1809。 以前，只能将它们设置为最低版本 1903。
  • Visual Studio 2022 预览版 5 和 GA 支持应用内工具栏、热重载和 WinUI 打包应用的实时可视化树。

重要限制：

  • 打包和解压缩的 WinUI 应用程序的已知问题：

    • 引用 C++ Windows 运行时组件的 C++ 或 C# 应用中的运行时错误：

      • 若要解决此问题，请将以下目标添加到 Windows 运行时组件的.vcxproj末尾：
      <Target Name="GetPriIndexName">
<PropertyGroup>
    <!-- Winmd library targets use the default root namespace of the project for the App package name -->
    <PriIndexName Condition="'$(RootNamespace)' != ''">$(RootNamespace)</PriIndexName>
    <!-- If RootNamespace is empty fall back to TargetName -->
    <PriIndexName Condition="$(PriIndexName) == ''">$(TargetName)</PriIndexName>
</PropertyGroup>
</Target>
      • 预期错误将类似于 WinRT 发起错误 - 0x80004005：‘无法从“ms-appx:///BlankPage.xaml”中找到资源’。

  • 使用单项目 MSIX WinUI 应用程序的已知问题（空白应用，打包模板）：

    • 缺少包以及直到重新启动 Visual Studio 才出现“发布”菜单项：当使用“打包的空白应用（桌面版 WinUI 3）”项目模板在 Visual Studio 2019 和 Visual Studio 2022 中创建具有单项目 MSIX 的新应用时，关闭并重新打开 Visual Studio 之前，将不会在菜单中显示用于发布项目的命令。
    • 如果没有安装“C++（v14x）通用 Windows 平台工具”可选组件，具有单项目 MSIX 的 C# 应用将不会编译。 有关其他信息 ，请参阅 Windows 应用 SDK 的安装工具 。
    • 使用引用的 Windows 运行时组件中定义的类型的单项目 MSIX 的应用中可能出现的运行时错误： 若要解决，请手动将可激活的类条目 添加到 appxmanifest.xml。
      • C# 应用程序中的预期错误是“COMException：类未注册（0x80040154（REGDB_E_CLASSNOTREG））。
      • C++/WinRT 应用程序中的预期错误为“winrt::hresult_class_not_registered”。

  • 未打包 的 WinUI 3 应用的 已知问题（未打包的应用）：

  • 打包和部署 WinUI 应用程序的已知问题：

    • 使用单一项目 MSIX（空白应用，打包模板）的 WinUI 应用不支持 Package 命令。 请使用 Package & Publish 命令来创建 MSIX 包。
    • 要使用 Pack 命令从 C# 类库创建 NuGet 包，请确保活动的 Configuration 是 Release。
    • Pack C++ Windows 运行时组件不支持该命令来创建 NuGet 包。

有关详细信息，或开始使用 WinUI 进行开发，请参阅：

窗口

Windows 应用 SDK 提供了一个 AppWindow 类，该类可改进以前易于使用的 Windows.UI.WindowManagement.AppWindow 预览类，并使它适用于所有 Windows 应用，包括 Win32、WPF 和 WinForms。

新功能：

  • AppWindow 是一个高级窗口化 API，它允许易于使用的窗口化方案，这些方案与 Windows 用户体验和其他应用很好地集成。 表示由系统管理的应用内容容器的高级抽象。 这是托管内容的容器，表示用户在调整应用大小并在屏幕上移动应用时与之交互的实体。 对于熟悉 Win32 的开发人员，AppWindow 可以被视为 HWND 的高级抽象。
  • DisplayArea 表示 HMONITOR 的高级抽象，遵循与 AppWindow 相同的原则。
  • DisplayAreaWatcher 允许开发人员观察显示拓扑中的更改，并枚举系统中当前定义的 DisplayAreas。

有关详细信息，请参阅管理应用窗口（Windows 应用 SDK）。

输入

这些是支持 WinUI 并为开发人员提供较低级别的 API 图面以实现更高级的输入交互的输入 API。

新功能：

重要限制：

  • 已删除所有 PointerPoint 静态工厂函数：GetCurrentPoint、GetCurrentPointTransformed、GetIntermediatePoints 和 GetIntermediatePointsTransformed。
  • Windows 应用 SDK 不支持使用指针 ID 检索 PointerPoint 对象。 相反，可以使用 PointerPoint 成员函数 GetTransformedPoint 检索现有 PointerPoint 对象的转换版本。 对于中间点，可以使用 PointerEventArgs 成员函数 GetIntermediatePoints 和 GetTransformedIntermediatePoints。
  • 直接使用平台 SDK API Windows.UI.Core.CoreDragOperation 不适用于 WinUI 应用程序。
  • 已删除 PointerPoint 属性 RawPosition 和 ContactRectRaw ，因为它们引用了非预测值，这些值与 OS 中的正常值相同。 请改用 Position 和 ContactRect 。 指针预测现在使用 Microsoft.UI.Input.PointerPredictor API 对象进行处理。

应用生命周期

大多数应用生命周期功能已存在于 UWP 平台中，并且已引入 Windows 应用 SDK 供桌面应用类型使用，尤其是未打包的控制台应用、Win32 应用、Windows 窗体应用和 WPF 应用。 这些功能的 Windows 应用 SDK 实现不能用于 UWP 应用，因为 UWP 平台本身具有等效的功能。

重要

如果使用的是 UWP 应用，请参阅 从 UWP 迁移到 Windows 应用 SDK。

非 UWP 应用也可以打包到 MSIX 包中。 虽然这些应用可以使用某些 Windows 应用 SDK 应用生命周期功能，但它们必须在适用的情况下使用清单方法。 例如，它们不能使用 Windows 应用 SDK RegisterForXXXActivation API，而是必须通过清单注册以获得丰富的激活功能。

打包应用的所有约束也适用于打包的 WinUI 应用，还有如下所述的其他注意事项。

重要注意事项：

  • 丰富激活：GetActivatedEventArgs

  • 注册/注销富激活功能

  • 单一/多实例化

    • 解压缩的应用：完全可用。
    • 打包的应用：完全可用。
    • WinUI 应用：如果应用想要检测其他实例并重定向激活，则它必须尽早执行此作，并在初始化任何窗口等之前执行此作。若要启用此功能，应用必须定义DISABLE_XAML_GENERATED_MAIN，并编写自定义 Main（C#）或 WinMain（C++），以便在其中执行检测和重定向。
    • RedirectActivationToAsync 是异步调用，如果应用在 STA 中运行，则不应等待异步调用。 对于 Windows 窗体和 C# WinUI 应用，可以根据需要将 Main 声明为异步。 对于C++ WinUI 和 C# WPF 应用，无法将 Main 声明为异步，因此需要将重定向调用移动到另一个线程，以确保不会阻止 STA。
    • 有关更多信息，请参阅应用生命周期 API 下的应用程序实例化 。

  • 电源/状态通知

已知问题：

  • 设置动词处理程序的命令行模板时，文件类型关联错误地将 %1 编码为 %251，这会崩溃解压缩的 Win32 应用。 可以手动编辑注册表值，将其改为 %1 作为部分解决方法。 如果目标文件路径中有一个空格，则它仍然会失败，并且该方案没有解决方法。
  • 这些单实例/多实例问题将会在即将发布的服务补丁中修复：
    • 为 x86 编译时，AppInstance 重定向不起作用
    • 注册密钥、注销密钥并重新注册它会导致应用崩溃

DWriteCore

DWriteCore 是 DirectWrite 的 Windows 应用 SDK 实现，它是用于高质量文本呈现的 DirectX API、与分辨率无关的轮廓字体以及完整的 Unicode 文本和布局支持。 DWriteCore 是一种 DirectWrite 的形式，可以在 Windows 各个版本上运行，从 Windows 10 版本 1809（10.0；生成 17763）开始，并为跨平台使用打开了大门。

“特色”：

DWriteCore 包含 DirectWrite 的所有功能，但有一些例外情况。

重要限制：

  • DWriteCore 不包含以下 DirectWrite 功能：
    • 每次会话字体
    • 最终用户定义字符 （EUDC） 字体
    • 字体流式处理 API
  • API 对低级渲染的支持是部分的。
  • DWriteCore 不与 Direct2D 互作，但可以使用 IDWriteGlyphRunAnalysis 和 IDWriteBitmapRenderTarget。

有关详细信息，请参阅 DWriteCore 概述。

MRT 核心

MRT Core 是新式 Windows 资源管理系统 的简化版本，作为 Windows 应用 SDK 的一部分分发。

重要限制：

  • 在 .NET 项目中，如果应用程序已被构建，复制粘贴到项目文件夹中的资源文件在按下 F5 键时不会被编入索引。 解决方法是重新生成应用。 有关详细信息，请参阅 问题 1503 。

  • 在 .NET 项目中，使用 Visual Studio UI 将资源文件添加到项目时，默认情况下可能无法为文件编制索引。 有关详细信息，请参阅 问题 1786 。 若要解决此问题，请删除 CSPROJ 文件中的以下条目：

    <ItemGroup>
    <Content Remove="<image file name>" />
</ItemGroup>
<ItemGroup>
    <PRIResource Remove="<resw file name>" />
</ItemGroup>

  • 未打包的 C++ WinUI 应用程序无法正确构建资源 URI。 若要解决此问题，请在 vcxproj 中添加以下内容：

    <!-- Add the following after <Import Project="$(VCTargetsPath)\Microsoft.Cpp.props" /> -->

<PropertyGroup>
    <AppxPriInitialPath></AppxPriInitialPath>   
</PropertyGroup>

有关详细信息，请参阅 使用 MRT Core 管理资源。

部署

新功能和更新：

重要限制：

  • 引导程序 API 的 .NET 包装器仅用于解压缩的 .NET 应用程序，以简化对 Windows 应用 SDK 的访问。
  • 只有完全信任或具有 packageManagement 受限功能的 MSIX 应用包才有权使用部署 API 来安装主包和单独包依赖项。 后续版本将支持部分信任打包应用程序。
  • 当 F5 在 x64 系统上测试使用 DeploymentManager.Initialize 方法的 x86 应用时，请确保先通过运行 WindowsAppRuntimeInstall.exe来安装 x64 框架。 否则，您将遇到 NOT_FOUND 错误，这是由于 Visual Studio 并未部署 x64 框架，该框架通常通过应用商店部署或旁加载进行。

其他限制和已知问题

  • 不支持任何 CPU 生成配置：将 Windows 应用 SDK 添加到 支持 任何 CPU 的现有 .NET 应用程序或组件时，必须指定所需的体系结构： x86或 x64arm64。

  • 从 .NET 5 升级到 .NET 6：在 Visual Studio UI 中升级时，可能会遇到生成错误。 解决方法是手动将项目文件 TargetFrameworkPackage 更新为以下内容：

      <TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>

  • 如果未安装 C++ UWP 工具，则 C# 单项目 MSIX 应用不会编译。 如果你有 C# 单项目 MSIX 项目，则需要安装 C++ （v14x） 通用 Windows 平台工具 可选组件。

  • 安装多个版本的 Visual Studio 2019 时，后续语言 VSIX 无法安装到 Visual Studio 2019 中。 如果安装了多个版本的 Visual Studio 2019（例如发布和预览），然后安装适用于 C++ 和 C# 的 Windows 应用 SDK VSIX，则第二次安装将失败。 若要解决此问题，请在第一种语言 VSIX 之后卸载 Visual Studio 2019 的单项目 MSIX 打包工具。 查看此反馈 ，以获取有关此问题的其他信息。

  • DispatcherQueue.TryEnqueue（用于在调度程序队列线程上恢复执行）的替代方法是在 Windows 实现库（WIL）中使用resume_foreground帮助程序函数：

    1. 将对项目的引用添加到 Microsoft.Windows.ImplementationLibrary NuGet 包。
    2. 将 #include <wil/cppwinrt_helpers.h> 添加到 pch.h。
    3. 将 #include <winrt/Microsoft.UI.Dispatching.h> 添加到 pch.h。
    4. 现在 co_await wil::resume_foreground(your_dispatcherqueue);。