Microsoft.Web.WebView2.Wpf

This class is a bundle of the most common parameters used to create a . Its main purpose is to be set to in order to customize the environment used by a during implicit initialization. It is also a nice WPF integration utility which allows commonly used environment parameters to be dependency properties and be created and used in markup.

This class isn't intended to contain all possible environment customization options. If you need complete control over the environment used by a WebView2 control then you'll need to initialize the control explicitly by creating your own environment with and passing it 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.

The WPF DependencyProperty which backs the property.

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

The WPF DependencyProperty which backs the property.

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

The WPF DependencyProperty which backs the property.

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

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

A task which will provide the created environment on completion. 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.

A control to embed web content in a WPF application.

This control is effectively a wrapper around the [WebView2 COM API](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 property will be null. This is because creating the is an expensive operation which involves things like launching Edge browser processes. There are two ways to cause the to be created: Call the method. This is referred to as explicit initialization. Set the 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 to or set the control's 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 event will be invoked. If you need to perform one time setup operations on the 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 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 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 is a very heavyweight object (potentially responsible for multiple running processes and megabytes of disk space) the control implements to provide an explicit means to free it. Calling will release the and its underlying resources (except any that are also being used by other WebViews), and reset to null. After has been called the cannot be re-initialized, and any attempt to use functionality which requires it will throw an . 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. Note that this control extends 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 and . See the and [WPF/Win32 interop](https://docs.microsoft.com/dotnet/framework/wpf/advanced/wpf-and-win32-interoperation#hwnds-inside-wpf) documentation for more information.

Creates a new instance of a WebView2 control. Note that the control's will be null until initialized. See the class documentation for an initialization overview.

The WPF which backs the property.

Gets or sets a bag of options which are used during initialization of the control's . Setting this property will not work after initialization of the control's has started (the old value will be retained). See the class documentation for an initialization overview.

This is overridden from and is called to instruct us to create our HWND.

The HWND that we should use as the parent of the one we create. The HWND that we created.

This is overridden from and is called to instruct us to destroy our HWND.

Our HWND that we need to destroy.

This is overridden from and is called to provide us with Win32 messages that are sent to our hwnd.

Window receiving the message (should always match our ). Indicates the message being received. See Win32 documentation for WM_* constant values. The "wParam" data being provided with the message. Meaning varies by message. The "lParam" data being provided with the message. Meaning varies by message. If true then the message will not be forwarded to any (more) handlers. Return value varies by message.

Override for painting to draw

The tools to handle the drawing via .

Accesses the complete functionality of the underlying COM API. Returns null until initialization has completed. See the class documentation for an initialization overview.

Thrown 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. Thrown if has already been called on the control.

This event is triggered either 1) when the control's has finished being initialized (regardless of how initialization was triggered) but before it is used for anything, or 2) if the initialization failed. You should handle this event if you need to perform one time setup operations on the 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 class documentation for an initialization overview.

This sender will be the control, whose 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.

Explicitly triggers initialization of the control's . See the class documentation for an initialization overview.

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 an environment 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 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. Calling this method additional times will have no effect (any specified environment is ignored) and return the same Task as the first call. Calling this method after initialization has been implicitly triggered by setting the property will have no effect (any specified environment is ignored) and simply return a Task representing that initialization already in progress. 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 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. Thrown if has already been called on the control.

This is called by our base class according to the typical implementation of the pattern. We implement it by releasing all of our underlying COM resources, including our .

True if a caller is explicitly calling Dispose, false if we're being finalized.

This is an event handler for our CoreWebView2's ProcessFailedEvent

Implementation of the ISupportInitialize pattern. Prevents the control from implicitly initializing its until is called. Does *not* prevent explicit initialization of the CoreWebView2 (i.e. ). Mainly intended for use by interactive UI designers.

Note that the "Initialize" in ISupportInitialize and the "Init" in BeginInit/EndInit mean something different and more general than this control's specific concept of initializing its CoreWebView2 (explicitly or implicitly). This ISupportInitialize pattern is a general way to set batches of properties on the control to their initial values without triggering any dependent side effects until all of the values are set (i.e. until EndInit is called). In the case of this control, a specific side effect to be avoided is triggering implicit initialization of the CoreWebView2 when setting the Source property. For example, normally if you set after you've already set Source, the data set to CreationProperties is ignored because implicit initialization has already started. However, if you set the two properties (in the same order) in between calls to BeginInit and EndInit then the implicit initialization of the CoreWebView2 is delayed until EndInit, so the data set to CreationProperties is still used even though it was set after Source.

Implementation of the ISupportInitialize pattern. Invokes any functionality that has been delayed since the corresponding call to . Mainly intended for use by interactive UI designers.

See the documentation of for more information.

Specifies a Source-related action to be invoked but which must be delayed if BeginInit has already been called but EndInit hasn't. If the control is currently between BeginInit/EndInit calls then the action will be invoked during EndInit. Otherwise the action will be invoked immediately. If this is called multiple times between BeginInit/EndInit then the action passed to the last call is the only one that will be invoked during EndInit.

