测试即将推出的 API 和功能

本文介绍如何切换到 Microsoft Edge 的预览通道，以测试 WebView2 预发布 SDK 包中的实验 API。

若要测试新的或即将推出的 API 和功能，请切换到 Microsoft Edge 预览通道，而不是使用稳定的 WebView2 运行时。 Evergreen WebView2 运行时会频繁更新，以添加新的 API 和功能。 这些更新可能包括已从 Experimental 预发布 WebView2 SDK Stable 升级到 WebView2 发布 SDK 中的 API。 Evergreen WebView2 运行时中的某些更新可能会中断 WebView2 应用。

建议在 WebView2 发布 SDK 中将其提升为 Stable 之前，通过切换到包含 WebView2) 的 Microsoft Edge (预览通道来提前测试实验 API，以确保应用向前兼容。

另请参阅：

• 在 WebView2 的预发布 SDK 和发布 SDK 中引入 API 的阶段。
• 用于 WebView2 的预发行版 SDK 和发布 SDK - 使用预发行版本的 SDK 以及 Microsoft Edge 的预览通道;或者将 SDK 的版本与 Evergreen WebView2 运行时一起使用。

使用 WebView2 的预览通道根据最新的试验性 WebView2 API 测试应用

Evergreen WebView2 运行时不包括实验性 WebView2 API。 相反，若要在 WebView2 代码中使用这些实验性功能，请让应用使用Microsoft Edge 预览频道中的 WebView2 版本， (Edge Beta、Edge Dev 或 Edge Canary) 。

建议使用 Canary 通道，因为它提供最新的实验 API。

WebView2 预发布 SDK 与 Microsoft Edge 预览版频道之间的交互

• 预发布 SDK： 此版本的 WebView2 SDK 提供实验性 API 的方法签名，使你能够在应用中使用实验性 WebView2 API 编写代码。

• Microsoft Edge 预览频道： 这些通道 (Edge Beta、Edge Dev 或 Edge Canary) 包含必要的Microsoft Edge 二进制文件。 这些通道允许应用使用实验 API 运行和呈现。

有关 SDK 版本如何与 WebView2 运行时和 Microsoft Edge 预览通道交互的详细信息，请参阅 预发行版和发布 SDK for WebView2。

使用预览通道进行向前兼容性测试

我们建议你遵循以下最佳做法，使用预览通道测试即将进行的更改，以确保应用的向前兼容性：

• 使用预览频道进行预发布测试
• 通过部署预览通道进行自承载

下载预发行 SDK 和预览频道

若要使用实验性 API，请从 Microsoft.Web.WebView2 包下载 WebView2 SDK 的预发行版。

Microsoft Edge 的预览通道包括预览版 WebView2 运行时。 预览版频道也称为 预览体验成员频道。 安装后，预览频道会保持最新状态;将自动安装每个预览频道的最新版本。 例如，这意味着 Canary 频道几乎每天都会更新自己。 若要下载 Microsoft Edge 预览版频道 (Canary、Dev 或 Beta) ，请转到 成为 Microsoft Edge 预览体验成员。

若要将预览通道部署到多台计算机，请参阅下面的 如何部署预览频道。

使应用使用特定浏览器通道的方法

初始化 WebView2 时，它将尝试在计算机上查找要使用的有效运行时。 这可以是 WebView2 运行时、Microsoft Edge 的预览通道，也可以是包含固定版本二进制文件的指定位置。 有关支持的运行时的详细信息，请参阅 分发应用和 WebView2 运行时。

可通过两种方法使 WebView2 应用使用特定预览通道 Microsoft Edge：

• 建议 () 切换通道搜索顺序 。

• 为本地测试设置浏览器可执行文件文件夹 () 。

下面介绍了这些方法。

切换频道搜索顺序 (建议)

本部分适用于使用 API、注册表替代、环境变量或组策略。

如果未指定特定的浏览器可执行文件文件夹，则 WebView2 将尝试从已知默认位置之一加载运行时。 默认情况下，WebView2 加载程序使用找到的第一个运行时从最稳定到最不稳定 (Canary) 搜索运行时。

WebView2 Runtime (Stable) ->  Edge Beta -> Edge Dev -> Edge Canary

可以通过将 API 设置为 ChannelSearchKindLeastStable或将策略、注册表项或环境变量设置为 ChannelSearchKind1来反转默认搜索顺序。 反转搜索顺序可使 WebView2 加载程序搜索从最不稳定 (Canary) 到最稳定：

Edge Canary -> Edge Dev -> Edge Beta -> WebView2 Runtime (Stable)

必须在初始化 WebView2 控件之前完成此操作。

如果需要更具体的顺序，请参阅 如何使用 ChannelSearchKind 确保使用特定通道。

API

默认情况下，属性 CoreWebView2EnvironmentOptions.ChannelSearchKindCoreWebView2ChannelSearchKind.MostStable (枚举值) 。 相反，通过将 属性设置为 CoreWebView2EnvironmentOptions.ChannelSearchKind 来 CoreWebView2ChannelSearchKind.LeastStable反转搜索顺序。

。网：

• CoreWebView2EnvironmentOptions.ChannelSearchKind 属性
• CoreWebView2ChannelSearchKind Enum

WinRT：

• CoreWebView2EnvironmentOptions.ChannelSearchKind 属性
• CoreWebView2ChannelSearchKind Enum

Win32：

• ICoreWebView2EnvironmentOptions7：：get_ChannelSearchKind
• ICoreWebView2EnvironmentOptions7：:p ut_ChannelSearchKind
• COREWEBVIEW2_CHANNEL_SEARCH_KIND 枚举

注册表项

1. 打开 PowerShell 终端或已启用 PowerShell 的命令提示符。

2. 修改并运行以下命令：

   REG ADD <HKLM/HKCU>\Software\Policies\Microsoft\Edge\WebView2\ChannelSearchKind /v WebView2APISample.exe /t REG_DWORD /d 1
   

将 替换为 WebView2APISample.exe 你自己的应用可执行文件名称或应用程序用户模型 ID。 警告：如果改用通配符 (*) ，则替代将应用于计算机上的 所有 WebView2 应用，这可能会导致意外行为。

对反向搜索顺序或0默认搜索顺序使用 值1。

环境变量

• 名称：WEBVIEW2_CHANNEL_SEARCH_KIND
• 值：1

使用环境变量时，无法指定目标应用。 因此，设置为全局环境时，会影响计算机上使用 WebView2 的所有应用。

对反向搜索顺序或0默认搜索顺序使用 值1。

另请参阅：

• 如何设置环境变量，如下所示。

组策略

ChannelSearchKind设置策略。

• 名称：<app exe name or app user model ID - ex: WebView2APISample.exe>
• 值：1

对反向搜索顺序或0默认搜索顺序使用 值1。

执行以下任一操作：

• 从 下载和配置 Microsoft Edge for Business 下载Microsoft Edge 策略文件，其中包括 WebView2 策略文件。 有关详细信息，请参阅 在 Windows 设备上配置 Microsoft Edge 策略设置。

• 在 Intune 上使用内置策略。 请参阅以下文章。 WebView2 的步骤与 Microsoft Edge 的步骤相同，只不过使用类别“Microsoft Edge WebView2”而不是“Microsoft Edge”。

  • Microsoft Intune 文档中的 Microsoft Intune 中配置Microsoft Edge 策略设置 。
  • 使用 Microsoft Edge Enterprise 文档中的 Microsoft Intune 配置 Microsoft Edge 策略设置 。

如何使用 ChannelSearchKind 来确保使用特定通道

使用 ChannelSearchKind时，下面介绍如何确保在安装了多个预览浏览器通道时使用特定的预览浏览器通道。

除了反转通道搜索顺序外，还可以修改要包含在搜索中的发布通道集，以提供对通道选择的进一步控制。 加载程序将按照通道搜索类型指定的顺序搜索设备上的通道，但只考虑位于指定发布通道集中的通道。

如果要面向特定通道，而不只是选择最稳定或最不稳定的通道，则此选项非常有用。 默认情况下，发布通道包括所有通道：稳定 (0) 、Beta (1) 、Dev (2) 和 Canary (3) 。

示例：

Channel Search Kind: 1 (Least Stable)
Release Channels: 0 (Stable), 1 (Beta)

如果设备上安装了 Edge Beta，则此示例设置会导致加载程序尝试使用 Edge Beta 运行应用，否则会回退到使用稳定 WebView2 运行时。

发布通道同样可以通过 API、注册表项、环境变量或组策略进行设置。

API

默认情况下，加载程序会考虑所有发布通道。 设置为 ReleaseChannels 希望加载程序搜索的通道的掩码。

。网：

• CoreWebView2EnvironmentOptions.ReleaseChannels 属性
• CoreWebView2ReleaseChannels 枚举

WinRT：

• CoreWebView2EnvironmentOptions.ReleaseChannels 属性
• CoreWebView2ChannelSearchKind Enum

Win32：

• ICoreWebView2EnvironmentOptions7：：get_ReleaseChannels
• ICoreWebView2EnvironmentOptions7：:p ut_ReleaseChannels
• COREWEBVIEW2_RELEASE_CHANNELS枚举

注册表项

1. 打开 PowerShell 终端或已启用 PowerShell 的命令提示符。

2. 修改并运行以下命令：

   REG ADD <HKLM/HKCU>\Software\Policies\Microsoft\Edge\WebView2\ReleaseChannels /v WebView2APISample.exe /t REG_SZ /d "0,1"
   

将 替换为 WebView2APISample.exe 你自己的应用可执行文件名称或应用程序用户模型 ID。 使用通配符 (*) 作为值名称会将替代应用于计算机上的 所有 WebView2 应用，并可能导致意外行为。

环境变量

• 名称：WEBVIEW2_RELEASE_CHANNELS
• 值：<string of desired channels (ex: 0,1)>

使用环境变量方法时，无法设置目标应用。 因此，设置为全局环境时，此设置将影响计算机上使用 WebView2 的所有应用。

另请参阅：

• 如何设置环境变量，如下所示。

组策略

ReleaseChannel设置策略。

• 名称：<app exe name or app user model ID - ex: WebView2APISample.exe>
• 值：<string of desired channels (ex: 0,1)>

执行以下任一操作：

• 从 下载和配置 Microsoft Edge for Business 下载Microsoft Edge 策略文件，其中包括 WebView2 策略文件。 有关详细信息，请参阅 在 Windows 设备上配置 Microsoft Edge 策略设置。

• 在 Intune 上使用内置策略。 有关详细信息，请参阅 在 Microsoft Intune 中配置Microsoft Edge 策略设置。

为本地测试) 设置浏览器可执行文件文件夹 (

另一种方法是使用浏览器可执行文件夹。 在此方法中，指定包含运行时二进制文件的文件夹。 此文件夹可以是以下任意位置：

• WebView2 运行时的安装位置。
• Microsoft Edge 的预览频道。
• 包含你自己部署到计算机的固定版本二进制文件的文件夹。

如果将浏览器可执行文件文件夹设置为 Microsoft Edge 的特定预览通道，则需要在该预览通道更新到较新版本时更新位置。 这是因为位置包含版本号作为其路径的一部分。 因此，建议仅使用此方法进行本地测试。

API

在创建环境期间使用以下 API 传递浏览器可执行文件文件夹的路径。

.NET (WPF) ：

• CreationProperties 属性
• CoreWebView2CreationProperties 类

.NET (WinForms) ：

• CreationProperties 属性
• CoreWebView2CreationProperties 类

WinRT：

• CoreWebView2Environment.CreateWithOptionsAsync 方法

Win32：

• CreateCoreWebView2EnvironmentWithOptions

注册表项

1. 打开 PowerShell 终端或已启用 PowerShell 的命令提示符。

2. 修改并运行以下命令：

   REG ADD <HKLM/HKCU>\Software\Policies\Microsoft\Edge\WebView2\BrowserExecutableFolder /v WebView2APISample.exe /t REG_SZ /d "C:\Users\myname\AppData\Local\Microsoft\Edge SxS\Application\88.0.680.0"
   

   • 将 替换为 WebView2APISample.exe 你自己的应用可执行文件名称或应用程序用户模型 ID。
   • 将示例路径替换为所需Microsoft Edge 预览通道的路径。

环境变量

• 名称：WEBVIEW2_BROWSER_EXECUTABLE_FOLDER
• 值：<path to desired Microsoft Edge preview channel>

使用环境变量方法时，无法设置目标应用。 因此，设置为全局环境时，此设置将影响计算机上使用 WebView2 的所有应用。

另请参阅：

• 如何设置环境变量，如下所示。

组策略

BrowserExecutableFolder设置策略。

• 名称：<app exe name or app user model ID - ex: WebView2APISample.exe>
• 值：<path to desired Microsoft Edge preview channel>

执行以下任一操作：

• 从 下载和配置 Microsoft Edge for Business 下载Microsoft Edge 策略文件，其中包括 WebView2 策略文件。 请参阅 在 Windows 设备上配置 Microsoft Edge 策略设置。

• 在 Intune 上使用内置策略。 请参阅 在 Microsoft Intune 中配置 Microsoft Edge 策略设置。

选取新运行时时

如果使用环境变量、注册表项或组策略，则它们仅应用于创建的任何新的 WebView2 运行时浏览器进程;它们不适用于已在运行的 WebView2 运行时浏览器进程。 例如，如果 WebView2 具有特定用户数据文件夹 (因此相应的浏览器进程) 和更改 ChannelSearchKind ，然后再尝试使用同一用户数据文件夹创建新的 WebView2，它将使用现有的 WebView2 运行时浏览器进程，而不搜索其他运行时。

若要确保所有进程都使用环境变量、注册表项或组策略，需要执行以下任一操作：

• 重新启动应用。
• 重新创建共享用户数据文件夹的所有 WebView2 控件。
• 创建一个新的 WebView2，其用户数据文件夹不同于当前正在运行的任何其他 WebView2 控件。

如何设置环境变量

可以使用多种方法来设置环境变量：

• 使用 API 为特定应用设置环境变量。
• 为所有应用全局设置环境变量。

下面介绍了这些方法。

使用 API 为特定应用设置环境变量

可以使用 设置环境变量 SetEnvironmentVariable。 从主机应用调用此函数将环境变量的范围限制为仅主机应用及其创建的 WebView2 控件，并且不会影响系统上的其他应用。

• .NET： Environment.SetEnvironmentVariable 方法

• WinRT： EnvironmentManager.SetEnvironmentVariable 方法

• Win32： setEnvironmentVariable 函数 (winbase.h)

为所有应用全局设置环境变量

可以使用 Windows 系统 UI 设置环境变量。 此方法使环境变量的范围成为当前用户或系统的全局范围，并影响创建 WebView2 控件的所有应用。

1. 在 Windows 搜索栏中，输入“环境”，然后选择 “编辑系统环境变量”：

   

   此时将打开“ 系统属性 ”对话框。

2. 选择“ 高级 ”选项卡，然后单击“ 环境变量 ”按钮：

   

   此时将打开“ 环境变量 ”对话框。

3. 在顶部的 “用户变量 ”部分中，单击“ 新建 ”按钮。 此时将打开“ 新建用户变量 ”对话框。

4. 在 “变量名称 ”文本框中，输入环境变量名称或 WEBVIEW2_CHANNEL_SEARCH_KINDWEBVIEW2_BROWSER_EXECUTABLE_FOLDER。

5. 在 “变量值 ”文本框中，执行以下操作之一：

   • 如果设置 ChannelSearchKind，则输入 1 以从默认值反转搜索顺序，首先 (Canary、Beta、Dev) ，然后使用 WebView2 运行时使用预览频道。 除 1 之外的任何值都会导致使用默认搜索顺序 (WebView2 Runtime、Edge Dev、Edge Beta 和 Edge Canary) 。

   • 如果设置 ， BrowserExecutableFolder请输入首选浏览器通道或固定版本二进制文件的路径。

6. 单击 “确定” 按钮关闭对话框。

如何部署预览频道

若要将 Microsoft Edge 的预览通道部署到多台计算机，请执行下列操作之一：

• 选项 1：在计算机上手动安装预览频道。

• 选项 2：通过 API 终结点以编程方式部署预览通道。

下面介绍了这些选项。

选项 1：在计算机上手动安装预览频道

预览通道可以手动安装 (手动安装，也可以通过以下企业链接通过部署的自定义脚本) 安装：

频道	链接
Canary	下载
开发	下载
Beta	下载

每台计算机只需执行一次手动安装。 预发布频道是常青的，因此当有较新版本可用时，它们会自动更新。

选项 2：通过 API 终结点以编程方式部署预览通道

在应用的代码中，编写自己的自定义逻辑，以部署最新版本的 Microsoft Edge 预览通道，如下所示：

1. 调用与要部署的预览通道对应的以下 API 终结点：

   频道	链接
   Canary	https://edgeupdates.microsoft.com/api/products/canary MSI 链接
   开发	https://edgeupdates.microsoft.com/api/products/dev
   Beta	https://edgeupdates.microsoft.com/api/products/beta

   Canary 通道具有单独的 MSI 链接。 开发和 Beta 版通道包含 MSI 链接。

2. 将最新的包提取到设备。

3. 安装包。

另请参阅

• 在 WebView2 的预发布 SDK 和发布 SDK 中引入 API 的阶段。