Windows 应用 SDK 的预览通道版本说明

  • 项目

重要

预览通道不支持在生产环境中使用，并且无法将使用预览版本的应用发布到 Microsoft Store。

预览通道提供了即将推出的稳定版本的预览。 在给定的预览通道版本和下一个稳定版本之间，可能会存在中断性的 API 变更。 预览通道版本不包含实验性 API。

重要链接：

版本 1.1 预览版 3 (1.1.0-preview3)

这是版本 1.1 的预览频道的最新版本。 它支持所有预览频道功能， (请参阅 发布频道) 提供的功能 。

在使用 Windows 应用 SDK 1.0 Stable 的现有应用中，可以将 Nuget 包更新为 1.1.0-preview3 (请参阅使用 NuGet 程序包管理器) 在 Visual Studio 中安装和管理包的“更新”部分。 此外，请参阅更新的运行时和 MSIX Windows 应用 SDK的下载。

注意

对于 C# 开发人员，以下 .NET SDK 版本之一 (或更高版本) 是必需的：6.0.202、6.0.104、5.0.407、5.0.213。 若要更新 .NET SDK 版本，请访问 .NET 下载或更新到最新版本的 Visual Studio。 如果没有所需的 .NET SDK 版本，更新NuGet包时，会出现如下错误：“此版本的 WindowsAppSDK 需要WinRT.Runtime.dll版本 1.6 或更高版本。

除了所有 预览版 2 功能之外，以下部分还介绍了此版本的新增功能和更新的功能、限制和已知问题。

WinUI 3

Mica 和 Background Acrylic 现已可用于 WinUI 3 应用程序。

有关这些材料的详细信息，请查看Windows 11中的材料。 查看在将 SystemBackdropController 与 WinUI 3 XAML 配合使用时在 C++ 应用程序中应用 Mica 的示例代码，以及作为 WinUI 控件库的一部分在 GitHub 上的 C# 应用程序中应用 Mica 的示例代码。

通知

已解决的问题：

  • 在 1.1.0-preview1 和 1.1.0-preview2 中，某些未打包的应用图标将错误地复制到 AppData\LocalMicrosoftWindowsAppSDK。 对于此版本，它们将改为复制到 AppData\Local\Microsoft\WindowsAppSDK。 若要避免泄露图标，应在更新到 1.1.0-preview3 后，在错误路径上手动删除应用图标。
  • 现在支持通过快捷方式检索应用通知的应用图标和应用显示名称。 此应用图标将优先于资源文件中指定的任何图标。
  • 已还原对未打包应用的推送通知的支持， (请参阅) 指出的异常 限制 。 我们引入了 PushNotificationManager：：IsSupported API，以检查应用是否支持推送通知。

限制：

  • 不支持 提升 的未打包应用的通知。 PushNotificationManager：：IsSupported 不会对提升的模式执行检查。 但是，我们正在努力在将来的版本中支持此功能。

MSIX 打包

我们已通过扩展类别增强了 MSIX 添加新功能和扩展现有功能：

  • windows.appExecutionAlias
  • windows.customDesktopEventLog
  • windows.dataShortcuts
  • windows.fileTypeAssociation
  • windows.fileTypeAssociation.iconHandler
  • windows.folder
  • windows.shortcut

这些要求安装Windows 应用 SDK框架包。 请参阅Windows 应用 SDK下载以安装运行时。

环境管理器

API 集允许开发人员添加、删除和修改环境变量，而无需直接使用注册表 API。

1.1 预览版 1 中的说明：卸载已使用环境管理器的应用仅适用于打包的应用时，自动删除任何环境变量更改。 此外，还原环境变量更改需要安装Windows 应用 SDK框架包，请参阅运行时的Windows 应用 SDK下载。

其他已知限制

1.1 预览版 2 的回归：

  • 对于未使用单项目 MSIX 部署的 MRT Core API 和 WinUI 应用的 .NET 应用：
    • 作为现有项添加到项目的 RESW 和图像文件，并且以前自动包含在 PRIResource 和 Content ItemGroups 中，不会分别包含在这些 ItemGroup 中。 因此，这些资源不会在 PRI 生成期间编制索引，因此它们在运行时不可用。
      • 解决方法：手动将资源包含在项目文件中，并将其从 None ItemGroup 中删除。
      • 替代解决方法：可用时，请将应用的 .NET SDK 升级到 6.0.300。 有关其他 信息，请参阅 .NET SDK 的版本要求 。
  • 对于不使用单项目 MSIX 部署 的 .NET 应用：
    • 如果将文件添加到 Content ItemGroup 两次或更多，则会出现生成错误。
      • 解决方法：删除重复的包含/s 或在项目文件中将 EnableDefaultContentItems 设置为 false。

