CoreWebView2Environment.CreateAsync Method
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
Creates a WebView2 Environment using the installed or a custom WebView2 Runtime version.
public static System.Threading.Tasks.Task<Microsoft.Web.WebView2.Core.CoreWebView2Environment> CreateAsync (string browserExecutableFolder = default, string userDataFolder = default, Microsoft.Web.WebView2.Core.CoreWebView2EnvironmentOptions options = default);static member CreateAsync : string * string * Microsoft.Web.WebView2.Core.CoreWebView2EnvironmentOptions -> System.Threading.Tasks.Task<Microsoft.Web.WebView2.Core.CoreWebView2Environment>Public Shared Function CreateAsync (Optional browserExecutableFolder As String = Nothing, Optional userDataFolder As String = Nothing, Optional options As CoreWebView2EnvironmentOptions = Nothing) As Task(Of CoreWebView2Environment)Parameters
- browserExecutableFolder
- String
The relative path to the folder that contains a custom version of WebView2 Runtime.
To use a fixed version of the WebView2 Runtime, pass the
folder path that contains the fixed version of the WebView2 Runtime
to browserExecutableFolder. BrowserExecutableFolder supports both relative
(to the application's executable) and absolute file paths. To create WebView2 controls
that use the installed version of the WebView2 Runtime that exists on
user machines, pass a null or empty string to
browserExecutableFolder. In this scenario, the API tries to
find a compatible version of the WebView2 Runtime that is installed
on the user machine (first at the machine level, and then per user)
using the selected channel preference. The path of fixed version of
the WebView2 Runtime should not contain \Edge\Application\. When
such a path is used, the API fails with ERROR_NOT_SUPPORTED.
- userDataFolder
- String
The user data folder location for WebView2.
The path is either an absolute file path or a relative file path that is interpreted as relative to the compiled code for the current process. The default user data folder {Executable File Name}.WebView2 is created in the same directory next to the compiled code for the app. WebView2 creation fails if the compiled code is running in a directory in which the process does not have permission to create a new directory. The app is responsible to clean up the associated user data folder when it is done.
- options
- CoreWebView2EnvironmentOptions
Options used to create WebView2 Environment.
As a browser process may be shared among WebViews, WebView creation
fails if the specified options does not match the options of
the WebViews that are currently running in the shared browser
process.
Returns
Remarks
The default channel search order is the WebView2 Runtime, Beta, Dev, and Canary. When an override WEBVIEW2_RELEASE_CHANNEL_PREFERENCE environment variable or applicable releaseChannelPreference registry value is set to 1, the channel search order is reversed.
To use a fixed version of the WebView2 Runtime, pass the relative folder path that contains the fixed version of the WebView2 Runtime to browserExecutableFolder. To create WebView2 controls that use the installed version of the WebView2 Runtime that exists on user machines, pass a null or empty string to browserExecutableFolder. In this scenario, the API tries to find a compatible version of the WebView2 Runtime that is installed on the user machine (first at the machine level, and then per user) using the selected channel preference. The path of fixed version of the WebView2 Runtime should not contain \Edge\Application\. When such a path is used, the API fails with the following error.
The browserExecutableFolder, userDataFolder, and options may be overridden by values either specified in environment variables or in the registry.
When creating a CoreWebView2Environment the following environment variables are verified.
-
WEBVIEW2_BROWSER_EXECUTABLE_FOLDER: -
WEBVIEW2_USER_DATA_FOLDER: -
WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS: -
WEBVIEW2_RELEASE_CHANNEL_PREFERENCE:
If browser executable folder or user data folder is specified in an environment variable or in the registry, the specified browserExecutableFolder or userDataFolder values are overridden. If additional browser arguments are specified in an environment variable or in the registry, it is appended to the corresponding value in the specified options.
While not strictly overrides, additional environment variables may be set.
| Value | Description |
|---|---|
WEBVIEW2_WAIT_FOR_SCRIPT_DEBUGGER | When found with a non-empty value, this indicates that the WebView is being launched under a script debugger. In this case, the WebView issues a Page.waitForDebugger CDP command that runs the script inside the WebView to pause on launch, until a debugger issues a corresponding Runtime.runIfWaitingForDebugger CDP command to resume the runtime. Note that this environment variable does not have a registry key equivalent. |
WEBVIEW2_PIPE_FOR_SCRIPT_DEBUGGER | When found with a non-empty value, it indicates that the WebView is being launched under a script debugger that also supports host apps that use multiple WebViews. The value is used as the identifier for a named pipe that is opened and written to when a new WebView is created by the host app. The payload should match the payload of the remote-debugging-port JSON target and an external debugger may use it to attach to a specific WebView instance. The format of the pipe created by the debugger should be \\.\pipe\WebView2\Debugger\{app_name}\{pipe_name}, where the following are true.
To enable debugging of the targets identified by the JSON, you must set the
If both |
If none of those environment variables exist, then the registry is examined next.
-
[{Root}]\Software\Policies\Microsoft\Edge\WebView2\BrowserExecutableFolder "{AppId}"="": -
[{Root}]\Software\Policies\Microsoft\Edge\WebView2\ReleaseChannelPreference "{AppId}"="": -
[{Root}]\Software\Policies\Microsoft\Edge\WebView2\AdditionalBrowserArguments "{AppId}"="": -
[{Root}]\Software\Policies\Microsoft\Edge\WebView2\UserDataFolder "{AppId}"="":
Use a group policy under Administrative Templates > Microsoft Edge WebView2 to configure browser executable folder and release channel preference.
| Value | Description |
|---|---|
ERROR_DISK_FULL | In the unlikely scenario where some instances of WebView are open during a browser update, the deletion of the previous WebView2 Runtime may be blocked. To avoid running out of disk space, a new WebView creation fails with this error if it detects that too many previous WebView2 Runtime versions exist. |
COREWEBVIEW2_MAX_INSTANCES | The default maximum number of WebView2 Runtime versions allowed is 20. To override the maximum number of the previous WebView2 Runtime versions allowed, set the value of the following environment variable. |
ERROR_PRODUCT_UNINSTALLED | If the Webview depends upon an installed WebView2 Runtime version and it is uninstalled, any subsequent creation fails with this error. |
First verify with Root as HKLM and then HKCU. AppId is first set to the Application User Model ID of the process, then if no corresponding registry key, the AppId is set to the compiled code name of the process, or if that is not a registry key then *. If an override registry key is found, use the browserExecutableFolder and userDataFolder registry values as replacements and append additionalBrowserArguments registry values for the corresponding values in the provided options.