分发应用和 WebView2 运行时

分发 WebView2 应用时,请确保客户端计算机上存在 WebView2 运行时。 此要求适用于常青和固定版本分发模式。

有关介绍性信息,请参阅 WebView2 运行时的常青与固定版本。

详细内容:

开发或生产期间的运行时或浏览器支持

在开发和测试期间,WebView2 应用可以使用任一选项作为后备 Web 平台:

  • WebView2 运行时。 运行时通常提供与 Microsoft Edge 浏览器的稳定渠道相同的 Web 平台功能和更新发布节奏;请参阅 Microsoft Edge 发布计划。 在生产环境中使用 WebView2 运行时,或针对用户目前拥有的 Web 平台进行开发和测试。

  • 预览 (预览体验成员) Microsoft Edge 浏览器频道。 这些 Microsoft Edge 预览频道是 Beta 版、开发人员版和 Canary。 使用此方法测试应用的前向兼容性,以便了解是否即将发生需要更新应用的重大更改。 请参阅 切换到预览频道以测试即将推出的 API 和功能。

WebView2 应用的生产版本只能使用 WebView2 运行时作为后备 Web 平台,而不能使用 Microsoft Edge。

WebView2 不支持 Microsoft Edge 稳定渠道

不允许 WebView2 应用使用 Microsoft Edge 的稳定渠道作为后备 Web 平台。 此限制可防止 WebView2 应用的生产版本获取浏览器依赖项。 WebView2 应用在生产期间无法依赖于浏览器,原因如下:

  • 不保证 Microsoft Edge 显示在所有用户设备上。 企业和教育中的许多设备已与 Windows 更新断开连接,或者不受 Microsoft 直接管理。 此类设备可能未安装 Microsoft Edge。 要求 WebView2 应用的生产版本使用 WebView2 运行时而不是 Microsoft Edge,可避免使 Microsoft Edge 成为运行 WebView2 应用的先决条件。

  • 浏览器和应用具有不同的用例。 如果 WebView2 应用需要客户端上存在 Microsoft Edge,则可能会对 WebView2 应用产生意外的副作用。 例如,IT 管理员可以阻止从特定版本更新浏览器,以保持浏览器与内部网站兼容。 要求 WebView2 应用的生产版本使用 WebView2 运行时而不是浏览器,这样即使客户端管理员阻止浏览器更新,WebView2 应用也可以保持常青。

  • 与浏览器相反,WebView2 运行时是针对应用方案开发和测试的,在某些情况下,WebView2 运行时可能包括浏览器中尚不可用的 bug 修复。

Evergreen WebView2 运行时将作为 Windows 11 操作系统的一部分包含在内。 各种 WebView2 应用已在操作系统低于 Windows 11 的设备上安装了 Evergreen 运行时。 但是,某些设备可能未预安装运行时,因此最好检查客户端上是否存在运行时。

在应用创建 WebView2 之前,应用应检查是否存在 WebView2 运行时, (检查注册表项或调用 API) 并安装运行时(如果缺少)。 在 (建议的) 安装或更新应用时,或在应用运行时,应用可以检查执行此操作。 若要检查运行时是否存在,请参阅下面的“部署 Evergreen WebView2 运行时”。

常青运行时分发模式

常青分发模式可确保 WebView2 应用利用最新的 WebView2 功能和安全更新。 有关介绍性信息,请参阅常青运行时分发模式与 WebView2 运行时的固定版本。

常青分布模式具有以下特点:

  • WebView2 运行时会自动更新,无需你进行任何操作。 它接收与 Microsoft Edge 稳定频道发行说明和 MicrosoftEdge 安全汇报发行说明中所述的相同 Microsoft Edge 更新。

  • 使用常青分发模式的所有 WebView2 应用都使用常青 WebView2 运行时的共享副本,从而节省了磁盘空间。

  • 在符合条件的系统上,当 Microsoft Edge 和 Evergreen WebView2 运行时的二进制文件位于同一版本上时,它们将硬链接在一起。 这种关联可以带来磁盘占用空间、内存和性能方面的好处。

使用 WebView2 运行时的常青分发模式时,WebView2 应用假定客户端具有最新的运行时。 应用不能对客户端上的所有应用要求特定版本的 WebView2 运行时。 到发布新的 WebView2 SDK 包时,兼容版本的 WebView2 运行时已分发到客户端。 因此,WebView2 应用可以使用最新版本 WebView2 SDK 中的 API。