这两个回归将在下一个稳定版本中还原。

版本 1.1 预览版 2 (1.1.0-preview2)

这是版本 1.1 的第二个预览频道版本。 它支持所有预览频道功能， (请参阅 发布频道) 提供的功能 。

在使用 Windows 应用 SDK 1.0 Stable 的现有应用中，可以将 Nuget 包更新为 1.1.0-preview2 (，请参阅使用 NuGet 程序包管理器) 在 Visual Studio 中安装和管理包的“更新”部分。 此外，请参阅更新的运行时和 MSIX Windows 应用 SDK的下载。

注意

对于 C# 开发人员，以下 .NET SDK 版本之一 (或更高版本) 是必需的：6.0.202、6.0.104、5.0.407、5.0.213。 若要更新 .NET SDK 版本，请访问 .NET 下载或更新到最新版本的 Visual Studio。 如果没有所需的 .NET SDK 版本，更新NuGet包时，会出现如下错误：“此版本的 WindowsAppSDK 需要WinRT.Runtime.dll版本 1.6 或更高版本。

除了所有 预览版 1 功能之外，以下部分还介绍了此版本的新增功能和更新的功能、限制和已知问题。

通知

已解决的问题：

  • 如果图标是应用资源的一部分，则没有包标识发送通知的应用现在会在通知中看到其应用图标。 如果应用资源没有图标，则使用Windows默认应用图标。
  • 现在，无法运行的 WinUI 3 应用现在可以通过通知进行后台激活。

从 1.1 预览版 1 回归： 推送通知支持未打包的应用。 预期在下一个版本中还原。

已知限制：

  • 我们引入了 PushNotificationManager：：IsSupported API，以检查自包含应用是否支持推送通知。 但是，此 API 尚未按预期工作，因此请关注下一个预览版，以获取 IsSupported API 的完全支持。
  • 某些未打包的应用将看到其应用图标错误地复制到 AppData\LocalMicrosoftWindowsAppSDK。 对于下一个版本，它们将改为复制到 AppData\Local\Microsoft\WindowsAppSDK。 为了避免泄露图标，开发人员应在升级到下一个版本后，在错误的路径上手动删除其应用图标。
  • 不支持通过快捷方式检索通知的应用图标和应用显示名称。 但我们正在努力在将来的版本中支持这一点。

部署

新功能：

已知限制：

  • 仅在 Windows 10、1903 及更高版本上支持自包含部署。

窗口化

为了更轻松地对 (中USER32.dll实现的功能进行编程访问，请参阅Windows和消息) ，此版本在 AppWindow 本身中呈现了更多功能。

新功能：

  • 具有现有窗口的应用通过调用 AppWindow.ShowOnceWithRequestedStartupState（等效 ShowWindow(SW_SHOWDEFAULT)）可以更好地控制窗口的显示方式。
  • 应用可以显示、最小化或还原窗口，并指定在调用时是否应激活该窗口。
  • 应用现在可以在 Win32 坐标中设置窗口的工作区大小。
  • 我们添加了 API 以支持 Windows 的 z 顺序管理。
  • 使用 AppWindowTitleBar.ExtendsContentIntoTitleBar 绘制自定义标题栏的应用可以设置 PreferredTitleBarHeight 选项。 可以选择 标准高度 标题栏或 高 标题栏，为交互式内容提供更多空间。 有关何时使用高标题栏的建议，请参阅Fluent设计指南中的标题栏。

已知限制：

  • 高标题栏支持仅适用于Windows 11。 我们正在努力将此级别与其他自定义标题栏 API 一起降低。

WinUI 3

