Skip to main content This browser is no longer supported. Show
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support. Distribute your app and the WebView2 Runtime
In this articleWhen releasing an app that uses Microsoft Edge WebView2, you need distribute the WebView2 Runtime, either by distributing the automatically updated Evergreen Runtime, or by distributing a Fixed Version of the Runtime. A WebView2 app depends on the WebView2 Runtime on client machines. When you distribute your WebView2 app, you need to take into account how the WebView2 Runtime is distributed to and updated on client machines. The WebView2 RuntimeThe WebView2 Runtime is a redistributable runtime and serves as the underlying (or backing) web platform for WebView2 apps. The concept is similar to Visual C++ or the .NET Runtime for C++/.NET apps. The WebView2 Runtime contains modified Microsoft Edge binaries that are fine-tuned and tested for WebView2 apps. After the WebView2 Runtime is installed, it doesn't appear as a user-visible browser app. For example, a user doesn't have a browser desktop shortcut or an entry in the Start menu. There are two different ways of distributing and updating the WebView2 Runtime to client machines: the Evergreen distribution mode, and the Fixed Version distribution mode. The Evergreen Runtime distribution modeIn the Evergreen distribution mode, the WebView2 Runtime isn't packaged with your app, but is initially installed onto clients using an online bootstrapper or an offline installer. Afterwards, the WebView2 Runtime is automatically updated on client machines. You can then distribute updates of your WebView2 app that use the latest WebView2 APIs, from the latest WebView2 SDK. The Evergreen distribution mode is recommended for most developers. Pros:
Cons:
The Fixed Version runtime distribution modeIn the Fixed Version distribution mode, you download a specific version of the WebView2 Runtime and package it together with your WebView2 app in your app package. The WebView2 Runtime that you package with your app is used only by your WebView2 app, not by any other apps on the client's machine. Pros:
Cons:
Understanding the options at the Runtime download pageThe Download the WebView2 Runtime section of the Microsoft Edge WebView2 page provides several options for distributing the WebView2 Runtime onto client machines. Understanding the options at this page provides a good introduction, to help decide which approach you want to use. The Evergreen distribution mode is recommended for most apps.
Details about the WebView2 RuntimeWhen distributing your WebView2 app, make sure that the WebView2 Runtime is present on the client machine. This requirement applies to both the Evergreen and Fixed Version distribution modes. If you want to use the Fixed Version distribution mode, you can skip the next couple of sections and jump ahead to Details about the Fixed Version runtime distribution mode. Servicing the WebView2 Runtime through Windows Server Update Services (WSUS)See Windows Server Update Services (WSUS) in Enterprise management of WebView2 Runtimes. Runtime or browser support during development or productionDuring development and testing, a WebView2 app can use either option as the backing web platform:
A production release of a WebView2 app can only use the WebView2 Runtime as the backing web platform, not Microsoft Edge. Microsoft Edge Stable channel isn't supported for WebView2WebView2 apps aren't permitted to use the Stable channel of Microsoft Edge as the backing web platform. This restriction prevents a production release of a WebView2 app from taking a dependency on the browser. A WebView2 app cannot take a dependency on the browser during production, for the following reasons:
The Evergreen WebView2 Runtime will be included as part of the Windows 11 operating system. Various WebView2 apps have installed the Evergreen Runtime on devices with an operating system prior to Windows 11. However, some devices might not have the Runtime pre-installed, so it's a good practice to check whether the Runtime is present on the client. Before your app creates a WebView2, the app should check whether the WebView2 Runtime is present (either by checking a registry key or by calling an API) and install the Runtime if it is missing. The app can do this check when installing or updating your app (recommended), or at app runtime. To check whether the Runtime is present, see Deploying the Evergreen WebView2 Runtime, below. Details about the Evergreen Runtime distribution modeThe Evergreen distribution mode ensures that your WebView2 app is taking advantage of the latest WebView2 features and security updates. The Evergreen distribution mode has the following characteristics:
When you use the Evergreen distribution mode of the WebView2 Runtime, your WebView2 app assumes that clients have the latest Runtime. Your app cannot require a particular version of the WebView2 Runtime for all apps on the client. By the time a new WebView2 SDK package is released, a compatible version of the WebView2 Runtime has already been distributed to clients. Therefore it's OK for your WebView2 app to use the APIs that are in the latest version of the WebView2 SDK. See Understanding browser versions and WebView2. Deploying the Evergreen WebView2 RuntimeOnly one installation of the Evergreen WebView2 Runtime is needed for all Evergreen apps on the device. Several tools are available at Download the WebView2 Runtime to help you deploy the Evergreen Runtime.
Installing the Runtime as per-machine or per-userThe latest bootstrapper and standalone installer support both per-machine and per-user installs of the WebView2 Runtime. If you run the installer from an elevated process or command prompt, the Runtime is installed as per-machine. If you don't run the installer from an elevated process or command prompt, the Runtime will be installed as per-user. However, a per-user install is automatically replaced by a per-machine install, if a per-machine Microsoft Edge Updater is in place. A per-machine Microsoft Edge Updater is included as part of Microsoft Edge, except for the Canary preview channel of Microsoft Edge. Use the following online deployment workflow or offline deployment workflow to ensure that the Runtime is already installed before your app launches. You can adjust your workflow depending on your scenario. Sample code is available in the Samples repo. Detect if a suitable WebView2 Runtime is already installedTo verify that a WebView2 Runtime is installed, use one of the following approaches:
Online-only deploymentIf you have an online-only deployment scenario where users are assumed to have internet access, use the following workflow.
The above workflow has several benefits:
Alternatively, instead of programmatically downloading the bootstrapper on-demand by getting a link, as shown above, you can package the Evergreen Bootstrapper for the WebView2 Runtime with your app. Offline deploymentIf you have an offline deployment scenario, where app deployment has to work entirely offline, use the following workflow.
Test your app for forward-compatibilityThe Web is constantly evolving. In the Evergreen distribution mode, the WebView2 Runtime is automatically kept up to date on the client to provide the latest features and security fixes. If you use Evergreen distribution, to ensure that your WebView2 app stays compatible with the web, you should set up testing infrastructure. Microsoft Edge preview channels (Beta, Dev, and Canary) provide a sneak peek into what is coming next in the WebView2 Runtime. Test your WebView2 app regularly against a Microsoft Edge preview channel, and update your app or report issues if issues arise. Canary is the recommended preview channel, because it ships at the fastest cadence and has the newest APIs. To help you decide which channel is right, see Overview of the Microsoft Edge channels. You can Download Microsoft Edge Insider Channels on your test environment, and use regkey or environment variables to indicate the channel preference for your testing app. See CreateCoreWebView2EnvironmentWithOptions. You can also use WebDriver to automate WebView2 testing, as described in Automate, and test WebView2 with Microsoft Edge WebDriver. Feature-detect when using recent APIsIf you use the Evergreen mode, when your WebView2 app uses a new WebView2 API from a recent SDK, you should use an approach such as QueryInterface or try-catch to make sure the new API is present on the client's machine. This feature-detecting is a best practice, because there are cases where the WebView2 Runtime isn't updated. Even if you use the Evergreen distribution mode, the WebView2 Runtime might not be updated, for the following reasons:
The update policies for Microsoft Edge and the WebView2 Runtime are separate. Even if the IT Admin has disabled automatic updates of Microsoft Edge, the WebView2 Runtime is still automatically updated, unless the Admin turns off Runtime updating. If the Admin disables updating Microsoft Edge (which is somewhat common), that doesn't affect which WebView2 APIs are available on the client machine. See Feature-detecting to test whether the installed Runtime supports recently added APIs. Details about the Fixed Version runtime distribution modeFor constrained environments with strict compatibility requirements, consider using the Fixed Version distribution mode. The Fixed Version distribution mode was previously called bring-your-own. In the Fixed Version distribution mode, you control the timing of updates to the WebView2 Runtime for your app. You download a specific version of the WebView2 Runtime and then package it with your WebView2 app. The WebView2 Runtime on the client isn't automatically updated. Instead, you periodically update the WebView2 Runtime that's packaged and distributed together with your updated app. The Fixed Version approach doesn't use a registry key for the WebView2 Runtime. The Fixed Version binaries are over 250 MB and will make your app package larger by that amount. To use the Fixed Version distribution mode:
Known issues for Fixed Version
Files to ship with the appThe WebView2Loader code needs to be shipped with the app. This can be done by statically linking WebView2Loader.lib into the app binaries, or by including the WebView2Loader.dll that matches the app's architecture. Usually this is handled automatically for you by Visual Studio when using the .targets file in the WebView2 SDK, but there may be cases when you need to manually specify what files to publish with your app. WebView2Loader.dll is a native and architecture-specific binary, so you need to include all flavors of this binary that you expect your app to run in. For example:
Example native app folder structure: \<myApp> \WebView2Loader.dllFor .NET managed apps, you also need to include the WebView2 .NET assemblies for the core WebView2 functionality (Microsoft.Web.WebView2.Core.dll) and for the WPF/WinForms-specific functionality (Microsoft.Web.WebView2.Winforms.dll or Microsoft.Web.WebView2.WPF.dll). Example managed app folder structure: \<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)FeedbackSubmit and view feedback for How do I Uninstall Microsoft Edge enterprise?Open the Settings app in Windows 10 by clicking the Start button and selecting the gear icon. When the Settings window opens, click Apps. 2. In the “Apps & features” window, scroll down to “Microsoft Edge.” Select that item and click the Uninstall button.
Why does Microsoft not let me Uninstall Edge?Microsoft Edge is the web browser recommended by Microsoft and is the default web browser for Windows. Because Windows supports applications that rely on the web platform, our default web browser is an essential component of our operating system and can't be uninstalled.
Can not install the same Microsoft Edge version that is currently running?Can not install the same Microsoft Edge version that is currently running. Please close Microsoft Edge and try again. Close Microsoft Edge and try again. If you're still seeing this error, wait a couple minutes and try again.
How do I Uninstall Microsoft Edge installer?If you did install one of those builds, you can remove it by first opening up the 'Settings' app on your Windows 10 PC. Next, click on 'Apps' and then find the version of Microsoft Edge in the apps list. Select it and click the 'Uninstall' button and it will be removed from your PC.
|