Skip to content

Latest commit

 

History

History
3271 lines (2375 loc) · 226 KB

overview-features-apis.md

File metadata and controls

3271 lines (2375 loc) · 226 KB
title description author ms.author ms.topic ms.service ms.subservice ms.date
Overview of WebView2 features and APIs
Overview of WebView2 features and APIs.
MSEdgeTeam
msedgedevrel
conceptual
microsoft-edge
webview
08/26/2024

Overview of WebView2 features and APIs

Embedding the WebView2 control in your app gives your app access to various methods and properties that are provided through the WebView2 classes or interfaces. WebView2 has hundreds of APIs that provide a vast set of capabilities, ranging from enhancing your app's native-platform capabilities, to enabling your app to modify browser experiences. This article provides a high-level grouping of the WebView2 APIs to help you understand the different things you can do using WebView2.

Overview of top-level feature areas

When hosting the WebView2 control, your app has access to the following features and APIs:

Feature area Purpose
Main classes: Environment, Controller, and Core The CoreWebView2Environment, CoreWebView2Controller, and CoreWebView2 classes (or equivalent interfaces) work together so your app can host a WebView2 browser control and access its browser features. These large classes expose a wide range of APIs that your host app can access to provide the below categories of browser-related features for your users.
Web/native interop Embed web content into native applications. Communicate between native code and web code using simple messages, JavaScript code, and native objects.
Browser features The WebView2 control gives your app access to many browser features. You can modify these browser features and turn them on or off.
Process management Get information about running WebView2 processes, exiting processes, and failed processes, so your app can take action accordingly.
Navigate to pages and manage loaded content Manage navigation to webpages and manage content that's loaded in the webpages.
iframes Embed other webpages into your own webpage. Detect when embedded webpages are created, detect when embedded webpages are navigating, and optionally bypass x-frame options.
Authentication Your app can handle basic authentication using the WebView2 control. Basic authentication is a specific authentication approach that's part of the HTTP protocol.
Rendering WebView2 in non-framework apps Use these APIs to set up the WebView2 rendering system if your host app doesn't use a UI framework. This rendering setup controls how WebView2 renders output into your host app, and how WebView2 handles input, focus, and accessibility.
Rendering WebView2 using Composition For composition-based WebView2 rendering, use CoreWebView2Environment to create a CoreWebView2CompositionController. CoreWebView2CompositionController provides the same APIs as CoreWebView2Controller, but also includes APIs for composition-based rendering.
Environment options User data: Manage the user data folder (UDF), which is a folder on the user's machine. The UDF contains data related to the host app and WebView2. WebView2 apps use user data folders to store browser data, such as cookies, permissions, and cached resources. Manage multiple profiles under a single UDF.
Runtime selection supports prerelease testing and self-hosting. You can specify a search order for browser preview channels, and specify which browser preview channels are searched for.
Performance and debugging Analyze and debug performance, handle performance-related events, and manage memory usage to increase the responsiveness of your app.
Chrome DevTools Protocol (CDP) Instrument, inspect, debug, and profile Chromium-based browsers. The Chrome DevTools Protocol (CDP) is the foundation for the Microsoft Edge DevTools. Use the Chrome DevTools Protocol for features that aren't implemented in the WebView2 platform.

This page only lists APIs that are in Release SDKs; it doesn't list Experimental APIs, or Stable APIs that are not yet available in Release SDKs. For a comprehensive list of APIs including Experimental APIs, see Release Notes for the WebView2 SDK.

Main classes: Environment, Controller, and Core

The CoreWebView2Environment, CoreWebView2Controller, and CoreWebView2 classes (or equivalent interfaces) work together so your app can host a WebView2 browser control and access its browser features. These three large classes expose a wide range of APIs that your host app can access to provide many categories of browser-related features for your users.

  • The CoreWebView2Environment class represents a group of WebView2 controls that share the same WebView2 browser process, user data folder, and renderer processes. From this CoreWebView2Environment class, you create pairs of CoreWebView2Controller and CoreWebView2 instances.
  • The CoreWebView2Controller class is responsible for hosting-related functionality such as window focus, visibility, size, and input, where your app hosts the WebView2 control.
  • The CoreWebView2 class is for the web-specific parts of the WebView2 control, including networking, navigation, script, and parsing and rendering HTML.

