diff --git a/microsoft-edge/toc.yml b/microsoft-edge/toc.yml index 26242e3e98..fbc86f2d04 100644 --- a/microsoft-edge/toc.yml +++ b/microsoft-edge/toc.yml @@ -1369,6 +1369,9 @@ - name: Overview of WebView2 APIs href: ./webview2/concepts/overview-features-apis.md + - name: Overview of the 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 diff --git a/microsoft-edge/webview2/concepts/browser-features.md b/microsoft-edge/webview2/concepts/browser-features.md index 4c1feaf886..9963a07a68 100644 --- a/microsoft-edge/webview2/concepts/browser-features.md +++ b/microsoft-edge/webview2/concepts/browser-features.md @@ -109,6 +109,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 @@ -214,3 +216,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 1f2c5ba9e2..a40da61c08 100644 --- a/microsoft-edge/webview2/concepts/data-privacy.md +++ b/microsoft-edge/webview2/concepts/data-privacy.md @@ -10,7 +10,9 @@ 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-section), 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 the [Download the WebView2 Runtime](https://developer.microsoft.com/microsoft-edge/webview2#download) section of the **Microsoft Edge WebView2** page, and then click any of the download buttons, such as **Get the Link**, **Download**, or **x64**. The license terms are shown in a dialog. Additionally, WebView2 follows the standards that are outlined in [Microsoft Edge Privacy Whitepaper](/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 100172b29c..dedbb9c99e 100644 --- a/microsoft-edge/webview2/concepts/distribution.md +++ b/microsoft-edge/webview2/concepts/distribution.md @@ -68,7 +68,7 @@ Cons: ## Understanding the options at the Runtime download page -The [Download the WebView2 Runtime](https://developer.microsoft.com/microsoft-edge/webview2#download-section) section of the **Microsoft Edge WebView2** page provides several options for distributing the WebView2 Runtime onto client machines. Understanding the options at this page provides a good introduction, to help decide which approach you want to use. +The [Download the WebView2 Runtime](https://developer.microsoft.com/microsoft-edge/webview2#download) section of the **Microsoft Edge WebView2** page provides several options for distributing the WebView2 Runtime onto client machines. Understanding the options at this page provides a good introduction, to help decide which approach you want to use. ![Options for distributing and updating the WebView2 Runtime](./distribution-images/runtime-distrib-options.png) @@ -158,7 +158,7 @@ See also: #### Deploying the Evergreen WebView2 Runtime -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-section) to help you deploy the Evergreen Runtime. +Only one installation of the Evergreen WebView2 Runtime is needed for all Evergreen apps on the device. Several tools are available at the [Download the WebView2 Runtime](https://developer.microsoft.com/microsoft-edge/webview2#download) section of the **Microsoft Edge WebView2** page, 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. @@ -247,7 +247,7 @@ Alternatively, instead of programmatically downloading the bootstrapper on-deman If you have an offline deployment scenario, where app deployment has to work entirely offline, use the following workflow. -1. Download the Evergreen Standalone Installer from [Download the WebView2 Runtime](https://developer.microsoft.com/microsoft-edge/webview2#download-section) to your development machine. The Evergreen Standalone Installer installs the Evergreen WebView2 Runtime on the client. +1. Download the Evergreen Standalone Installer from the [Download the WebView2 Runtime](https://developer.microsoft.com/microsoft-edge/webview2#download) section of the **Microsoft Edge WebView2** page to your development machine. The Evergreen Standalone Installer installs the Evergreen WebView2 Runtime on the client. 1. Include the Evergreen Standalone Installer in your app installer or updater. @@ -294,6 +294,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). @@ -318,7 +325,7 @@ The Fixed Version binaries are over 250 MB and will make your app package larger To use the Fixed Version distribution mode: -1. Download the Fixed Version of the WebView2 Runtime from [Download the WebView2 Runtime](https://developer.microsoft.com/microsoft-edge/webview2#download-section), as a package. +1. Download the Fixed Version of the WebView2 Runtime from the [Download the WebView2 Runtime](https://developer.microsoft.com/microsoft-edge/webview2#download) section of the **Microsoft Edge WebView2** page, as a package. The most-patched version of the latest and second-latest major releases are available for download at this site. Keep an archived copy of any versions you need. @@ -423,5 +430,5 @@ Example managed app folder structure: ## See also - +* [Download the WebView2 Runtime](https://developer.microsoft.com/microsoft-edge/webview2#download) - a section of the **Microsoft Edge WebView2** page, which links to the present article. * [Microsoft Edge release schedule](/deployedge/microsoft-edge-release-schedule) diff --git a/microsoft-edge/webview2/concepts/intro-diagrams-images/app-design.png b/microsoft-edge/webview2/concepts/intro-diagrams-images/app-design.png new file mode 100644 index 0000000000..a69d458b1a Binary files /dev/null and b/microsoft-edge/webview2/concepts/intro-diagrams-images/app-design.png differ diff --git a/microsoft-edge/webview2/concepts/intro-diagrams-images/control-runtime-sdk.png b/microsoft-edge/webview2/concepts/intro-diagrams-images/control-runtime-sdk.png new file mode 100644 index 0000000000..4106d7fcbe Binary files /dev/null and b/microsoft-edge/webview2/concepts/intro-diagrams-images/control-runtime-sdk.png differ diff --git a/microsoft-edge/webview2/concepts/intro-diagrams-images/control-sdk-runtime.png b/microsoft-edge/webview2/concepts/intro-diagrams-images/control-sdk-runtime.png new file mode 100644 index 0000000000..d6f91a7997 Binary files /dev/null and b/microsoft-edge/webview2/concepts/intro-diagrams-images/control-sdk-runtime.png differ diff --git a/microsoft-edge/webview2/concepts/intro-diagrams-images/dev-side-user-side.png b/microsoft-edge/webview2/concepts/intro-diagrams-images/dev-side-user-side.png new file mode 100644 index 0000000000..c80a4ebcf5 Binary files /dev/null and b/microsoft-edge/webview2/concepts/intro-diagrams-images/dev-side-user-side.png differ diff --git a/microsoft-edge/webview2/concepts/intro-diagrams-images/distribute-runtime.png b/microsoft-edge/webview2/concepts/intro-diagrams-images/distribute-runtime.png new file mode 100644 index 0000000000..4d9f63ec30 Binary files /dev/null and b/microsoft-edge/webview2/concepts/intro-diagrams-images/distribute-runtime.png differ diff --git a/microsoft-edge/webview2/concepts/intro-diagrams-images/full-diagram.png b/microsoft-edge/webview2/concepts/intro-diagrams-images/full-diagram.png new file mode 100644 index 0000000000..b6216fc092 Binary files /dev/null and b/microsoft-edge/webview2/concepts/intro-diagrams-images/full-diagram.png differ diff --git a/microsoft-edge/webview2/concepts/intro-diagrams-images/hostapp-wv2ctrl-httpserver.png b/microsoft-edge/webview2/concepts/intro-diagrams-images/hostapp-wv2ctrl-httpserver.png new file mode 100644 index 0000000000..8e6b4d1bf2 Binary files /dev/null and b/microsoft-edge/webview2/concepts/intro-diagrams-images/hostapp-wv2ctrl-httpserver.png differ diff --git a/microsoft-edge/webview2/concepts/intro-diagrams-images/resources.png b/microsoft-edge/webview2/concepts/intro-diagrams-images/resources.png new file mode 100644 index 0000000000..cc0f88d622 Binary files /dev/null and b/microsoft-edge/webview2/concepts/intro-diagrams-images/resources.png differ diff --git a/microsoft-edge/webview2/concepts/intro-diagrams-images/web-native.png b/microsoft-edge/webview2/concepts/intro-diagrams-images/web-native.png new file mode 100644 index 0000000000..ff39c4aa39 Binary files /dev/null and b/microsoft-edge/webview2/concepts/intro-diagrams-images/web-native.png differ diff --git a/microsoft-edge/webview2/concepts/intro-diagrams-images/what-webview.png b/microsoft-edge/webview2/concepts/intro-diagrams-images/what-webview.png new file mode 100644 index 0000000000..f41954bfcc Binary files /dev/null and b/microsoft-edge/webview2/concepts/intro-diagrams-images/what-webview.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/hostapp-wv2ctrl-httpserver.png b/microsoft-edge/webview2/concepts/platform-components-images/hostapp-wv2ctrl-httpserver.png new file mode 100644 index 0000000000..8e6b4d1bf2 Binary files /dev/null and b/microsoft-edge/webview2/concepts/platform-components-images/hostapp-wv2ctrl-httpserver.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..9766d1cd0f --- /dev/null +++ b/microsoft-edge/webview2/concepts/platform-components.md @@ -0,0 +1,322 @@ +--- +title: Overview of the 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: conceptual +ms.service: microsoft-edge +ms.subservice: webview +ms.date: 04/21/2023 +--- +# Overview of the 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 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 of the Dev machine: +* 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. + * WebView2 SDK + * Per-platform WebView2 APIs including CoreWebView2, CoreWebView2Controller, CoreWebView2Environment. Primarily called by native-side code. + * `AddHostObjectToScript` -- enables exposing platform APIs and WebView2 APIs to JavaScript code. + * [JavaScript APIs](/microsoft-edge/webview2/webview2-api-reference#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. +* Runtime -- browser component that contains WebView2 APIs. + +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. + +For more information, see [Approaches for distributing the WebView2 Runtime](#approaches-for-distributing-the-webview2-runtime) below. + + +Details of the User machine: +* Host app + * WebView2 native code + * WebView2 web code -- the WebView2 APIs are mostly called by native-side code|web-side code. + * WebView2 control instances -- your app's web-side code runs in a WebView2 control. + * Non-WebView2 native code + * Non-WebView2 web code + * Native control instances +* Runtime + +Resources include: +* Docs +* Samples repo +* Announcements repo +* Feedback repo + +See [Resources](#resources) below. + + + +## 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. | + + + +#### Diagram: 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 + + + +#### Diagram: 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: +* .NET/C# APIs +* WinRT/C# +* Win32/C++ +* WebView2Script package (JavaScript APIs) + +Prerelease SDK: +* .NET/C# APIs, including experimental APIs +* WinRT/C# APIs, including experimental APIs +* Win32/C++ APIs, including experimental APIs +* WebView2Script package (JavaScript APIs) + +Runtime (for release) or Browser (for Prerelease) +* WebView2Script package (JavaScript APIs) + + +Runtime (for Release SDK) - WebView2Script package (JavaScript APIs) +Browser (for Prerelease SDK) - 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. + + + +#### Diagram: 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. + + + +#### Diagram: 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](./distribution.md#understanding-the-options-at-the-runtime-download-page) in _Distribute your app and 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. + + + +#### Diagram: Host app, WebView2 control, and HTTP server + +![Host app, WebView2 control, and HTTP server](./platform-components-images/hostapp-wv2ctrl-httpserver.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](./distribution.md#understanding-the-options-at-the-runtime-download-page) in _Distribute your app and 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: +* [Understand the different WebView2 SDK versions](./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: +* [Understand the different WebView2 SDK versions](./versioning.md) - Either use a prerelease SDK with a preview channel of Microsoft Edge, or use a release SDK with the WebView2 Runtime. + + + +## How the WebView2 SDK is laid out in relation to how the WebView2 Runtime is laid out + +todo: what's the intention here? + + + +## Differences in the Runtime and the SDK across the frameworks + +todo + + + +## Resources + +* Docs - the present article is the main page for WebView2 docs. +* 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 - see [Contact the WebView2 Team](../contact.md). Direct links: + * [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) + + + +#### Diagram: Resources + +![Diagram: Resources](./platform-components-images/resources.png) + + + +## 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 0e5b8af26c..9de5a86629 100644 --- a/microsoft-edge/webview2/concepts/versioning.md +++ b/microsoft-edge/webview2/concepts/versioning.md @@ -163,7 +163,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-section) 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 is 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) section of the **Microsoft Edge WebView2** page. 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 17c719282d..0a42749cf3 100644 --- a/microsoft-edge/webview2/how-to/context-menus.md +++ b/microsoft-edge/webview2/how-to/context-menus.md @@ -728,7 +728,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 7dd7f843a3..c429a0ab24 100644 --- a/microsoft-edge/webview2/how-to/debug-visual-studio-code.md +++ b/microsoft-edge/webview2/how-to/debug-visual-studio-code.md @@ -99,7 +99,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 +257,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 +265,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 5f2c6d000d..badbe9d286 100644 --- a/microsoft-edge/webview2/how-to/javascript.md +++ b/microsoft-edge/webview2/how-to/javascript.md @@ -23,7 +23,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 +34,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: @@ -67,11 +67,14 @@ For example: ## Scenario: Running a dedicated script file In this section, you access a dedicated JavaScript file from your WebView2 control. + + > [!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 with your code, and then pass a reference to that file using the `ExecuteScriptAsync` parameters. +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. 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`. 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 8632d7aef9..fa640faed0 100644 --- a/microsoft-edge/webview2/how-to/publish-uwp-app-store.md +++ b/microsoft-edge/webview2/how-to/publish-uwp-app-store.md @@ -89,7 +89,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 efa84fcb40..682519ac88 100644 --- a/microsoft-edge/webview2/how-to/webresourcerequested.md +++ b/microsoft-edge/webview2/how-to/webresourcerequested.md @@ -108,7 +108,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 +142,7 @@ Intercepting requests sent from WebView2 enables you to further configure your r #### Example: Intercepting a request, to monitor or modify it + @@ -484,7 +484,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.md b/microsoft-edge/webview2/index.md index 45ae7193e8..baa9d539a1 100644 --- a/microsoft-edge/webview2/index.md +++ b/microsoft-edge/webview2/index.md @@ -33,7 +33,7 @@ The following diagram shows the spectrum of apps, from maximum reach, to maximum * 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 +63,25 @@ Hybrid apps, in the middle of this spectrum, allow you to enjoy the best of both +## Overview of the 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 [Overview of the 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 +160,7 @@ After your environment is set up and the samples build and run on your machine, ## See also +* [Overview of the 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 80cc7907ff..21528adf4a 100644 --- a/microsoft-edge/webview2/release-notes/about.md +++ b/microsoft-edge/webview2/release-notes/about.md @@ -74,7 +74,7 @@ WebView2 shares code and binaries with the Microsoft Edge browser, and is releas * 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-section) 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) section of the **Microsoft Edge WebView2** page. * 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 4bc4961b5c..2e448c4660 100644 --- a/microsoft-edge/webview2/samples/webview2browser.md +++ b/microsoft-edge/webview2/samples/webview2browser.md @@ -314,7 +314,7 @@ We're setting up a few things here. The [ICoreWebView2Settings](/microsoft-edge/ #### Navigate to web page -You can navigate to a web page 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. Code below shows how the host Win32 application will handle that message. ```cpp case MG_NAVIGATE: @@ -525,9 +525,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 +592,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) {