IWebView2.EnsureCoreWebView2Async 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.
Overloads
| EnsureCoreWebView2Async(CoreWebView2Environment) |
Explicitly triggers initialization of the control's CoreWebView2. See the WebView2 class documentation for an initialization overview. |
| EnsureCoreWebView2Async(CoreWebView2Environment, CoreWebView2ControllerOptions) |
Explicitly triggers initialization of the control's CoreWebView2. See the WebView2 class documentation for an initialization overview. |
EnsureCoreWebView2Async(CoreWebView2Environment)
Explicitly triggers initialization of the control's CoreWebView2. See the WebView2 class documentation for an initialization overview.
public System.Threading.Tasks.Task EnsureCoreWebView2Async (Microsoft.Web.WebView2.Core.CoreWebView2Environment environment);abstract member EnsureCoreWebView2Async : Microsoft.Web.WebView2.Core.CoreWebView2Environment -> System.Threading.Tasks.TaskPublic Function EnsureCoreWebView2Async (environment As CoreWebView2Environment) As TaskParameters
- environment
- CoreWebView2Environment
A pre-created CoreWebView2Environment that should be used to create the CoreWebView2.
Creating your own environment gives you control over several options that affect how the CoreWebView2 is initialized.
If you pass an environment to this method then it will override any settings specified on the CreationProperties property.
If you pass null and no value has been set to CreationProperties then a default environment will be created and used automatically.
Returns
A Task that represents the background initialization process. When the task completes then the CoreWebView2 property will be available for use (i.e. non-null). Note that the control's CoreWebView2InitializationCompleted event will be invoked before the task completes.
Exceptions
Thrown if this method is called with a different environment than when it was initialized. See Remarks for more info.
Thrown if the calling thread isn't the thread which created this object (usually the UI thread). See VerifyAccess() for more info. May also be thrown if Current is null, which probably indicates that the application's event loop hasn't started yet. May also be thrown if the browser process has crashed unexpectedly and left the control in an invalid state. We are considering throwing a different type of exception for this case in the future.
Thrown if Dispose() has already been called on the control.
Remarks
Unless previous initialization has already failed, calling this method additional times with the same parameter will have no effect (any specified environment is ignored) and return the same Task as the first call. Unless previous initialization has already failed, calling this method after initialization has been implicitly triggered by setting the Source property will have no effect if no environment is given and simply return a Task representing that initialization already in progress, unless previous initialization has already failed. Unless previous initialization has already failed, calling this method with a different environment after initialization has begun will result in an ArgumentException. For example, this can happen if you begin initialization by setting the Source property and then call this method with a new environment, if you begin initialization with CreationProperties and then call this method with a new environment, or if you begin initialization with one environment and then call this method with no environment specified. When this method is called after previous initialization has failed, it will trigger initialization of the control's CoreWebView2 again. Note that even though this method is asynchronous and returns a Task, it still must be called on the UI thread like most public functionality of most UI controls.
See also
Applies to
EnsureCoreWebView2Async(CoreWebView2Environment, CoreWebView2ControllerOptions)
Explicitly triggers initialization of the control's CoreWebView2. See the WebView2 class documentation for an initialization overview.
public System.Threading.Tasks.Task EnsureCoreWebView2Async (Microsoft.Web.WebView2.Core.CoreWebView2Environment environment = default, Microsoft.Web.WebView2.Core.CoreWebView2ControllerOptions controllerOptions = default);abstract member EnsureCoreWebView2Async : Microsoft.Web.WebView2.Core.CoreWebView2Environment * Microsoft.Web.WebView2.Core.CoreWebView2ControllerOptions -> System.Threading.Tasks.TaskPublic Function EnsureCoreWebView2Async (Optional environment As CoreWebView2Environment = Nothing, Optional controllerOptions As CoreWebView2ControllerOptions = Nothing) As TaskParameters
- environment
- CoreWebView2Environment
A pre-created CoreWebView2Environment that should be used to create the CoreWebView2.
Creating your own environment gives you control over several options that affect how the CoreWebView2 is initialized.
If you pass an environment to this method then it will override any settings specified on the CreationProperties property.
If you pass null (the default value) and no value has been set to CreationProperties then a default environment will be created and used automatically.
- controllerOptions
- CoreWebView2ControllerOptions
A pre-created CoreWebView2ControllerOptions that should be used to create the CoreWebView2.
Creating your own controller options gives you control over several options that affect how the CoreWebView2 is initialized.
If you pass a controllerOptions to this method then it will override any settings specified on the CreationProperties property.
If you pass null (the default value) and no value has been set to CreationProperties then a default controllerOptions will be created and used automatically.
Returns
A Task that represents the background initialization process. When the task completes then the CoreWebView2 property will be available for use (i.e. non-null). Note that the control's CoreWebView2InitializationCompleted event will be invoked before the task completes.
Exceptions
Thrown if this method is called with a different environment than when it was initialized. See Remarks for more info.
Thrown if the calling thread isn't the thread which created this object (usually the UI thread). See VerifyAccess() for more info. May also be thrown if Current is null, which probably indicates that the application's event loop hasn't started yet. May also be thrown if the browser process has crashed unexpectedly and left the control in an invalid state. We are considering throwing a different type of exception for this case in the future.
Thrown if Dispose() has already been called on the control.
Remarks
Unless previous initialization has already failed, calling this method additional times with the same parameter will have no effect (any specified environment is ignored) and return the same Task as the first call. Unless previous initialization has already failed, calling this method after initialization has been implicitly triggered by setting the Source property will have no effect if no environment is given and simply return a Task representing that initialization already in progress, unless previous initialization has already failed. Unless previous initialization has already failed, calling this method with a different environment after initialization has begun will result in an ArgumentException. For example, this can happen if you begin initialization by setting the Source property and then call this method with a new environment, if you begin initialization with CreationProperties and then call this method with a new environment, or if you begin initialization with one environment and then call this method with no environment specified. When this method is called after previous initialization has failed, it will trigger initialization of the control's CoreWebView2 again. Note that even though this method is asynchronous and returns a Task, it still must be called on the UI thread like most public functionality of most UI controls.
The following summarizes the possible error values and a description of why these errors occur.
| Error Value | Description | |
|---|---|---|
HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED) | *\\Edge\\Application* path used in browserExecutableFolder. | |
HRESULT_FROM_WIN32(ERROR_INVALID_STATE) | Specified options do not match the options of the WebViews that are currently running in the shared browser process. | |
HRESULT_FROM_WIN32(ERROR_INVALID_WINDOW_HANDLE) | WebView2 Initialization failed due to an invalid host HWND parentWindow. | |
HRESULT_FROM_WIN32(ERROR_DISK_FULL) | WebView2 Initialization failed due to reaching the maximum number of installed runtime versions. | |
HRESULT_FROM_WIN32(ERROR_PRODUCT_UNINSTALLED | If the Webview depends upon an installed WebView2 Runtime version and it is uninstalled. | |
HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND) | Could not find Edge installation. | |
HRESULT_FROM_WIN32(ERROR_FILE_EXISTS) | User data folder cannot be created because a file with the same name already exists. | |
E_ACCESSDENIED | Unable to create user data folder, Access Denied. | |
E_FAIL | Edge runtime unable to start. |