Understand the different WebView2 SDK versions
The NuGet package for the WebView2 SDK contains both a release and prerelease package. Either use a prerelease SDK with a preview channel of Microsoft Edge, or use a release SDK with the WebView2 Runtime.
Prerelease SDK packages are for use during development if you want to test the latest WebView2 APIs, including the experimental APIs, before support for those APIs is added to the Runtime. The Canary channel is recommended, because it has the implementations of the latest APIs. When you want to test and use experimental WebView2 APIs, use the following combination:
- A prerelease version of the WebView2 SDK.
- A preview channel of Microsoft Edge on your development client.
Release SDK packages only contain stable APIs, not experimental APIs. When you're working on a production release of your WebView2 app, use the following combination:
- A release version of the WebView2 SDK.
- The WebView2 Runtime on your development client.
More detail about the prerelease and release SDK packages is provided below.
Use a prerelease version of the SDK along with a preview channel of Microsoft Edge
When developing an Evergreen WebView2 app, regularly test the app against the latest Microsoft Edge preview channel, in addition to testing against the WebView2 Runtime. Because the web platform is constantly evolving, regular testing is the best way to ensure your app will continue to work as intended.
When you use a WebView2 SDK prerelease package, use a Microsoft Edge preview channel on your development client. Preview channels are also called Insiders channels. The Canary preview channel is recommended rather than Beta or Dev, because Canary is most recent and has implementations of the latest experimental APIs.
The SDK prerelease package is a superset of the SDK release package, with method signatures for more, Experimental APIs. Preview channels provide the implementations of the experimental WebView2 APIs. The experimental APIs are subject to change based on your feedback. Avoid using the SDK prerelease package to build production apps.
For information about temporarily pointing your app to a preview channel instead of defaulting to the WebView2 Runtime, see Test upcoming APIs and features.
Use a release version of the SDK along with the Runtime
When you use a WebView2 SDK release package, use the WebView2 Evergreen Runtime on your development client, rather than a Microsoft Edge preview channel. By default, a WebView2 app targets the Runtime rather than Microsoft Edge. By design, the Microsoft Edge Stable channel doesn't support WebView2.
The SDK release package contains all of the stable Win32 C/C++ and .NET APIs, and doesn't include method signatures for experimental APIs. All of the APIs that are in an SDK release package are fully supported, in an equal or higher build number of the WebView2 Runtime.
The SDK release package contains the following components:
- Win32 C/C++ APIs.
- .NET APIs: WPF, WinForms, and Core.
For more information about automatic updating of the Evergreen Runtime, see Distribute your app and the WebView2 Runtime.
Release cadence
New versions of the WebView2 SDK are shipped at the same general cadence as the Microsoft Edge browser, which is approximately every four weeks.
Minimum version and build number to instantiate WebView2
For the client to be able to create a WebView2 instance and use the set of APIs in the WebView2 General Availability release (SDK build 616), the client must have WebView2 Runtime version 86.0.616.0 or higher. Runtime 86.0.616.0 is a special release, because it is the General Availability release.
On a development machine, the client must have either the Microsoft Edge preview channel version 86.0.616.0 or higher, or the WebView2 Runtime version 86.0.616.0 or higher.
Forward compatibility of APIs
The WebView2 release SDK has been forward-compatible ever since version 1 (that is, SDK version 1.0.622.22). You can update your WebView2 app to use the latest APIs from the most recent release version of the SDK. Your app will continue to work on clients because clients automatically have the latest WebView2 Evergreen Runtime.
The WebView2 APIs in an SDK release package are stable and forward-compatible. A WebView2 API works when using a WebView2 Runtime that has an equal or higher build number as the SDK build number in which the API was introduced. The build number is the third part of the four-part version number for the Webview2 SDK, and of the four-part version number for Microsoft Edge and the WebView2 Runtime.
When you use a WebView2 SDK that has a build number equal to or less than the WebView2 Runtime, every API that you have access to in that SDK works with that version of the Runtime.
When you use a WebView2 SDK that has a build number greater than the WebView2 Runtime, the newer APIs' implementations aren't available in the Runtime.
For example, if an API is introduced in SDK 1.0.900.0, that API would work with Runtime 94.0.900+.0, but not with Runtime 90.0.700.0.
You must coordinate the WebView2 SDK version that you use for development, and the WebView2 Runtime version that's installed on client machines. The client should have a version of the Runtime that supports all of the latest APIs that are in the SDK version you use to develop the app. For full support for the latest APIs in a release version of the SDK, the Runtime on the client must have a build number that's greater than or equal to the SDK build number.
Experimental APIs
To try out new forthcoming features that are in development, use experimental APIs. Experimental APIs are contained in prerelease versions of the WebView2 SDK, but not in release versions of the WebView2 SDK.
Developing with experimental APIs and providing feedback
The experimental APIs in a WebView2 SDK prerelease package aren't guaranteed to be forward-compatible and might be removed in future Runtime updates. When a prerelease version of the WebView2 SDK is initially made available, that SDK only works with Microsoft Edge Canary. Soon after that, the prerelease SDK also works with the Beta and Dev channels. Use a prerelease SDK to try out new APIs early and provide feedback before the new APIs are promoted to become stable, forward-compatible APIs.
For full support of experimental APIs, use a Microsoft Edge preview channel, not the WebView2 Evergreen Runtime. Any experimental APIs that are in a prerelease SDK aren't guaranteed to be forward-compatible. The APIs that are in an SDK release version are forward-compatible. For more information, see Forward compatibility of APIs, above.
The WebView2 team is seeking feedback on experimental WebView2 APIs that might be promoted to Stable in future releases. The experimental APIs are indicated as "experimental" in the WebView2 SDK Reference documentation.
To help you evaluate the experimental APIs and share your feedback, use the WebView2Feedback repo.
Moving from experimental APIs to stable APIs
Once an API has been moved from experimental to stable APIs, you need to move your app's code to the stable API. Using experimental APIs is not recommended for production apps. Follow these practices when moving your app from using experimental APIs to using stable APIs:
In your project in Visual Studio, update your WebView2 SDK package version. See Install the WebView2 SDK in Set up your Dev environment for WebView2.
Update your app's code to use stable APIs instead of experimental APIs (for COM). The stable API will be supported with bug fixes, but the experimental API will be deprecated, and not available in the newer SDK. After the release of an API as stable, the experimental version of that API is supported for two releases, in a deprecated state. In subsequent versions of the SDK, experimental APIs might be modified, removed, or added.
Always use feature detection, to ensure that the stable API is implemented in the user's version of the WebView2 Runtime. See Feature-detecting to test whether the installed Runtime supports recently added APIs, below.
Note for .NET only: In a prerelease WebView2 SDK, the .NET stable APIs will fallback to the corresponding experimental APIs, if the user's WebView2 Runtime has only the experimental API implementation and doesn't have the stable API implementation.
Matching the Runtime version with the SDK version
In the Evergreen distribution approach, the client's WebView2 Runtime automatically updates to the latest version available. However, a user or IT admin might choose to prevent automatic updating of the WebView2 Runtime. The resulting outdated Runtime on the client might cause compatibility issues with your updated WebView2 app that uses new APIs from a recent SDK.
In case updating the WebView2 Runtime is prevented on the client, make sure that you know the minimum build number of the WebView2 Runtime that is required by your app. See Microsoft Edge WebView2. The minimum required Runtime version to support the General Availability release of the SDK (build 616) is older than for the latest Runtime. The latest Runtime supports all APIs that are in the latest SDK release build.
To check the compatibility between specific build numbers of the SDK and the Runtime or Microsoft Edge preview channel, see Release Notes for the WebView2 SDK.
Feature-detecting to test whether the installed Runtime supports recently added APIs
If your app uses the Evergreen Runtime rather than Fixed Version, you should wrap any calls to relatively new WebView2 APIs by using QueryInterface
or try-catch
. There are edge cases where a client's Evergreen Runtime isn't the latest build and therefore falls behind the SDK build number, because the Admin might have turned off updating of the WebView2 Runtime, or the client might be offline.
When you develop a WebView2 app using a recent version of the WebView2 SDK, if you use a recently added API, you should test or "feature-detect" whether that API is present in the client's installed WebView2 Runtime. How your app programmatically tests for API support depends on the coding platform.
Win32 C/C++. When requesting the DLL export
CreateCoreWebView2Environment
and when runningQueryInterface
on anyCoreWebView2
object, test for a return value ofE_NOINTERFACE
. That return value likely indicates that the client's WebView2 Runtime is an older version that doesn't support that interface.For an example of checking for the existence of specific WebView2 APIs in the Runtime, find
try_query
in AppWindow.cpp. This file wraps WebView2 API calls in theCHECK_FAILURE
macro function, defined inCheckFailure.h
..NET and WinUI. Use
try/catch
and check for aNo such interface supported
exception when using methods, properties, and events that were added to more recent versions of the WebView2 SDK. This exception likely indicates that the client's WebView2 Runtime is an older version that doesn't support that API.
If your code determines that an API is unavailable in the client's installed WebView2 Runtime, you should provide graceful fallback for the associated feature, or inform the user that they must update the WebView2 Runtime to use the feature.
This technique is listed as a WebView2 development best practice, at Test whether APIs are supported by the installed WebView2 Runtime.
Feedback
Submit and view feedback for