The Source-related action to invoke, delayed until EndInit if necessary. In the future if we need this delayed-invoke functionality for actions unrelated to Source, then we should generalize _initAction_Source to a list and generalize this method to take a list index along with the action. Then we can just assign each index to a different potential action (e.g. 0 for Source), and potentially use constants to name the indices. For now it didn't seem worth dynamically allocating a list for one thing, but I still wanted to keep the delay-or-not logic abstracted away from the Source setter.

Updates one of our dependency properties to match a new value from the . It both sets the value and remembers (in _propertyChangingFromCore) that it came from the CoreWebView2 rather than the caller, allowing the property's "on changed" handler to alter its behavior based on where the new value came from. It's only intended to be called in a CoreWebView2 event handler that's informing us of a new property value. It's basically just a wrapper around the inherited SetCurrentValue which also maintains _propertyChangingFromCore. See the comments on for additional background info. One more thing worth explicitly stating is that it wraps SetCurrentValue rather than SetValue, in order to avoid overwriting any OneWay bindings that are set on the specified properties. Check the link https://stackoverflow.com/q/4230698 for more information about the difference between SetValue and SetCurrentValue.

The property to change due to an equivalent change in the CoreWebView2. The new value from the CoreWebView2.

Checks if a given property is currently being updated to match an equivalent change in the . This method should only be called from a property's "on changed" handler; it has no meaning at any other time. It is used to determine if the property is changing to match the CoreWebView2 or because the caller set it. Usually this is used in order to decide if the new value needs to be propagated down to the CoreWebView2. See the comments on for additional background info.

The property to check. True if the property is changing to match the CoreWebView2, or false if the property was changed by the caller.

Changes our controller's ParentWindow to the given HWND, along with any other necessary associated work.

The new HWND to set as the controller's parent. IntPtr.Zero means that the controller will have no parent and the CoreWebView2 will be hidden. Whether or not to call as required. Defaults to true. If you pass false then you should call it yourself if required. Reparenting the controller isn't necessarily as simple as changing its ParentWindow property, and this method exists to ensure that any other work that needs to be done at the same time gets done. The reason that SyncControllerWithParentWindow isn't baked directly into this method is because sometimes we want to call the Sync functionality without necessarily reparenting (e.g. during initialization).

Syncs visual/windowing information between the controller and its parent HWND. This should be called any time a new, non-null HWND is set as the controller's parent, including when the controller is first created.

This is a handler for our base UIElement's IsVisibleChanged event. It's predictably fired whenever IsVisible changes, and IsVisible reflects the actual current visibility status of the control. We just need to pass this info through to our CoreWebView2Controller so it can save some effort when the control isn't visible.

This is overridden from 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.

The WPF which backs the property.

The top-level which the WebView is currently displaying (or will display once initialization of its is finished). Generally speaking, getting this property is equivalent to getting the property and setting this property (to a different value) is equivalent to calling the method.

Getting this property before the has been initialized will retrieve the last Uri which was set to it, or null (the default) if none has been. Setting this property before the has been initialized will cause initialization to start in the background (if not already in progress), after which the will navigate to the specified . This property can never be set back to null or to a relative . See the class documentation for an initialization overview. Thrown if has already been called on the control. Thrown if the property is set to null. Thrown if the property is set to a relative (i.e. a whose property is false).

This is a callback that WPF calls to validate a potential new Source value.

True if the value is valid, false if it is not. If we return false then WPF should respond by throwing an . Note that we unfortunately can't treat null as invalid here because null is valid prior to initialization.

This is a callback that WPF calls when the WPF Source property's value changes. This might have been triggered by either: 1) The caller set Source to programmatically trigger a navigation. 2) The CoreWebView changed its own source and we're just updating the dependency property to match. We use to distinguish the two cases.

A wrapper around the . The only difference between this event and is the first parameter that's passed to handlers. Handlers of this event will receive the control, whereas handlers of will receive the instance.

This is an event handler for our CoreWebView2's SourceChanged event. Unsurprisingly, it fires when the CoreWebView2's source URI has been changed. Note that there are two distinct triggers for this: 1) The CoreWebView2 was told to navigate programmatically (potentially by us, see SourcePropertyChanged). 2) The user interacted with the CoreWebView2, e.g. clicked a link. In either of the above cases, this event might trigger several times due to e.g. redirection. Aside from propagating to our own event, we just need to update our WPF Source property to match the CoreWebView2's.

This is an event handler for our CoreWebView2's NavigationStarting event. We just need to propagate the event to WPF.

This is an event handler for our CoreWebView2's NavigationCompleted event. We just need to propagate the event to WPF.

This is an event handler for our CoreWebView2's HistoryChanged event. We're handling it in order to update our WPF CanGoBack and CanGoForward properties.