See also:

.NET/C#
WinRT/C#
Win32/C++

Web/native interop

The Microsoft Edge WebView2 control lets you embed web content into native applications. You can communicate between native code and web code using simple messages, JavaScript code, and native objects. The following are the main APIs for communicating between web and native code.

Subsections below:

Common use cases for web/native interop:

  • Update the native host window title after navigating to a different website.
  • Send a native camera object and use its methods from a web app.
  • Run a dedicated JavaScript file on the web side of an application.

See also:

Host/web object sharing

WebView2 enables objects that are defined in native code to be passed to your app's web-side code. Host objects are any objects that are defined in native code that you choose to pass to your app's web-side code.

Host objects can be projected into JavaScript, so that you can call native object methods (or other APIs) from your app's web-side code. For example, your app can call such APIs as a result of user interaction on the web side of your app. This way, you don't need to reimplement your native objects' APIs, such as methods or properties, in your web-side code.

.NET/C#
WinRT/C#
Win32/C++

Script execution

Allows the host app to add JavaScript code in the web content within the WebView2 control.

.NET/C#
WinRT/C#
Win32/C++

Web messaging

Your app can send messages to the web content that's within the WebView2 control, and receive messages from that web content. Messages are sent as strings or JSON objects.

You can optionally post and receive DOM objects along with your message, via the additionalObjects parameter of PostWebMessageAsJson (.NET, WinRT) or via PostWebMessageAsJsonWithAdditionalObjects (Win32). The WebView2 CoreWebView2FileSystemHandle class represents the DOM FileSystemHandle, and CoreWebView2File represents the DOM File. See also chrome.webview.postMessageWithAdditionalObjects in the JavaScript Reference.

.NET/C#
WinRT/C#
Win32/C++

Script dialogs

When hosting WebView2, your app can manage different JavaScript dialogs, to suppress them or to replace them with custom dialogs.

.NET/C#
WinRT/C#
Win32/C++

Shared buffer

The SharedBuffer API supports sharing buffers between the WebView2 host app process and WebView2 renderer process, based on shared memory from the OS.

See also:

.NET/C#
WinRT/C#
Win32/C++

Browser features

The WebView2 control gives your app access to many browser features. You can modify these browser features and turn them on or off.

Subsections below:

Printing

You can print a webpage to a printer, PDF file, or PDF stream by configuring custom print settings.

See also:

.NET/C#
WinRT/C#
Win32/C++

Cookies

You can use cookies in WebView2 to manage user sessions, store user personalization preferences, and track user behavior.

See also:

.NET/C#
WinRT/C#
Win32/C++

Image capture

By hosting WebView2, your app can capture screenshots and indicate which format to use to save the image.

.NET/C#
WinRT/C#
Win32/C++

Downloads

Your app can manage the download experience in WebView2. Your app can:

  • Allow or block downloads based on different metadata.
  • Change the download location.
  • Configure a custom download UI.
  • Customize the default UI.
.NET/C#

General:

Modify Default Experience:

Custom Download Experience:

WinRT/C#

General:

Modify Default Experience:

Custom Download Experience:

Win32/C++

General:

Modify Default Experience:

Custom Download Experience:

Save as

The Save As APIs allow you to programmatically perform the Save as operation. You can use these APIs to block the default Save as dialog, and then either save silently, or build your own UI for Save as. These APIs pertain only to the Save as dialog, not the Download dialog, which uses the Download APIs.

.NET/C#
WinRT/C#
Win32/C++

Web notification handling

