Microsoft.Web.WebView2.WinForms

This class is a bundle of the most common parameters used to create and instances. Its main purpose is to be set to in order to customize the environment and/or controller used by a during implicit initialization.

This class isn't intended to contain all possible environment or controller customization options. If you need complete control over the environment and/or controller used by a WebView2 control then you'll need to initialize the control explicitly by creating your own environment (with ) and/or controller options (with ) and passing them to *before* you set the property to anything. See the class documentation for an initialization overview.

Creates a new instance of with default data for all properties.

Gets or sets the value to pass as the browserExecutableFolder parameter of when creating an environment with this instance.

Gets or sets the value to pass as the userDataFolder parameter of when creating an environment with this instance.

Gets or sets the value to use for the Language property of the CoreWebView2EnvironmentOptions parameter passed to when creating an environment with this instance.

Gets or sets the value to use for the ProfileName property of the CoreWebView2ControllerOptions parameter passed to CreateCoreWebView2ControllerWithOptionsAsync when creating an controller with this instance.

Gets or sets the value to pass as the AdditionalBrowserArguments parameter of which is passed to when creating an environment with this instance.

Gets or sets the value to use for the IsInPrivateModeEnabled property of the CoreWebView2ControllerOptions parameter passed to CreateCoreWebView2ControllerWithOptionsAsync when creating an controller with this instance.

Create a using the current values of this instance's properties.

A task which will provide the created environment on completion, or null if no environment-related options are set. As long as no other properties on this instance are changed, repeated calls to this method will return the same task/environment as earlier calls. If some other property is changed then the next call to this method will return a different task/environment.

Creates a using the current values of this instance's properties.

A object or null if no controller-related properties are set. Thrown if the parameter environment is null.

Control to embed WebView2 in WinForms.

Create a new WebView2 WinForms control. After construction the property is null. Call to initialize the underlying .

This control is effectively a wrapper around the WebView2 COM API, which you can find documentation for here: https://aka.ms/webview2 You can directly access the underlying ICoreWebView2 interface and all of its functionality by accessing the property. Some of the most common COM functionality is also accessible directly through wrapper methods/properties/events on the control. Upon creation, the control's CoreWebView2 property will be null. This is because creating the CoreWebView2 is an expensive operation which involves things like launching Edge browser processes. There are two ways to cause the CoreWebView2 to be created: 1) Call the method. This is referred to as explicit initialization. 2) Set the property. This is referred to as implicit initialization. Either option will start initialization in the background and return back to the caller without waiting for it to finish. To specify options regarding the initialization process, either pass your own to EnsureCoreWebView2Async or set the control's property prior to initialization. When initialization has finished (regardless of how it was triggered) then the following things will occur, in this order: 1) The control's event will be invoked. If you need to perform one time setup operations on the CoreWebView2 prior to its use then you should do so in a handler for that event. 2) If a Uri has been set to the property then the control will start navigating to it in the background (i.e. these steps will continue without waiting for the navigation to finish). 3) The Task returned from will complete. For more details about any of the methods/properties/events involved in the initialization process, see its specific documentation. Accelerator key presses (e.g. Ctrl+P) that occur within the control will fire standard key press events such as OnKeyDown. You can suppress the control's default implementation of an accelerator key press (e.g. printing, in the case of Ctrl+P) by setting the Handled property of its EventArgs to true. Also note that the underlying browser process is blocked while these handlers execute, so: You should avoid doing a lot of work in these handlers. Some of the WebView2 and CoreWebView2 APIs may throw errors if invoked within these handlers due to being unable to communicate with the browser process. If you need to do a lot of work and/or invoke WebView2 APIs in response to accelerator keys then consider kicking off a background task or queuing the work for later execution on the UI thread.

Cleans up any resources being used.

true if managed resources should be disposed; otherwise, false.

Overrides the base OnPaint event to have custom actions in designer mode

The graphics devices which is the source

Overrides the base WndProc events to handle specific window messages.

The Message object containing the HWND window message and parameters

Gets or sets a bag of options which are used during initialization of the control's . This property cannot be modified (an exception will be thrown) after initialization of the control's CoreWebView2 has started.

Thrown if initialization of the control's CoreWebView2 has already started.

Explicitly trigger initialization of the control's .

A pre-created that should be used to create the . Creating your own environment gives you control over several options that affect how the is initialized. If you pass null (the default value) then a default environment will be created and used automatically. A pre-created that should be used to create the . Creating your own controller options gives you control over several options that affect how the is initialized. If you pass a controllerOptions to this method then it will override any settings specified on the property. If you pass null (the default value) and no value has been set to then a default controllerOptions will be created and used automatically. A Task that represents the background initialization process. When the task completes then the property will be available for use (i.e. non-null). Note that the control's event will be invoked before the task completes or on exceptions. 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 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, calling this method with a different environment after initialization has begun will result in an . For example, this can happen if you begin initialization by setting the property and then call this method with a new environment, if you begin initialization with 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 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. Thrown if this method is called with a different environment than when it was initialized. See Remarks for more info. Thrown if this instance of is already disposed, or if the calling thread isn't the thread which created this object (usually the UI thread). See for more info. 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.

