WebView2 的预发布和发布 SDK

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

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

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

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

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

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

引入 API 的阶段

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

API 状态 说明
预发布 SDK 中的实验性 1. 首先，API 在预发布 SDK 中是实验性的。 (有时，API 会跳过实验阶段，而是直接添加到预发布 SDK 的稳定版中。) 可以测试这些 API 并提供反馈。 API 尚不在发布 SDK 中。
在预发布 SDK 中稳定 2. 然后，API 在预发布 SDK 中提升为稳定版。 API 尚不在发布 SDK 中。
在发布 SDK 中稳定 3. 然后，将稳定 API 提升为包含在发布 SDK 中。 (有时，API 在预发布 SDK 中同时提升为稳定版，并在发布 SDK 中同时提升为稳定版。) 这通常发生在 API 在预发布 SDK 中提升为稳定版 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 的预览频道

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

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

预发布 SDK 包是发布 SDK 包的超集。 预发布 SDK 包含以下内容的方法签名：

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

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

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

另请参阅：

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

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

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

另请参阅：

有关自动更新 Evergreen 运行时的详细信息，请参阅：

版本节奏

请参阅：

用于实例化 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 的前向兼容性

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

发布 SDK 包中的 WebView2 API 稳定且向前兼容。 WebView2 API 在使用内部版本号等于或更高于在其中引入 API 的 SDK 内部版本号的 WebView2 运行时起作用。 内部版本号是 Webview2 SDK 由四部分组成的版本号的第三部分，也是 Microsoft Edge 和 WebView2 运行时由四部分组成的版本号的第三部分。

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

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

例如，如果在 SDK 1.0 中引入了 API。900.0，则该 API 将与运行时 94.0 一起使用。900+.0，但不适用于运行时 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 运行时。 最初提供 WebView2 SDK 的预发行版本时，该 SDK 仅适用于 Microsoft Edge Canary。 此后不久，预发布 SDK 也适用于 Beta 和 Dev 渠道。

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

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

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

WebView2 团队正在寻求有关实验性 WebView2 API 的反馈，这些 API 可能会在将来的版本中提升为稳定版。 实验性 API 在 WebView2 SDK 参考文档中指示为“实验性”，例如：“注意：这是预发布 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 提升到稳定版后，该 API 的实验版本将受两个版本的预发布 SDK 支持，处于已弃用状态。 在预发布 SDK 的后续版本中，可能会修改、删除或添加实验性 API。

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

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

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

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

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

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

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

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

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

.NET 和 WinUI，以及 WinRT

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

Win32 C/C++

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

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

提供正常回退

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

另请参阅

Microsoft Edge 企业版文档：

下载次数：

GitHub：

  • Last updated on