修复了以下问题：

  • 修复了将 WebView2 SDK 从 1020.46 升级到 1185.39，导致 C/C++ 运行时 (CRT) 时启动 C# 应用崩溃的问题。
  • 修复了导致某些圆角在应为纯色时显示渐变的问题。 有关详细信息，请参阅GitHub上的问题 6076&问题 6194。
  • 修复了 generic.xaml 中缺少更新样式的问题。
  • 修复了在滚动到 ListView 末尾时导致应用崩溃的布局周期问题。 有关详细信息，请参阅有关GitHub的问题 6218。

性能

C# 应用程序具有多项性能改进。 有关详细信息，请参阅 C#/WinRT 1.6.1 发行说明。

版本 1.1 预览版 1 (1.1.0-preview1)

这是版本 1.1 的预览频道的第一个版本。 它支持所有预览频道功能 (请参阅 发布频道) 提供的功能 。

在使用 Windows 应用 SDK 1.0 Stable 的现有应用中，可以使用 NuGet 程序包管理器) 将 Nuget 包更新到 1.1.0-preview1 (请参阅“在Visual Studio中安装和管理包”部分中的“更新包”部分。 此外，请参阅更新的运行时和 MSIX Windows 应用 SDK的下载。

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

WinUI 3

已知问题：启用拖放后，用户无法删除元素。

提升的 (管理员) 支持

使用 Windows 应用 SDK 1.1 预览版 1， (包括 WinUI 3) 的应用将能够使用提升的权限运行。

重要限制

  • 目前仅在Windows 11上可用。 但我们正在评估在更高版本中降低这种支持水平。

已知问题

  • 在拖放交互期间拖动元素时，WinUI 3 应用崩溃。

独立部署

Windows 应用 SDK 1.1 将引入对独立部署的支持。 我们的 部署概述 详细介绍了依赖于框架的部署和独立部署之间的差异，以及如何入门。

已知问题：

  • MSIX 打包的 C++ 应用需要将其添加到项目文件的底部，以解决自包含 .targets 文件中的 bug，该 bug 会删除对 VCLibs 的框架引用：

    <PropertyGroup>
    <IncludeGetResolvedSDKReferences>true</IncludeGetResolvedSDKReferences>
</PropertyGroup>

<Target Name="_RemoveFrameworkReferences"
    BeforeTargets="_ConvertItems;_CalculateInputsForGenerateCurrentProjectAppxManifest">
    <ItemGroup>
        <FrameworkSdkReference Remove="@(FrameworkSdkReference)" Condition="'%(FrameworkSdkReference.SDKName)' == 'Microsoft.WindowsAppRuntime.1.1-preview1'" />
    </ItemGroup>
</Target>

  • 仅在 Windows 10、1903 及更高版本上受支持

通知

MSIX 打包、稀疏打包和未打包应用的开发人员现在可以发送Windows通知。

新功能：

  • 支持打包和解压缩应用的应用通知。 有关GitHub的完整详细信息
    • 开发人员可以在本地或自己的云服务中发送应用通知，也称为 Toast 通知。
  • 支持打包和解压缩应用的推送通知。 有关GitHub的完整详细信息
    • 开发人员可以从自己的云服务发送原始通知或应用通知。

限制：

  • 作为独立应用发布的应用可能没有推送通知支持。 请留意 IsSupported () API 的下一个预览版，以检查推送通知支持。
  • 非 MSIX 打包发送应用通知的应用将不会在应用通知中看到其应用图标，除非它们是控制台应用程序。 非 MSIX 打包的控制台应用应遵循 ToastNotificationsDemoApp 示例中所示的模式。
  • 必须安装Windows 应用 SDK运行时才能支持推送通知，请参阅安装程序的Windows 应用 SDK下载。
  • 未运行的 WinUI 3 应用无法通过通知进行后台激活。 但我们正在努力在将来的版本中支持这一点。

环境管理器

API 集允许开发人员添加、删除和修改环境变量，而无需直接使用注册表 API。

新功能

  • 在卸载已使用环境管理器的应用时，自动删除任何环境变量。

限制

  • C# 应用中当前不可用。 但我们正在评估在更高版本中将此功能引入 C# 应用。

其他限制和已知问题

  • 如果使用 C# 和 1.1.0 预览版 1，则必须至少使用以下 .NET SDK 版本之一：.NET SDK 6.0.201、6.0.103、5.0.212 或 5.0.406。 若要升级 .NET SDK，可以更新到最新版本的 Visual Studio，或访问下载 .NET。

版本 1.0 预览版 3 (1.0.0-preview3)

预览版 3 是适用于 1.0 版 Windows 应用 SDK 的通道最新预览版。 预览版 3 支持所有预览通道功能。

(VSIX) 下载 1.0 预览版 3 Visual Studio 扩展

注意

如果已安装 Windows 应用 SDK Visual Studio (VSIX) 扩展，则在安装新版本之前卸载这些扩展。 有关说明，请参阅管理 Visual Studio 的扩展。

可以从下表中下载 1.0 预览版 3 版本的 Visual Studio 扩展 (VSIX)。 对于所有版本，请参阅 Windows 应用 SDK 的下载。 如果尚未这样做，请先使用安装工具中的Windows 应用 SDK步骤配置开发环境。

以下扩展适用于编程语言和 Visual Studio 版本。

1.0 预览版 3 下载 说明
C# Visual Studio 2019 扩展 使用 Windows 应用 SDK Visual Studio 2019 扩展生成 C# 应用。
C++ Visual Studio 2019 扩展 使用 Windows 应用 SDK Visual Studio 2019 扩展生成 C++ 应用。
C# Visual Studio 2022 扩展 使用 Windows 应用 SDK Visual Studio 2022 扩展生成 C# 应用。
C++ Visual Studio 2022 扩展 使用 Windows 应用 SDK Visual Studio 2022 扩展生成 C++ 应用。
.exe 安装程序，和 MSIX 包 使用 .exe 安装程序和 MSIX 包将 Windows 应用 SDK 部署到应用。

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

WinUI 3

我们现在支持部署 WinUI 3 应用，而无需 MSIX 打包。 请参阅 创建第一个 WinUI 3 项目以配置 WinUI 3 应用程序以支持未打包的部署。

重要限制

  • 仅 Windows 版本 1909 及更高版本支持未打包的 WinUI 3 应用程序。
  • x86 和 x64 支持未打包的 WinUI 3 应用程序；下一个稳定版本将添加 arm64 支持。
  • 对于未打包的应用程序，Visual Studio 2019 或 Visual Studio 2022 的单项目 MSIX 打包工具是必需的。
  • 在未打包的应用中，你可能会收到安装 .NET 3.5 的提示；如果已这样做，则可以将其忽略。
  • 某些 API 目前在未打包的应用中不受支持。 我们将在下一个稳定版本中修复此问题。 一些示例：
  • ListView、CalendarView 和 GridView 控件使用的样式不正确，我们将在下一个稳定版本中修复此问题。

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

其他限制和已知问题

  • Windows 10 版本 1809 不支持未打包的应用。 我们将在稳定通道的下一版本中修复此问题。

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

  • 此版本引入了适用于 C# 和 C++ 的打包的空白应用（桌面版 WinUI 3）项目模板。 使用这些模板，无需使用单独的打包项目，即可将应用生成到 MSIX 包中（请参阅使用单项目 MSIX 打包应用）。 在此版本中，这些模板有一些已知问题：

    • 在重新启动 Visual Studio 之前，缺少发布菜单项。 当使用“打包的空白应用（桌面版 WinUI 3）”项目模板在 Visual Studio 2019 和 Visual Studio 2022 中创建新应用时，关闭并重新打开 Visual Studio 之前，将不会在菜单中显示用于发布项目的命令。

    • 使用单项目 MSIX 打包向 C++ 应用添加 C++ 静态/动态库项目引用时出错。 Visual Studio 显示错误消息，指出由于项目类型不兼容，无法将项目添加为引用。

    • 引用类库项目中的自定义用户控件时出错。 如果系统找不到指定的路径，应用程序将崩溃并出现错误。

    • 用于 Visual Studio 2019 的 C# 或 C++ 模板。 当尝试生成项目时，将遇到“项目不知道如何运行配置文件项目名称”的错误。 若要解决此问题，请安装单项目 MSIX 打包工具扩展。

    • 适用于 2019 Visual Studio 和 2022 Visual Studio 的 C# 模板。 在 Visual Studio 中，当“开始调试”或“启动而不调试”时，如果应用未部署并运行（并且没有来自 Visual Studio 的反馈），请单击“解决方案资源管理器”中的项目节点将其选中，然后重试。

    • 适用于 2019 Visual Studio 和 2022 Visual Studio 的 C# 模板。 在开发计算机上尝试运行或调试项目时，会遇到以下错误：“需要先部署项目，然后才能进行调试。 请在配置管理器中启用部署。若要解决此问题，请在“配置管理器”中为项目启用部署。 有关详细说明，请参阅 创建第一个 WinUI 3 项目。

    • 适用于 Visual Studio 2022 版本 17.0（版本最高可达预览版 4）的 C++ 模板。 首次尝试运行项目时，将遇到以下错误：“存在部署错误”。 若要解决此问题，请再次运行或部署项目。 此问题将在 Visual Studio 2022 版本 17.0 预览版 7 中得到修复。

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

  • 使用 1.0 预览版 3 的 C# 项目必须使用以下 .NET SDK：.NET 6 SDK 或更高版本 (请参阅 下载 .NET 和 .NET 5 将于 2022 年 5 月 10 日结束支持) 。

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

    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);。