Windows 11设备和Windows 10设备 (详细信息)

有关介绍性信息,请参阅常青版中的 Windows 11 设备和 Windows 10 设备与 WebView2 运行时的固定版本。

绝大多数 Windows 10 设备都已安装 WebView2 运行时,如向托管 Windows 10 设备提供 Microsoft Edge WebView2 运行时中所述。 少数 Windows 10 设备未安装 WebView2 运行时。 建议使用以下任一方法处理此极端情况:

另请参阅:

  • 适用于 WebView2 的预发布和发布 SDK - 使用 SDK 的预发布版本以及 Microsoft Edge 的预览频道;或将 SDK 的发行版与 Evergreen WebView2 运行时一起使用。

部署常青 WebView2 运行时

设备上的所有 Evergreen 应用只需安装一次 Evergreen WebView2 运行时。 下载 WebView2 运行时 提供了多个工具来帮助你部署 Evergreen 运行时。

  • 对于联机客户端: WebView2 运行时引导程序 是一个小型 (大约 2 MB) 安装程序。 WebView2 运行时引导程序从与用户的设备体系结构匹配的 Microsoft 服务器下载并安装常青运行时。

    • 在 WebView2 应用的设置部分中,链接到引导程序。 使用链接以编程方式下载引导程序;在上述下载页面中选择“ 获取链接 ”按钮。

    • 或者,下载引导程序并将其与 WebView2 应用打包。

  • 对于脱机客户端: WebView2 运行时独立安装程序 是一个完整安装程序,可在脱机环境中安装 Evergreen WebView2 运行时。

  • 如果使用应用安装程序部署 MSIX 应用程序,则可以将 WebView2 运行时指定为依赖项,以将其与应用程序一起安装。 有关如何执行此操作的详细信息,请参阅应用包清单文档中的 win32dependencies:ExternalDependency (Windows 10,Windows 11) 。另请参阅使用应用安装程序安装 Windows 10 应用。

按计算机或按用户安装运行时

最新的引导程序和独立安装程序支持 每台计算机 和 每用户 安装 WebView2 运行时。

如果从提升的进程或命令提示符运行安装程序,则运行时将作为 每台计算机安装。 如果不从提升的进程或命令提示符运行安装程序,则运行时将作为 每个用户安装。 但是,如果存在每台计算机的 Microsoft Edge 更新程序,则每用户安装将自动替换为每台计算机的安装。 每台计算机的 Microsoft Edge 更新程序作为 Microsoft Edge 的一部分包含在内,但 Microsoft Edge 的 Canary 预览频道除外。

使用以下联机部署工作流或脱机部署工作流确保在应用启动之前已安装运行时。 可根据方案调整工作流。 示例代码在 示例存储库中可用。

检测是否已安装 WebView2 运行时

若要验证是否已安装 WebView2 运行时,请使用以下方法之一:

  • 方法 1:在 pv (REG_SZ) 以下两个注册表位置检查 WebView2 运行时的注册表项。 HKEY_LOCAL_MACHINE注册表项用于每台计算机的安装。 HKEY_CURRENT_USER注册表项用于每用户安装。

    对于 WebView2 应用程序,必须存在这些注册表项中至少一个,并且定义其版本大于 0.0.0.0。 如果注册表项都不存在,或者这些注册表项中只有一个存在,但其值为 null、空字符串或 0.0.0.0,则这意味着客户端上未安装 WebView2 运行时。 检查这些注册表项以检测是否已安装 WebView2 运行时,并获取 WebView2 运行时的版本。 在以下两个位置查找 pv (REG_SZ) 。

    要在 64 位 Windows 上检查的两个注册表位置:

    HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Microsoft\EdgeUpdate\Clients\{F3017226-FE2A-4295-8BDF-00C3A9A7E4C5}
    
    HKEY_CURRENT_USER\Software\Microsoft\EdgeUpdate\Clients\{F3017226-FE2A-4295-8BDF-00C3A9A7E4C5}
    

    要在 32 位 Windows 上检查的两个注册表位置:

    HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\EdgeUpdate\Clients\{F3017226-FE2A-4295-8BDF-00C3A9A7E4C5}
    
    HKEY_CURRENT_USER\Software\Microsoft\EdgeUpdate\Clients\{F3017226-FE2A-4295-8BDF-00C3A9A7E4C5}
    
  • 方法 2:运行 GetAvailableCoreWebView2BrowserVersionString 并评估是否为 versionInfonullptr. nullptr 指示未安装 WebView2 运行时。 此 API 返回 WebView2 运行时或 Microsoft Edge (Beta、Dev 或 Canary) 的任何已安装预览频道的版本信息。

