WebView2 Class

Definition

Namespace:

Microsoft.Web.WebView2.WinForms

Assembly:

Microsoft.Web.WebView2.WinForms.dll

Package:

Microsoft.Web.WebView2 v1.0.2420.47

Control to embed WebView2 in WinForms.

public class WebView2 : System.Windows.Forms.Control, System.ComponentModel.ISupportInitialize

type WebView2 = class
    inherit Control
    interface ISupportInitialize

Public Class WebView2
Inherits Control
Implements ISupportInitialize

Inheritance

Control

WebView2

Implements

ISupportInitialize

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.
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
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)	Explicitly trigger initialization of the control's CoreWebView2.
EnsureCoreWebView2Async(CoreWebView2Environment, CoreWebView2ControllerOptions)	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).
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.
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

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).
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()