影响 1.0 预览版 1 和预览版 2 的重要问题

Windows 应用 SDK 的 1.0 版预览版 1 和预览版 2 包含一种机制，可用于清理打包应用在卸载该应用时所做的任何环境变量更改。 此功能处于实验状态，第一个版本包含可能损坏系统“PATH”环境变量的已知 bug。

预览版 1 和预览版 2 损坏了包含扩展字符 % 的任何“PATH”环境变量。 每当卸载任何打包应用时，无论该应用是否使用 Windows 应用 SDK，都会发生这种情况。

另请参阅PATH 环境变量损坏问题。

详细信息

系统“PATH”项存储在 Windows 注册表中以下项的“路径”值中：

Computer\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Environment

如果启动注册表编辑器 （regedit.exe），则可以将上面的路径复制并粘贴到痕迹导航栏（菜单栏正下方）中，然后按 Enter 键找到该项。

该键的“Path”值应该为“REG_EXPAND_SZ”类型，但 Bug 会将其更改为“REG_SZ”。 这会使系统“PATH”环境变量在包含变量扩展字符 % 时不可用。

受影响的版本

缓解措施

若要使计算机恢复为良好状态，请执行以下步骤：

  1. 检查注册表中的“PATH”是否已损坏，如果是，请运行以下脚本来重置它。

    可以使用以下 Windows PowerShell 脚本完成步骤 1（PowerShell Core 将停用）。 以提升权限运行。

    # This script must be run from an elevated Windows PowerShell