仅联机部署

如果假设用户具有 Internet 访问权限的仅联机部署方案,请使用以下工作流。

  1. 在应用设置期间,运行测试以确保已安装 WebView2 运行时。 请参阅上文的 检测是否已安装 WebView2 运行时。

  2. 如果未安装运行时,请在应用设置过程中使用下载页上“ 获取链接 ”按钮中的链接 () 以编程方式下载 WebView2 运行时引导程序。

  3. 通过发出以下命令调用 WebView2 运行时引导程序。

    如果从提升的进程或命令提示符运行以下命令,它将触发 每台计算机 的安装。 如果不从提升的进程或命令提示符运行命令,将进行 每用户 安装。 但是,如果存在每台计算机的 Microsoft Edge 更新程序,则每用户安装将自动替换为每台计算机的安装。 每台计算机的 Microsoft Edge 更新程序作为 Microsoft Edge 的一部分提供,但 Microsoft Edge 的 Canary 预览频道除外。 有关详细信息,请参阅 按计算机或按用户安装运行时。

    MicrosoftEdgeWebview2Setup.exe /silent /install
    

上述工作流有几个优点:

  • 运行时仅在需要时安装。

  • 无需将运行时安装程序与 WebView2 应用打包。

  • WebView2 运行时引导程序会自动检测设备的体系结构 (平台) ,然后安装匹配的 WebView2 运行时。

  • 运行时以静默方式安装。

或者,你可以将 WebView2 运行时的常青引导程序与应用打包,而不是通过获取链接以编程方式按需下载引导程序,如上所示。

脱机部署

如果是脱机部署方案,其中应用部署必须完全脱机工作,请使用以下工作流。

  1. 从以下位置下载 Evergreen 独立安装程序 将 WebView2 运行时下载 到开发计算机。 Evergreen 独立安装程序在客户端上安装 Evergreen WebView2 运行时。

  2. 在应用安装程序或更新程序中包括 Evergreen 独立安装程序。

  3. 在应用设置期间,运行测试以确保已安装 WebView2 运行时。 请参阅上文的 检测是否已安装 WebView2 运行时。

  4. 如果未安装 WebView2 运行时,请运行 Evergreen 独立安装程序。 如果要运行静默安装,可以运行以下命令。

    如果从提升的进程或命令提示符运行以下命令,它将触发 每台计算机 的安装。 如果不从提升的进程或命令提示符运行命令,将进行 每用户 安装。 但是,如果存在每台计算机的 Microsoft Edge 更新程序,则每用户安装将自动替换为每台计算机的安装。 每台计算机的 Microsoft Edge 更新程序作为 Microsoft Edge 的一部分提供,但 Microsoft Edge 的 Canary 预览频道除外。 有关详细信息,请参阅 按计算机或按用户安装运行时。

    MicrosoftEdgeWebView2RuntimeInstaller{X64/X86/ARM64}.exe /silent /install
    

处理常青 WebView2 运行时更新

将自动下载新版本的 Evergreen WebView2 运行时到客户端。 重启 WebView2 应用时,客户端将使用新版本的 WebView2 运行时。 但是,如果应用连续运行,则应用将继续使用以前版本的 WebView2 运行时。 这存在安全隐患,因为以前版本的 WebView2 运行时可能存在新版本中修复的安全漏洞。 应根据应用的威胁模型,考虑应用尽快采用最新版本的 WebView2 运行时是否重要。 例如,如果你的 WebView2 应用访问第三方内容,则应将该内容视为不受信任,因此你的应用需要使用最新版本的 WebView2 运行时。

若要使用新版本的 WebView2 运行时,需要释放对以前的 WebView2 环境对象的所有引用,或重启应用。 下次应用创建新的 WebView2 环境时,该应用将使用新版本的 WebView2 运行时。 为此,可以为 NewBrowserVersionAvailable 事件设置事件处理程序,让应用自动通知用户重启应用。 如果你的应用处理重启应用,请考虑在 WebView2 应用退出之前保存用户状态。

测试应用的正向兼容性

