A control to embed web content in a WPF application.
public class WebView2 : System.Windows.Interop.HwndHost
type WebView2 = class inherit HwndHost
Public Class WebView2 Inherits HwndHost
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
- Call the EnsureCoreWebView2Async(CoreWebView2Environment) method. This is referred to as explicit initialization.
- Set the Source property (which could be done from markup, for example). 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(CoreWebView2Environment) or set the control's CreationProperties property prior to initialization.
When initialization has finished (regardless of how it was triggered or whether it succeeded) then the following things will occur, in this order:
- 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.
- If initialization was successful and 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).
- 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.
Because the control's CoreWebView2 is a very heavyweight
object (potentially responsible for multiple running processes and
megabytes of disk space) the control implements IDisposable to provide an explicit means to free it.
Calling Dispose(Boolean) will release the CoreWebView2
and its underlying resources (except any that are also being used by other
WebViews), and reset CoreWebView2 to
null. After Dispose(Boolean) has been called the CoreWebView2 cannot be
re-initialized, and any attempt to use functionality which requires it
will throw an ObjectDisposedException.
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.
Note that this control extends HwndHost in order to embed windows which live outside of the WPF ecosystem. This has some implications regarding the control's input and output behavior as well as the functionality it "inherits" from UIElement and FrameworkElement. See the HwndHost and WPF/Win32 interop documentation for more information.
Gets or sets a bag of options which are used during initialization of the control's CoreWebView2. Setting this property will not work after initialization of the control's CoreWebView2 has started (the old value will be retained). See the WebView2 class documentation for an initialization overview.
The default background color for the WebView.
This property directly exposes DefaultBackgroundColor, see its documentation for more info.
Getting this property before the CoreWebView2Controller has been initialized will retrieve the last value which was
set to it, or
The top-level Uri which the WebView is currently displaying (or will display once initialization of its CoreWebView2 is finished). Generally speaking, getting this property is equivalent to getting the Source property and setting this property (to a different value) is equivalent to calling the Navigate(String) method.
The zoom factor for the WebView.
This property directly exposes ZoomFactor, see its documentation for more info.
Getting this property before the CoreWebView2 has been initialized will retrieve the last value which was set to it, or
Implementation of the ISupportInitialize pattern. Prevents the control from implicitly initializing its CoreWebView2 until EndInit() is called. Does not prevent explicit initialization of the CoreWebView2 (i.e. EnsureCoreWebView2Async(CoreWebView2Environment)). Mainly intended for use by interactive UI designers.
This is overridden from HwndHost and is called to instruct us to create our HWND.
This is overridden from HwndHost and is called to instruct us to destroy our HWND.
Implementation of the ISupportInitialize pattern. Invokes any functionality that has been delayed since the corresponding call to BeginInit(). Mainly intended for use by interactive UI designers.
This is overridden from HwndHost and is called when WPF needs to know if the focus is in our control/window. WPF can't know on its own since we're hosting a non-WPF window, so instead it asks us by calling this. To answer, we just track state based on CoreWebView2 events that fire when it gains or loses focus.
Initiates a navigation to htmlContent as source HTML of a new document. Equivalent to calling NavigateToString(String).
This is overridden from UIElement and is called to inform us when we receive the keyboard focus. We handle this by passing the keyboard focus on to the underlying CoreWebView2. We never want to land in a state where our window (this.Handle) actually has the keyboard focus.
This is overridden from UIElement and called to allow us to handle key press input. WPF should never actually call this in response to keyboard events because we're hosting a non-WPF window. When our window has focus Windows will send the input directly to it rather than to WPF's top-level window and input system. This override should only be called when we're explicitly forwarding accelerator key input from the CoreWebView2 to WPF (in CoreWebView2Controller_AcceleratorKeyPressed). Even then, this KeyDownEvent is only triggered because our PreviewKeyDownEvent implementation explicitly triggers it, matching WPF's usual system. So the process is:
This is the "Preview" (i.e. tunneling) version of OnKeyDown(KeyEventArgs), so it actually happens first. Like OnKeyDown, this will only ever be called if we're explicitly forwarding key presses from the CoreWebView2. In order to mimic WPF's standard input handling, when we receive this we turn around and fire off the standard bubbling KeyDownEvent. That way others in the WPF tree see the same standard pair of input events that WPF itself would have triggered if it were handling the key press.
This is overridden from HwndHost and called when our control's location has changed. The HwndHost takes care of updating the HWND we created. What we need to do is move our CoreWebView2 to match the new location.
Reloads the current page. Equivalent to calling Reload().
Stops all navigations and pending resource fetches. Equivalent to calling Stop().
This is overridden from HwndHost and is called to inform us that tabbing has caused the focus to move into our control/window. Since WPF can't manage the transition of focus to a non-WPF HWND, it delegates the transition to us here. So our job is just to place the focus in our external HWND.
|WndProc(IntPtr, Int32, IntPtr, IntPtr, Boolean)||
This is overridden from HwndHost and is called to provide us with Win32 messages that are sent to our hwnd.
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
A wrapper around the ContentLoading. The only difference between this event and ContentLoading is the first parameter that's passed to handlers. Handlers of this event will receive the WebView2 control, whereas handlers of ContentLoading will receive the CoreWebView2 instance.
This event is triggered either
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). See the WebView2 class documentation for an initialization overview.
A wrapper around the NavigationCompleted. The only difference between this event and NavigationCompleted is the first parameter that's passed to handlers. Handlers of this event will receive the WebView2 control, whereas handlers of NavigationCompleted will receive the CoreWebView2 instance.
A wrapper around the NavigationStarting. The only difference between this event and NavigationStarting is the first parameter that's passed to handlers. Handlers of this event will receive the WebView2 control, whereas handlers of NavigationStarting will receive the CoreWebView2 instance.
A wrapper around the SourceChanged. The only difference between this event and SourceChanged is the first parameter that's passed to handlers. Handlers of this event will receive the WebView2 control, whereas handlers of SourceChanged will receive the CoreWebView2 instance.
A wrapper around the WebMessageReceived. The only difference between this event and WebMessageReceived is the first parameter that's passed to handlers. Handlers of this event will receive the WebView2 control, whereas handlers of WebMessageReceived will receive the CoreWebView2 instance.