# window (right-click Windows PowerShell in the Start menu,
# and select Run as Administrator).

# If the PATH in the Registry has been set to REG_SZ, then delete
# it, and recreate it as REG_EXPAND_SZ.

$EnvPath = 'Registry::HKLM\System\CurrentControlSet\Control\Session Manager\Environment'
$Environment=Get-Item $EnvPath
$PathKind = $Environment.GetValueKind('Path')

if ($PathKind -ne 'ExpandString') {
  $Path = $Environment.GetValue('Path')
  Remove-ItemProperty $EnvPath -Name Path
  New-ItemProperty $EnvPath -Name Path -PropertyType ExpandString -Value $Path
}

  2. 卸载使用 Windows 应用 SDK 1.0 预览版 1 或 预览版 2 的所有应用（请参阅以下脚本）。

  3. 卸载 Windows 应用 SDK 1.0 预览版 1/预览版 2 包，包括包含 bug 的包（请参阅以下脚本）。

    可以使用以下 Windows PowerShell 脚本完成步骤 2 和 3（PowerShell Core 将停用）。 以提升权限运行。

    # This script must be run from an elevated Windows PowerShell
# window (right-click Windows PowerShell in the Start menu,
# and select Run as Administrator).

# Remove the Windows App SDK 1.0 Preview1/2, and all apps that use it.

$winappsdk = "Microsoft.WindowsAppRuntime.1.0-preview*"
Get-AppxPackage | Where-Object { $_.Dependencies -like $winappsdk } | Remove-AppxPackage
Get-AppxPackage $winappsdk | Remove-AppxPackage

修复了 Windows 应用 SDK 1.0 预览版 3 的问题

在即将推出的 Windows 应用 SDK 1.0 预览版 3 中将删除导致“PATH”环境变量损坏的功能。 在修复并全面测试所有 bug 后，几天后可能会再进行更新。

建议使用版本 1.0 预览版 3。

版本 1.0 预览版 2 (1.0.0-preview2)

