Share via


WebView2 Class

Definition

Control to embed WebView2 in WinForms.

public class WebView2 : System.Windows.Forms.Control
public class WebView2 : System.Windows.Forms.Control, System.ComponentModel.ISupportInitialize
type WebView2 = class
    inherit Control
type WebView2 = class
    inherit Control
    interface ISupportInitialize
Public Class WebView2
Inherits Control
Public Class WebView2
Inherits Control
Implements ISupportInitialize
Inheritance
WebView2
Implements

Remarks

This control is effectively a wrapper around the WebView2 COM API. You can directly access the underlying ICoreWebView2 interface and all of its functionality by accessing the CoreWebView2 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 EnsureCoreWebView2Async(CoreWebView2Environment) method. This is referred to as explicit initialization. 2) Set the Source 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 CoreWebView2Environment to EnsureCoreWebView2Async or set the control's CreationProperties 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 CoreWebView2InitializationCompleted 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 Source 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 EnsureCoreWebView2Async(CoreWebView2Environment) 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:

  1. You should avoid doing a lot of work in these handlers.
  2. 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.

Constructors

WebView2()

Create a new WebView2 WinForms control. After construction the CoreWebView2 property is null. Call EnsureCoreWebView2Async(CoreWebView2Environment, CoreWebView2ControllerOptions) to initialize the underlying CoreWebView2.

Properties

AllowDrop
AllowExternalDrop

Enable/disable external drop.

CanGoBack

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

CanGoForward

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

ContextMenu
ContextMenuStrip
CoreWebView2

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 EnsureCoreWebView2Async(CoreWebView2Environment, CoreWebView2ControllerOptions) method.

CreateParams

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

CreationProperties

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

DefaultBackgroundColor

The default background color for the WebView.

Font
IsInDesignMode
Source

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

Text
ZoomFactor

The zoom factor for the WebView.

Methods

Dispose(Boolean)

Cleans up any resources being used.

EnsureCoreWebView2Async(CoreWebView2Environment, CoreWebView2ControllerOptions)

Explicitly trigger initialization of the control's CoreWebView2.

EnsureCoreWebView2Async(CoreWebView2Environment)

Explicitly trigger initialization of the control's CoreWebView2.

ExecuteScriptAsync(String)

Executes the provided script in the top level document of the WebView2. This is equivalent to ExecuteScriptAsync(String).

GoBack()

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

GoForward()

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

NavigateToString(String)

Renders the provided HTML as the top level document of the WebView2. This is equivalent to NavigateToString(String).

OnEnter(EventArgs)

Protected focus handler.

OnGotFocus(EventArgs)

Protected OnGotFocus handler.

OnPaint(PaintEventArgs)

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

OnParentChanged(EventArgs)

Protected OnParentChanged handler.

OnSizeChanged(EventArgs)

Protected SizeChanged handler.

OnVisibleChanged(EventArgs)

Protected VisibilityChanged handler.

ProcessCmdKey(Message, Keys)

Protected command key handler.

Reload()

Reloads the top level document of the WebView2. This is equivalent to Reload().

Select(Boolean, Boolean)

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

Stop()

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

WndProc(Message)

Overrides the base WndProc events to handle specific window messages.

Events

AcceleratorKeyPressed

AcceleratorKeyPressed dispatches when an accelerator key is pressed and before it gets handled by the WebView2. You can write a custom handler to suppress handling by the Webview by doing e.Handled = true;.

ContentLoading

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

CoreWebView2InitializationCompleted

This event is triggered either 1) when the control's CoreWebView2 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).

CoreWebView2Ready

This event is triggered when the control's CoreWebView2 has finished being initialized (regardless of how initialization was triggered) but before it is used for anything. 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).

NavigationCompleted

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

NavigationStarting

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

SourceChanged

SourceChanged dispatches after the Source 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 SourceChanged event.

WebMessageReceived

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

ZoomFactorChanged

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

Explicit Interface Implementations

ISupportInitialize.BeginInit()
ISupportInitialize.EndInit()

Applies to