Microsoft.Web.WebView2.Wpf

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. It is also a nice WPF integration utility which allows commonly used environment/controller parameters to be dependency properties and be created and used in markup.

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.

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.

The WPF DependencyProperty which backs the property.

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.

The WPF DependencyProperty which backs the property.

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.

Create 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.

Tracks the conditions which block implicit initialization and whether it has been requested or not. The analogy is a set of gates which are either open (implicit init allowed) or closed (will have to wait). All sub-gates must be open before implicit init can proceed. If implicit init is requested while the gate is open then it happens immediately. If it's requested while the gate is closed then it occurs when the gate becomes open.

It should be reasonably straight-forward to expand this class in the future to: * add new sub-gates to further restrict when implicit initialization can occur * support storing and invoking multiple actions next time the gate is open instead of only one

Tracks whether a sub-gate regarding / is open or closed. This sub-gate is only closed after calls to `BeginInit` and before an equal number of calls to `EndInit`.

We don't want implicit initialization to occur in between those calls, because implicit initialization is a side effect of setting the Source property, and side effects of setting properties during that period are supposed to be delayed until `EndInit`.

How many times has been called without being called.

Tracks whether a sub-gate regarding is open or closed. This sub-gate is closed if `SynchronizationContext.Current == null`.

Initialization won't work without a `SynchronizationContext` because otherwise an `await` might resume on a different thread. As far as I know so far this only occurs before an event loop as started on the running thread. Once there's an event loop running the `SynchronizationContext` ensures that `await`s resume in the same event loop (i.e. same thread). Although it's a rare corner case, it's possible to create a `Window` w/ `WebView2` before an app's event loop starts. This sub-gate handles that corner case.

An action which will trigger initialization next time the gate is open (and only once).

This basically tracks whether or not implicit initialization has been requested while the gate is closed. If this is non-null then it should be a delegate that calls .

Closes the gate until is called an equal number of times.

Opens the gate closed by after being called the same number of times.

A handler that should be attached to an event which indicates that exists. The best one I know of right now is . When the handler is called, the gate will re-evaluate its state and potentially allow any pending initialization action.

Run a given action when the gate is open.

If the gate is currently open then the action runs immediately. Otherwise the action runs next time the gate is discovered to be open. The action is only ever run once; it will not run again a second/subsequent time the gate opens. If the gate is closed and another action is already pending then the new action *overwrites* the current one (i.e. the currently stored action will never run). To "forget" a currently stored action, pass `null`. Action to run when the gate is open, or null to clear a previously specified action.

Examine our overall open/closed state and run any pending action if appropriate.

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 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. 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. 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 the calling thread isn't the thread which created this object (usually the UI thread). See for more info. May also be thrown if is null, which probably indicates that the application's event loop hasn't started yet. 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

This is a "gate" which controls whether or not implicit initialization can occur. If implicit initialization is triggered while the gate is closed, then the initialization should be delayed until the gate opens. When we want to trigger implicit initialization we route the call through this gate. If the gate is open then the initialization will proceed. If the gate is closed then it will remember to trigger the initialization when it opens.

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.

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 AllowExternalDrop property 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 true (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 AllowExternalDrop property's value changes. Since CoreWebView2Controller does not update this property itself, this is only triggered by the caller setting AllowExternalDrop.

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.