重要

版本 1.0 预览版 1 和预览版 2 存在严重 bug。 如果已安装其中一个预览版，请参阅如何解决此问题。 建议改为使用版本 1.0 预览版 3。

这是 1.0 版预览版通道的最新版本。 它支持所有预览通道功能。

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

WinUI 3

新更新：

  • 控件已更新，以反映 WinUI 2.6 的最新 Windows 样式。
  • 支持单项目 MSIX。
  • WinUI 3 包现在可以面向内部版本 17763 及更高版本。 有关详细信息，请参阅问题 #921。
  • 支持应用内工具栏。 但是，应用内工具栏和现有的热重载/实时可视化树支持需要即将推出的 Visual Studio 17.0 预览版 5 版本（10 月即将提供）。

Bug 已修复：WebView2Runtime 文本现已本地化。

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

窗口化

此版本引入了 AppWindow 类的更新。 此版本中未添加任何主要新功能，但方法名称、属性发生了更改，并且删除了一些返回值。 有关详细更新，请参阅文档和示例。 如果在 1.0 实验版或 1.0 预览版 1 版本中使用 AppWindow，则代码会进行一些更改。

新更新：

  • AppWindowConfiguration 类已删除。 此类的属性现在可用于 AppWindow 本身或“Presenter”类。
  • 此空间中 WinRT API 方法大多数 bool 返回值已删除，现在为 void，因为这些方法始终会成功。
  • GetWindowIdFromWindow 和 GetWindowFromWindowId 不再需要 C# ImportDll 调用。 请改用 Microsoft.UI.Win32Interop 类中提供的 .NET 包装器方法。

重要限制：

  • Windows 应用 SDK 当前不提供将 UI 框架内容附加到 AppWindow 的方法，只能使用 HWND 互操作访问方法。
  • 窗口标题栏自定义仅适用于 Windows 11。 使用 IsCustomizationSupported 方法检查标题栏自定义功能支持。 我们计划将此功能降级。

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

输入

新更新：

  • 改进了对精度触摸板输入的支持。

重要限制：

  • 已删除所有 PointerPoint静态工厂函数：GetCurrentPoint、GetCurrentPointTransformed、GetIntermediatePoints 及 GetIntermediatePointsTransformed。
  • Windows 应用 SDK 不支持检索具有指针 ID 的“PointerPoint”对象。 相反，可以使用“PointerPoint”成员函数“GetTransformedPoint”，检索现有“PointerPoint”对象的转换版本。 对于中间点，可以使用“PointerEventArgs”成员函数 GetIntermediatePoints 和 GetTransformedIntermediatePoints。 有关更多详细信息，请参阅文档。

MRT 核心

新更新：

  • 应用开发人员现在可以选择不在 .NET 项目的 PRI 文件中为图像文件或 RESW 文件编制索引。 有关详细信息，请参阅问题 980。

重要限制：

  • 在 .NET 项目中，如果已生成应用，则复制粘贴到项目文件夹中的资源文件不会在 F5 上编制索引。 解决方法是重新生成应用。 有关详细信息，请参阅问题 1503]。
  • 在 .NET 项目中，如果不手动设置生成操作，则不会对从外部文件夹添加的现有资源文件编制索引。 若要解决此问题，请在 Visual Studio 中设置生成操作：图像文件的“内容”和 RESW 文件的“PRIResource”。 有关详细信息，请参阅问题 1504。

适用于未打包应用的部署

新增功能：

  • Windows 应用 SDK 1.0 预览版 2 引入了引导程序 API 的 .NET 包装器。 引导程序 API 是一组本机 C/C++ 函数，解包应用必须使用这些函数在运行时动态获取 Windows 应用 SDK 框架包的依赖项。 .NET 包装器提供了一种从 .NET 应用（包括 Windows 窗体和 WPF 应用）调用引导程序 API 的更简单方法。 引导程序 API 的 .NET 包装器在应用项目的本地程序集 Microsoft.WindowsAppRuntime.Bootstrap.Net.dll 中可用。 有关 .NET 包装器详细信息，请参阅 .NET 包装器库。
  • 打包应用现在可以使用部署 API 获取计算机上安装的主和单独 MSIX 包。 主包和单独包是随应用一起安装的框架包的一部分，但由于 Windows 应用程序模型存在限制，打包应用需要执行此附加步骤才能安装这些包。 有关部署 API 工作原理详细信息，请参阅打包应用的部署指南。

