CoreWebView2Environment Class
This represents the WebView2 Environment. WebViews created from an environment run on the Browser process specified with environment parameters and objects created from an environment should be used in the same environment. Using it in different environments are not guaranteed to be compatible and may fail.
Summary
| Members | Description |
|---|---|
| BrowserVersionString | Gets the browser version info of the current CoreWebView2Environment, including channel name if it is not the stable channel. |
| UserDataFolder | Gets the user data folder that all CoreWebView2s created from this environment are using. |
| CompareBrowserVersionString | Compares two instances of browser versions correctly and returns an integer that indicates whether the first instance is older, the same as, or newer than the second instance. |
| CreateAsync | Creates a WebView2 Environment using the installed or a custom WebView2 Runtime version. |
| CreateCoreWebView2CompositionControllerAsync | Asynchronously creates a new WebView for use with visual hosting. |
| CreateCoreWebView2ControllerAsync | Asynchronously creates a new WebView. |
| CreateCoreWebView2PointerInfo | Creates an empty CoreWebView2PointerInfo. |
| CreatePrintSettings | Creates the CoreWebView2PrintSettings used by the CoreWebView2.PrintToPdfAsync method. |
| CreateWebResourceRequest | Creates a new CoreWebView2WebResourceRequest object. |
| CreateWebResourceResponse | Creates a new CoreWebView2WebResourceResponse object. |
| CreateWithOptionsAsync | Creates a WebView2 Environment with a custom version of WebView2 Runtime, user data folder, and environment options. |
| GetAvailableBrowserVersionString | Gets the browser version info including channel name if it is not the stable channel or WebView2 Runtime. |
| GetAvailableBrowserVersionString | Gets the browser version info including channel name if it is not the stable channel or WebView2 Runtime where browserExecutableFolder is the relative path to the folder that contains the WebView2 Runtime. |
| BrowserProcessExited | BrowserProcessExited is raised when the collection of WebView2 Runtime processes for the browser process of this CoreWebView2Environment terminate due to browser process failure or normal shutdown (for example, when all associated WebViews are closed), after all resources have been released (including the user data folder). |
| NewBrowserVersionAvailable | NewBrowserVersionAvailable is raised when a newer version of the WebView2 Runtime is installed and available using WebView2. |
Properties
BrowserVersionString
readonly string BrowserVersionString
Gets the browser version info of the current CoreWebView2Environment, including channel name if it is not the stable channel.
It matches the format of the CoreWebView2Environment.GetAvailableBrowserVersionString method. Channel names are beta, dev, and canary.
UserDataFolder
readonly string UserDataFolder
Gets the user data folder that all CoreWebView2s created from this environment are using. This could be either the value passed in by the developer when creating the environment object or the calculated one for default handling. And will always be an absolute path.
Methods
CompareBrowserVersionString
static int CompareBrowserVersionString(string browserVersionString1, string browserVersionString2)
Compares two instances of browser versions correctly and returns an integer that indicates whether the first instance is older, the same as, or newer than the second instance.
browserVersionString1 is one of the version strings to compare. browserVersionString2 is the other version string to compare.
CreateAsync
static
IAsyncOperation<CoreWebView2Environment> CreateAsync()
Creates a WebView2 Environment using the installed or a custom WebView2 Runtime version.
CreateCoreWebView2CompositionControllerAsync
IAsyncOperation<CoreWebView2CompositionController> CreateCoreWebView2CompositionControllerAsync(CoreWebView2ControllerWindowReference ParentWindow)
Asynchronously creates a new WebView for use with visual hosting.
ParentWindow will be the HWND that the app will receive pointer/mouse input meant for the WebView (and will need to use CoreWebView2CompositionController.SendMouseInput or CoreWebView2CompositionController.SendPointerInput to forward). If the app moves the WebView visual tree to underneath a different window, then it needs to set CoreWebView2Controller.ParentWindow to update the new parent HWND of the visual tree.
Set CoreWebView2CompositionController.RootVisualTarget property on the created CoreWebView2CompositionController to provide a visual to host the browser's visual tree.
It is recommended that the application set Application User Model ID for the process or the application window. If none is set, during WebView creation a generated Application User Model ID is set to root window of ParentWindow.
CreateCoreWebView2Controller is supported in the following versions of Windows:
- Windows 11
- Windows 10
- Windows Server 2019
- Windows Server 2016
CreateCoreWebView2ControllerAsync
IAsyncOperation<CoreWebView2Controller> CreateCoreWebView2ControllerAsync(CoreWebView2ControllerWindowReference ParentWindow)
Asynchronously creates a new WebView. The WebView adds a child window to the provided window during WebView creation. Z-order and other things impacted by sibling window order are affected accordingly.
It is recommended that the application set Application User Model ID for the process or the application window. If none is set, during WebView creation a generated Application User Model ID is set to root window of ParentWindow.
It is recommended that the app handles restart manager messages, to gracefully restart it in the case when the app is using the WebView2 Runtime from a certain installation and that installation is being uninstalled. For example, if a user installs a version of the WebView2 Runtime and opts to use another version of the WebView2 Runtime for testing the app, and then uninstalls the 1st version of the WebView2 Runtime without closing the app, the app restarts to allow un-installation to succeed.
When the app retries CreateCoreWebView2ControllerAsync upon failure, it is recommended that the app restarts from creating a new WebView2 Environment. If a WebView2 Runtime update happens, the version associated with a WebView2 Environment may have been removed and causing the object to no longer work. Creating a new WebView2 Environment works since it uses the latest version.
WebView creation fails if a running instance using the same user data folder exists, and the Environment objects have different CoreWebView2EnvironmentOptions. For example, if a WebView was created with one CoreWebView2EnvironmentOptions.Language, an attempt to create a WebView with a different CoreWebView2EnvironmentOptions.Language using the same user data folder fails.
CreateCoreWebView2PointerInfo
CoreWebView2PointerInfo CreateCoreWebView2PointerInfo()
Creates an empty CoreWebView2PointerInfo. The returned CoreWebView2PointerInfo needs to be populated with all of the relevant info before calling CoreWebView2CompositionController.SendPointerInput.
CreatePrintSettings
CoreWebView2PrintSettings CreatePrintSettings()
Creates the CoreWebView2PrintSettings used by the CoreWebView2.PrintToPdfAsync method.
CreateWebResourceRequest
CoreWebView2WebResourceRequest CreateWebResourceRequest(string uri, string Method, IRandomAccessStream postData, string Headers)
Creates a new CoreWebView2WebResourceRequest object.
uri parameter must be absolute URI. It's also possible to create this object with null headers string and then use the CoreWebView2HttpRequestHeaders to construct the headers line by line.
CreateWebResourceResponse
CoreWebView2WebResourceResponse CreateWebResourceResponse(IRandomAccessStream Content, int StatusCode, string ReasonPhrase, string Headers)
Creates a new CoreWebView2WebResourceResponse object. It is also possible to create this object with empty headers string and then use the CoreWebView2HttpResponseHeaders to construct the headers line by line.
CreateWithOptionsAsync
static
IAsyncOperation<CoreWebView2Environment> CreateWithOptionsAsync(string browserExecutableFolder, string userDataFolder, CoreWebView2EnvironmentOptions options)
Creates a WebView2 Environment with a custom version of WebView2 Runtime, user data folder, and environment options.
GetAvailableBrowserVersionString
static string GetAvailableBrowserVersionString()
Gets the browser version info including channel name if it is not the stable channel or WebView2 Runtime.
GetAvailableBrowserVersionString
static string GetAvailableBrowserVersionString(string browserExecutableFolder)
Gets the browser version info including channel name if it is not the stable channel or WebView2 Runtime where browserExecutableFolder is the relative path to the folder that contains the WebView2 Runtime.
Events
BrowserProcessExited
BrowserProcessExited is raised when the collection of WebView2 Runtime processes for the browser process of this CoreWebView2Environment terminate due to browser process failure or normal shutdown (for example, when all associated WebViews are closed), after all resources have been released (including the user data folder). Multiple app processes can share a browser process by creating their webviews from a CoreWebView2Environment with the same user data folder. When the entire collection of WebView2Runtime processes for the browser process exit, all associated CoreWebView2Environment objects receive the BrowserProcessExited event. Multiple processes sharing the same browser process need to coordinate their use of the shared user data folder to avoid race conditions and unnecessary waits. For example, one process should not clear the user data folder at the same time that another process recovers from a crash by recreating its WebView controls; one process should not block waiting for the event if other app processes are using the same browser process (the browser process will not exit until those other processes have closed their webviews too).
Note this is an event from CoreWebView2Environment, not CoreWebView2. The difference between BrowserProcessExited and CoreWebView2.ProcessFailed is that BrowserProcessExited is raised for any browser process exit (expected or unexpected, after all associated processes have exited too), while CoreWebView2.ProcessFailed is raised for unexpected process exits of any kind (browser, render, GPU, and all other types), or for main frame render process unresponsiveness. To learn more about the WebView2 Process Model, go to Process model.
In the case the browser process crashes, both BrowserProcessExited and CoreWebView2.ProcessFailed events are raised, but the order is not guaranteed. These events are intended for different scenarios. It is up to the app to coordinate the handlers so they do not try to perform reliability recovery while also trying to move to a new WebView2 Runtime version or remove the user data folder.
Type: TypedEventHandler<CoreWebView2Environment, CoreWebView2BrowserProcessExitedEventArgs>
NewBrowserVersionAvailable
NewBrowserVersionAvailable is raised when a newer version of the WebView2 Runtime is installed and available using WebView2. To use the newer version of the browser you must create a new environment and WebView. The event is only raised for new version from the same WebView2 Runtime from which the code is running. When not running with installed WebView2 Runtime, no event is raised.
Because a user data folder is only able to be used by one browser process at a time, if you want to use the same user data folder in the WebViews using the new version of the browser, you must close the environment and instance of WebView that are using the older version of the browser first. Or simply prompt the user to restart the app.
Type: TypedEventHandler<CoreWebView2Environment, Object>