diff --git a/microsoft-edge/develop-web-microsoft-edge.md b/microsoft-edge/develop-web-microsoft-edge.md index 1f8c8d2e5e..02740a06e4 100644 --- a/microsoft-edge/develop-web-microsoft-edge.md +++ b/microsoft-edge/develop-web-microsoft-edge.md @@ -11,6 +11,8 @@ ms.date: 02/06/2025 Develop for the web with Microsoft Edge by using standards-based web platform features, Microsoft Edge DevTools, Microsoft Edge extensions, Progressive Web Apps, WebDriver automation, WebView2, and more. + + For end-user documentation about how to use Microsoft Edge, see: * [Get to know Microsoft Edge](https://www.microsoft.com/edge/) @@ -99,7 +101,6 @@ The WebView2 control is powered by Microsoft Edge, and enables you to embed web The following diagram shows the spectrum of apps, from maximum reach, to maximum power: ![The spectrum of apps, from maximum reach but less power, to an optimal hybrid blend, to maximum power but less reach](./develop-web-microsoft-edge-images/web-hybrid-native.png) - Hybrid apps, in the middle of this spectrum, allow you to enjoy the best of both worlds: the ubiquity and strength of the web platform, combined with the power and full capabilities of the native platform. diff --git a/microsoft-edge/toc.yml b/microsoft-edge/toc.yml index 4ffae82a67..2b428d0035 100644 --- a/microsoft-edge/toc.yml +++ b/microsoft-edge/toc.yml @@ -1453,6 +1453,9 @@ - name: Overview of WebView2 APIs href: ./webview2/concepts/overview-features-apis.md + - name: Components of the WebView2 platform + href: webview2/concepts/platform-components.md + - name: "Main classes for WebView2: Environment, Controller, and Core" href: ./webview2/concepts/environment-controller-core.md @@ -1639,7 +1642,6 @@ items: - name: Prerelease and Release SDKs for WebView2 href: ./webview2/concepts/versioning.md - displayName: experimental APIs, Understand WebView2 SDK versions, Understand the different WebView2 SDK versions # old titles - name: Distribute the app and Runtime items: diff --git a/microsoft-edge/webview2/concepts/browser-features.md b/microsoft-edge/webview2/concepts/browser-features.md index 6ab34d7956..4f17ceb3da 100644 --- a/microsoft-edge/webview2/concepts/browser-features.md +++ b/microsoft-edge/webview2/concepts/browser-features.md @@ -13,6 +13,27 @@ ms.date: 11/14/2025 WebView2 is based on the Microsoft Edge browser. You have the opportunity to extend features from the browser to WebView2-based apps, which is useful. However, since WebView2 isn't limited to browser-like apps, there are some browser features that need to be modified or removed. +**Detailed contents:** +* [Introduction](#introduction) +* [Design guidelines](#design-guidelines) +* [Browser features](#browser-features) +* [Web platform features](#web-platform-features) +* [Blocked internal URLs](#blocked-internal-urls) +* [Google Authentication](#google-authentication) +* [Additional keyboard shortcuts information](#additional-keyboard-shortcuts-information) + * [Preventing shortcuts from changing during update](#preventing-shortcuts-from-changing-during-update) + * [Shortcuts that are turned off](#shortcuts-that-are-turned-off) + * [Shortcuts turned off except when event not handled](#shortcuts-turned-off-except-when-event-not-handled) + * [Shortcuts turned off if AcceleratorEnabled is False](#shortcuts-turned-off-if-acceleratorenabled-is-false) + * [Customizing an individual key](#customizing-an-individual-key) +* [See also](#see-also) + + + +## Introduction + +WebView2 is based on the Microsoft Edge browser. You have the opportunity to extend features from the browser to WebView2-based apps, which is useful. However, since WebView2 isn't limited to browser-like apps, there are some browser features that need to be modified or removed. + This article covers: * The modified browser features and supporting information. @@ -108,6 +129,8 @@ The following Microsoft Edge and Google Chrome settings webpages aren't availabl Google has disabled Google Authentication in embedded webviews, which includes WebView2, due to a security policy they have set. See [Upcoming security changes to Google's OAuth 2.0 authorization endpoint in embedded webviews](https://developers.googleblog.com/2021/06/upcoming-security-changes-to-googles-oauth-2.0-authorization-endpoint.html). To stay up-to-date on the latest discussion, in the WebView2Feedback repo, see [Google Auth Flows and WebView2](https://github.com/MicrosoftEdge/WebView2Feedback/issues/1647). + + ## Additional keyboard shortcuts information @@ -213,3 +236,10 @@ If you set `AreBrowserAcceleratorKeysEnabled` to `FALSE`, the following addition #### Customizing an individual key To customize any of the keys individually, use the [AcceleratorKeyPressed](/dotnet/api/microsoft.web.webview2.core.corewebview2controller.acceleratorkeypressed) event. + + + +## See also + +* [List of Chromium Command Line Switches](https://peter.sh/experiments/chromium-command-line-switches) +* [AcceleratorKeyPressed](/dotnet/api/microsoft.web.webview2.core.corewebview2controller.acceleratorkeypressed?view=webview2-dotnet-1.0.774.44&preserve-view=true) event diff --git a/microsoft-edge/webview2/concepts/data-privacy.md b/microsoft-edge/webview2/concepts/data-privacy.md index 7d3a682087..2bc58a3a4f 100644 --- a/microsoft-edge/webview2/concepts/data-privacy.md +++ b/microsoft-edge/webview2/concepts/data-privacy.md @@ -10,7 +10,11 @@ ms.date: 06/02/2023 --- # Data and privacy in WebView2 -WebView2 collects a set of optional and required diagnostic data to keep WebView2 secure and up to date, diagnose issues, and improve WebView2. By agreeing to the WebView2 Runtime Terms and Conditions License, WebView2 developers acknowledge that WebView2 will collect the data that's described in this article. To view the license, go to [Download the WebView2 Runtime](https://developer.microsoft.com/microsoft-edge/webview2#download-the-webview2-runtime), where clicking any of the download buttons, such as **Get the Link**, **Download**, or **x64**, shows the license in a dialog. +WebView2 collects a set of optional and required diagnostic data to keep WebView2 secure and up-to-date, diagnose issues, and improve WebView2. By agreeing to the Microsoft Software License Terms for the Microsoft Edge WebView2 Runtime, you acknowledge (as a WebView2 developer) that WebView2 will collect the data that's described in this article. + + + +To view the license terms, go to [Download the WebView2 Runtime](https://developer.microsoft.com/microsoft-edge/webview2#download-the-webview2-runtime), and then click any of the download buttons, such as **Get the Link**, **x64**, or **Download**. The license terms are shown in a dialog. Additionally, WebView2 follows the standards that are outlined in [User data and privacy in Microsoft Edge](/legal/microsoft-edge/privacy). WebView2 has mechanisms to ensure privacy. WebView2 data collection follows the same strict standards as Microsoft Edge. For more information, see [Microsoft Privacy Statement – Microsoft privacy](https://privacy.microsoft.com/privacystatement). diff --git a/microsoft-edge/webview2/concepts/distribution.md b/microsoft-edge/webview2/concepts/distribution.md index 42fb09d7b4..9a4f4ca8ec 100644 --- a/microsoft-edge/webview2/concepts/distribution.md +++ b/microsoft-edge/webview2/concepts/distribution.md @@ -19,9 +19,33 @@ When distributing your WebView2 app, make sure that the WebView2 Runtime is pres For introductory information, see [Evergreen vs. fixed version of the WebView2 Runtime](./evergreen-vs-fixed-version.md). +**Detailed contents:** +* [Introductory notes](#introductory-notes) + * [Servicing the WebView2 Runtime through Windows Server Update Services (WSUS)](#servicing-the-webview2-runtime-through-windows-server-update-services-wsus) + * [Runtime or browser support during development or production](#runtime-or-browser-support-during-development-or-production) + * [Microsoft Edge Stable channel isn't supported for WebView2](#microsoft-edge-stable-channel-isnt-supported-for-webview2) +* [The Evergreen Runtime distribution mode](#the-evergreen-runtime-distribution-mode) + * [Windows 11 devices and Windows 10 devices (details)](#windows-11-devices-and-windows-10-devices-details) + * [Deploying the Evergreen WebView2 Runtime](#deploying-the-evergreen-webview2-runtime) + * [Installing the Runtime as per-machine or per-user](#installing-the-runtime-as-per-machine-or-per-user) + * [Detect if a WebView2 Runtime is already installed](#detect-if-a-webview2-runtime-is-already-installed) + * [Online-only deployment](#online-only-deployment) + * [Offline deployment](#offline-deployment) + * [Handle Evergreen WebView2 Runtime updates](#handle-evergreen-webview2-runtime-updates) + * [Test your app for forward-compatibility](#test-your-app-for-forward-compatibility) + * [Feature-detect when using recent APIs](#feature-detect-when-using-recent-apis) +* [The Fixed Version runtime distribution mode](#the-fixed-version-runtime-distribution-mode) + * [Known issues for Fixed Version](#known-issues-for-fixed-version) +* [Files to ship with the app](#files-to-ship-with-the-app) +* [See also](#see-also) + + + +## Introductory notes + -#### Servicing the WebView2 Runtime through Windows Server Update Services (WSUS) +#### Servicing the WebView2 Runtime through Windows Server Update Services (WSUS) See [Windows Server Update Services (WSUS)](./enterprise.md#windows-server-update-services-wsus) in _Enterprise management of WebView2 Runtimes_. @@ -77,9 +101,9 @@ For introductory information, see [Windows 11 devices and Windows 10 devices](./ The vast majority of Windows 10 devices have the WebView2 Runtime installed already, as described in [Delivering Microsoft Edge WebView2 Runtime to managed Windows 10 devices](https://blogs.windows.com/msedgedev/2022/12/14/delivering-microsoft-edge-webview2-runtime-to-managed-windows-10-devices/). A small number of Windows 10 devices don't have the WebView2 Runtime installed. We recommend that you handle this edge case, by using either of the following approaches: -* Programmatically deploy the Evergreen Runtime with your app. See [Deploying the Evergreen WebView2 Runtime](#deploying-the-evergreen-webview2-runtime) below. +* Programmatically deploy the Evergreen Runtime with your app. See [Deploying the Evergreen WebView2 Runtime](#deploying-the-evergreen-webview2-runtime) below. -* Redirect your end users to the Microsoft site: [Download Microsoft Edge WebView2](https://developer.microsoft.com/microsoft-edge/webview2/consumer/), and have end users download the Evergreen WebView2 Runtime installer from the site and install the Runtime themselves. +* Redirect your end users to the Microsoft site: [Download Microsoft Edge WebView2](https://developer.microsoft.com/microsoft-edge/webview2/consumer/), and have end users download the Evergreen WebView2 Runtime installer from the site and install the Runtime themselves. See also: * [Prerelease and Release SDKs for WebView2](./versioning.md) - Use a Prerelease version of the SDK along with a preview channel of Microsoft Edge; or use a Release version of the SDK along with the Evergreen WebView2 Runtime. @@ -90,15 +114,15 @@ See also: Only one installation of the Evergreen WebView2 Runtime is needed for all Evergreen apps on the device. Several tools are available at [Download the WebView2 Runtime](https://developer.microsoft.com/microsoft-edge/webview2#download-the-webview2-runtime) to help you deploy the Evergreen Runtime. -* For online clients: _WebView2 Runtime Bootstrapper_ is a tiny (approximately 2 MB) installer. The WebView2 Runtime Bootstrapper downloads and installs the Evergreen Runtime from Microsoft servers that matches the user's device architecture. +* For online clients: _WebView2 Runtime Bootstrapper_ is a tiny (approximately 2 MB) installer. The WebView2 Runtime Bootstrapper downloads and installs the Evergreen Runtime from Microsoft servers that matches the user's device architecture. - * In the setup part of your WebView2 app, link to the bootstrapper. Use a link to programmatically download the bootstrapper; select the **Get the Link** button at the above download page. + * In the setup part of your WebView2 app, link to the bootstrapper. Use a link to programmatically download the bootstrapper; select the **Get the Link** button at the above download page. - * Or, download the bootstrapper and package it with your WebView2 app. + * Or, download the bootstrapper and package it with your WebView2 app. -* For offline clients: _WebView2 Runtime Standalone Installer_ is a full installer that installs the Evergreen WebView2 Runtime in offline environments. +* For offline clients: _WebView2 Runtime Standalone Installer_ is a full installer that installs the Evergreen WebView2 Runtime in offline environments. -* If you're using App Installer to deploy MSIX applications, you can specify the WebView2 Runtime as a dependency, to have it be installed with the application. For details about how to do this, see [win32dependencies:ExternalDependency (Windows 10, Windows 11)](/uwp/schemas/appxpackage/uapmanifestschema/element-win32dependencies-externaldependency) in the App package manifest docs. See also [Install Windows 10 apps with App Installer](/windows/msix/app-installer/app-installer-root). +* If you're using App Installer to deploy MSIX applications, you can specify the WebView2 Runtime as a dependency, to have it be installed with the application. For details about how to do this, see [win32dependencies:ExternalDependency (Windows 10, Windows 11)](/uwp/schemas/appxpackage/uapmanifestschema/element-win32dependencies-externaldependency) in the App package manifest docs. See also [Install Windows 10 apps with App Installer](/windows/msix/app-installer/app-installer-root). @@ -224,6 +248,13 @@ To use the new version of the WebView2 Runtime, you need to either release all r In the Evergreen distribution mode, the WebView2 Runtime is automatically kept up to date on the client to provide the latest features and security fixes. If you use Evergreen distribution, to ensure that your WebView2 app stays compatible with the web, you should set up testing infrastructure. +Microsoft Edge preview channels (Beta, Dev, and Canary) provide a sneak peek into what is coming next in the WebView2 Runtime. Test your WebView2 app regularly against a Microsoft Edge preview channel, and update your app or [report issues](https://github.com/MicrosoftEdge/WebViewFeedback) if issues arise. See [Test upcoming APIs and features](../how-to/set-preview-channel.md). + Canary is the recommended preview channel, because it ships at the fastest cadence and has the newest APIs. + +To help you decide which channel is right, see [Overview of the Microsoft Edge channels](/deployedge/microsoft-edge-channels). You can [Download Microsoft Edge Insider Channels](https://www.microsoft.com/edge/download/insider) on your test environment, and use `regkey` or environment variables to indicate the channel preference for your testing app. + +See [CreateCoreWebView2EnvironmentWithOptions](/microsoft-edge/webview2/reference/win32/webview2-idl#createcorewebview2environmentwithoptions). You can also use WebDriver to automate WebView2 testing, as described in [Automate, and test WebView2 with Microsoft Edge WebDriver](../how-to/webdriver.md). + For best practices about how to test your app for forward-compatibility, see [Prerelease testing using preview channels](../how-to/prerelease-testing.md) and [Self-host by deploying preview channels](../how-to/self-hosting.md). diff --git a/microsoft-edge/webview2/concepts/evergreen-vs-fixed-version.md b/microsoft-edge/webview2/concepts/evergreen-vs-fixed-version.md index 6951bc7a1a..2b543e0320 100644 --- a/microsoft-edge/webview2/concepts/evergreen-vs-fixed-version.md +++ b/microsoft-edge/webview2/concepts/evergreen-vs-fixed-version.md @@ -12,6 +12,21 @@ ms.date: 10/10/2025 When releasing an app that uses Microsoft Edge WebView2, you need to distribute the WebView2 Runtime, either by distributing the automatically updated _Evergreen_ Runtime, or by distributing a _Fixed Version_ of the Runtime. +**Detailed contents:** +* [Introduction](#introduction) +* [The WebView2 Runtime](#the-webview2-runtime) +* [The Evergreen Runtime distribution mode](#the-evergreen-runtime-distribution-mode) + * [Windows 11 devices and Windows 10 devices](#windows-11-devices-and-windows-10-devices) +* [The Fixed Version runtime distribution mode](#the-fixed-version-runtime-distribution-mode) +* [Understanding the options at the Runtime download page](#understanding-the-options-at-the-runtime-download-page) +* [See also](#see-also) + + + +## Introduction + +When releasing an app that uses Microsoft Edge WebView2, you need to distribute the WebView2 Runtime, either by distributing the automatically updated _Evergreen_ Runtime, or by distributing a _Fixed Version_ of the Runtime. + A WebView2 app depends on the WebView2 Runtime on client machines. When you distribute your WebView2 app, you need to take into account how the WebView2 Runtime is distributed to and updated on client machines. For details about how to distribute the Runtime, see [Distribute your app and the WebView2 Runtime](./distribution.md). @@ -32,15 +47,15 @@ In the _Evergreen_ distribution mode, the WebView2 Runtime isn't packaged with y Pros: -* The underlying web platform (WebView2 Runtime) updates automatically without more effort from you. +* The underlying web platform (WebView2 Runtime) updates automatically without more effort from you. -* Less disk space is required for the WebView2 Runtime on client systems, because the WebView2 Runtime is shared by all WebView2 apps that are on the client. +* Less disk space is required for the WebView2 Runtime on client systems, because the WebView2 Runtime is shared by all WebView2 apps that are on the client. -* On eligible systems, binaries for Microsoft Edge and the Evergreen WebView2 Runtime are hard-linked together when they are on the same version. This linking provides benefits for disk footprint, memory, and performance. +* On eligible systems, binaries for Microsoft Edge and the Evergreen WebView2 Runtime are hard-linked together when they are on the same version. This linking provides benefits for disk footprint, memory, and performance. Cons: -* Your WebView2 app cannot specify that a particular version of the WebView2 Runtime is required. +* Your WebView2 app cannot specify that a particular version of the WebView2 Runtime is required. See also: * [The Evergreen Runtime distribution mode](./distribution.md#the-evergreen-runtime-distribution-mode) in _Distribute your app and the WebView2 Runtime_. @@ -66,15 +81,16 @@ See: In the _Fixed Version_ distribution mode, you download a specific version of the WebView2 Runtime and package it together with your WebView2 app in your app package. The WebView2 Runtime that you package with your app is used only by your WebView2 app, not by any other apps on the client's machine. Pros: -* You have more control over versioning of the WebView2 Runtime. You know which WebView2 APIs are available to your app, because you control which version of the WebView2 Runtime is available to your app. Your app doesn't need to test whether the latest APIs are present. + +* You have more control over versioning of the WebView2 Runtime. You know which WebView2 APIs are available to your app, because you control which version of the WebView2 Runtime is available to your app. Your app doesn't need to test whether the latest APIs are present. Cons: -* You need to manage the WebView2 Runtime yourself. The WebView2 Runtime isn't automatically updated on clients, so to use the latest WebView2 APIs, you must periodically update your app together with the updated WebView2 Runtime. +* You need to manage the WebView2 Runtime yourself. The WebView2 Runtime isn't automatically updated on clients, so to use the latest WebView2 APIs, you must periodically update your app together with the updated WebView2 Runtime. -* More disk space is required on the client, if there are multiple WebView2 apps installed. +* More disk space is required on the client, if there are multiple WebView2 apps installed. -* The Fixed Version runtime can't be installed by using an installer. +* The Fixed Version runtime can't be installed by using an installer. See also: * [The Fixed Version runtime distribution mode](./distribution.md#the-fixed-version-runtime-distribution-mode) in _Distribute your app and the WebView2 Runtime_. @@ -89,15 +105,15 @@ The [Download the WebView2 Runtime](https://developer.microsoft.com/microsoft-ed The Evergreen distribution mode is recommended for most apps. -* The **Evergreen Bootstrapper** section of the page provides a small Evergreen Runtime bootstrapper that runs on the client machine, for online users. The bootstrapper downloads and installs the appropriate Evergreen WebView2 Runtime onto the client. You can use the bootstrapper a couple different ways: +* The **Evergreen Bootstrapper** section of the page provides a small Evergreen Runtime bootstrapper that runs on the client machine, for online users. The bootstrapper downloads and installs the appropriate Evergreen WebView2 Runtime onto the client. You can use the bootstrapper a couple different ways: - * Link to the bootstrapper, using a link that you obtain from the **Get the Link** button. Your app uses this link to programmatically download the bootstrapper onto the client and invoke the bootstrapper. This approach avoids the need to package the bootstrapper with your app. This approach has a dependency on Microsoft's Content Delivery Network (CDN), to get the bootstrapper. + * Link to the bootstrapper, using a link that you obtain from the **Get the Link** button. Your app uses this link to programmatically download the bootstrapper onto the client and invoke the bootstrapper. This approach avoids the need to package the bootstrapper with your app. This approach has a dependency on Microsoft's Content Delivery Network (CDN), to get the bootstrapper. - * Download the bootstrapper (using the **Download** button in the **Bootstrapper** section) and then distribute the bootstrapper with your app. In this approach, you package the bootstrapper with your app installer/updater or with your app itself, and invoke the bootstrapper that you included with your app. This approach avoids dependency on Microsoft's CDN, to get the bootstrapper. + * Download the bootstrapper (using the **Download** button in the **Bootstrapper** section) and then distribute the bootstrapper with your app. In this approach, you package the bootstrapper with your app installer/updater or with your app itself, and invoke the bootstrapper that you included with your app. This approach avoids dependency on Microsoft's CDN, to get the bootstrapper. -* The **Evergreen Standalone Installer** section of the page provides a large, standalone Evergreen installer, primarily for offline users. In this approach, you package the standalone installer with your app installer/updater or app itself, and invoke the Evergreen Standalone installer. This approach avoids dependency on Microsoft's CDN, to get the Runtime. +* The **Evergreen Standalone Installer** section of the page provides a large, standalone Evergreen installer, primarily for offline users. In this approach, you package the standalone installer with your app installer/updater or app itself, and invoke the Evergreen Standalone installer. This approach avoids dependency on Microsoft's CDN, to get the Runtime. -* The **Fixed Version** section of the page provides a Fixed Version runtime, which is a specific version of the WebView2 Runtime that you distribute along with your app. +* The **Fixed Version** section of the page provides a Fixed Version runtime, which is a specific version of the WebView2 Runtime that you distribute along with your app. diff --git a/microsoft-edge/webview2/concepts/platform-components-images/app-control-server.png b/microsoft-edge/webview2/concepts/platform-components-images/app-control-server.png new file mode 100644 index 0000000000..8e6b4d1bf2 Binary files /dev/null and b/microsoft-edge/webview2/concepts/platform-components-images/app-control-server.png differ diff --git a/microsoft-edge/webview2/concepts/platform-components-images/app-design.png b/microsoft-edge/webview2/concepts/platform-components-images/app-design.png new file mode 100644 index 0000000000..f70568668b Binary files /dev/null and b/microsoft-edge/webview2/concepts/platform-components-images/app-design.png differ diff --git a/microsoft-edge/webview2/concepts/platform-components-images/control-runtime-sdk.png b/microsoft-edge/webview2/concepts/platform-components-images/control-runtime-sdk.png new file mode 100644 index 0000000000..4106d7fcbe Binary files /dev/null and b/microsoft-edge/webview2/concepts/platform-components-images/control-runtime-sdk.png differ diff --git a/microsoft-edge/webview2/concepts/platform-components-images/control-sdk-runtime.png b/microsoft-edge/webview2/concepts/platform-components-images/control-sdk-runtime.png new file mode 100644 index 0000000000..d6f91a7997 Binary files /dev/null and b/microsoft-edge/webview2/concepts/platform-components-images/control-sdk-runtime.png differ diff --git a/microsoft-edge/webview2/concepts/platform-components-images/dev-side-user-side.png b/microsoft-edge/webview2/concepts/platform-components-images/dev-side-user-side.png new file mode 100644 index 0000000000..c80a4ebcf5 Binary files /dev/null and b/microsoft-edge/webview2/concepts/platform-components-images/dev-side-user-side.png differ diff --git a/microsoft-edge/webview2/concepts/platform-components-images/distribute-runtime.png b/microsoft-edge/webview2/concepts/platform-components-images/distribute-runtime.png new file mode 100644 index 0000000000..4d9f63ec30 Binary files /dev/null and b/microsoft-edge/webview2/concepts/platform-components-images/distribute-runtime.png differ diff --git a/microsoft-edge/webview2/concepts/platform-components-images/full-diagram.png b/microsoft-edge/webview2/concepts/platform-components-images/full-diagram.png new file mode 100644 index 0000000000..b6216fc092 Binary files /dev/null and b/microsoft-edge/webview2/concepts/platform-components-images/full-diagram.png differ diff --git a/microsoft-edge/webview2/concepts/platform-components-images/resources-support.png b/microsoft-edge/webview2/concepts/platform-components-images/resources-support.png new file mode 100644 index 0000000000..cc0f88d622 Binary files /dev/null and b/microsoft-edge/webview2/concepts/platform-components-images/resources-support.png differ diff --git a/microsoft-edge/webview2/concepts/platform-components-images/resources.png b/microsoft-edge/webview2/concepts/platform-components-images/resources.png new file mode 100644 index 0000000000..838a570e64 Binary files /dev/null and b/microsoft-edge/webview2/concepts/platform-components-images/resources.png differ diff --git a/microsoft-edge/webview2/concepts/platform-components.md b/microsoft-edge/webview2/concepts/platform-components.md new file mode 100644 index 0000000000..281357a89f --- /dev/null +++ b/microsoft-edge/webview2/concepts/platform-components.md @@ -0,0 +1,374 @@ +--- +title: Components of the WebView2 platform +description: Which parts of WebView2 reside on the Dev and user machine. How native code and controls interact with web code and the WebView2 control. +author: MSEdgeTeam +ms.author: msedgedevrel +ms.topic: article +ms.service: microsoft-edge +ms.subservice: webview +ms.date: 04/21/2023 +--- +# Components of the WebView2 platform + +To add WebView2 to your app, you use the WebView2 SDK on your development machine, and distribute the WebView2 Runtime to user machines. + +**Detailed contents:** +* [Components on the Dev machine and user machines](#components-on-the-dev-machine-and-user-machines) + * [Dev machine](#dev-machine) + * [Distributing the app and Runtime](#distributing-the-app-and-runtime) + * [User machine](#user-machine) + * [Resources](#resources) +* [Top-level WebView2 components](#top-level-webview2-components) +* [The WebView2 control, SDK, and Runtime](#the-webview2-control-sdk-and-runtime) + * [Relationship between the WebView2 control, SDK, and Runtime](#relationship-between-the-webview2-control-sdk-and-runtime) + * [WebView2 control, Runtime, and SDK](#webview2-control-runtime-and-sdk) +* [Design architecture of a WebView2 app](#design-architecture-of-a-webview2-app) + * [Design architecture of a WebView2 app](#design-architecture-of-a-webview2-app) +* [Development machine vs. user machine](#development-machine-vs-user-machine) + * [App on the Development machine and user machine](#app-on-the-development-machine-and-user-machine) +* [Ways to distribute, install, and update the Runtime on the user's machine](#ways-to-distribute-install-and-update-the-runtime-on-the-users-machine) + * [Approaches for distributing the WebView2 Runtime](#approaches-for-distributing-the-webview2-runtime) +* [Host app, WebView2 control, and HTTP server](#host-app-webview2-control-and-http-server) + * [Host app, WebView2 control, and HTTP server](#host-app-webview2-control-and-http-server) +* [Prerelease SDK with preview browser channel, or Release SDK with Runtime](#prerelease-sdk-with-preview-browser-channel-or-release-sdk-with-runtime) +* [Using a Prerelease SDK and experimental APIs with a Preview channel of Microsoft Edge](#using-a-prerelease-sdk-and-experimental-apis-with-a-preview-channel-of-microsoft-edge) +* [Using a Release SDK and stable APIs with the Runtime](#using-a-release-sdk-and-stable-apis-with-the-runtime) +* [See also](#see-also) + + + +## Components on the Dev machine and user machines + +To add WebView2 to your app, you use the WebView2 SDK on your development machine, and distribute the WebView2 Runtime to user machines. + +The following diagram shows the high-level WebView2 components on your development machine and user machines: + +![Full diagram of WebView2](./platform-components-images/full-diagram.png) + +Developing a WebView2 app involves software residing in the following places: + +| Location | Description | +|---|---| +| [Dev machine](#dev-machine) | You use a Visual Studio project that includes the WebView2 SDK. The SDK includes the WebView2 Runtime, which is an embedded web browser component used for the WebView2 control instances in your host app. | +| [Distributing the app and Runtime](#distributing-the-app-and-runtime) | There are several ways to deliver the always up-to-date Evergreen version of the WebView2 Runtime to user machines, with several levels of Internet connectivity supported. Some scenarios benefit from distributing a specific, fixed-version WebView2 Runtime. | +| [User machine](#user-machine) | Your host app on user machines includes instances of the WebView2 control, which uses the WebView2 Runtime. | +| [Resources](#resources) | The present documentation; the WebView2Samples repo including basic Getting Started WebView2 projects and more full-featured Sample projects; the WebView2Announcements repo; and the WebView2Feedback repo. | + +Details are below. + + + +#### Dev machine + +This section explains the left column of the above diagram. + +The Dev machine for developing a WebView2 app consists of the following components: + +* Visual Studio project - Use a Visual Studio project template to create a standard platform app, and then add the WebView2 SDK to the project as a NuGet package. + + * Layout designer - Lay out your controls in Visual Studio. + + * WebView2 control instances - Web content areas of your app. The app's web-side code runs in this control. + + * Native control instances - Native controls and panes of your app. + + * The WebView2 SDK. + + * Per-platform WebView2 APIs, including `CoreWebView2`, `CoreWebView2Controller`, and `CoreWebView2Environment`. Primarily called by native-side code. + + * `AddHostObjectToScript` - Enables exposing platform APIs and WebView2 APIs to JavaScript code. See [Interop of native and web code](../how-to/communicate-btwn-web-native.md) + + * [JavaScript APIs](../webview2-api-reference.md#javascript) (WebView2Script package) - Called by web-side code to communicate with the host application. + + * Platform APIs - Non-WebView2 APIs provided by the platform; can be exposed to web-side code. + +* WebView2 Runtime - A browser component that contains WebView2 APIs. + + + +#### Distributing the app and Runtime + +This section explains the middle column of the above diagram. + +There are three ways to distribute the Evergreen Runtime to user machines, as well as a fixed-version Runtime option: + +* Evergreen Runtime - The WebView2 Evergreen Runtime is automatically updated to the latest version, on user machines, any of several ways with different degrees of relying on an Internet connection: + + * Link to the Evergreen Runtime bootstrapper from your app installer. Maximally relies on an internet connection. + + * Package the Evergreen Runtime bootstrapper into your app installer. Moderately relies on an internet connection. + + * Package the Evergreen Runtime standalone installer. Minimally relies on an internet connection. + +* Package a fixed-version Runtime. Gives fully determinate control of which version of which APIs are present. + +See also: +* [Approaches for distributing the WebView2 Runtime](#approaches-for-distributing-the-webview2-runtime), below. + + + +#### User machine + +This section explains the right-hand column of the above diagram. + +On the end-user machine are the following components that are involved in running a WebView2 app: + +* The host app. + + * WebView2 native code. + + * WebView2 web code - The WebView2 APIs are mostly called by native-side code|web-side code. + + * WebView2 control instances - The WebView2 app's web-side code runs in a WebView2 control. + + * Non-WebView2 native code. + + * Non-WebView2 web code. + + * Native control instances. + +* The WebView2 Runtime. + + + +#### Resources + +![Diagram: Resources](./platform-components-images/resources.png) + +Resources for WebView2 app development include: + +* Documentation, such as [Introduction to Microsoft Edge WebView2](../index.md). + +* Runtime installer download page - see the [Download the WebView2 Runtime](https://developer.microsoft.com/microsoft-edge/webview2#download) section of the **Microsoft Edge WebView2** page. + +* NuGet SDK package download site - see [Microsoft.Web.WebView2](https://www.nuget.org/packages/Microsoft.Web.WebView2) at NuGet.org. + +* GitHub repos and support: + + * [WebView2Samples repo](https://github.com/MicrosoftEdge/WebView2Samples) - contains completed Getting Started article projects (minimal code) and code-rich Samples. + + * [WebView2Announcements repo](https://github.com/MicrosoftEdge/WebView2Announcements) + + * [WebView2Feedback repo](https://github.com/MicrosoftEdge/WebView2Feedback) + + * [Contact the WebView2 Team](../contact.md). + + + +## Top-level WebView2 components + +| Shorthand term | Complete term | +|---|---| +| _App_ | Any app, for any framework or platform, that includes an instance of the WebView2 control. An app can have areas that use a WebView2 control instance, and other areas that don't use the control. | +| _SDK_ | The WebView2 SDK. When part of your app uses WebView2, that code can call these APIs in conjunction with instances of the WebView2 control. The Release SDK ships to users, and contains only stable APIs. The Prerelease SDK is only used by Devs, and contains some experimental APIs. | +| _Control_ | An instance of the WebView2 control. In an app, typically appears as a rectangular area than contains web content. | +| _Runtime_ | The WebView2 Runtime, which is a browser engine. Installed on user machines, as well as Dev and test machines. | +| _Preview channel_ | A preview channel of Microsoft Edge, either Beta (near-stable), Dev, or Canary (the very latest build; daily). For Dev and test machines only, not user machines. | + + + +## The WebView2 control, SDK, and Runtime + +The WebView2 control, WebView2 SDK, and WebView2 Runtime have the following roles: + +| Component | Role | +|:---|:---| +| WebView2 SDK | Provides APIs for developers to use in an app's code. Used by Dev locally while coding the app. Two versions: Prerelease SDK for local Dev testing, and Release SDK for developing shippable code for users. | +| WebView2 control | You embed the WebView2 control in the app. Hosts the Runtime; serves as a visible area to display web content. | +| WebView2 Runtime | On Dev's test machine and on user machines. Or, instead of using the Runtime, Dev can use a preview channel of Microsoft Edge for local testing, when using the Prerelease SDK. | + + + +#### Relationship between the WebView2 control, SDK, and Runtime + +![Diagram: Relationship between the WebView2 control, SDK, and Runtime](./platform-components-images/control-sdk-runtime.png) + +Control: +* WebView2 control - in the app layout; hosts the Runtime. + +SDK: +* WebView2 SDK - used by Dev while coding. Either: + * Prerelease SDK (Dev only; includes experimental APIs for Dev testing). + * Release SDK. + +Runtime: +* WebView2 Runtime - a browser for use as a component of an app; on user machines. Either: + * Preview channel of Microsoft Edge (Dev only) + * Runtime + + + +#### WebView2 control, Runtime, and SDK + +![WebView2 control, Runtime, and SDK](./platform-components-images/control-runtime-sdk.png) + +This diagram shows the following outline: + +Release SDK (left side of diagram): +* .NET/C# APIs. +* WinRT/C#. +* Win32/C++. +* WebView2Script package (JavaScript APIs). + +The Release SDK uses the WebView2 Runtime. +* The Runtime includes the WebView2Script package (JavaScript APIs). + +Prerelease SDK (right side of diagram): +* .NET/C# APIs, including experimental APIs. +* WinRT/C# APIs, including experimental APIs. +* Win32/C++ APIs, including experimental APIs. +* WebView2Script package (JavaScript APIs). + +The Prerelease SDK uses a preview channel of the browser. +* The browser includes the WebView2Script package (JavaScript APIs). + +You periodically download the latest SDK from NuGet. NuGet links are in [Release Notes for the WebView2 SDK](../release-notes.md). + +The SDK includes the JavaScript API, which is in the `WebView2Script` package. + +See also: +* [WebView2 API Reference](../webview2-api-reference.md) + + + +## Design architecture of a WebView2 app + +A host app contains the following categories of code and components: +* Native code calls platform APIs and WebView2 APIs. +* WebView2 control instance. +* Native code calls platform APIs and WebView2 APIs. +* Web (JavaScript) code calls WebView2Script APIs & exposed native APIs. + + + +#### Design architecture of a WebView2 app + +![Design architecture of a WebView2 app](./platform-components-images/app-design.png) + +Categories of code: +* Native WebView2 code, calls WebView2 APIs and platform APIs. +* Web code (JavaScript), calls WebView2Script APIs & exposed native APIs. +* Native non-WebView2 code, calls platform APIs and native controls. +* Non-WebView2 web code (JavaScript). + +Two-way code: +* Call web code (JavaScript) from native code. +* Call native code from web code (JavaScript). + + + +## Development machine vs. user machine + +Here are the differences between the Dev machine and User machine, for which components are used. + + + +#### App on the Development machine and user machine + +![App on the Development machine and user machine](./platform-components-images/dev-side-user-side.png) + +| Component | Dev machine | User machine | +|---|---|---| +| Runtime | A Preview channel of Microsoft Edge, or the Runtime that's part of the SDK. | Runtime (downloaded via bootstrapper, or packaged with app); Microsoft Edge isn't used. | +| Working environment | Visual Studio project that has the SDK package installed. Layout designer includes WebView control areas & native, non-WebView control areas. | The App (including WebView control areas, and native, non-WebView control areas). | +| Activity | Dev works with the APIs in code (experimental APIs or stable APIs). | User machine runs app. The WebView2 parts of the app (instances of the WebView2 control) use the Runtime to display webpage functionality. | +| User interface environment | Visual Studio (layout designer includes WebView control areas & native, non-WebView control areas). | The App (including WebView control areas, and native, non-WebView control areas). | +| SDK | Prerelease SDK (experimental APIs) or Release SDK (stable APIs). | No SDK; just the Runtime containing the executable stable APIs. | +| Control | Placed on layout designer in Visual Studio. | Areas (regions) of the app containing web content. | + + + +## Ways to distribute, install, and update the Runtime on the user's machine + +There are several ways to distribute the WebView2 Runtime with your app: + + + +#### Approaches for distributing the WebView2 Runtime + +![Diagram: Four approaches to distribute the WebView2 Runtime](./platform-components-images/distribute-runtime.png) + +| Name of distribution approach | Description | Notes | +|---|---|---| +| Link to the Evergreen Runtime bootstrapper | In your app's installer, link to the Evergreen Runtime bootstrapper. Have your app's installer use this link to programmatically download and install the Evergreen bootstrapper onto the user's machine. Then invoke the bootstrapper to install the appropriate Runtime for the user's device. | For users who have an online connection. The Evergreen bootstrapper is a tiny installer that installs the correct Runtime for the user's CPU, using an internet connection. | +| Package the Evergreen Runtime bootstrapper | Download the Evergreen bootstrapper to your Dev machine. Package and distribute the Evergreen bootstrapper with your app installer. Then your app installer invokes the bootstrapper to install the Runtime on the user's machine. | For users who don't have a reliable connection to the bootstrapper CDN site. | +| Package the Evergreen Runtime standalone installer | Download the Evergreen standalone installer to your Dev machine, and package it with your app. Package the Evergreen standalone installer with your app's installer. Your app's installer then invokes the Evergreen standalone installer to install the Runtime on the user's device. | For offline users. A large, standalone Evergreen Runtime installer for offline users, that includes the Evergreen Runtime. | +| Package a fixed-version Runtime | Download a version-specific, CPU-specific Runtime to your Dev machine. Package and distribute the fixed-version Runtime with your app's installer. Your app's installer installs the specific fixed-version Runtime on the user's machine. | Specialty case, for when you need specific version of the APIs; avoids testing whether latest APIs are available. | + +The above approaches are listed in the same sequence as in the [Download the WebView2 Runtime](https://developer.microsoft.com/microsoft-edge/webview2#download) section of the **Microsoft Edge WebView2** page, from lightweight to heavyweight approaches. Favor the lightweight approaches; use a heavyweight approach if required by a specialized scenario. + +_Your app's installer_ means your app's installer/updater, which can be separate from your app, or a part of your app. + +See also: +* [Understanding the options at the Runtime download page](../concepts/evergreen-vs-fixed-version.md#understanding-the-options-at-the-runtime-download-page) in _Evergreen vs. fixed version of the WebView2 Runtime_. + + + +## Host app, WebView2 control, and HTTP server + +The WebView2 control acts as an intermediary for communication between the host app and the HTTP server. + + + +#### Host app, WebView2 control, and HTTP server + +![Host app, WebView2 control, and HTTP server](./platform-components-images/app-control-server.png) + + + +## Prerelease SDK with preview browser channel, or Release SDK with Runtime + +| Version | Renderer platform | Description | +|:---|:---|:---| +| Prerelease SDK | A preview channel of Microsoft Edge (Beta, Dev, or Canary) | For experimenting and testing your app against upcoming changes, on your Dev machines. | +| Release SDK | The WebView2 Runtime | For shipping your app to end users. | + +* A Prerelease version of the WebView2 SDK uses a preview channel of Microsoft Edge (Beta, Dev, or Canary). +* A Release version of the WebView2 SDK uses the WebView2 Runtime. + +See also: +* [Understanding the options at the Runtime download page](../concepts/evergreen-vs-fixed-version.md#understanding-the-options-at-the-runtime-download-page) in _Evergreen vs. fixed version of the WebView2 Runtime_. +* [Prerelease and release SDKs for WebView2](./versioning.md) +* [Distribute your app and the WebView2 Runtime](./distribution.md) + + + +## Using a Prerelease SDK and experimental APIs with a Preview channel of Microsoft Edge + +To develop the prerelease version of your app using experimental APIs, or to test your app against upcoming SDK changes: + +* On your Dev machine, in the Visual Studio project, install a **Prerelease** version of the `Microsoft.Web.WebView2` SDK NuGet package. Write code that uses the **experimental** APIs (and stable APIs). +* On your Dev machine, install and use a preview channel of Microsoft Edge. + +To distribute your prerelease app to your test machine: +* On your test machine, install a preview channel of Microsoft Edge. + +See also: +* [Prerelease and Release SDKs for WebView2](./versioning.md) - Either use a prerelease SDK with a preview channel of Microsoft Edge, or use a release SDK with the WebView2 Runtime. + + + +## Using a Release SDK and stable APIs with the Runtime + +To develop the release version of your app: +* On your Dev machine, in the Visual Studio project, install a **Release** version of the `Microsoft.Web.WebView2` SDK NuGet package. Write code that uses only the **stable** APIs. +* On your Dev machine, use the WebView2 Runtime (part of the SDK package). + +The WebView2 Runtime is like a browser engine for use as a component in your app. + +There are several ways to distribute your app and the Runtime to users. See [Ways to distribute, install, and update the Runtime on the user's machine](#ways-to-distribute-install-and-update-the-runtime-on-the-users-machine) above. + + +See also: +* [Prerelease and Release SDKs for WebView2](./versioning.md) - Either use a prerelease SDK with a preview channel of Microsoft Edge, or use a release SDK with the WebView2 Runtime. + + + +## See also + +* [Overview of WebView2 features and APIs](./overview-features-apis.md) +* [Getting Started tutorials](../get-started/get-started.md) +* [Distribute your app and the WebView2 Runtime](./distribution.md) + +developer.microsoft.com: +* [Microsoft Edge WebView2](https://developer.microsoft.com/microsoft-edge/webview2) - initial introduction to WebView2 features at developer.microsoft.com. diff --git a/microsoft-edge/webview2/concepts/versioning.md b/microsoft-edge/webview2/concepts/versioning.md index 9c6493312d..2e6ddd2d6d 100644 --- a/microsoft-edge/webview2/concepts/versioning.md +++ b/microsoft-edge/webview2/concepts/versioning.md @@ -12,6 +12,31 @@ ms.date: 04/25/2023 The WebView2 SDK is provided as a Prerelease or Release version of the **Microsoft.Web.WebView2** NuGet package. Either use a Prerelease SDK with a preview channel of Microsoft Edge, or use a Release SDK with the WebView2 Runtime. +**Detailed contents:** +* [Introduction](#introduction) + * [Phases of introducing APIs](#phases-of-introducing-apis) + * [Selecting which type of SDK to use](#selecting-which-type-of-sdk-to-use) +* [Use a Prerelease version of the SDK along with a preview channel of Microsoft Edge](#use-a-prerelease-version-of-the-sdk-along-with-a-preview-channel-of-microsoft-edge) +* [Use a release version of the SDK along with the Runtime](#use-a-release-version-of-the-sdk-along-with-the-runtime) +* [Release cadence](#release-cadence) +* [Minimum version and build number to instantiate WebView2](#minimum-version-and-build-number-to-instantiate-webview2) +* [Forward compatibility of APIs](#forward-compatibility-of-apis) +* [Experimental APIs](#experimental-apis) + * [Developing with Experimental APIs and providing feedback](#developing-with-experimental-apis-and-providing-feedback) + * [Moving from Experimental APIs to Stable APIs](#moving-from-experimental-apis-to-stable-apis) +* [Matching the Runtime version with the SDK version](#matching-the-runtime-version-with-the-sdk-version) +* [Feature-detecting to test whether the installed Runtime supports recently added APIs](#feature-detecting-to-test-whether-the-installed-runtime-supports-recently-added-apis) + * [.NET and WinUI, and WinRT](#net-and-winui-and-winrt) + * [Win32 C/C++](#win32-cc) + * [Provide graceful fallback](#provide-graceful-fallback) +* [See also](#see-also) + + + +## Introduction + +The WebView2 SDK is provided as a Prerelease or Release version of the **Microsoft.Web.WebView2** NuGet package. Either use a Prerelease SDK with a preview channel of Microsoft Edge, or use a Release SDK with the WebView2 Runtime. + _Prerelease_ SDK packages are for use during development if you want to test the latest WebView2 APIs, including the Experimental APIs, before support for those APIs is added to the Runtime. The Canary channel is recommended, because it has the implementations of the latest APIs. When you want to test and use Experimental WebView2 APIs, use the following combination: * A _Prerelease_ version of the WebView2 SDK. * A _preview channel_ of Microsoft Edge on your development client. @@ -168,7 +193,7 @@ Once an API has been moved from Experimental to Stable status, you need to move In the Evergreen distribution approach, the client's WebView2 Runtime automatically updates to the latest version available. However, a user or IT admin might choose to prevent automatic updating of the WebView2 Runtime. The resulting outdated Runtime on the client might cause compatibility issues with your updated WebView2 app that uses new APIs from a recent SDK. -In case updating the WebView2 Runtime is prevented on the client, make sure that you know the minimum build number of the WebView2 Runtime that is required by your app. To view or get the latest WebView2 Runtime versions, see [Download the WebView2 Runtime](https://developer.microsoft.com/microsoft-edge/webview2#download-the-webview2-runtime) in the _Microsoft Edge WebView2_ page at developer.microsoft.com. The minimum required Runtime version to support the General Availability release of the SDK (build 616) is older than for the latest Runtime. The latest Runtime supports all APIs that are in the latest Release SDK. +In case updating the WebView2 Runtime is prevented on the client, make sure that you know the minimum build number of the WebView2 Runtime that's required by your app. To view or get the latest WebView2 Runtime versions, use the [Download the WebView2 Runtime](https://developer.microsoft.com/microsoft-edge/webview2#download-the-webview2-runtime) section of the _Microsoft Edge WebView2_ page at developer.microsoft.com. The minimum required Runtime version to support the General Availability release of the SDK (build 616) is older than for the latest Runtime. The latest Runtime supports all APIs that are in the latest Release SDK. To check the compatibility between specific build numbers of the SDK and the Runtime or Microsoft Edge preview channel, see [Release notes for the WebView2 SDK](../release-notes/index.md). diff --git a/microsoft-edge/webview2/how-to/context-menus.md b/microsoft-edge/webview2/how-to/context-menus.md index cbedb48ac0..f1a6c5a92e 100644 --- a/microsoft-edge/webview2/how-to/context-menus.md +++ b/microsoft-edge/webview2/how-to/context-menus.md @@ -10,7 +10,32 @@ ms.date: 04/27/2022 --- # Customize context menus in WebView2 -The WebView2 control provides a default context menu, and you can create your own context menu when using a WebView2 control. Use the **ContextMenuRequested** API to customize the context-menus (right-click menus) of a WebView2 app. For example, you can do any of the following: +The WebView2 control provides a default context menu, and you can create your own context menu when using a WebView2 control. Use the **ContextMenuRequested** API to customize the context-menus (right-click menus) of a WebView2 app. + +**Detailed contents:** +* [Introduction](#introduction) +* [Adding a custom context menu](#adding-a-custom-context-menu) +* [Example: Adding a custom context menu](#example-adding-a-custom-context-menu) +* [Adding menu items to a context menu](#adding-menu-items-to-a-context-menu) + * [Adding custom menu items to a default context menu](#adding-custom-menu-items-to-a-default-context-menu) +* [Example: Adding custom menu items to a default context menu](#example-adding-custom-menu-items-to-a-default-context-menu) +* [Removing menu items from a default context menu](#removing-menu-items-from-a-default-context-menu) +* [Example: Removing menu items from a default context menu](#example-removing-menu-items-from-a-default-context-menu) +* [Detecting when the user requests a context menu](#detecting-when-the-user-requests-a-context-menu) +* [Detecting when the user selects a custom menu item](#detecting-when-the-user-selects-a-custom-menu-item) +* [Reporting a selected command menu item to WebView2](#reporting-a-selected-command-menu-item-to-webview2) + * [Custom menu items](#custom-menu-items) +* [Disabling context menus](#disabling-context-menus) +* [API Reference overview](#api-reference-overview) +* [See also](#see-also) + + + +## Introduction + +The WebView2 control provides a default context menu, and you can create your own context menu when using a WebView2 control. Use the **ContextMenuRequested** API to customize the context-menus (right-click menus) of a WebView2 app. + +For example, you can do any of the following: * Add a custom context menu. @@ -728,7 +753,7 @@ When the user selects a WebView2 context menu command (a default menu item that' --- - + #### Custom menu items If your host app reports a custom menu item as the selected menu item, then the `CustomMenuItemSelected` event will be fired for the custom menu item. diff --git a/microsoft-edge/webview2/how-to/debug-visual-studio-code.md b/microsoft-edge/webview2/how-to/debug-visual-studio-code.md index dc0dfc121c..60773ab5d7 100644 --- a/microsoft-edge/webview2/how-to/debug-visual-studio-code.md +++ b/microsoft-edge/webview2/how-to/debug-visual-studio-code.md @@ -11,6 +11,32 @@ ms.date: 03/25/2025 # Debug WebView2 apps with Visual Studio Code Use Microsoft Visual Studio Code to debug scripts that run in WebView2 controls. + +**Detailed contents:** +* [Introduction](#introduction) +* [Create a launch.json file](#create-a-launchjson-file) + * [Using a registry value](#using-a-registry-value) + * [Command-line URL parameter passed in](#command-line-url-parameter-passed-in) +* [Debug your code](#debug-your-code) +* [Targeted WebView2 debugging](#targeted-webview2-debugging) + * [Cannot debug two WebView2 controls at the same time](#cannot-debug-two-webview2-controls-at-the-same-time) +* [Debug running processes](#debug-running-processes) + * [Using an environment variable](#using-an-environment-variable) +* [Debug tracing options](#debug-tracing-options) +* [Debug Office Add-ins](#debug-office-add-ins) +* [Debug WebView2 WinUI 2 (UWP) apps](#debug-webview2-winui-2-uwp-apps) +* [Source maps with the WebResourceRequested event or virtual host name mapping](#source-maps-with-the-webresourcerequested-event-or-virtual-host-name-mapping) +* [Troubleshoot the debugger](#troubleshoot-the-debugger) + * [Doesn't stop at breakpoint](#doesnt-stop-at-breakpoint) + * [Can't attach to running process](#cant-attach-to-running-process) +* [See also](#see-also) + + + +## Introduction + +Use Microsoft Visual Studio Code to debug scripts that run in WebView2 controls. + Visual Studio Code has a built-in debugger for browser debugging. See [Browser debugging in VS Code](https://code.visualstudio.com/docs/nodejs/browser-debugging). @@ -99,7 +125,7 @@ Open `launch.json` and complete the following actions to use targeted WebView2 d When debugging your app, you might need to step through the code from the beginning of the rendering process. If you are rendering webpages on sites and you don't have access to the source code, you can use the `?=value` option, because webpages ignore unrecognized parameters. - + #### Cannot debug two WebView2 controls at the same time After the first match is found in the URL, the debugger stops. You cannot debug two WebView2 controls at the same time, because the CDP port is shared by all WebView2 controls, and uses a single port number. @@ -257,7 +283,7 @@ WebView2 doesn't load source maps that are referenced by content which was loade You might encounter these scenarios when using the debugger. - + #### Doesn't stop at breakpoint If the debugger doesn't stop at the breakpoint, and you have debug output: @@ -265,7 +291,7 @@ If the debugger doesn't stop at the breakpoint, and you have debug output: To solve the issue, confirm that the file with the breakpoint is the same file that's used by the WebView2 control. The debugger doesn't perform source path mapping. - + #### Can't attach to running process If you can't attach to a running process, and you get a timeout error: diff --git a/microsoft-edge/webview2/how-to/javascript.md b/microsoft-edge/webview2/how-to/javascript.md index d29659f9d4..aa97ac5a67 100644 --- a/microsoft-edge/webview2/how-to/javascript.md +++ b/microsoft-edge/webview2/how-to/javascript.md @@ -13,6 +13,8 @@ ms.date: 4/1/2022 Using JavaScript in WebView2 controls allows you to customize native apps to meet your requirements. This article explores how to use JavaScript in WebView2, and reviews how to develop using advanced WebView2 features and functions. + + ## Before you begin @@ -23,7 +25,7 @@ This article assumes that you already have a working project. If you don't have ## Basic WebView2 functions -Use the following functions to begin embedding JavaScript in your WebView2 app. +Use the following functions to embed JavaScript in the native-side code of your WebView2 app: | API | Description | | --- | --- | @@ -34,27 +36,27 @@ Use the following functions to begin embedding JavaScript in your WebView2 app. ## Scenario: ExecuteScript JSON-encoded results -Because the result of `ExecuteScriptAsync` is JSON-encoded, if the result of evaluating the JavaScript is a string, you will receive a JSON-encoded string and not the value of the string. +Because the result of `ExecuteScriptAsync` is JSON-encoded, if the result of evaluating the JavaScript is a string, your native-side code will receive a JSON-encoded string, not the value of the string. -For example, the following code executes script that results in a string. The resulting string includes a quote at the start, a quote at the end, and escaping slashes: +For example, the following native-side code executes script that results in a string. The resulting string includes a quote at the start, a quote at the end, and escaping slashes: ```csharp string result = await coreWebView2.ExecuteScriptAsync(@"'example'"); Debug.Assert(result == "\"example\""); ``` -The script returns a string that `ExecuteScript` JSON-encodes for you. If you call `JSON.stringify` from your script, then the result is doubly encoded as a JSON string the value of which is a JSON string. +The script returns a string that `ExecuteScript` JSON-encodes for you. If you call `JSON.stringify` from your script (in your web-side code), then the result is doubly encoded, as a JSON string the value of which is a JSON string. -Only the properties that are directly in the result are included in the JSON-encoded object; inherited properties aren't included in the JSON-encoded object. Most DOM objects inherit all properties, so you'll need to explicitly copy their values into another object to return. For example: +Only the properties that are directly in the result are included in the JSON-encoded object; inherited properties aren't included in the JSON-encoded object. Most DOM objects inherit all properties, so your web-side code must explicitly copy the properties' values into another object and return that object to your native-side code. For example: Script | Result --- | --- `performance.memory` | `{}` `(() => { const {totalJSHeapSize, usedJSHeapSize} = performance.memory; return {totalJSHeapSize, usedJSHeapSize}; })();` | `{"totalJSHeapSize":4434368,"usedJSHeapSize":2832912}` -When we return just `performance.memory` we don't see any of its properties in the result because all properties are inherited. If instead, we copy particular property values from `performance.memory` into our own new object to return, then we see those properties in the result. +When we return just `performance.memory`, we don't see any of its properties in the result, because all properties are inherited. If instead, the web-side code copies particular property values from `performance.memory` into a new object and returns that object, then the native-side code sees those properties in the result. -When executing script via `ExecuteScriptAsync` that script is run in the global context. It helps to have your script in an anonymous function so that any variables you define aren't polluting the global context. +When executing script via `ExecuteScriptAsync`, that script is run in the global context. It helps to have your script in an anonymous function, so that any variables you define aren't polluting the global context. For example: @@ -64,24 +66,25 @@ For example: -## Scenario: Running a dedicated script file +## Scenario: Running a dedicated JavaScript file + +You can access a dedicated JavaScript file from your WebView2 control. -In this section, you access a dedicated JavaScript file from your WebView2 control. +Inline JavaScript code works well for quick JavaScript commands. However, inline JavaScript code doesn't support color themes and line formatting in the code editor. That makes it difficult to write large sections of code, such as in Visual Studio. -> [!NOTE] -> Although writing JavaScript inline may be efficient for quick JavaScript commands, you lose JavaScript color themes and line formatting that makes it difficult to write large sections of code in Visual Studio. +To solve the problem, create a separate JavaScript file that contains your code, and then pass a reference to that file by using the `ExecuteScriptAsync` parameters. -To solve the problem, create a separate JavaScript file with your code, and then pass a reference to that file using the `ExecuteScriptAsync` parameters. +To create and use a separate, dedicated JS file: 1. Create a `.js` file in your project, and add the JavaScript code that you want to run. For example, create a file called `script.js`. -1. Convert the JavaScript file to a string that is passed to `ExecuteScriptAsync`, by pasting the following code after the page is done navigating: +1. Convert the JavaScript file to a string that's passed to `ExecuteScriptAsync`, by pasting the following code after the page is done navigating: ```csharp string text = System.IO.File.ReadAllText(@"C:\PATH_TO_YOUR_FILE\script.js"); ``` -1. Pass your text variable using `ExecuteScriptAsync`: +1. Pass the `text` variable to `ExecuteScriptAsync`: ```csharp await webView.CoreWebView2.ExecuteScriptAsync(text); diff --git a/microsoft-edge/webview2/how-to/publish-uwp-app-store.md b/microsoft-edge/webview2/how-to/publish-uwp-app-store.md index da7febc16a..370b71467d 100644 --- a/microsoft-edge/webview2/how-to/publish-uwp-app-store.md +++ b/microsoft-edge/webview2/how-to/publish-uwp-app-store.md @@ -12,6 +12,28 @@ ms.date: 04/27/2022 A _UWP WebView2 app_ is a Universal Windows Platform (UWP) app that hosts the WebView2 control. To make a UWP WebView2 app widely available, you can publish it to the [Microsoft Store](https://apps.microsoft.com), by following the steps below. +**Detailed contents:** +* [Introduction](#introduction) +* [Step 1: Configure a Microsoft Store account in Visual Studio](#step-1-configure-a-microsoft-store-account-in-visual-studio) +* [Step 2: Test the non-packaged host app](#step-2-test-the-non-packaged-host-app) +* [Step 3: Package the host app](#step-3-package-the-host-app) +* [Step 4: Test the package](#step-4-test-the-package) +* [Step 5: Run Windows App Certification Kit (WACK)](#step-5-run-windows-app-certification-kit-wack) + * [Resolving tests](#resolving-tests) + * [Restricted name-space](#restricted-name-space) + * [Branding](#branding) + * [App Capabilities](#app-capabilities) + * [General metadata correctness](#general-metadata-correctness) + * [Supported API](#supported-api) +* [Step 6: Upload the app package](#step-6-upload-the-app-package) +* [See also](#see-also) + + + +## Introduction + +A _UWP WebView2 app_ is a Universal Windows Platform (UWP) app that hosts the WebView2 control. To make a UWP WebView2 app widely available, you can publish it to the [Microsoft Store](https://apps.microsoft.com), by following the steps below. + For general background information about publishing to the Windows Store, see [Get started: Publish your first app in the Microsoft Store](/windows/apps/publish/). The steps below provide the specific details about how to publish a UWP WebView2 app. @@ -87,7 +109,7 @@ Once you're satisfied that your packaged app works, run the Windows App Certific 1. After a few minutes, the Windows App Certification Kit (WACK) shows a results page. If the app failed, click the link to review the results. - + #### Resolving tests The results page of the Windows App Certification Kit (WACK) app shows any tests that need to be resolved. diff --git a/microsoft-edge/webview2/how-to/webresourcerequested.md b/microsoft-edge/webview2/how-to/webresourcerequested.md index 046d41b0a3..9914164947 100644 --- a/microsoft-edge/webview2/how-to/webresourcerequested.md +++ b/microsoft-edge/webview2/how-to/webresourcerequested.md @@ -15,16 +15,44 @@ ms.date: 08/03/2023 # Navigating with web resource request and response events --> - +The Microsoft Edge WebView2 control lets you interact with and modify network requests. You can either provide a response or modify the network request using the `WebResourceRequested` and `WebResourceResponseReceived` events. + +You can navigate via specific network requests by using the `NavigateWithWebResourceRequest` method. + +**Detailed contents:** +* [Introduction](#introduction) +* [When to use custom vs. basic approaches](#when-to-use-custom-vs-basic-approaches) + * [How your host app, the WebView2 control, and the HTTP server interact](#how-your-host-app-the-webview2-control-and-the-http-server-interact) +* [Intercepting a request, to monitor or modify it](#intercepting-a-request-to-monitor-or-modify-it) + * [What you can do with headers](#what-you-can-do-with-headers) + * [Filtering the WebResourceRequested event based on URL and resource type](#filtering-the-webresourcerequested-event-based-on-url-and-resource-type) + * [Why would you want to intercept requests that are sent from WebView2?](#why-would-you-want-to-intercept-requests-that-are-sent-from-webview2) + * [Sequence for modifying requests](#sequence-for-modifying-requests) + * [Example: Intercepting a request, to monitor or modify it](#example-intercepting-a-request-to-monitor-or-modify-it) +* [Overriding a response, to proactively replace it](#overriding-a-response-to-proactively-replace-it) + * [Sequence for overriding responses](#sequence-for-overriding-responses) + * [Example: Overriding a response, to proactively replace it](#example-overriding-a-response-to-proactively-replace-it) +* [Constructing a custom request and navigating using that request](#constructing-a-custom-request-and-navigating-using-that-request) + * [Example: Constructing a custom request and navigating using that request](#example-constructing-a-custom-request-and-navigating-using-that-request) +* [Monitoring the requests and responses via the WebResourceResponseReceived event](#monitoring-the-requests-and-responses-via-the-webresourceresponsereceived-event) + * [Example: Monitoring the requests and responses via the WebResourceResponseReceived event](#example-monitoring-the-requests-and-responses-via-the-webresourceresponsereceived-event) +* [API Reference overview](#api-reference-overview) +* [See also](#see-also) + + + +## Introduction + +The Microsoft Edge WebView2 control lets you interact with and modify network requests. You can either provide a response or modify the network request using the `WebResourceRequested` and `WebResourceResponseReceived` events. + +You can navigate via specific network requests by using the `NavigateWithWebResourceRequest` method. -The Microsoft Edge WebView2 control lets you interact with and modify network requests. You can either provide a response or modify the network request using the `WebResourceRequested` and `WebResourceResponseReceived` events. There is also special functionality that allows you to navigate with specific network requests using the `NavigateWithWebResourceRequest API`. +You can modify network requests, as described below. Use the `NavigateWithWebResourceRequest` method to: -This article describes how you can modify network requests. Use this API and approach to: * Upload local file content to your app to add support for offline functionality. + * Block content in a webpage, such as specific images. + * Fine-tune authentication for specific pages. **Terminology:** @@ -108,7 +136,6 @@ Another example is if the host app is only interested in all requests that are u --- - For details about how the URL filter works, see [CoreWebView2.AddWebResourceRequestedFilter Method > Remarks](/dotnet/api/microsoft.web.webview2.core.corewebview2.addwebresourcerequestedfilter#remarks) @@ -143,6 +170,9 @@ Intercepting requests sent from WebView2 enables you to further configure your r #### Example: Intercepting a request, to monitor or modify it + @@ -484,7 +514,6 @@ m_webView->add_WebResourceResponseReceived( ##### [.NET](#tab/dotnet) - **Request:** * [CoreWebView2.AddWebResourceRequestedFilter Method](/dotnet/api/microsoft.web.webview2.core.corewebview2.addwebresourcerequestedfilter) diff --git a/microsoft-edge/webview2/index-images/full-diagram.png b/microsoft-edge/webview2/index-images/full-diagram.png new file mode 100644 index 0000000000..1a27ffefd8 Binary files /dev/null and b/microsoft-edge/webview2/index-images/full-diagram.png differ diff --git a/microsoft-edge/webview2/index-images/web-native.png b/microsoft-edge/webview2/index-images/web-hybrid-native.png similarity index 100% rename from microsoft-edge/webview2/index-images/web-native.png rename to microsoft-edge/webview2/index-images/web-hybrid-native.png diff --git a/microsoft-edge/webview2/index.md b/microsoft-edge/webview2/index.md index 69f8652907..1be37830d6 100644 --- a/microsoft-edge/webview2/index.md +++ b/microsoft-edge/webview2/index.md @@ -13,6 +13,24 @@ ms.date: 06/10/2025 The Microsoft Edge WebView2 control allows you to embed web technologies (HTML, CSS, and JavaScript) in your native apps. The WebView2 control uses Microsoft Edge as the rendering engine to display the web content in native apps. +**Detailed contents:** +* [Introduction](#introduction) +* [Hybrid app approach](#hybrid-app-approach) +* [WebView2 benefits](#webview2-benefits) +* [Components of the WebView2 platform](#components-of-the-webview2-platform) +* [Supported Windows versions](#supported-windows-versions) + * [Windows Client](#windows-client) + * [Windows Server](#windows-server) +* [Supported programming environments and devices](#supported-programming-environments-and-devices) +* [Sequence of samples to install and run](#sequence-of-samples-to-install-and-run) +* [See also](#see-also) + + + +## Introduction + +The Microsoft Edge WebView2 control allows you to embed web technologies (HTML, CSS, and JavaScript) in your native apps. The WebView2 control uses Microsoft Edge as the rendering engine to display the web content in native apps. + With WebView2, you can embed web code in different parts of your native app, or build all of the native app within a single WebView2 instance. ![Diagram of an app with native UI areas in the left and top left, and WebView2 UI areas in the top right and bottom](./index-images/what-webview.png) @@ -29,11 +47,11 @@ Developers must often decide between building a web app or a native app. This d The following diagram shows the spectrum of apps, from maximum reach, to maximum power: -![The spectrum of apps, from maximum reach but less power, to an optimal hybrid blend, to maximum power but less reach](./index-images/web-native.png) +![The spectrum of apps, from maximum reach but less power, to an optimal hybrid blend, to maximum power but less reach](./index-images/web-hybrid-native.png) * Wide **reach** includes websites and Progressive Web Apps. -* In the middle are hybrid apps, such as WebViews and Electron. +* In the middle are hybrid apps, such as WebViews and [Electron](https://en.wikipedia.org/wiki/Electron_(software_framework)). * Maximum **power** is native apps. @@ -63,6 +81,24 @@ Hybrid apps, in the middle of this spectrum, allow you to enjoy the best of both +## Components of the WebView2 platform + +To add WebView2 to your app, you use the WebView2 SDK on your development machine, and distribute the WebView2 Runtime to user machines. The following diagram shows the high-level WebView2 components on your development machine and user machines. + +![Full diagram of WebView2](./index-images/full-diagram.png) + +Developing a WebView2 app involves software residing in the following places: + +| Location | Description | +|---|---| +| Dev machine | You use a Visual Studio project that includes the WebView2 SDK. The SDK includes the WebView2 Runtime, which is an embedded web browser component used for the WebView2 control instances in your host app. | +| Distributing the app and Runtime | There are several ways to deliver the always up-to-date Evergreen version of the WebView2 Runtime to user machines, with several levels of Internet connectivity supported. Some scenarios benefit from distributing a specific, fixed-version WebView2 Runtime. | +| User machine | Your host app on user machines includes instances of the WebView2 control, which uses the WebView2 Runtime. | +| Resources | The product documentation; the WebView2Samples repo including basic Getting Started WebView2 projects and more full-featured Sample projects; the WebView2Announcements repo; and the WebView2Feedback repo. | + +For details, see [Components of the WebView2 platform](./concepts/platform-components.md). + + ## Supported Windows versions The Windows operating systems that are supported by Webview2 are the same as those supported by Microsoft Edge. @@ -141,6 +177,7 @@ After your environment is set up and the samples build and run on your machine, ## See also +* [Components of the WebView2 platform](./concepts/platform-components.md) * [Overview of WebView2 APIs](concepts/overview-features-apis.md) * [Distribute your app and the WebView2 Runtime](concepts/distribution.md) diff --git a/microsoft-edge/webview2/release-notes/about.md b/microsoft-edge/webview2/release-notes/about.md index f6dcff248d..09ce2f6d1f 100644 --- a/microsoft-edge/webview2/release-notes/about.md +++ b/microsoft-edge/webview2/release-notes/about.md @@ -12,6 +12,8 @@ ms.date: 03/20/2024 The WebView2 team updates the WebView2 Release SDK and the WebView2 Prerelease SDK on a four-week cadence. These release notes contain the latest information on product announcements, additions, modifications, and breaking changes to the APIs. + + You can view the list of [Microsoft.Web.WebView2](https://www.nuget.org/packages/Microsoft.Web.WebView2) SDK packages at the NuGet site. Generally, release notes apply across the supported platforms, which are listed in [WebView2 API Reference](../webview2-api-reference.md). For an outline of APIs that are in Release SDK packages, see [Overview of WebView2 APIs](../concepts/overview-features-apis.md). @@ -80,9 +82,9 @@ WebView2 changes may require an update to the Runtime, SDK, or both. Most new A WebView2 shares code and binaries with the Microsoft Edge browser, and is released around the same time. As a result, WebView2 Runtime releases generally also include Microsoft Edge updates. -* For Microsoft Edge updates, see [Release notes for Microsoft Edge Stable Channel](/deployedge/microsoft-edge-relnote-stable-channel) and [Release notes for Microsoft Edge Beta Channel](/deployedge/microsoft-edge-relnote-beta-channel). +* For Microsoft Edge updates, see [Release notes for Microsoft Edge Stable Channel](/deployedge/microsoft-edge-relnote-stable-channel) and [Release notes for Microsoft Edge Beta Channel](/deployedge/microsoft-edge-relnote-beta-channel). -* To update the WebView2 Runtime on your development machine and on user machines, see [Distribute your app and the WebView2 Runtime](../concepts/distribution.md). To view or get the latest WebView2 Runtime versions, see [Download the WebView2 Runtime](https://developer.microsoft.com/microsoft-edge/webview2#download-the-webview2-runtime) in the _Microsoft Edge WebView2_ page at developer.microsoft.com. +* To update the WebView2 Runtime on your development machine and on user machines, see [Distribute your app and the WebView2 Runtime](../concepts/distribution.md). To view or get the latest WebView2 Runtime versions, use the [Download the WebView2 Runtime](https://developer.microsoft.com/microsoft-edge/webview2#download-the-webview2-runtime) section of the _Microsoft Edge WebView2_ page at developer.microsoft.com. * To install or update the WebView2 SDK, see [Install or update the WebView2 SDK](../how-to/machine-setup.md#install-or-update-the-webview2-sdk) in _Set up your Dev environment for WebView2_. diff --git a/microsoft-edge/webview2/samples/webview2browser.md b/microsoft-edge/webview2/samples/webview2browser.md index 25649a311f..9374acb9c0 100644 --- a/microsoft-edge/webview2/samples/webview2browser.md +++ b/microsoft-edge/webview2/samples/webview2browser.md @@ -9,7 +9,6 @@ ms.subservice: webview ms.date: 07/18/2022 --- # Win32 sample WebView2Browser - +## Introduction + +This sample, **WebView2Browser**, is a web browser built with the [Microsoft Edge WebView2](https://aka.ms/webview2) control. + This sample has its own dedicated repo. * Sample name: **WebView2Browser** @@ -314,7 +346,7 @@ We're setting up a few things here. The [ICoreWebView2Settings](/microsoft-edge/ #### Navigate to webpage -You can navigate to a webpage by entering its URI in the Address bar. When pressing Enter, the controls WebView will post a web message to the host app so it can navigate the active tab to the specified location. Code below shows how the host Win32 application will handle that message. +You can navigate to a webpage by entering its URI in the Address bar. When pressing **Enter**, the controls WebView will post a web message to the host app so it can navigate the active tab to the specified location. The following code shows how the host Win32 application will handle that message. ```cpp case MG_NAVIGATE: @@ -525,9 +557,9 @@ function reloadActiveTabContent() { #### Communicating the WebViews -We need to communicate the WebViews that power the tabs and UI, so that user interactions in one tab's WebView have the desired effect in the other WebView. WebView2Browser makes use of set of very useful WebView2 APIs for this purpose, including [PostWebMessageAsJson](/microsoft-edge/webview2/reference/win32/icorewebview2#postwebmessageasjson), [add_WebMessageReceived](/microsoft-edge/webview2/reference/win32/icorewebview2#add_webmessagereceived) and [ICoreWebView2WebMessageReceivedEventHandler](/microsoft-edge/webview2/reference/win32/icorewebview2webmessagereceivedeventhandler). +We need to communicate the WebViews that power the tabs and UI, so that user interactions in one tab's WebView have the desired effect in the other WebView. To do this, WebView2Browser uses WebView2 APIs, including [PostWebMessageAsJson](/microsoft-edge/webview2/reference/win32/icorewebview2#postwebmessageasjson), [add_WebMessageReceived](/microsoft-edge/webview2/reference/win32/icorewebview2#add_webmessagereceived) and [ICoreWebView2WebMessageReceivedEventHandler](/microsoft-edge/webview2/reference/win32/icorewebview2webmessagereceivedeventhandler). -On the JavaScript side, we're making use of the `window.chrome.webview` object exposed to call the `postMessage` method and add an event lister for received messages. +On the JavaScript side, we use the exposed `window.chrome.webview` object to call the `postMessage` method and add an event lister for received messages. ```cpp HRESULT BrowserWindow::CreateBrowserControlsWebView() @@ -592,7 +624,7 @@ function reloadActiveTabContent() { #### Tab handling -A new tab will be created whenever the user clicks on the **new tab** button to the right of the open tabs. The control's WebView will post a message to the host application to create the WebView for that tab and create an object tracking its state. +A new tab is created whenever the user clicks the **New tab** button to the right of the open tabs. The control's WebView will post a message to the host application to create the WebView for that tab and create an object tracking its state. ```javascript function createNewTab(shouldBeActive) {