Explicitly trigger initialization of the control's .

A pre-created that should be used to create the . Creating your own environment gives you control over several options that affect how the is initialized. If you pass null then a default environment will be created and used automatically. A Task that represents the background initialization process. When the task completes then the property will be available for use (i.e. non-null). Note that the control's event will be invoked before the task completes or on exceptions. 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 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, calling this method with a different environment after initialization has begun will result in an . For example, this can happen if you begin initialization by setting the property and then call this method with a new environment, if you begin initialization with 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 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. Thrown if this method is called with a different environment than when it was initialized. See Remarks for more info. Thrown if this instance of is already disposed, or if the calling thread isn't the thread which created this object (usually the UI thread). See for more info. 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.

This is the private function which implements the actual background initialization task. Cannot be called if the control is already initialized or has been disposed.

The environment to use to create the . If that is null then a default environment is created with and its default parameters. The controllerOptions to use to create the . If that is null then a default controllerOptions is created with its default parameters. A task representing the background initialization process. All the event handlers added here need to be removed in .

Protected CreateParams property. Used to set custom window styles to the forms HWND.

Protected VisibilityChanged handler.

Protected SizeChanged handler.

Protected Select method: override this to capture tab direction when WebView control is activated

Protected OnGotFocus handler.

Protected OnParentChanged handler.

True if initialization finished successfully and the control is not disposed yet.

Recursive retrieval of the parent control

The control to get the parent for The root parent control

The underlying CoreWebView2. Use this property to perform more operations on the WebView2 content than is exposed on the WebView2. This value is null until it is initialized and the object itself has undefined behaviour once the control is disposed. You can force the underlying CoreWebView2 to initialize via the method.

Thrown if the calling thread isn't the thread which created this object (usually the UI thread). See for more info.

The zoom factor for the WebView.

Enable/disable external drop.

The Source property is the URI of the top level document of the WebView2. Setting the Source is equivalent to calling . Setting the Source will trigger initialization of the , if not already initialized. The default value of Source is null, indicating that the is not yet initialized.

Specified value is not an absolute . Specified value is null and the control is initialized.

Returns true if the webview can navigate to a next page in the navigation history via the method. This is equivalent to the . If the underlying is not yet initialized, this property is false.

Returns true if the webview can navigate to a previous page in the navigation history via the method. This is equivalent to the . If the underlying is not yet initialized, this property is false.

The default background color for the WebView.

Executes the provided script in the top level document of the . This is equivalent to .

Reloads the top level document of the . This is equivalent to .

Navigates to the next page in navigation history. This is equivalent to . If the underlying is not yet initialized, this method does nothing.

Navigates to the previous page in navigation history. This is equivalent to . If the underlying is not yet initialized, this method does nothing.

Renders the provided HTML as the top level document of the . This is equivalent to .

The underlying is not yet initialized. Thrown when browser process has unexpectedly and left this control in an invalid state. We are considering throwing a different type of exception for this case in the future. The htmlContent parameter may not be larger than 2 MB (2 * 1024 * 1024 bytes) in total size. The origin of the new page is about:blank.

Stops any in progress navigation in the . This is equivalent to . If the underlying is not yet initialized, this method does nothing.

This event is triggered either 1) when the control's has finished being initialized (regardless of how it was triggered or whether it succeeded) but before it is used for anything OR 2) the initialization failed. You should handle this event if you need to perform one time setup operations on the CoreWebView2 which you want to affect all of its usages (e.g. adding event handlers, configuring settings, installing document creation scripts, adding host objects).

This sender will be the WebView2 control, whose CoreWebView2 property will now be valid (i.e. non-null) for the first time if is true. Unlikely this event can fire second time (after reporting initialization success first) if the initialization is followed by navigation which fails.

NavigationStarting dispatches before a new navigate starts for the top level document of the . This is equivalent to the event.

NavigationCompleted dispatches after a navigate of the top level document completes rendering either successfully or not. This is equivalent to the event.

WebMessageReceived dispatches after web content sends a message to the app host via chrome.webview.postMessage. This is equivalent to the event.

SourceChanged dispatches after the property changes. This may happen during a navigation or if otherwise the script in the page changes the URI of the document. This is equivalent to the event.

ContentLoading dispatches after a navigation begins to a new URI and the content of that URI begins to render. This is equivalent to the event.

ZoomFactorChanged dispatches when the property changes. This is equivalent to the event.

Required designer variable.

Required method for Designer support - do not modify the contents of this method with the code editor.