The WPF which backs the property.

Returns true if the WebView can navigate to a previous page in the navigation history. Wrapper around the property of . If isn't initialized yet then returns false.

The WPF which backs the property.

Returns true if the WebView can navigate to a next page in the navigation history. Wrapper around the property of . If isn't initialized yet then returns false.

This is overridden from 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.

Information about how the focus is moving. true to indicate that we handled the navigation, or false to indicate that we didn't.

This is overridden from and is called to inform us when we receive the keyboard focus. We handle this by passing the keyboard focus on to the underlying . We never want to land in a state where our window (this.Handle) actually has the keyboard focus.

Arguments from the underlying GotKeyboardFocus event. Note that it's actually possible for us to receive keyboard focus without this method being called. One known case where that happens is when our parent window is deactivated while we have focus, then reactivated. We handle that case in .

This is an event handler for our CoreWebView2Controller's MoveFocusRequested event. It fires when the CoreWebView2Controller has focus but wants to move it elsewhere in the app. E.g. this happens when the user tabs past the last item in the CoreWebView2 and focus needs to return to some other app control. So our job is just to tell WPF to move the focus on to the next control. Note that we don't propagate this event outward as a standard WPF routed event because we've implemented its purpose here. If users of the control want to track focus shifting in/out of the control, they should use standard WPF events.

This is an event handler for our CoreWebView2Controller's GotFocus event. We just need to propagate the event to WPF.

This is an event handler for our CoreWebView2Controller's LostFocus event. We just need to propagate the event to WPF.

This is an event handler for our CoreWebView2Controller's AcceleratorKeyPressed event. This is called to inform us about key presses that are likely to have special behavior (e.g. esc, return, Function keys, letters with modifier keys). WPF can't detect this input because Windows sends it directly to the Win32 CoreWebView2Controller control. We implement this by generating standard WPF key input events, allowing callers to handle the input in the usual WPF way if they want. If nobody handles the WPF key events then we'll allow the default CoreWebView2Controller logic (if any) to handle it. Of the possible options, this implementation should provide the most flexibility to callers.

This is overridden from 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: CoreWebView2Controller_AcceleratorKeyPressed PreviewKeyDownEvent KeyDownEvent OnKeyDown .

See .

This is the "Preview" (i.e. tunneling) version of , 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.

See .

The WPF which backs the property.

The zoom factor for the WebView. This property directly exposes , see its documentation for more info. Getting this property before the has been initialized will retrieve the last value which was set to it, or 1.0 (the default) if none has been. The most recent value set to this property before the CoreWebView2 has been initialized will be set on it after initialization.

This is a callback that WPF calls when our WPF ZoomFactor property's value changes. This might have been triggered by either: 1) The caller set ZoomFactor to change the zoom of the CoreWebView2. 2) The CoreWebView2 changed its own ZoomFactor and we're just updating the dependency property to match. We use to distinguish the two cases.

The event is raised when the property changes. This event directly exposes .

This is an event handler for our CoreWebView2Controller's ZoomFactorChanged event. Unsurprisingly, it fires when the CoreWebView2Controller's ZoomFactor has been changed. Note that there are two distinct triggers for this: 1) The value was changed programmatically (potentially by us, see ZoomFactorPropertyChanged). 2) The user interacted with the CoreWebView2, e.g. CTRL + Mouse Wheel. Aside from propagating to our own event, we just need to update our WPF ZoomFactor property to match the CoreWebView2Controller's.

The WPF which backs the property.

The default background color for the WebView. This property directly exposes , see its documentation for more info. Getting this property before the has been initialized will retrieve the last value which was set to it, or Color.White (the default) if none has been. The most recent value set to this property before CoreWebView2Controller has been initialized will be set on it after initialization.

This is a callback that WPF calls when our WPF DefaultBackgroundColor property's value changes. Since CoreWebView2Controller does not update this property itself, this is only triggered by the caller setting DefaultBackgroundColor.

The WPF which backs the property.

The foreground color to be used in design mode.

Navigates the WebView to the previous page in the navigation history. Equivalent to calling If hasn't been initialized yet then does nothing.

Navigates the WebView to the next page in the navigation history. Equivalent to calling . If hasn't been initialized yet then does nothing.

Reloads the current page. Equivalent to calling .

Thrown if hasn't been initialized yet, 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. Thrown if has already been called on the control.

Stops all navigations and pending resource fetches. Equivalent to calling .

Initiates a navigation to htmlContent as source HTML of a new document. Equivalent to calling .

This is an event handler for our CoreWebView2's ContentLoading event. We just need to propagate the event to WPF.

Executes JavaScript code from the javaScript parameter in the current top level document rendered in the WebView. Equivalent to calling .

This is an event handler for our CoreWebView2's WebMessageReceived event. We just need to propagate the event to WPF.

True when we're in design mode and shouldn't create an underlying CoreWebView2.