CoreWebView2Environment.CreateAsync Method

Definition

Namespace:

Microsoft.Web.WebView2.Core

Assembly:

Microsoft.Web.WebView2.Core.dll

Package:

Microsoft.Web.WebView2 v1.0.2849.39

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

Task<CoreWebView2Environment>

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. {app_name} is the host app exe file name, for example, WebView2Example.exe {pipe_name} is the value set for WEBVIEW2_PIPE_FOR_SCRIPT_DEBUGGER To enable debugging of the targets identified by the JSON, you must set the WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS environment variable to send --remote-debugging-port={port_num}, where the following is true. {port_num} is the port on which the CDP server binds. If both WEBVIEW2_PIPE_FOR_SCRIPT_DEBUGGER and WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS environment variables, the WebViews hosted in your app and associated contents may exposed to 3rd party apps such as debuggers. Note that this environment variable does not have a registry key equivalent.

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.