重要限制：

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

应用生命周期

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

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

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

重要注意事项：

  • 丰富激活：GetActivatedEventArgs

  • 注册/注销丰富激活

    • 未打包应用：完全可用。
    • 打包应用：不可用，请改用应用的 MSIX 清单。
    • 有关详细信息，请参阅丰富激活。

  • 单/多实例化

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

  • 电源/状态通知

    • 未打包应用：完全可用。
    • 打包应用：完全可用。
    • 有关详细信息，请参阅电源管理。

已知问题：

在设置 Verb 处理程序的命令行模板时，文件类型关联将 %1 错误地编码为 %251，这会导致未打包的 Win32 应用崩溃。 可以手动将注册表值编辑为 %1，作为部分解决方法。 如果目标文件路径中具有空格，则它仍将失败，并且没有针对该方案的解决方法。

其他限制和已知问题

  • 版本 1.0 预览版 1 和预览版 2 存在严重 bug。 如果已安装其中一个预览版，请参阅如何解决此问题。 建议改为使用版本 1.0 预览版 3。

  • 此版本引入了适用于 C# 和 C++ 项目的打包的空白应用（桌面版 WinUI 3）模板。 使用这些模板，无需使用单独的打包项目，即可将应用生成到 MSIX 包中。 在此版本中，这些模板有一些已知问题：

    • 适用于 2019 Visual Studio 的 C# 模板。 当尝试生成项目时，将遇到“项目不知道如何运行配置文件项目名称”的错误。 若要解决此问题，请安装单项目 MSIX 打包工具扩展。

    • 适用于 2019 Visual Studio 和 2022 Visual Studio 的 C# 模板。 在开发计算机上尝试运行或调试项目时，会遇到以下错误：“需要先部署项目，然后才能进行调试。 请在配置管理器中启用部署。若要解决此问题，请在“配置管理器”中为项目启用部署。 有关详细说明，请参阅 创建第一个 WinUI 3 项目。

    • 适用于 2019 Visual Studio 和 2022 Visual Studio 的 C++ 模板。 在此版本中，这些项目仅限于调用 UWP 应用可调用的 Win32 API 子集。 使用 WAP 打包的空白应用（桌面版 WinUI 3）模板不受此问题的影响。

    • 适用于 Visual Studio 2022 版本 17.0（版本最高可达预览版 4）的 C++ 模板。 首次尝试运行项目时，将遇到以下错误：“存在部署错误”。 若要解决此问题，请再次运行或部署项目。 此问题将在 Visual Studio 2022 版本 17.0 预览版 5 中得到修复。

  • 推送通知 API（Microsoft.Windows.PushNotifications.命名空间）错误地包含在 1.0 预览版 2 版本中。 这仍是一项实验性功能，若要使用，则必须改为安装 1.0 实验版。 此功能将从即将推出的 1.0 稳定版中删除。

  • 应用生命周期 API （Microsoft.Windows.AppLifecycle 命名空间）错误地在 1.0 预览版 2 版本中包含实验属性。 下一版本将从此 API 中删除实验性属性。

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

  • 使用 1.0 预览版 2 的 C# 项目必须使用以下 .NET SDK：.NET 6 SDK 或更高版本 (请参阅 下载 .NET 和 .NET 5 将于 2022 年 5 月 10 日结束支持) 。

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

    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);。

版本 1.0 预览版 1 (1.0.0-preview1)

重要

版本 1.0 预览版 1 和预览版 2 存在严重 bug。 如果已安装其中一个预览版，请参阅如何解决此问题。 建议改为使用版本 1.0 预览版 3。

这是 1.0 版预览版通道的首个版本。 它支持所有预览通道功能。

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

WinUI 3

此版本的 WinUI 3 侧重于生成 1.0 稳定版，并修复了 bug。

  • 新功能：预览版 1 中无新功能。
  • 已修复问题：有关此版本中已解决问题的完整列表，请参阅 GitHub 存储库。

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

窗口化

此版本将实验版 1 中引入的窗口 API 引入预览状态。 此版本没有主要新功能领域，因为它侧重于 BUG 修复、稳定性和 API 签名调整。 下面列出了值得注意的更改和附加内容。