Web Notification APIs support non-persistent notifications. The NotificationReceived event for CoreWebView2 controls web notification handling, allowing customization or suppression by the host app. Unhandled notifications default to WebView2's UI.

.NET/C#
WinRT/C#
Win32/C++

Permissions

Different webpages may ask you for permissions to access some privileged resources, such as geolocation sensor, camera, and microphone. Your host app can programmatically respond to permissions requests and can replace the default permissions UI with its own UI.

.NET/C#
WinRT/C#
Win32/C++

Context menus

The WebView2 control provides a default context menu (right-click menu) which you can customize or disable, and you can also create your own context menu.

See also:

.NET/C#
WinRT/C#
Win32/C++

Status bar

A status bar is located in the bottom left of the page and displays the state of the webpage being displayed. In WebView2 you can enable/disable the status bar, get the text in the status bar, and find out when the status bar text has changed.

.NET/C#
WinRT/C#
Win32/C++

Fluent overlay scrollbars

Stylizes scrollbars with Microsoft Fluent design and makes the scrollbars overlay over the web content. This adaptive scrollbar design adjusts to various devices and window sizes.

To experiment with Fluent overlay scrollbars, in Microsoft Edge, go to edge://flags and then enter Fluent overlay scrollbars.

See also:

.NET/C#
WinRT/C#
Win32/C++

User Agent

The user agent is a string that represents the identity of the program on behalf of the user, such as the browser name. In WebView2, you can set the user agent.

See also:

.NET/C#
WinRT/C#
Win32/C++

Autofill

Your app can independently control whether the browser's autofill functionality is enabled for general information or for passwords.

.NET/C#
WinRT/C#
Win32/C++

Audio

Your app can mute and unmute all audio, and find out when audio is playing.

.NET/C#
WinRT/C#
Win32/C++

Hit-testing of mouse-clicks in regions

Provides hit-testing results on the regions that a WebView2 contains. Useful for visually hosted applications that want to handle mouse events on the non-client area of the WebView2 window.

.NET/C#
WinRT/C#
Win32/C++

Swipe gesture navigation

By hosting the WebView2 control, your app can enable or disable swiping gesture navigation on touch input-enabled devices. This gesture allows end users to:

  • Swipe left/right (swipe horizontally) to navigate to the previous or next page in the navigation history.
  • Pull to refresh (swipe vertically) the current page.

This feature is currently disabled by default in the browser. To enable this feature in WebView2, set the AdditionalBrowserArguments property, specifying the --pull-to-refresh switch.

.NET/C#
WinRT/C#
Win32/C++

Enable or disable the browser responding to accelerator keys (shortcut keys)

ICoreWebView2AcceleratorKeyPressedEventArgs has a IsBrowserAcceleratorKeyEnabled property to allow you to control whether the browser handles accelerator keys (shortcut keys), such as Ctrl+P or F3.

See also:

.NET/C#
WinRT/C#
Win32/C++

Fullscreen

In WebView2, you can find out when an HTML element enters or leaves full-screen view.

.NET/C#
WinRT/C#
Win32/C++

PDF toolbar

In the browser PDF viewer, there's a PDF-specific toolbar along the top. In WebView2, you can hide some of the items in the PDF viewer toolbar.

.NET/C#
WinRT/C#
Win32/C++

Theming

In WebView2, you can customize the color theme as system, light, or dark.

.NET/C#
WinRT/C#
Win32/C++

Language

The Language property sets the default display language for WebView2 that applies to the browser UI (such as context menus and dialogs), along with setting the accept-language HTTP header which WebView2 sends to websites.

The ScriptLocale property allows the host app to set the default locale for all Intl JavaScript APIs and other JavaScript APIs that depend on it, such as Intl.DateTimeFormat(), which affects string formatting in time/date formats.

.NET/C#
WinRT/C#
Win32/C++

New window

WebView2 provides functionality to handle the JavaScript function window.open().

.NET/C#
WinRT/C#
Win32/C++