在常青分发模式下,WebView2 运行时在客户端上自动保持最新,以提供最新功能和安全修补程序。 如果使用常青分布,为确保 WebView2 应用与 Web 保持兼容,应设置测试基础结构。

Microsoft Edge 预览频道 (Beta、Dev 和 Canary) 提供对 WebView2 运行时后续功能的预览。 定期针对 Microsoft Edge 预览频道测试 WebView2 应用,并在出现问题时更新应用或 报告问题 。 请参阅 测试即将推出的 API 和功能。 Canary 是推荐的预览频道,因为它以最快的速度交付,并且具有最新的 API。

为了帮助你确定哪个频道是正确的,请参阅 Microsoft Edge 频道概述。 可以在测试环境中 下载 Microsoft Edge 预览体验成员频道 ,并使用 regkey OR 环境变量指示测试应用的频道首选项。

请参阅 CreateCoreWebView2EnvironmentWithOptions。 还可以使用 WebDriver 自动执行 WebView2 测试(如“自动化”中所述), 并使用 Microsoft Edge WebDriver 测试 WebView2。

有关如何测试应用的向前兼容性的最佳做法,请参阅 通过部署预览频道使用 Microsoft Edge 和自托管的预览频道进行预发布测试。

使用最近使用的 API 时的功能检测

在 WebView2 应用中使用常青模式时,使用诸如 或 try-catch之类的方法QueryInterface检查客户端计算机上是否存在新 API 至关重要,因为客户端计算机可能没有包含新 API 的最新 WebView2 运行时。 如果 IT 管理员禁用更新或客户端处于脱机状态,则可能不会对 WebView2 运行时进行汇报。

有关详细信息,请参阅 功能检测,以测试已安装的运行时是否支持WebView2 的预发布和发布 SDK 中最近添加的 API。