新增功能：

  • DisplayAreaWatcher 已添加到窗口 API。 开发人员可以观察显示拓扑中的更改，并枚举系统中当前定义的 DisplayAreas。
  • AppWindow 现在支持通过 SetIcon 方法设置窗口图标，并且 AppWindowTitleBar 现在支持通过 IconShowOptions 属性选择是否显示/隐藏窗口图标以及系统菜单。

重要限制：

  • 此版本的 AppWindow 目前仅适用于（打包和未打包的） Win32 应用。
  • Windows 应用 SDK 当前不提供将 UI 框架内容附加到 AppWindow 的方法，只能使用 HWND 互操作访问方法。
  • 窗口标题栏自定义仅适用于 Windows 11。 使用 IsCustomizationSupported 方法检查标题栏自定义功能支持。 我们计划将此功能降级。

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

输入

此版本为输入 API 带来了一些新功能。 下面列出了值得注意的更改和附加内容。

新功能和更新：

  • PointerPredictor 使输入延迟敏感型应用程序（如墨迹书写应用程序）能够预测输入点位置（最多 15 毫秒），以实现更好的延迟和流畅的动画。
  • 通过使用 FromPointerPoint 方法，PenDeviceInterop 使你能够获取对 Windows.Devices.Input.PenDevice 的引用。
  • InputCursor 通过删除 CoreCursor 中的“自定义”类型，以及将 CoreCursor 对象拆分为单独的对象，在预设的系统游标类型和自定义游标类型之间提供了显式区别。
  • InputCursor API 的更新。
  • GestureRecognizer 从实验版移动到 Microsoft.UI.Input。
  • PointerPoint 从实验版移动到 Microsoft.UI.Input。
  • WinUI 3 拖放完全支持鼠标、触摸和笔输入。

重要限制：

  • 此版本的输入 API 在 Windows 版本 1809 中存在已知问题。
  • InputCursor 的任何子类尚不支持 MRT Core。
  • 直接使用平台 SDK API Windows。UI。Core.CoreDragOperation 不适用于 WinUI 3 应用程序。
  • 删除了 PointerPoint 属性的 RawPosition 和 ContactRectRaw，因为它们引用了非预测值，这与操作系统中的常规值相同。 请改为使用位置和 ContactRect。 指针预测现在通过 PointerPredictor API 对象进行处理。

MRT 核心

从版本 1.0 预览版 1 开始，MRT.LOG Core API 已从Microsoft.ApplicationModel.Resources 命名空间移动到 Microsoft.Windows.ApplicationModel.Resources命名空间。

其他限制和已知问题

  • 版本 1.0 预览版 1 和预览版 2 存在严重 bug。 如果已安装其中一个预览版，请参阅如何解决此问题。 我们建议改用版本 1.0 预览版 3。

  • 默认情况下，使用 C++ 使用 WAP 打包的空白应用（桌面版 WinUI 3）项目模板创建的项目会遇到以下生成错误：fatal error C1083: Cannot open include file: 'winrt/microsoft.ui.dispatching.co_await.h': No such file or directory。 若要解决此问题，请从“pch.h”文件中删除以下代码行。 此问题将在下一版本中修复。

    #include <winrt/microsoft.ui.dispatching.co_await.h>

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

    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);。

  • 不支持任何 CPU 生成配置：Windows 应用 SDK 是用本机代码编写的，因此不支持任何 CPU 生成配置。 Visual Studio中的 WinUI 3 模板仅允许特定于体系结构的生成。 添加 Windows 应用 SDK 到支持任何 CPU 的现有 .NET 应用程序或组件时，必须指定所需的体系结构：x86、x64 或 arm64。

  • .NET 应用必须面向内部版本 18362 或更高版本：TFM 必须设置为 net6.0-windows10.0.18362 或更高版本，并且打包项目的 <TargetPlatformVersion> 必须设置为 18362 或更高版本。 有关详细信息，请参阅 GitHub 上的已知问题。

  • 使用 1.0 预览版 1 的 C# 项目必须使用以下 .NET SDK：.NET 6 SDK 或更高版本 (请参阅 下载 .NET 和 .NET 5 将于 2022 年 5 月 10 日结束支持) 。

  • Windows 10 版本 1809 不支持未打包的应用：应在下一版本中解决此情况。