了解不同的 WebView2 SDK 版本

  • 项目

WebView2 SDK 作为 Microsoft.Web.WebView2 NuGet 包的预发行版或发布版本提供。 将预发布 SDK 与 Microsoft Edge 的预览频道配合使用，或者将发布 SDK 与 WebView2 运行时配合使用。

预发行版 如果要在将最新的 WebView2 API（包括实验 API）添加到运行时之前测试最新的 WebView2 API，SDK 包可在开发期间使用。 建议使用 Canary 通道，因为它具有最新 API 的实现。 如果要测试和使用实验 WebView2 API，请使用以下组合：

  • WebView2 SDK 的 预发行版 。
  • 开发客户端上的 Microsoft Edge 预览频道 。

释放 SDK 包仅包含稳定 API，不包含实验 API。 处理 WebView2 应用的生产版本时，请使用以下组合：

  • WebView2 SDK 的 发布 版本。
  • 开发客户端上的 WebView2 运行时 。

下面提供了有关预发行 SDK 包和发布 SDK 包的更多详细信息。

引入 API 的阶段

新 API 按如下所示分阶段引入：

API 状态 说明
实验 1. 首先，API 是预发布 SDK 中的实验性 API。 可以测试这些 API 并提供反馈。 该 API 尚未在发布 SDK 中。
在预发布 SDK 中稳定 2.然后，在预发行版 SDK 中将 API 提升为 Stable。 该 API 尚未在发布 SDK 中。
在发布 SDK 中稳定 3.然后，将稳定 API 提升为包含在发布 SDK 中。 这通常在预发布 SDK 中将 API 提升为稳定版 1 个月后发生。 API 也保留在预发布 SDK 中。

引入新 API 的阶段关系图

选择要使用的 SDK 类型

若要选择 Visual Studio 项目使用的 WebView2 SDK NuGet 包版本，请在 Visual Studio 中右键单击项目，选择“ 管理 NuGet 包”，选中或清除“ 包括预发行版 ”复选框，选择 Microsoft.Web.WebView2 包，然后在“ 版本 ”下拉列表中选择 Microsoft.Web.WebView2 NuGet 包的版本。

有关详细信息，请参阅 为 WebView2 设置开发环境中的安装或更新WebView2 SDK。 还可以在 NuGet 站点上查看 Microsoft.Web.WebView2 SDK 包的列表。

使用 SDK 的预发行版本以及 Microsoft Edge 的预览频道

开发 Evergreen WebView2 应用时，除了针对 WebView2 运行时进行测试外，还定期针对最新的 Microsoft Edge 预览通道测试应用。 由于 Web 平台不断发展，因此定期测试是确保应用继续按预期工作的最佳方式。

使用 WebView2 预发布 SDK 包时，请在开发客户端上使用 Microsoft Edge 预览通道。 预览频道也称为 预览体验成员 频道。 建议使用 Canary 预览版通道，而不是 Beta 版或开发版，因为 Canary 是最新的，并且具有最新实验 API 的实现。

预发布 SDK 包是发布 SDK 包的超集。 预发布 SDK 包含用于：

  • 实验性 API。
  • 已不是实验性的稳定 API，但尚未包含在发布 SDK 中。
  • 已添加到发布 SDK 的稳定 API。

Microsoft Edge 的预览通道提供实验 WebView2 API 和稳定 API 的实现。 实验性 API 可能会根据反馈进行更改。 避免使用预发布 SDK 包来生成生产应用。

有关暂时将应用指向预览通道而不是默认为 WebView2 运行时的信息，请参阅 测试即将推出的 API 和功能。

将 SDK 的发布版本与运行时一起使用

使用 WebView2 发布 SDK 包时，请在开发客户端上使用 WebView2 Evergreen Runtime ，而不是 Microsoft Edge 预览通道。 默认情况下，WebView2 应用面向运行时，而不是 Microsoft Edge。 根据设计，Microsoft Edge 稳定通道不支持 WebView2。