Close window

WebView2 provides functionality to handle the JavaScript function window.close().

.NET/C#
WinRT/C#
Win32/C++

Document title

Your app can detect when the title of the current top-level document has changed.

.NET/C#
WinRT/C#
Win32/C++

Favicon

In WebView2, you can set a Favicon for a website, or get notified when it changes.

.NET/C#
WinRT/C#
Win32/C++

Security and privacy

Tracking prevention

Tracking prevention enables the host app to control the level of tracking prevention of the WebView2 control that's associated with the user profile.

.NET/C#
WinRT/C#
Win32/C++
SmartScreen

Microsoft Defender SmartScreen ("SmartScreen") is enabled by default. The IsReputationCheckingRequired property controls whether SmartScreen is enabled.

If you don't disable SmartScreen, you must provide notice to all users that your software includes Microsoft Defender SmartScreen, and collects and sends the user's information to Microsoft as disclosed in Microsoft Privacy Statement and in SmartScreen in Microsoft Edge Privacy Whitepaper.

See also:

.NET/C#
WinRT/C#
Win32/C++
Custom crash reporting

If any WebView2 process crashes, one or more minidump files are created and sent to Microsoft for diagnosis. Use this API to customize crash reporting when running diagnostics and doing analysis.

  • To prevent crash dumps from being sent to Microsoft, set the IsCustomCrashReportingEnabled property to false.
  • To locate crash dumps and do customization with them, use the CrashDumpFolderPath property.

See also:

.NET/C#
WinRT/C#
Win32/C++

Browser extensions

Your app can embed a WebView2 control that uses browser extensions (add-ons). A Microsoft Edge extension is a small app that developers use to add or modify features of Microsoft Edge to improve a user's browsing experience.

See also:

.NET/C#
WinRT/C#
Win32/C++

Process management

Get information about running WebView2 processes, exiting processes, and failed processes, so that your app can take action accordingly.

Subsections below:

.NET/C#
WinRT/C#
Win32/C++

Frame process info

The Frame Process Info API, including GetProcessExtendedInfos, provides a snapshot collection of all frames that are actively running in the associated renderer process. This API enables your app to detect which part of WebView2 is consuming resources such as memory or CPU usage.

.NET/C#
WinRT/C#
Win32/C++

Navigate to pages and manage loaded content

Through the WebView2 control, your app can manage navigation to webpages and manage content that's loaded in the webpages.

Subsections below:

Manage content loaded into WebView2

These APIs load, stop loading, and reload content to WebView2. The content that's loaded can be:

  • Content from a URL.
  • A string of HTML.
  • Local content via virtual host name to local folder mapping.
  • Content from a constructed network request.

See also:

.NET/C#
WinRT/C#
Win32/C++

Navigation history

The history methods allow back and forward navigation in WebView2, and the history events provide information about the changes in history and in WebView2's current source.

.NET/C#
WinRT/C#
Win32/C++

Navigation kind

NavigationKind gets the navigation kind of each navigation, such as Back/Forward, Reload, or navigation to a new document.

.NET/C#
WinRT/C#
Win32/C++

Block unwanted navigating

The NavigationStarting event allows the app to cancel navigating to specified URLs in WebView2, including for frames.

.NET/C#
WinRT/C#
Win32/C++

Navigation events

With NavigationStarting and the other navigation events, the app can be informed of the state of navigation in WebView2. A navigation is the process for loading a new URL.

See also:

.NET/C#
WinRT/C#
Win32/C++

Manage network requests in WebView2

The WebResourceRequested event allows the app to intercept and override all network requests in WebView2. The WebResourceResponseReceived event allows the app to monitor the request sent to and the response received from the network.

See also:

.NET/C#
WinRT/C#
Win32/C++

Custom scheme registration

The CustomSchemeRegistration allows registration of custom schemes in WebView2 so that the app can handle the WebResourceRequested event for requests to those custom scheme URLs and navigate the WebView2 to such URLs.

