分发应用和 WebView2 运行时

发布使用 Microsoft Edge WebView2 的应用时,需要通过分发自动更新的 Evergreen Runtime 或分发 固定版本的 运行时来分发 WebView2 运行时。

WebView2 应用依赖于客户端计算机上的 WebView2 运行时。 分发 WebView2 应用时,需要考虑 WebView2 运行时的分发方式和在客户端计算机上更新的方式。

WebView2 运行时

WebView2 运行时是可再发行的运行时,充当 WebView2 应用的基础 (或 支持) Web 平台。 此概念类似于 Visual C++ 或适用于 C++/.NET 应用的 .NET 运行时。 WebView2 运行时包含已修改的 Microsoft Edge 二进制文件,这些二进制文件已针对 WebView2 应用进行了微调和测试。 安装 WebView2 运行时后,它不会显示为用户可见的浏览器应用。 例如,用户在 “开始 ”菜单中没有浏览器桌面快捷方式或条目。

可通过两种不同的方式将 WebView2 运行时分发和更新到客户端计算机:Evergreen 分发模式和固定版本分发模式。

Evergreen Runtime 分发模式

Evergreen 分发模式下,WebView2 运行时不随应用一起打包,但最初使用联机引导程序或脱机安装程序安装到客户端上。 之后,WebView2 运行时会自动在客户端计算机上更新。 然后,可以从最新的 WebView2 SDK 分发使用最新 WebView2 API 的 WebView2 应用的更新。 建议大多数开发人员使用 Evergreen 分发模式。

优点:

  • 基础 Web 平台 (WebView2 运行时) 自动更新,无需你执行更多工作。

  • 客户端系统上的 WebView2 运行时所需的磁盘空间更少,因为 WebView2 运行时由客户端上的所有 WebView2 应用共享。

  • 在符合条件的系统上,Microsoft Edge 和 Evergreen WebView2 运行时的二进制文件在同一版本上时会硬链接在一起。 此链接为磁盘占用量、内存和性能提供了优势。

缺点:

  • WebView2 应用无法指定需要特定版本的 WebView2 运行时。

Evergreen 运行时作为Windows 11操作系统的一部分预安装在所有Windows 11设备上。 Microsoft 将 WebView2 运行时安装到所有符合条件的Windows 10设备,如将 Microsoft Edge WebView2 运行时交付到托管Windows 10设备中所述。 即使应用使用 Evergreen 分发模式,我们建议分发 WebView2 运行时,以涵盖尚未安装运行时的边缘情况。 请参阅下面的 有关 Evergreen Runtime 分发模式的详细信息

固定版本运行时分发模式

“固定版本” 分发模式下,下载特定版本的 WebView2 运行时,并将其与 WebView2 应用一起打包到应用包中。 随应用一起打包的 WebView2 运行时仅由 WebView2 应用使用,而不能由客户端计算机上的任何其他应用使用。

优点:

  • 可以更好地控制 WebView2 运行时的版本控制。 你知道哪些 WebView2 API 可用于你的应用,因为你控制了哪个版本的 WebView2 运行时可用于你的应用。 你的应用不需要测试是否存在最新的 API。

缺点:

  • 需要自行管理 WebView2 运行时。 WebView2 运行时不会在客户端上自动更新,因此若要使用最新的 WebView2 API,必须定期更新应用和更新后的 WebView2 运行时。

  • 如果安装了多个 WebView2 应用,则客户端上需要更多的磁盘空间。

  • 无法使用安装程序安装固定版本运行时。

了解运行时下载页中的选项

Microsoft Edge WebView2 页的“下载WebView2 运行时”部分提供了多个选项,用于将 WebView2 运行时分发到客户端计算机上。 了解此页中的选项提供了很好的介绍,有助于确定要使用的方法。

用于分发和更新 WebView2 运行时的选项