发布 SDK 包包含所有处于生产版本的稳定 Win32 C/C++ 和 .NET API，不包括实验 API 的方法签名。 在 WebView2 运行时的相同或更高的内部版本号中，完全支持发布 SDK 包中的所有 API。

发布 SDK 包包含以下组件：

有关自动更新 Evergreen 运行时的详细信息，请参阅 分发应用和 WebView2 运行时。

发布节奏

新版本的 WebView2 SDK 以与 Microsoft Edge 浏览器相同的常规节奏发布，大约每四周一次。

用于实例化 WebView2 的最低版本和内部版本号

要使客户端能够创建 WebView2 实例并使用 WebView2 正式发布版 (SDK 版本 616) 中的 API 集，客户端必须具有 WebView2 运行时版本 86.0.616.0 或更高版本。 运行时 86.0.616.0 是一个特殊版本，因为它是正式版。

在开发计算机上，客户端必须具有 Microsoft Edge 预览通道版本 86.0.616.0 或更高版本，或者 WebView2 运行时版本 86.0.616.0 或更高版本。

API 向前兼容性

自版本 1 (WebView2 SDK) 的存档发行说明中发布 SDK 1.0.622.22 以来， WebView2 发布 SDK 一直向前兼容。 可以更新 WebView2 应用，以使用 SDK 最新版本中的最新 API。 应用将继续在客户端上运行，因为客户端自动具有最新的 WebView2 Evergreen 运行时。

发布 SDK 包中的 WebView2 API 稳定且向前兼容。 使用与引入 API 的 SDK 内部版本号相等或更高的 WebView2 运行时时，WebView2 API 有效。 内部版本号是 Webview2 SDK 的四部分版本号的第三部分，也是 Microsoft Edge 和 WebView2 运行时的四部分版本号的第三部分。

  • 使用内部版本号 等于或小于 WebView2 运行时的 WebView2 SDK 时，在该 SDK 中有权访问的每个 API 都适用于该版本的运行时。

  • 使用内部版本号 大于 WebView2 运行时的 WebView2 SDK 时，较新的 API 实现在运行时中不可用。

例如，如果在 SDK 1.0 中引入了 API。900.0，该 API 适用于 Runtime 94.0。900+.0，但不适用于 Runtime 90.0。700.0。

必须协调用于开发的 WebView2 SDK 版本和安装在客户端计算机上的 WebView2 运行时版本。 客户端应具有运行时版本，该版本支持用于开发应用的 SDK 版本中的所有最新 API。 若要完全支持 SDK 发行版中的最新 API，客户端上的运行时必须具有大于或等于 SDK 内部版本号的内部版本号。

实验性 API

若要尝试即将推出的正在开发的新功能，请使用 实验 API。 实验性 API 包含在预发布 SDK 中，但不包含在发布 SDK 中。

使用实验 API 进行开发并提供反馈

WebView2 预发布 SDK 包中的实验性 API 不能保证向前兼容，并且可能会在将来的运行时更新中删除。

若要完全支持实验 API，请使用 Microsoft Edge 预览通道，而不是 WebView2 Evergreen Runtime。 当 WebView2 SDK 的预发布版本最初可用时，该 SDK 仅适用于 Microsoft Edge Canary。 不久之后，预发行版 SDK 也适用于 Beta 和开发频道。

