分发应用和 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 运行时。
Windows 11设备和Windows 10设备
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 运行时分发到客户端计算机上。 了解此页中的选项提供了很好的介绍,有助于确定要使用的方法。
建议将常青分布模式用于大多数应用。
页面的 Evergreen Bootstrapper 部分为联机用户提供了在客户端计算机上运行的小型 Evergreen Runtime 引导程序。 引导程序会将相应的 Evergreen WebView2 运行时下载并安装到客户端上。 可以通过几种不同的方式使用引导程序:
使用从“ 获取 链接”按钮获取的链接链接到引导程序。 你的应用使用此链接以编程方式将引导程序下载到客户端并调用引导程序。 此方法无需将引导程序打包到应用中。 此方法依赖于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 版、Dev 版和 Canary 版。 使用此方法测试应用的向前兼容性,以便了解是否需要更新应用的中断性变更。 请参阅 测试即将推出的 API 和功能。
WebView2 应用的生产版本只能将 WebView2 运行时用作支持 Web 平台,而不能Microsoft Edge。
Microsoft WebView2 不支持 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 11设备和Windows 10设备 (详细信息)
绝大多数Windows 10设备都已安装 WebView2 运行时,如将 Microsoft Edge WebView2 运行时传送到托管Windows 10设备中所述。 少数Windows 10设备未安装 WebView2 运行时。 建议使用以下任一方法处理此边缘情况:
使用应用以编程方式部署 Evergreen 运行时。 请参阅下面的 部署 Evergreen WebView2 运行时 。
将最终用户重定向到Microsoft站点: 下载Microsoft Edge WebView2,让最终用户从站点下载 Evergreen WebView2 运行时安装程序并自行安装运行时。
另请参阅:
- 用于 WebView2 的预发行版 SDK 和发布 SDK - 使用预发行版本的 SDK 以及 Microsoft Edge 的预览通道;或者将 SDK 的版本与 Evergreen WebView2 运行时一起使用。
- 将 Microsoft Edge WebView2 运行时传送到托管Windows 10设备。
部署 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 并评估 是否
versionInfo
为nullptr
。nullptr
指示未安装 WebView2 运行时。 此 API 返回 WebView2 运行时或任何已安装的 Microsoft Edge (Beta、Dev 或 Canary) 的版本信息。
仅联机部署
如果假设用户具有 Internet 访问权限的仅限联机部署方案,请使用以下工作流。
在应用安装期间,运行测试以确保已安装 WebView2 运行时。 请参阅上面的 检测是否已安装 WebView2 运行时。
如果未安装运行时,请在应用设置过程中,使用下载页上的“ 获取链接 ”按钮 (链接) 以编程方式下载 WebView2 运行时引导程序。
通过发出以下命令调用 WebView2 运行时引导程序。
如果从提升的进程或命令提示符运行以下命令,则会触发 每台计算机 安装。 如果不从提升的进程或命令提示符运行命令,将进行 每用户 安装。 但是,如果安装了每台计算机Microsoft Edge Updater,则每用户安装将自动替换为每计算机安装。 每台计算机Microsoft Edge 更新程序作为 Microsoft Edge 的一部分提供,Microsoft Edge 的 Canary 预览频道除外。 有关详细信息,请参阅按 计算机或按用户安装运行时。
MicrosoftEdgeWebview2Setup.exe /silent /install
上述工作流有几个好处:
仅在需要时安装运行时。
无需将运行时安装程序打包到 WebView2 应用。
WebView2 运行时引导程序会自动检测设备的体系结构 (平台) 然后安装匹配的 WebView2 运行时。
运行时以无提示方式安装。
或者,你可以将 WebView2 运行时的 Evergreen Bootstrapper 与应用打包,而不是通过获取链接以编程方式按需下载引导程序(如上所示)。
脱机部署
如果你有一个脱机部署方案,其中应用部署必须完全脱机工作,请使用以下工作流。
从将 WebView2 运行时下载 到开发计算机中的 Evergreen 独立安装程序。 Evergreen 独立安装程序在客户端上安装 Evergreen WebView2 运行时。
在应用安装程序或更新程序中包含 Evergreen 独立安装程序。
在应用安装期间,运行测试以确保已安装 WebView2 运行时。 请参阅上面的 检测是否已安装 WebView2 运行时。
如果未安装 WebView2 运行时,请运行 Evergreen 独立安装程序。 如果要运行无提示安装,可以运行以下命令。
如果从提升的进程或命令提示符运行以下命令,则会触发 每台计算机 安装。 如果不从提升的进程或命令提示符运行命令,将进行 每用户 安装。 但是,如果安装了每台计算机Microsoft Edge Updater,则每用户安装将自动替换为每计算机安装。 每台计算机Microsoft Edge 更新程序作为 Microsoft Edge 的一部分提供,Microsoft Edge 的 Canary 预览频道除外。 有关详细信息,请参阅按 计算机或按用户安装运行时。
MicrosoftEdgeWebView2RuntimeInstaller{X64/X86/ARM64}.exe /silent /install
处理 Evergreen WebView2 运行时更新
新版本的 Evergreen WebView2 运行时会自动下载到客户端。 重启 WebView2 应用时,客户端将使用新版本的 WebView2 运行时。 但是,如果应用持续运行,则应用将继续使用以前版本的 WebView2 运行时。 这会产生安全隐患,因为以前版本的 WebView2 运行时可能有新版本中修复的安全漏洞。 应考虑应用根据应用的威胁模型尽快采用最新版本的 WebView2 运行时是否重要。 例如,如果 WebView2 应用访问第三方内容,该内容应被视为不受信任,因此应用需要使用最新版本的 WebView2 运行时。
若要使用新版本的 WebView2 运行时,需要释放对以前的 WebView2 环境对象的所有引用,或重启应用。 下次应用创建新的 WebView2 环境时,应用将使用新版本的 WebView2 运行时。 为此,你可以为事件设置事件处理程序 NewBrowserVersionAvailable
,让应用自动通知用户重启应用。 如果应用处理重启应用,请考虑在 WebView2 应用退出之前保存用户状态。
-
CoreWebView2Environment
类:
测试应用的向前兼容性
在 Evergreen 分发模式下,WebView2 运行时会自动在客户端上保持最新状态,以提供最新的功能和安全修补程序。 如果使用 Evergreen 分发版,为确保 WebView2 应用与 Web 保持兼容,应设置测试基础结构。
有关如何测试应用的向前兼容性的最佳做法,请参阅使用预览通道进行预发布测试和通过部署预览通道进行自承载。
使用最新 API 时的功能检测
在 WebView2 应用中使用 Evergreen 模式时,使用 或 try-catch
等QueryInterface
方法检查客户端计算机上是否存在新 API 至关重要,因为客户端计算机可能没有包含新 API 的最新 WebView2 运行时。 如果 IT 管理员禁用更新或客户端脱机,则可能不会汇报 WebView2 运行时。
有关详细信息,请参阅功能检测以测试已安装的运行时是否支持最近在预发行 SDK for WebView2 中添加的 API。
Microsoft Edge 和 WebView2 运行时有单独的更新策略。 禁用Microsoft Edge 的更新不会影响最新 WebView2 API 的可用性,因为除非管理员) 禁用更新 WebView2 运行时,否则 WebView2 运行时仍可 (自动更新。
有关固定版本运行时分发模式的详细信息
对于具有严格兼容性要求的约束环境,请考虑使用固定版本分发模式。 (固定版本分发模式以前称为 自带.)
在“固定版本”分发模式下,可以控制应用的 WebView2 运行时的更新时间。 下载特定版本的 WebView2 运行时,然后将其与 WebView2 应用一起打包。 客户端上的 WebView2 运行时不会自动更新。 相反,会定期更新打包和分发的 WebView2 运行时以及更新的应用。 固定版本方法不使用 WebView2 运行时的注册表项。
固定版本二进制文件超过 250 MB,将使应用包更大。
若要使用固定版本分发模式,请执行以下操作:
从下载 WebView2 运行时中下载 固定版本的 WebView2 运行时,作为包。
此站点上提供了最新和第二个最新主要版本的修补次数最多的版本。 保留所需任何版本的存档副本。
使用命令行命令
expand {path to the package} -F:* {path to the destination folder}
或使用 WinRAR 等解压缩工具解压缩 WebView2 运行时包。 避免通过文件资源管理器解压缩,因为该方法可能不会生成正确的文件夹结构。在应用包中包含所有解压缩的固定版本二进制文件,在应用安装期间将部署在目标计算机上。
指示创建 WebView2 环境时固定版本二进制文件的路径。
对于 Win32 C/C++,可以使用 CreateCoreWebView2EnvironmentWithOptions 函数创建环境。
browserExecutableFolder
使用 参数指示包含msedgewebview2.exe
的文件夹的路径。对于 .NET,必须在 WebView2
Source
属性生效之前指定环境。 对于 .NET,可以使用以下任一方法来指定环境:对于 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);
随应用打包并交付固定版本二进制文件。 根据需要更新二进制文件。
对于 WinUI,这可能包括在代码编辑器中打开项目文件 (
.csproj
) ,然后在项目标记中添加以下代码:<ItemGroup> <Content Include="FixedRuntime\(version number)\\**\*.*"> <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory> </Content> </ItemGroup>
验证文件夹是否具有匹配的
bin\**designated architecture**\Release
FixedRuntime\ (版本号) 文件夹中的运行时文件。
在Windows 10设备上,从固定版本 120 开始,使用固定版本的未打包 Win32 应用程序的开发人员必须运行以下命令,以便“固定版本”继续工作。 这是由于 v120 中在应用容器中运行呈现器进程的安全性改进。 此更改不会影响Windows 11设备、旧运行时或打包的应用。
找到在用户设备上部署固定版本包的路径,例如以下位置:
D:\myapp\Microsoft.WebView2.FixedVersionRuntime.87.0.664.8.x64
在用户的设备上运行以下命令:
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)
确认在“固定版本”文件夹的“安全性”选项卡中为
ALL APPLICATION PACKAGES
和ALL RESTRICTED APPLICATION PACKAGES
授予了权限,如下所示:
已修复版本的已知问题
- 目前,固定版本无法从网络位置或 UNC 路径运行。
要随应用一起提供的文件
代码 WebView2Loader
需要随应用一起提供。 这可以通过 静态链接到WebView2Loader.lib
应用二进制文件,或包括 WebView2Loader.dll
与应用体系结构匹配的 。 通常,在 WebView2 SDK 中使用文件时,Visual Studio .targets
会自动处理此问题,但在某些情况下,可能需要手动指定要随应用一起发布的文件。
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.dll
或 Microsoft.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)