.NET/C#
WinRT/C#
Win32/C++

Client certificates

In WebView2, you can use the Client Certificate API to select the client certificate at the application level. This API allows you to:

  • Display a UI to the user, if desired.
  • Replace the default client certificate dialog prompt.
  • Programmatically query the certificates.
  • Select a certificate from the list to respond to the server, when WebView2 is making a request to an HTTP server that needs a client certificate for HTTP authentication.
.NET/C#
WinRT/C#
Win32/C++

Server certificates

In WebView2, you can use the Server Certificate API to trust the server's TLS certificate at the application level. This way, your host app can render the page without prompting the user about the TLS error, or your host app can automatically cancel the request.

.NET/C#
WinRT/C#
Win32/C++

Launch an external URI scheme

Launch a URI scheme that is registered with the OS.

.NET/C#
WinRT/C#
Win32/C++

iframes

iframes allow you to embed other webpages into your own webpage. In WebView2, you can:

  • Find out when iframes are created.
  • Find out when iframes are navigating.
  • Allow bypassing x-frame options.

See also:

.NET/C#
WinRT/C#
Win32/C++

Authentication

Your app can handle basic authentication using the WebView2 control. Basic authentication is a specific authentication approach that's part of the HTTP protocol.

See also:

.NET/C#
WinRT/C#
Win32/C++

Rendering WebView2 in non-framework apps

Use these APIs to set up the WebView2 rendering system if your host app doesn't use a UI framework. This rendering setup controls how WebView2 renders output into your host app, and how WebView2 handles input, focus, and accessibility.

When to use these APIs

  • UI framework - If you're using a UI framework for your app, you should use the WebView2 element that's provided by that UI framework, rather than using these APIs.

  • No UI framework, and not using Composition - If you're not using a UI framework for your app (for example, if you're using pure Win32 directly), or if your UI framework doesn't have a WebView2 element, then you need to create CoreWebView2Controller and render it into your app, using these APIs in this section.

  • No UI framework, and using Composition - If your app UI is built using DirectComposition or Windows.UI.Composition, you should use CoreWebView2CompositionController rather than using these APIs; see Rendering WebView2 using Composition, below.

Subsections below:

.NET/C#
WinRT/C#
Win32/C++

Sizing, positioning, and visibility

CoreWebView2Controller takes a parent HWND. The Bounds property sizes and positions the WebView2 relative to the parent HWND. The visibility of WebView2 can be toggled using IsVisible.

.NET/C#
WinRT/C#
Win32/C++

Zooming

WebView2 ZoomFactor is used to scale just the web content of the window. UI scaling is also updated when the user zooms the content by pressing Ctrl while rotating the mouse wheel.

.NET/C#
WinRT/C#
Win32/C++

Rasterization scale

The RasterizationScale API scales all WebView2 UI including context menus, tooltip, and popups. The app can set whether the WebView2 should detect monitor scale changes and automatically update the RasterizationScale. BoundsMode is used to configure whether the Bounds property is interpreted as raw pixels, or DIPs (which need to be scaled by RasterizationScale).

.NET/C#
WinRT/C#
Win32/C++

Focus and tabbing

The WebView2 control raises events to let the app know when the control gains focus or loses focus. For tabbing (pressing the Tab key), there's an API to move focus into WebView2 and an event for WebView2 to request the app to take focus back.

.NET/C#
WinRT/C#
Win32/C++

Parent window

WebView2 can be reparented to a different parent window handle (HWND). WebView2 also needs to be notified when the app's position on the screen has changed.

.NET/C#
WinRT/C#
Win32/C++

Keyboard accelerators

When WebView2 has focus, it directly receives input from the user. An app may want to intercept and handle certain accelerator key combinations (shortcut keys), or disable the normal browser accelerator key behaviors.

See also Enable or disable the browser responding to accelerator keys (shortcut keys), above.

.NET/C#
WinRT/C#
Win32/C++