使用预发布 SDK 尽早试用新的实验 API，并在实验 API 提升为稳定、向前兼容的 API 之前提供反馈。

  • 预发布 SDK) 中 (实验 API 不保证向前兼容。
  • 预发布 SDK 中的稳定 API 是向前兼容的，即使它们尚未包含在发布 SDK 中。
  • 发布 SDK 中的稳定 API 向前兼容。

有关详细信息，请参阅上面的 API 向前兼容性。

WebView2 团队正在寻求有关实验性 WebView2 API 的反馈，这些 API 可能在将来的版本中提升为稳定版。 在 WebView2 SDK 参考文档中，实验 API 指示为“实验性”，例如：“注意：这是预发行版 SDK 附带的实验性 API。

为了帮助你评估实验 API 并共享反馈，请使用 WebView2Feedback 存储库。

从实验 API 迁移到稳定 API

将 API 从“试验”状态移动到“稳定”状态后，需要将应用代码移动到“稳定 API”。 不建议对生产应用使用实验 API 或预发行 SDK。 在将应用从使用实验 API 迁移到使用稳定 API 时，请遵循以下做法：

  • 在 Visual Studio 的项目中，将 WebView2 SDK 包版本更新为较新的预发布 SDK 或发布 SDK。 请参阅 为 WebView2 设置开发环境中的安装或更新 WebView2 SDK。

  • 更新应用的代码，以使用稳定 API 而不是适用于 COM) 的实验 API (。 Bug 修复将支持稳定 API，但实验 API 将被弃用，在较新的 (预发行版或发布) SDK 中不可用。 将 API 提升为稳定版后，处于已弃用状态的两个预发布 SDK 版本支持该 API 的实验版本。 在后续版本的预发布 SDK 中，可能会修改、删除或添加实验 API。

  • 始终使用功能检测，以确保稳定 API 在用户的 WebView2 运行时版本中实现。 请参阅下面的 功能检测以测试已安装的运行时是否支持最近添加的 API。

  • 仅限 .NET 的注意事项：在预发布 WebView2 SDK 中，如果用户的 WebView2 运行时只有实验 API 实现且没有稳定 API 实现，则 .NET 稳定 API 将回退到相应的实验 API。

将运行时版本与 SDK 版本匹配

在 Evergreen 分发方法中，客户端的 WebView2 运行时会自动更新到可用的最新版本。 但是，用户或 IT 管理员可能会选择阻止自动更新 WebView2 运行时。 客户端上生成的过时运行时可能会导致更新的 WebView2 应用（使用最新 SDK 中的新 API）出现兼容性问题。

如果在客户端上阻止更新 WebView2 运行时，请确保知道应用所需的 WebView2 运行时的最小内部版本号。 若要查看或获取最新的 WebView2 运行时版本，请参阅 developer.microsoft.com 中的 Microsoft Edge WebView2 页下载 WebView2运行时。 支持 SDK (版本 616) 正式发布版所需的最低运行时版本早于最新运行时。 最新运行时支持最新版本 SDK 中的所有 API。

若要检查 SDK 的特定内部版本号与运行时或 Microsoft Edge 预览通道之间的兼容性，请参阅 WebView2 SDK 的发行说明。

用于测试已安装的运行时是否支持最近添加的 API 的功能检测

如果应用使用 Evergreen 运行时而不是固定版本，则应使用 QueryInterface 或 try-catch包装对相对较新的 WebView2 API 的任何调用。 在某些情况下，客户端的 Evergreen Runtime 不是最新版本，因此落后于 SDK 内部版本号，因为管理员可能已关闭 WebView2 运行时的更新，或者客户端可能处于脱机状态。

使用最新版本的 WebView2 SDK 开发 WebView2 应用时，如果使用最近添加的 API，则应测试或“功能检测”客户端安装的 WebView2 运行时中是否存在该 API。 应用如何以编程方式测试 API 支持，具体取决于编码平台。

  • Win32 C/C++。 请求 DLL 导出CreateCoreWebView2Environment并在任何CoreWebView2对象上运行时QueryInterface，请测试返回值E_NOINTERFACE。 该返回值可能指示客户端的 WebView2 运行时是不支持该接口的旧版本。

    有关检查运行时中是否存在特定 WebView2 API 的示例，请在 AppWindow.cpp 中找到try_query。 此文件将 WebView2 API 调用包装在 CHECK_FAILURE 中定义的宏函数中 CheckFailure.h。

  • .NET 和 WinUI。 使用添加到最新版本的 WebView2 SDK 的方法、属性和事件时，使用try/catch和检查No such interface supported异常。 此异常可能表示客户端的 WebView2 运行时是不支持该 API 的旧版本。

如果代码确定 API 在客户端安装的 WebView2 运行时中不可用，则应为关联的功能提供正常回退，或通知用户必须更新 WebView2 运行时才能使用该功能。

此技术在测试已安装的 WebView2 运行时是否支持 API 中列为 WebView2 开发最佳做法。