建议将常青分布模式用于大多数应用。

  • 页面的 Evergreen Bootstrapper 部分为联机用户提供了在客户端计算机上运行的小型 Evergreen Runtime 引导程序。 引导程序会将相应的 WebView2 Evergreen Runtime 下载并安装到客户端上。 可以通过几种不同的方式使用引导程序:

    • 使用从“ 获取 链接”按钮获取的链接链接到引导程序。 你的应用使用此链接以编程方式将引导程序下载到客户端并调用引导程序。 此方法无需将引导程序打包到应用中。 此方法依赖于 Microsoft 的内容分发网络 (CDN) 来获取引导程序。

    • 使用引导程序部分中的“ 下载 ”按钮) 下载 引导程序 (,然后将引导程序与应用一起分发。 在此方法中,你将引导程序与应用安装程序/更新程序或应用本身一起打包,并调用应用随附的引导程序。 此方法可避免依赖 Microsoft 的 CDN 来获取引导程序。

  • 页面的 “Evergreen 独立安装程序 ”部分提供大型的独立 Evergreen 安装程序,主要面向脱机用户。 在此方法中,将独立安装程序与应用安装程序/更新程序或应用本身打包,并调用 Evergreen 独立安装程序。 此方法可避免依赖 Microsoft CDN 来获取运行时。

  • 页面的 “固定版本 ”部分提供固定版本运行时,该运行时是随应用一起分发的特定 WebView2 运行时版本。

有关 WebView2 运行时的详细信息

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

如果要使用固定版本分发模式,可以跳过接下来的几个部分,并跳转到 有关固定版本运行时分发模式的详细信息

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

请参阅 webView2 运行时企业管理中的Windows Server Update Services (WSUS)

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

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

  • WebView2 运行时。 运行时通常提供与 Microsoft Edge 浏览器的稳定通道相同的 Web 平台功能和更新节奏。 在生产环境中使用 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操作系统的一部分包含在内。 在Windows 11之前,各种 WebView2 应用已在具有操作系统的设备上安装了 Evergreen Runtime。 但是,某些设备可能未预安装运行时,因此最好检查客户端上是否存在运行时。

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

有关 Evergreen Runtime 分发模式的详细信息

Evergreen 分发模式可确保 WebView2 应用利用最新的 WebView2 功能和安全更新。 常青分布模式具有以下特征:

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

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

  • 在符合条件的系统上,Microsoft Edge 和 Evergreen WebView2 运行时的二进制文件在同一版本上时会硬链接在一起。 此链接为磁盘占用量、内存和性能提供了优势。

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

绝大多数Windows 10设备已安装 WebView2 运行时,如将 Microsoft Edge WebView2 运行时传送到托管Windows 10设备中所述。 少数Windows 10设备未安装 WebView2 运行时。 建议使用以下任一方法处理此边缘情况:

另请参阅:

部署 Evergreen WebView2 运行时

设备上所有 Evergreen 应用只需安装一次 Evergreen WebView2 运行时。 下载 WebView2 运行时中提供了多种工具,可帮助部署 Evergreen 运行时。

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

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

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

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

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

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

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

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

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

检测是否已安装合适的 WebView2 运行时

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

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

    对于 WebView2 应用程序,必须至少存在其中一个正则键,并且其版本必须大于 0.0.0.0。 如果这两个 regkey 都不存在,或者只有其中一个 regkey 存在,但其值为 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 并评估 是否 versionInfonullptrnullptr 指示未安装 WebView2 运行时。 此 API 返回 WebView2 运行时或任何已安装的 Microsoft Edge (Beta、Dev 或 Canary) 预览版通道的版本信息。

仅联机部署

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

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

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

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

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

    MicrosoftEdgeWebview2Setup.exe /silent /install
    

上述工作流有几个好处:

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

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

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

  • 运行时以无提示方式安装。

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

脱机部署

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

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

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

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

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

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

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

测试应用的向前兼容性

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

Microsoft Edge 预览频道 (Beta 版、Dev 版和 Canary) 提供了一个关于 WebView2 运行时中即将推出的内容的一个预览版。 定期针对 Microsoft Edge 预览通道测试 WebView2 应用,并在出现问题时更新应用或 报告问题 。 Canary 是推荐的预览频道,因为它以最快的节奏提供,并且具有最新的 API。

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

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

使用最新 API 时的功能检测

如果使用常青模式,当 WebView2 应用使用来自最近 SDK 的新 WebView2 API 时,应使用 或 try-catchQueryInterface方法确保客户端计算机上存在新 API。 此功能检测是最佳做法,因为在某些情况下,WebView2 运行时未更新。

即使使用 Evergreen 分发模式,也可能不会更新 WebView2 运行时,原因如下:

  • IT 管理员可以关闭 WebView2 运行时的更新,因为管理员可以控制其设备的更新。

  • 脱机的客户端不会收到更新的 WebView2 运行时。

Microsoft Edge 和 WebView2 运行时的更新策略是分开的。 即使 IT 管理员禁用了 Microsoft Edge 的自动更新,WebView2 运行时仍会自动更新,除非管理员关闭运行时更新。 如果管理员禁用更新 Microsoft Edge (这是一些常见的) ,这不会影响客户端计算机上可用的 WebView2 API。

请参阅 功能检测以测试已安装的运行时是否支持最近添加的 API

有关固定版本运行时分发模式的详细信息

对于具有严格兼容性要求的受限环境,请考虑使用固定版本分发模式。 固定版本分发模式以前称为 “自带”。

在“固定版本”分发模式下,可以控制应用的 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使用 参数指示包含 msedgewebview2.exe的文件夹的路径。

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

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

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

    • 对于 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 路径运行。

要随应用一起提供的文件

代码 WebView2Loader 需要随应用一起提供。 这可以通过 静态链接到WebView2Loader.lib 应用二进制文件,或包括 WebView2Loader.dll 与应用体系结构匹配的 。 通常,在 .targets WebView2 SDK 中使用文件时,Visual Studio 会自动处理此问题,但在某些情况下,可能需要手动指定要与应用一起发布的文件。

WebView2Loader.dll 是本机和特定于体系结构的二进制文件,因此需要包含你期望运行应用的所有二进制文件。 例如:

  • 对于 x86,需要包括 的 x86 版本 WebView2Loader.dll

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

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

\<myApp>
    \WebView2Loader.dll

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

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

\<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)