Default background color

WebView2 can specify a default background color. The color can be any opaque color, or transparent. This color will be used if the HTML page doesn't set its own background color.

.NET/C#
WinRT/C#
Win32/C++

Rendering WebView2 using Composition

For composition-based WebView2 rendering, use CoreWebView2Environment to create a CoreWebView2CompositionController. CoreWebView2CompositionController provides the same APIs as CoreWebView2Controller, but also includes APIs for composition-based rendering.

Subsections below:

.NET/C#
WinRT/C#
Win32/C++

Connecting to the visual tree

WebView2 can connect its composition tree to an IDCompositionVisual, IDCompositionTarget, or Windows::UI::Composition::ContainerVisual.

.NET/C#
WinRT/C#
Win32/C++

Forwarding input

Spatial input (mouse, touch, pen) is received by the application and must be sent to WebView2. WebView2 notifies the app when the cursor should be updated based on the mouse position.

.NET/C#
WinRT/C#
Win32/C++

Drag and drop

Dragging from a WebView2 control to another application is supported by default. However, dragging to a WebView2 control requires that when the host app receives an IDropTarget event from the system, the host app must forward the event to the WebView2 control. Dragging to a WebView2 control includes drag-and-drop operations that are entirely within a WebView2 control.

Use the following APIs to forward IDropTarget events from the system to the WebView2 control.

.NET/C#
WinRT/C#
Win32/C++

Accessibility

By default, WebView2 will show up in the accessibility tree as a child of the parent HWND, for Win32/C++ apps. WebView2 provides API to better position the WebView2 content relative to other elements in the application.

.NET/C#

Not applicable.

WinRT/C#

Not applicable.

Win32/C++

Environment options

Subsections below:

User data

Manage the user data folder (UDF), which is a folder on the user's machine. The UDF contains data related to the host app and WebView2. WebView2 apps use user data folders to store browser data, such as cookies, permissions, and cached resources.

Subsections below:

See also:

.NET/C#

Clearing browsing data:

WinRT/C#

Clearing browsing data:

Win32/C++

Clearing browsing data:

Multiple profiles

Manage multiple profiles under a single user data folder.

See also:

.NET/C#

Create an options object that defines a profile:

Create a WebView2 control that uses the profile:

Access and manipulate the profile:

WinRT/C#

Create an options object that defines a profile:

Create a WebView2 control that uses the profile:

Access and manipulate the profile:

Win32/C++

Create an options object that defines a profile:

Create a WebView2 control that uses the profile:

Access and manipulate the profile:

Delete a profile

Your app can delete user profiles for a WebView2 web browser control.

See also:

.NET/C#
WinRT/C#
Win32/C++

Runtime selection

Runtime selection supports prerelease testing and self-hosting. When creating a WebView2 environment:

  • To specify a search order for browser preview channels, use the CoreWebView2EnvironmentOptions.ChannelSearchKind property.
  • To specify which browser preview channels are searched for, use the CoreWebView2EnvironmentOptions.ReleaseChannels property.

See also:

.NET/C#
WinRT/C#
Win32/C++

Performance and debugging

Analyze and debug performance, handle performance-related events, and manage memory usage to increase the responsiveness of your app.

Subsections below:

.NET/C#
WinRT/C#
Win32/C++

Memory usage target

Specifies memory consumption levels, such as low or normal.

.NET/C#
WinRT/C#
Win32/C++

Chrome DevTools Protocol (CDP)

The Chrome DevTools Protocol (CDP) provides APIs to instrument, inspect, debug, and profile Chromium-based browsers. The Chrome DevTools Protocol is the foundation for the Microsoft Edge DevTools. Use the Chrome DevTools Protocol for features that aren't implemented in the WebView2 platform.

See also:

.NET/C#

Open:

Call:

Receiver:

WinRT/C#

Open:

Call:

Receiver:

Win32/C++

Open:

Call:

Receiver:

See also