parentWindow is the HWND in which the WebView should be displayed and
from which receive input. The WebView adds a child window to the
provided window before this function returns. Z-order and other things
impacted by sibling window order are affected accordingly. If you want to
move the WebView to a different parent after it has been created, you must
call put_ParentWindow to update tooltip positions, accessibility trees,
and such.
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 is recommended that the app set Application User Model ID for the
process or the app 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.
\snippet AppWindow.cpp RestartManager
The app should retry CreateCoreWebView2Controller upon failure, unless the
error code is HRESULT_FROM_WIN32(ERROR_INVALID_STATE).
When the app retries CreateCoreWebView2Controller 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 with HRESULT_FROM_WIN32(ERROR_INVALID_STATE) if a
running instance using the same user data folder exists, and the Environment
objects have different EnvironmentOptions. 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 will fail.
The creation will fail with E_ABORT if parentWindow is destroyed
before the creation is finished. If this is caused by a call to
DestroyWindow, the creation completed handler will be invoked before
DestroyWindow returns, so you can use this to cancel creation and clean
up resources synchronously when quitting a thread.
In rare cases the creation can fail with E_UNEXPECTED if runtime does not have
permissions to the user data folder.
Asynchronously create a new WebView.
parentWindow is the HWND in which the WebView should be displayed and from which receive input. The WebView adds a child window to the provided window before this function returns. Z-order and other things impacted by sibling window order are affected accordingly. If you want to move the WebView to a different parent after it has been created, you must call put_ParentWindow to update tooltip positions, accessibility trees, and such.
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 is recommended that the app set Application User Model ID for the process or the app window. If none is set, during WebView creation a generated Application User Model ID is set to root window of parentWindow.
\snippet AppWindow.cpp CreateCoreWebView2Controller
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.
\snippet AppWindow.cpp RestartManager
The app should retry CreateCoreWebView2Controller upon failure, unless the error code is HRESULT_FROM_WIN32(ERROR_INVALID_STATE). When the app retries CreateCoreWebView2Controller 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 with HRESULT_FROM_WIN32(ERROR_INVALID_STATE) if a running instance using the same user data folder exists, and the Environment objects have different EnvironmentOptions. 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 will fail.
The creation will fail with E_ABORT if parentWindow is destroyed before the creation is finished. If this is caused by a call to DestroyWindow, the creation completed handler will be invoked before DestroyWindow returns, so you can use this to cancel creation and clean up resources synchronously when quitting a thread.
In rare cases the creation can fail with E_UNEXPECTED if runtime does not have permissions to the user data folder.