CoreWebView2Environment.CreateCoreWebView2ControllerAsync 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
| CreateCoreWebView2ControllerAsync(IntPtr, CoreWebView2ControllerOptions) |
Create a new WebView with options. |
| CreateCoreWebView2ControllerAsync(IntPtr) |
Asynchronously creates a new WebView. |
CreateCoreWebView2ControllerAsync(IntPtr, CoreWebView2ControllerOptions)
Create a new WebView with options.
public System.Threading.Tasks.Task<Microsoft.Web.WebView2.Core.CoreWebView2Controller> CreateCoreWebView2ControllerAsync (IntPtr ParentWindow, Microsoft.Web.WebView2.Core.CoreWebView2ControllerOptions options);member this.CreateCoreWebView2ControllerAsync : nativeint * Microsoft.Web.WebView2.Core.CoreWebView2ControllerOptions -> System.Threading.Tasks.Task<Microsoft.Web.WebView2.Core.CoreWebView2Controller>Public Function CreateCoreWebView2ControllerAsync (ParentWindow As IntPtr, options As CoreWebView2ControllerOptions) As Task(Of CoreWebView2Controller)Parameters
- ParentWindow
-
IntPtr
nativeint
The HWND in which the WebView should be displayed and from which receive input.
- options
- CoreWebView2ControllerOptions
The options contains profileName and inPrivate parameters that could be used to create CoreWebView2Profile, and it can be used to create multiple WebViews with multiple profiles under a single user data directory.
Returns
Remarks
Multiple profiles under single user data directory can share some system resources including memory, CPU footprint, disk space (such as compiled shaders and safebrowsing data) etc.
Applies to
CreateCoreWebView2ControllerAsync(IntPtr)
Asynchronously creates a new WebView.
public System.Threading.Tasks.Task<Microsoft.Web.WebView2.Core.CoreWebView2Controller> CreateCoreWebView2ControllerAsync (IntPtr ParentWindow);member this.CreateCoreWebView2ControllerAsync : nativeint -> System.Threading.Tasks.Task<Microsoft.Web.WebView2.Core.CoreWebView2Controller>Public Function CreateCoreWebView2ControllerAsync (ParentWindow As IntPtr) As Task(Of CoreWebView2Controller)Parameters
- ParentWindow
-
IntPtr
nativeint
The HWND in which the WebView should be displayed and from which receive input.
Returns
Remarks
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.
HWND_MESSAGE is a valid parameter for ParentWindow for an invisible WebView for Windows 8 and above. In this case the window will never become visible. You are not able to reparent the window after you have created the WebView. This is not supported in Windows 7 or below. Passing this parameter in Windows 7 or below will return ERROR_INVALID_WINDOW_HANDLE in the controller callback.
It can also accept a CoreWebView2ControllerOptions which is created by CreateCoreWebView2ControllerOptions() as the second parameter for multiple profiles support. As WebView2 is built on top of Edge browser, it follows Edge's behavior pattern. To create an InPrivate WebView, we gets an off-the-record profile (an InPrivate profile) from a regular profile, then create the WebView with the off-the-record profile. Multiple profiles under single user data directory can share some system resources including memory, CPU footprint, disk space (such as compiled shaders and safebrowsing data) etc.
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 Language, an attempt to create a WebView with a different Language using the same user data folder fails.
WebView creation can fail with `E_UNEXPECTED` if runtime does not have permissions to the user data folder.