Skip to content

overview-features-apis.md

Latest commit

 

History

History
2079 lines (1348 loc) · 142 KB

overview-features-apis.md

File metadata and controls

2079 lines (1348 loc) · 142 KB
Raw
title Overview of WebView2 features and APIs
description Overview of WebView2 features and APIs.
author MSEdgeTeam
ms.author msedgedevrel
ms.topic conceptual
ms.prod microsoft-edge
ms.technology webview
ms.date 04/14/2023

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.

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.
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.
Performance and debugging Analyze and debug performance, handle performance-related events, and manage memory usage to increase the responsiveness of your app.
Chrome Developer Protocol (CDP) 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.

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.

Some common use cases include:

  • 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:

The following are the main APIs for communicating between web and native code.

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 host app to add JavaScript 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.

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

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

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:

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++

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++

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++

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 you can set a Favicon for a website or get notified when it changes.

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

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++

Process management

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

.NET/C#

Info:

Exited:

Failed:

WinRT/C#

Info:

Exited:

Failed:

Win32/C++

Info:

Exited:

Failed:

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.

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++

Block unwanted navigating

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

.NET/C#

Superseded:

WinRT/C#

Superseded:

Win32/C++

Superseded:

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++

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.

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

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

Browser/gesture/zoom features:

WinRT/C#

Browser/gesture/zoom features:

Win32/C++

Browser/gesture/zoom features:

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, or disable the normal browser accelerator key behaviors.

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

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

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.

See also:

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

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:

Performance and debugging

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

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

Chrome Developer Protocol (CDP)

The Chrome DevTools Protocol 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