CoreWebView2Environment.CreateAsync(String, String, CoreWebView2EnvironmentOptions) Method
Definition
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 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 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 _{Executable File Name}.WebView2_ folder 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
overriden 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.
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 forWEBVIEW2_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.
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 the following error if it detects that too many previous WebView2 Runtime versions exist.
ERROR_DISK_FULL
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.
WEBVIEW2_MAX_INSTANCES
If the Webview depends upon an installed WebView2 Runtime version and it is uninstalled, any subsequent creation fails with the following error.
ERROR_PRODUCT_UNINSTALLED
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.