Microsoft Edge 和 WebView2 运行时有单独的更新策略。 禁用 Microsoft Edge 的更新不会影响最新 WebView2 API 的可用性,因为除非管理员) 禁用更新 WebView2 运行时,否则 WebView2 运行时仍可以自动更新 (。

已修复版本运行时分发模式

对于具有严格兼容性要求的受限环境,请考虑使用固定版本分发模式。 (固定版本分发模式以前称为自带。) 有关介绍性信息,请参阅 Evergreen 中的固定版本运行时分发模式与 WebView2 运行时的固定版本。

在固定版本分发模式下,可以控制应用的 WebView2 运行时更新的时间。 下载 WebView2 运行时的特定版本,然后将其与 WebView2 应用打包。 客户端上的 WebView2 运行时不会自动更新。 相反,应定期更新与更新的应用一起打包和分发的 WebView2 运行时。 “已修复版本”方法不对 WebView2 运行时使用注册表项。

已修复版本二进制文件超过 250 MB,会使应用包变大该数量。

若要使用固定版本分发模式:

  1. 从 下载 WebView2 运行时的固定版本 下载 WebView2 运行时,作为包。

    最新和次新主要版本的补丁更新最多的版本可在此站点上下载。 保留所需任何版本的存档副本。

  2. 使用命令行命令 expand {path to the package} -F:* {path to the destination folder} 或使用解压缩工具(如 WinRAR)解压缩 WebView2 运行时包。 避免通过文件资源管理器解压缩,因为该方法可能不会生成正确的文件夹结构。

  3. 在应用包中包含所有解压缩的已修复版本二进制文件,以便在安装应用期间部署在目标计算机上。

  4. 在创建 WebView2 环境时指示已修复版本二进制文件的路径。

    • 对于 Win32 C/C++,可以使用 CreateCoreWebView2EnvironmentWithOptions 函数创建环境。 使用参数 browserExecutableFolder 指示包含 WebView2 运行时 (msedgewebview2.exe) 的文件夹的路径。

    • 对于 .NET,必须在 WebView2 Source 属性生效之前指定环境。 对于 .NET,可以使用以下任一方法指定环境:

      • 在元素上WebView2设置 CreationProperties (WPF/WinForms) 属性。 使用 (WPF/WinForms) 类中的CoreWebView2CreationProperties成员来BrowserExecutableFolder指示固定版本二进制文件的路径。

      • 或者,使用 EnsureCoreWebView2Async (WPF/WinForms) 指定环境。 使用 CoreWebView2Environment.CreateAsync 中的参数指示browserExecutableFolder固定版本二进制文件的路径。

    • 对于 WinUI,通过指定安装位置和为运行时路径设置环境变量来确保应用有权访问文件夹。 执行此操作的一种方法是将以下 C# 代码添加到应用:

      StorageFolder localFolder = Windows.ApplicationModel.Package.Current.InstalledLocation;
      String fixedPath = Path.Combine(localFolder.Path, "FixedRuntime\\(version number)");
      Debug.WriteLine($"Launch path [{localFolder.Path}]");
      Debug.WriteLine($"FixedRuntime path [{fixedPath}]");
      Environment.SetEnvironmentVariable("WEBVIEW2_BROWSER_EXECUTABLE_FOLDER", fixedPath);
      
  5. 将已修复版本二进制文件打包并随应用一起交付。 根据需要更新二进制文件。

    • 对于 WinUI,这可能包括在代码编辑器中打开项目文件 (.csproj) ,然后在项目标记中添加以下代码:

      <ItemGroup>
          <Content Include="FixedRuntime\(version number)\\**\*.*">
          <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
          </Content>
      </ItemGroup>
      

      验证文件夹中 bin\**designated architecture**\Release 是否具有匹配的 FixedRuntime\ (版本号) 文件夹,其中包含运行时文件。

  6. 在 Windows 10 设备上,从已修复版本 120 开始,使用固定版本的未打包 Win32 应用程序的开发人员需要运行以下命令,以便固定版本继续工作。 这是由于 v120 中的安全性改进使得可在应用容器内运行呈现器进程。 此更改不会影响 Windows 11 设备、旧运行时或打包应用。

    1. 找到在用户设备上部署已修复版本包的路径,例如以下位置:

      D:\myapp\Microsoft.WebView2.FixedVersionRuntime.87.0.664.8.x64
      
    2. 在用户的设备上运行以下命令:

      icacls {Fixed Version path} /grant *S-1-15-2-2:(OI)(CI)(RX)
      icacls {Fixed Version path} /grant *S-1-15-2-1:(OI)(CI)(RX)
      
    3. 确认已在ALL APPLICATION PACKAGESALL RESTRICTED APPLICATION PACKAGES“已修复版本”文件夹的“安全”选项卡中授予权限,如下所示:

      PlayReady 的权限

已修复版本的已知问题

  • 目前,无法从网络位置或 UNC 路径运行固定版本。

应用附带的 Files

WebView2Loader代码需要随应用一起交付。 这可以通过静态链接 WebView2Loader.lib 到应用二进制文件或包含与应用的体系结构匹配的 来 WebView2Loader.dll 完成。 在 WebView2 SDK 中使用该文件时 .targets ,Visual Studio 通常会自动为你处理此操作,但在某些情况下,可能需要手动指定要随应用发布的文件。 若要静态链接 WebView2 加载程序库,请参阅 将 WebView2 应用分发为单个可执行文件。

WebView2Loader.dll 是一个本机且特定于体系结构的二进制文件,因此你需要包含希望应用在其中运行的此二进制文件的所有风格。 例如:

  • 对于 x86,应包括 x86 版本的 WebView2Loader.dll。

  • 对于使用 AnyCPU 的托管应用,应包括 x86、x64 和 arm64 版本的 WebView2Loader.dll. 从 WebView2Loader.dll 适当的特定于体系结构的文件夹加载的正确版本。

本机应用文件夹结构示例:

\<myApp>
    \WebView2Loader.dll

对于 .NET 托管应用,还需要为) (Microsoft.Web.WebView2.Core.dll 的核心 WebView2 功能以及 WPF/WinForms 特定功能 (Microsoft.Web.WebView2.Winforms.dll 或 Microsoft.Web.WebView2.WPF.dll) 包括 WebView2 .NET 程序集。

托管应用文件夹结构示例:

\<myApp>
    \Microsoft.Web.WebView2.Core.dll
    \Microsoft.Web.WebView2.Winforms.dll
    \Microsoft.Web.WebView2.WPF.dll
    \runtimes
        \win-arm64\native\WebView2Loader.dll (arm64)
        \win-x64\native\WebView2Loader.dll (x64)
        \win-x86\native\WebView2Loader.dll (x86)

通过 WSUS) 服务 WebView2 运行时Windows Server Update Services (

请参阅Windows Server Update Services (WebView2 企业管理中的 WSUS) 。

另请参阅

Microsoft Edge 企业版文档:

developer.microsoft.com:

博客:

Windows:

GitHub:

Windows 运行时 API:

API 参考: