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

  • 项目

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

重要链接：

最新稳定通道版本：

下载 Windows App SDK

注意

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

版本 1.0.4

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

Bug 修复 (1.0.4)

  • 修复了导致用作 Page.TopAppBar 或 Page.BottomAppBar 的 AppBars 不在屏幕上呈现的问题。
  • 修复了包名称不超过 12 个字符的、使用 MUXControls.dll 中的 WinUI 控件的应用立即崩溃的问题。 有关详细信息，请参阅 GitHub 上的问题 6360。
  • 修复了导致键盘快捷方式和其他方案出现问题的触摸输入问题。 有关详细信息，请参阅 GitHub 上的问题 6291。
  • 修复了导致使用 MSIX 打包的应用或作为独立应用部署的应用无法部署的问题。
  • 修复了在拖放操作期间导致应用有时崩溃的问题。 有关详细信息，请参阅 GitHub 上的问题 7002。

版本 1.0.3

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

Bug 修复 (1.0.3)

  • 修复了在未安装 C/C++ Runtime (CRT) 的情况下导致带有 WebView2 的 C# 应用在启动时崩溃的问题。
  • 修复了导致键盘快捷方式和其他方案出现问题的触摸输入问题。 有关详细信息，请参阅 GitHub 上的问题 6291。

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

版本 1.0.2

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

Bug 修复 (1.0.2)

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

版本 1.0.1

这是 Windows App SDK 的服务版本，其中包含针对版本 1.0 的关键 bug 修复和多窗口支持。

Bug 修复 (1.0.1)

  • 修复了导致 MddBootstrapAutoinitializer 无法使用已启用的 ImplicitUsings 进行编译的问题。 有关详细信息，请参阅 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 App SDK 的本机用户体验 (UX) 框架。 在此版本中，我们添加了多种来自 Windows App SDK 0.8 的新功能，并稳定了 1.0 预览版中的问题。

新功能和更新：

  • 我们添加了新控件（PipsPager、Expander、BreadcrumbBar）并更新了现有控件，以反映 WinUI 2.6 中的最新 Windows 样式。
  • 通过使用“打包的空白应用...”模板来创建新应用程序，WinUI 中支持单项目 MSIX 打包。
  • 我们现在支持在 Windows 1809 及更高版本上部署未打包的 WinUI 3 应用。 有关更多信息，请查看创建第一个 WinUI 3(Windows App 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 App 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。
    • C++ Windows 运行时组件中不支持 Pack 命令以创建 NuGet 包。

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

窗口化

Windows App SDK 提供了一个 AppWindow 类，该类改进了以前发布的易于使用的 Windows.UI.WindowManagement.AppWindow 预览版类，使其可用于所有 Windows 应用（包括 Win32、 WPF 和 WinForms）。

新功能：

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

有关详细信息，请参阅管理应用窗口(Windows App SDK)。

Input

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

新功能：

重要限制：

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

应用生命周期

UWP 平台中已经存在大多数应用生命周期功能，并已将其引入 Windows App SDK 以供桌面应用类型使用，特别是未封装的主机应用、Win32 应用、Windows 窗体应用和 WPF 应用。 这些功能的 Windows App SDK 实现不能在 UWP 应用中使用，因为 UWP 平台本身中存在等效功能。

重要

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

非 UWP 应用也可以打包到 MSIX 包中。 虽然这些应用可以使用某些 Windows App SDK 应用生命周期功能，但必须使用可用的清单方法。 例如，无法使用 Windows App SDK RegisterForXXXActivation API，而必须改为通过清单注册丰富激活。

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

重要注意事项：

已知问题：

  • 在设置 Verb 处理程序的命令行模板时，文件类型关联将 %1 错误地编码为 %251，这会导致未打包的 Win32 应用崩溃。 可以手动将注册表值编辑为 %1，作为部分解决方法。 如果目标文件路径中具有空格，则它仍将失败，并且没有针对该方案的解决方法。
  • 这些单/多实例化 bug 将在即将推出的服务修补中得到修复：
    • 针对 x86 进行编译时，AppInstance 重定向不起作用
    • 注册密钥，取消注册，然后重新注册会导致应用崩溃

DWriteCore

DWriteCore 是 DirectWrite 的 Windows App SDK 实现（它是用于高质量文本呈现、与分辨率无关的大纲字体以及完整的 Unicode 文本和布局支持的 DirectX API）。 DWriteCore 是 DirectWrite 的一种形式，可在低至 Windows 10 版本 1809（10.0；内部版本 17763）的各种 Windows 版本上运行，并为跨平台使用它奠定了基础。

功能：

DWriteCore 包含 DirectWrite 的所有功能，但有几个例外。

重要限制：

  • DWriteCore 不包含以下 DirectWrite 功能：
    • 每会话字体
    • 最终用户定义的字符 (EUDC) 字体
    • 字体流式处理 API
  • 部分支持低级呈现 API。
  • DWriteCore 不会与 Direct2D 互操作，但你可以使用 IDWriteGlyphRunAnalysis 和 IDWriteBitmapRenderTarget。

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

MRT Core

MRT Core 是新式 Windows 资源管理系统的简化版本，作为 Windows App 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 App SDK 的访问。
  • 只有完全信任或具有 packageManagement 受限功能的 MSIX 应用包才有权使用部署 API 来安装主包和单独包依赖项。 对部分信任打包音乐的支持将在后面的版本中推出。
  • 当 F5 在 x64 系统上测试使用 DeploymentManager.Initialize 方法的 x86 应用时，请确保首先通过运行 WindowsAppRuntimeInstall.exe 安装 x64 框架。 否则，由于 Visual Studio 未部署 x64 框架（通常通过应用商店部署或旁加载发生），你将遇到 NOT_FOUND 错误。

其他限制和已知问题

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

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

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

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

  • 安装多个版本的 2019 Visual Studio 时，后续语言 VSIX 未能安装到 Visual Studio 2019 中。 如果安装了多个版本的 Visual Studio 2019（例如发行版和预览版），然后安装适用于 C++ 和 C# 的 Windows App 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);。