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 2019Visual 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 应用程序或组件时,必须指定所需的体系结构:x86x64arm64

  • 使用 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,因为这些方法始终会成功。
  • GetWindowIdFromWindowGetWindowFromWindowId 不再需要 C# ImportDll 调用。 请改用 Microsoft.UI.Win32Interop 类中提供的 .NET 包装器方法。

重要限制

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

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

输入

新更新

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

重要限制

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

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 应用程序或组件时,必须指定所需的体系结构:x86x64arm64

  • 使用 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 应用程序或组件时,必须指定所需的体系结构:x86x64arm64

  • .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 不支持未打包的应用:应在下一版本中解决此情况。