diff --git a/microsoft-edge/toc.yml b/microsoft-edge/toc.yml index 820723a55f..368cb44d9f 100644 --- a/microsoft-edge/toc.yml +++ b/microsoft-edge/toc.yml @@ -1374,6 +1374,22 @@ - name: Automate and test WebView2 apps with Microsoft Edge WebDriver href: webview2/how-to/webdriver.md + - name: Prerelease testing using preview channels + href: webview2/how-to/prerelease-testing.md + + - name: Self-host by deploying preview channels + href: webview2/how-to/self-hosting.md + displayName: self-hosting + + - name: Best Practices + items: + - name: Development best practices + href: webview2/concepts/developer-guide.md + displayName: Development best practices for WebView2 apps # top-of-page title + + - name: Develop secure WebView2 apps + href: webview2/concepts/security.md + # ----------------------------------------------------------------------------- - name: Debug WebView2 apps items: @@ -1439,14 +1455,8 @@ href: webview2/concepts/clear-browsing-data.md # ----------------------------------------------------------------------------- - - name: Advanced Topics and Best Practices + - name: Advanced Topics items: - - name: Development best practices - href: webview2/concepts/developer-guide.md - displayName: Development best practices for WebView2 apps # top-of-page title - - - name: Develop secure WebView2 apps - href: webview2/concepts/security.md # - name: Customize the UI # not needed? flatten # items: diff --git a/microsoft-edge/webview2/concepts/developer-guide.md b/microsoft-edge/webview2/concepts/developer-guide.md index ec99c4d001..c9f2e863cd 100644 --- a/microsoft-edge/webview2/concepts/developer-guide.md +++ b/microsoft-edge/webview2/concepts/developer-guide.md @@ -23,9 +23,11 @@ If you use the Evergreen runtime, before running your WebView2 app, test whether ## Run compatibility tests regularly when using the Evergreen Runtime -When using the Evergreen WebView2 Runtime, the runtime updates automatically, so you must regularly run compatibility tests. To ensure that your WebView2 app will continue to work as expected, test your web content in the WebView2 control against [Microsoft Edge Insider (preview) Channels](https://www.microsoft.com/edge/download/insider) (Beta, Dev, or Canary). +When using the Evergreen WebView2 Runtime, the runtime updates automatically, so you must regularly run compatibility tests. To ensure that your WebView2 app will continue to work as expected, test your web content in the WebView2 control against the Microsoft Edge preview channels (Beta, Dev, or Canary). The preview channels are also called _Insider channels_. -This guidance is similar to the guidance that we give to web developers. See [Test your app for forward-compatibility](../concepts/distribution.md#test-your-app-for-forward-compatibility). +The above guidance is similar to the guidance for web developers. 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). + +To download the preview channels of Microsoft Edge, go to [Become a Microsoft Edge Insider](https://www.microsoft.com/edge/download/insider). diff --git a/microsoft-edge/webview2/concepts/distribution.md b/microsoft-edge/webview2/concepts/distribution.md index f565d29598..5b61af3658 100644 --- a/microsoft-edge/webview2/concepts/distribution.md +++ b/microsoft-edge/webview2/concepts/distribution.md @@ -42,6 +42,7 @@ Cons: +#### Windows 11 devices and Windows 10 devices The Evergreen Runtime is preinstalled onto all Windows 11 devices as a part of the Windows 11 operating system. Microsoft installed the WebView2 Runtime to all eligible Windows 10 devices, 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/). Even if your app uses the Evergreen distribution mode, we recommend that you distribute the WebView2 Runtime, to cover edge cases where the Runtime wasn't already installed. See [Details about the Evergreen Runtime distribution mode](#details-about-the-evergreen-runtime-distribution-mode) below. @@ -73,7 +74,7 @@ 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 WebView2 Evergreen 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. @@ -91,10 +92,14 @@ When distributing your WebView2 app, make sure that the WebView2 Runtime is pres If you want to use the Fixed Version distribution mode, you can skip the next couple of sections and jump ahead to [Details about the Fixed Version runtime distribution mode](#details-about-the-fixed-version-runtime-distribution-mode). + + #### 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_. + + #### Runtime or browser support during development or production During development and testing, a WebView2 app can use either option as the backing web platform: @@ -105,6 +110,8 @@ During development and testing, a WebView2 app can use either option as the back A production release of a WebView2 app can only use the WebView2 Runtime as the backing web platform, not Microsoft Edge. + + ###### Microsoft Edge Stable channel isn't supported for WebView2 WebView2 apps aren't permitted to use the Stable channel of Microsoft Edge as the backing web platform. This restriction prevents a production release of a WebView2 app from taking a dependency on the browser. A WebView2 app cannot take a dependency on the browser during production, for the following reasons: @@ -135,6 +142,7 @@ When you use the Evergreen distribution mode of the WebView2 Runtime, your WebVi +#### Windows 11 devices and Windows 10 devices (details) 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: @@ -144,10 +152,11 @@ The vast majority of Windows 10 devices have the WebView2 Runtime installed alre * 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: -* [Understand the different WebView2 SDK versions](versioning.md). +* [Understand the different WebView2 SDK versions](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. * [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/). + #### 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. @@ -163,6 +172,7 @@ Only one installation of the Evergreen WebView2 Runtime is needed for all Evergr * 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). + #### Installing the Runtime as per-machine or per-user The latest bootstrapper and standalone installer support both _per-machine_ and _per-user_ installs of the WebView2 Runtime. @@ -172,6 +182,8 @@ If you run the installer from an elevated process or command prompt, the Runtime Use the following online deployment workflow or offline deployment workflow to ensure that the Runtime is already installed before your app launches. You can adjust your workflow depending on your scenario. Sample code is available in the [Samples repo](https://github.com/MicrosoftEdge/WebView2Samples#webview2-deployment). + + ###### Detect if a suitable WebView2 Runtime is already installed To verify that a WebView2 Runtime is installed, use one of the following approaches: @@ -198,6 +210,8 @@ To verify that a WebView2 Runtime is installed, use one of the following approac * Approach 2: Run [GetAvailableCoreWebView2BrowserVersionString](/microsoft-edge/webview2/reference/win32/webview2-idl#getavailablecorewebview2browserversionstring) and evaluate whether the `versionInfo` is `nullptr`. `nullptr` indicates that the WebView2 Runtime isn't installed. This API returns version information for the WebView2 Runtime or for any installed preview channels of Microsoft Edge (Beta, Dev, or Canary). + + ###### Online-only deployment If you have an online-only deployment scenario where users are assumed to have internet access, use the following workflow. @@ -228,11 +242,13 @@ The above workflow has several benefits: Alternatively, instead of programmatically downloading the bootstrapper on-demand by getting a link, as shown above, you can package the Evergreen Bootstrapper for the WebView2 Runtime with your app. + + ###### Offline deployment 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 WebView2 Evergreen Runtime on the client. +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. Include the Evergreen Standalone Installer in your app installer or updater. @@ -249,17 +265,15 @@ If you have an offline deployment scenario, where app deployment has to work ent ``` + #### Test your app for forward-compatibility The Web is constantly evolving. 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. 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 on 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). + #### Feature-detect when using recent APIs @@ -350,6 +364,7 @@ To use the Fixed Version distribution mode: ![Permission for PlayReady](./distribution-images/play-ready-permission.png) + #### Known issues for Fixed Version * Currently, Fixed Version cannot be run from a network location or UNC path. diff --git a/microsoft-edge/webview2/concepts/versioning.md b/microsoft-edge/webview2/concepts/versioning.md index 65e24555be..e9f4afaed2 100644 --- a/microsoft-edge/webview2/concepts/versioning.md +++ b/microsoft-edge/webview2/concepts/versioning.md @@ -67,11 +67,15 @@ Preview channels of Microsoft Edge provide the implementations of Experimental W For information about temporarily pointing your app to a preview channel instead of defaulting to the WebView2 Runtime, see [Test upcoming APIs and features](../how-to/set-preview-channel.md). +See also: +* [Prerelease testing using preview channels](../how-to/prerelease-testing.md) +* [Self-host by deploying preview channels](../how-to/self-hosting.md) + ## Use a release version of the SDK along with the Runtime -When you use a WebView2 Release SDK package, use the WebView2 Evergreen _Runtime_ on your development client, rather than a Microsoft Edge preview channel. By default, a WebView2 app targets the Runtime rather than Microsoft Edge. By design, the Microsoft Edge Stable channel doesn't support WebView2. +When you use a WebView2 Release SDK package, use the Evergreen WebView2 _Runtime_ on your development client, rather than a Microsoft Edge preview channel. By default, a WebView2 app targets the Runtime rather than Microsoft Edge. By design, the Microsoft Edge Stable channel doesn't support WebView2. The Release SDK package contains all of the Stable Win32 C/C++ and .NET APIs that are in production release, and doesn't include method signatures for Experimental APIs. All of the APIs that are in a Release SDK package are fully supported, in an equal or higher build number of the WebView2 Runtime. @@ -99,7 +103,7 @@ On a development machine, the client must have either the Microsoft Edge preview ## Forward compatibility of APIs -The WebView2 _release_ SDK has been forward-compatible ever since version 1 (Release SDK [1.0.622.22](../release-notes/archive.md#1062222) in _Archived Release Notes for the WebView2 SDK_). You can update your WebView2 app to use the latest APIs from the most recent Release version of the SDK. Your app will continue to work on clients because clients automatically have the latest WebView2 Evergreen Runtime. +The WebView2 _release_ SDK has been forward-compatible ever since version 1 (Release SDK [1.0.622.22](../release-notes/archive.md#1062222) in _Archived Release Notes for the WebView2 SDK_). You can update your WebView2 app to use the latest APIs from the most recent Release version of the SDK. Your app will continue to work on clients because clients automatically have the latest Evergreen WebView2 Runtime. The WebView2 APIs in a Release SDK package are stable and forward-compatible. A WebView2 API works when using a WebView2 Runtime that has an equal or higher build number as the SDK build number in which the API was introduced. The build number is the third part of the four-part version number for the Webview2 SDK, and of the four-part version number for Microsoft Edge and the WebView2 Runtime. @@ -127,7 +131,7 @@ To try out new forthcoming features that are in development, use _Experimental_ The Experimental APIs in a WebView2 Prerelease SDK package aren't guaranteed to be forward-compatible, and might be removed in future Runtime updates. -For full support of Experimental APIs, use a Microsoft Edge preview channel, not the WebView2 Evergreen Runtime. When a Prerelease version of the WebView2 SDK is initially made available, that SDK only works with Microsoft Edge Canary. Soon after that, the Prerelease SDK also works with the Beta and Dev channels. +For full support of Experimental APIs, use a Microsoft Edge preview channel, not the Evergreen WebView2 Runtime. When a Prerelease version of the WebView2 SDK is initially made available, that SDK only works with Microsoft Edge Canary. Soon after that, the Prerelease SDK also works with the Beta and Dev channels. Use a Prerelease SDK to try out new, Experimental APIs early and provide feedback before the Experimental APIs are promoted to become Stable, forward-compatible APIs. diff --git a/microsoft-edge/webview2/get-started/winui.md b/microsoft-edge/webview2/get-started/winui.md index 083d7337f4..b7c71daa59 100644 --- a/microsoft-edge/webview2/get-started/winui.md +++ b/microsoft-edge/webview2/get-started/winui.md @@ -47,17 +47,11 @@ For this sample, you don't need to separately install the WebView2 SDK. Below, ## Step 2 - Install a preview channel of Microsoft Edge -1. Install the [WebView2 Runtime](https://developer.microsoft.com/microsoft-edge/webview2) or any [Microsoft Edge preview channel](https://www.microsoft.com/edge/download/insider) (Beta, Dev, or Canary) installed on Windows 10 version 1803 (build 17134) or later. +1. Install the WebView2 Runtime on devices that have Windows 10 version 1803 (build 17134) or later, by installing from either location: + * To directly download just the Runtime, use the **Download the WebView2 Runtime** section of the [Microsoft Edge WebView2](https://developer.microsoft.com/microsoft-edge/webview2) page at `developer.microsoft.com`. + * To download and install a Microsoft Edge preview channel (Beta, Dev, or Canary), go to [Become a Microsoft Edge Insider](https://www.microsoft.com/edge/download/insider). The preview channels are also called _Insider channels_. The preview channels include the WebView2 Runtime. -Return from that page and continue the steps below. - - +Then continue with the steps below. diff --git a/microsoft-edge/webview2/get-started/wpf.md b/microsoft-edge/webview2/get-started/wpf.md index b11258d40e..f5dd55789e 100644 --- a/microsoft-edge/webview2/get-started/wpf.md +++ b/microsoft-edge/webview2/get-started/wpf.md @@ -56,10 +56,12 @@ This tutorial also works with Visual Studio 2017. See [Visual Studio older down ## Step 2 - Install a preview channel of Microsoft Edge -1. Download any [Microsoft Edge Insider (preview) Channel](https://www.microsoft.com/edge/download/insider) (Beta, Dev, or Canary) on a supported operating system (OS): +1. Download any Microsoft Edge preview channel (Beta, Dev, or Canary) on a supported operating system: * Windows 10 * Windows 11 + To do this, go to [Become a Microsoft Edge Insider](https://www.microsoft.com/edge/download/insider). The preview channels are also called _Insider channels_. + We recommend using the Canary channel of Microsoft Edge. The minimum required version is 82.0.488.0. diff --git a/microsoft-edge/webview2/how-to/machine-setup.md b/microsoft-edge/webview2/how-to/machine-setup.md index 6845e8c947..473289bd62 100644 --- a/microsoft-edge/webview2/how-to/machine-setup.md +++ b/microsoft-edge/webview2/how-to/machine-setup.md @@ -26,10 +26,12 @@ This article covers general-purpose setup of your development environment for We ## Install a preview channel of Microsoft Edge -1. Install any [Microsoft Edge Insider (preview) Channel](https://www.microsoft.com/edge/download/insider) (Beta, Dev, or Canary) on a supported operating system (OS): +Install any Microsoft Edge preview channel (Beta, Dev, or Canary) on a supported operating system: * Windows 10 * Windows 11 +To do this, go to [Become a Microsoft Edge Insider](https://www.microsoft.com/edge/download/insider). The preview channels are also called _Insider channels_. + We recommend using the Canary channel. The minimum required version is 82.0.488.0. The preview channels of Microsoft Edge are required in order to use a prerelease version of the WebView2 SDK. A prerelease SDK enables testing your app against the latest APIs, and trying out the latest APIs. diff --git a/microsoft-edge/webview2/how-to/prerelease-testing.md b/microsoft-edge/webview2/how-to/prerelease-testing.md new file mode 100644 index 0000000000..5990bdeddf --- /dev/null +++ b/microsoft-edge/webview2/how-to/prerelease-testing.md @@ -0,0 +1,66 @@ +--- +title: Prerelease testing using preview channels +description: How to test your WebView2 app by using the preview channels of Microsoft Edge (Edge Canary, Edge Dev, or Edge Beta) to find issues that will affect your particular WebView2 app, before WebView2 changes reach the Evergreen WebView2 Runtime. +author: MSEdgeTeam +ms.author: msedgedevrel +ms.topic: conceptual +ms.service: microsoft-edge +ms.subservice: webview +ms.date: 04/22/2024 +--- +# Prerelease testing using preview channels + +_Prerelease testing_ means testing your WebView2 app by using the preview channels of Microsoft Edge to find issues that will affect your particular WebView2 app, before any changes ship in the Stable Evergreen WebView2 Runtime. This helps catch any bugs before they degrade the app experience for end users. + +Conduct both automated and manual testing: +* For **automated testing**, do **prerelease testing**, which means testing with a preview version of the WebView2 Runtime. Covered by the present article. +* For **manual testing**, use **self-hosting**, which means deploying a preview version of the WebView2 Runtime with your app, to use daily by your team. See [Self-host by deploying preview channels](./self-hosting.md). + + + +## Importance of prerelease testing + +Evergreen WebView2 is based on the evergreen Chromium platform, which receives monthly major updates. Regressions in WebView2 apps tend to be application-specific, rather than affecting all WebView2 apps. WebView2 is tested in a variety of general scenarios, but it's possible that some of the specific scenarios of your app are not covered. + +To catch app-specific regressions before WebView2 changes ship in Edge Stable, test your WebView2 app against the preview WebView2 Runtime that's shipped with the preview channels of Microsoft Edge (Canary, Dev, and Beta). To manually install the preview channels, go to [Become a Microsoft Edge Insider](https://www.microsoft.com/edge/download/insider). The preview channels are also called _Insider channels_. + + + +## Start by doing automated testing against Edge Canary + +Start with automated testing against the Microsoft Edge **Canary** channel, which ships daily. This enables you to catch issues as early as possible. The Microsoft Edge **Dev** channel ships weekly, and is also a good option. + +Start with automated testing against the preview WebView2 Runtime in the Microsoft Edge **Canary** channel, which ships daily. This enables you to catch issues as early as possible. The Microsoft Edge **Dev** channel ships weekly, and is also a good option. + +To do automated testing: + +1. **Set the preview channel for your app.** + + You can set the preview channel by using `ChannelSearchKind`, so that your WebView2 app uses the least-stable channel (Canary, then Dev). To do this, see [Switching the channel search order (recommended)](./set-preview-channel.md#switching-the-channel-search-order-recommended) in _Test upcoming APIs and features_. + +1. **Install or deploy the preview channel.** + + * If you choose to install preview channels manually, install them from the page [Become a Microsoft Edge Insider](https://www.microsoft.com/edge/download/insider). + * If you instead choose to deploy preview channels to devices, see [How to deploy preview channels](./set-preview-channel.md#how-to-deploy-preview-channels) in _Test upcoming APIs and features_. + +1. **Conduct automated testing on your app running against the preview channels.** + + You can use WebDriver to conduct automated testing of your WebView2 app. See [Automate and test WebView2 apps with Microsoft Edge WebDriver](./webdriver.md). + +1. **Compare the results with the baseline.** + + The baseline for testing should be the latest stable release of WebView2, which can be either the Evergreen WebView2 runtime, or the latest fixed-version Runtime. You can download the Runtime from the [Microsoft Edge WebView2](https://developer.microsoft.com/microsoft-edge/webview2/) page. + +Upon finding issues, you can report them via the [Microsoft Edge / WebView2Feedback repo](https://github.com/MicrosoftEdge/WebView2Feedback). Under the `Runtime Channel` section, be sure to indicate that you found the issue on a preview channel, so that the fix can be prioritized before the bug ships in the Stable release. + + + +## See also + +* [Self-host by deploying preview channels](./self-hosting.md) +* [Test upcoming APIs and features](./set-preview-channel.md) +* [Automate and test WebView2 apps with Microsoft Edge WebDriver](/microsoft-edge/webdriver) +* [WebView2 feedback repo](https://github.com/MicrosoftEdge/WebView2Feedback) +* [Site compatibility-impacting changes coming to Microsoft Edge](/microsoft-edge/web-platform/site-impacting-changes) +* [Overview of the Microsoft Edge channels](/deployedge/microsoft-edge-channels) +* [Become a Microsoft Edge Insider](https://www.microsoft.com/edge/download/insider) - download Edge Canary, Edge Dev, or Edge Beta. diff --git a/microsoft-edge/webview2/how-to/self-hosting.md b/microsoft-edge/webview2/how-to/self-hosting.md new file mode 100644 index 0000000000..110d606588 --- /dev/null +++ b/microsoft-edge/webview2/how-to/self-hosting.md @@ -0,0 +1,90 @@ +--- +title: Self-host by deploying preview channels +description: How to set up self-hosting by deploying using the WebView2 preview channels, which are the Insider preview channels of Microsoft Edge (Canary, Dev, and Beta). +author: MSEdgeTeam +ms.author: msedgedevrel +ms.topic: conceptual +ms.service: microsoft-edge +ms.subservice: webview +ms.date: 04/22/2024 +--- +# Self-host by deploying preview channels + +_Self-hosting_ means deploying a preview WebView2 Runtime with your app. This allows you and your development team to use your app daily with the preview version of the WebView2 Runtime, to find issues that will affect your particular WebView2 app, before the forthcoming changes reach the Evergreen WebView2 Runtime (Stable). + +The self-hosting approach provides real-world usage of your app with the latest preview WebView2 Runtime to catch any issues that may arise. You should self-host your app in tandem with doing prerelease testing on your app, to provide a structured approach to testing your app with the latest version of the WebView2 Runtime. + +Conduct both automated and manual testing: +* For **automated testing**, do **prerelease testing**, which means testing with a preview version of the WebView2 Runtime. See [Prerelease testing using preview channels](./prerelease-testing.md). +* For **manual testing**, use **self-hosting**, which means deploying a preview version of the WebView2 Runtime with your app, to use daily by your team. Covered by the present article. + + + +## How to self-host a preview channel of WebView2 + +We recommend that you self-host using the preview WebView2 Runtime in the Dev channel of the Edge browser. The Dev channel is updated weekly, so it allows you to catch issues early while having sufficient stability for daily use. + +The Canary channel is also suitable, but it might be less stable for daily use. The Beta channel allows you to test against the version of the runtime that is about to ship to stable, but you might not be able to catch issues early enough for your application. + + +To self-host a preview channel of WebView2: + +1. **Set the preview channel for your app.** + + You can [set the preview channel by using ChannelSearchKind](./set-preview-channel.md#switching-the-channel-search-order-recommended), making it such that your WebView2 app uses the least-stable channel on the device. We recommend using either the Registry Key or Group Policy for self-hosting. + +1. **Install the preview channel on your team's machines.** + + To install preview channels on a small number of devices, you can download and install them manually from the page [Become a Microsoft Edge Insider](https://www.microsoft.com/edge/download/insider). To deploy preview channels to a large number of devices, see [How to deploy preview channels](./set-preview-channel.md#how-to-deploy-preview-channels) in _Test upcoming APIs and features_. + +1. **Use your app daily with the preview channel of WebView2, and diagnose potential issues with the WebView2 Runtime.** + + See [Diagnose potential issues with the WebView2 Runtime](#diagnose-potential-issues-with-the-webview2-runtime), below. + +Upon finding issues, you can report them via the [Microsoft Edge / WebView2Feedback repo](https://github.com/MicrosoftEdge/WebView2Feedback). Under the `Runtime Channel` section, be sure to indicate that you found the issue on a preview channel, so that the fix can be prioritized before the bug ships in the Stable release. + + + +## Diagnose potential issues with the WebView2 Runtime + +To diagnose or troubleshoot potential preview WebView2 Runtime issues that are revealed by your app, do the following: + + + +#### Confirm that your app is running a preview channel of WebView2 + +1. In Windows, open Task Manager. + +1. Find your application's process, and then find the **WebView2 Manager** child process. + +1. Right-click the **Edge WebView2** process, and then select **Open file location**. The folder name is the version number of the Runtime. + + + +#### Switch to the Stable WebView2 Runtime channel to see if the issue is reproduced + +If the issue isn't reproduced on the Stable channel of the WebView2 Runtime, it's likely that the issue is with the preview channel of WebView2, or how your app interacts with the preview channel of WebView2. + +You can easily switch to the stable channel (Evergreen WebView2 Runtime) by [using environmental variables](./set-preview-channel.md?tabs=environment-variable#switching-the-channel-search-order-recommended), because revised environment variables override the registry settings (which are what's set by group policies). This allows you to easily switch from a preview channel to the stable channel, to see if the issue is reproduced. If you are already using environmental variables, you simply update the values. + +If you set the environment variable globally, it changes the WebView2 channel for all apps that use WebView2 on the machine. + +If you are using the API, then we recommend building UI in your app that allows your users to change between using the Stable Runtime or a preview Runtime. + + + +#### Collect diagnostics data + +1. See [Gathering Diagnostics and Logs](https://github.com/MicrosoftEdge/WebView2Feedback/tree/main/diagnostics). Crash dumps and Event Tracing for Windows (ETW) traces are the common formats that are required. + +1. You can then report the issue to the [Microsoft Edge / WebView2Feedback repo](https://github.com/MicrosoftEdge/WebView2Feedback), and include the log file. + + + +## See also + +* [Test upcoming APIs and features](./set-preview-channel.md) +* [Prerelease testing using preview channels](./prerelease-testing.md) +* [WebView2 feedback repo](https://github.com/MicrosoftEdge/WebView2Feedback) +* [Site compatibility-impacting changes coming to Microsoft Edge](../../web-platform/site-impacting-changes.md) +* [Become a Microsoft Edge Insider](https://www.microsoft.com/edge/download/insider) - download the Canary, Dev, or Beta channel of Microsoft Edge. diff --git a/microsoft-edge/webview2/how-to/set-preview-channel-images/system-properties-env-vars.png b/microsoft-edge/webview2/how-to/set-preview-channel-images/system-properties-env-vars.png index f5f932f3c3..19920ab668 100644 Binary files a/microsoft-edge/webview2/how-to/set-preview-channel-images/system-properties-env-vars.png and b/microsoft-edge/webview2/how-to/set-preview-channel-images/system-properties-env-vars.png differ diff --git a/microsoft-edge/webview2/how-to/set-preview-channel.md b/microsoft-edge/webview2/how-to/set-preview-channel.md index 5ad5dfdb23..15cef78975 100644 --- a/microsoft-edge/webview2/how-to/set-preview-channel.md +++ b/microsoft-edge/webview2/how-to/set-preview-channel.md @@ -6,28 +6,49 @@ ms.author: msedgedevrel ms.topic: conceptual ms.service: microsoft-edge ms.subservice: webview -ms.date: 02/24/2023 +ms.date: 04/22/2024 --- # Test upcoming APIs and features - + - +This article explains how to switch to a preview channel of Microsoft Edge, to test experimental APIs that are in a WebView2 Prerelease SDK package. -To test upcoming APIs and features, you switch to a preview channel, as follows. +To test new or forthcoming APIs and features, switch to a Microsoft Edge preview channel rather than using the stable WebView2 Runtime. The Evergreen WebView2 Runtime is updated frequently to add new APIs and functionalities. These updates can include APIs have been promoted from `Experimental` in a Prerelease WebView2 SDK to `Stable` in the WebView2 Release SDK. Some of the updates in the Evergreen WebView2 Runtime could potentially break your WebView2 app. -Updates of the WebView2 Evergreen Runtime often include new APIs and features. Some of these updates could potentially break your WebView2 app. To test the experimental APIs ahead of time and ensure your app's forward-compatibility, you should perform compatibility testing using a preview channel of Microsoft Edge, along with a prerelease version of the WebView2 SDK. +We recommend that you test the Experimental APIs ahead of time, before they are promoted to Stable in the WebView2 Release SDK, by switching to a preview channel of Microsoft Edge (which includes WebView2), to ensure that your app is forward-compatible. -When you test a prerelease SDK package, you need to direct your application to use a preview channel of Microsoft Edge (Beta, Dev, or Canary), instead of defaulting to using the WebView2 Runtime. Several approaches for doing this are explained below. +See also: +* [Phases of introducing APIs](../concepts/versioning.md#phases-of-introducing-apis) in _Understand the different WebView2 SDK versions_. +* [Understand the different WebView2 SDK versions](../concepts/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. -The WebView2 Runtime doesn't have the latest experimental WebView2 APIs. For your WebView2 code to run when using experimental APIs in a prerelease SDK, your client (on a development machine) needs to have a Microsoft Edge preview channel. The Canary preview channel is recommended, because it's ahead of the other channels and has the latest experimental APIs. -The prerelease SDK works together with a preview channel as follows: + +#### Use a preview channel of WebView2 to test your app against the most recent experimental WebView2 APIs -* A prerelease version of the WebView2 SDK contains the method signatures for experimental APIs, which allow you to write code using the experimental WebView2 APIs in your app. +The Evergreen WebView2 Runtime doesn't include experimental WebView2 APIs. Instead, to use these experimental features in your WebView2 code, have your app use the version of WebView2 that is in a Microsoft Edge preview channel (Edge Beta, Edge Dev, or Edge Canary). -* The preview channels of Microsoft Edge contain the Microsoft Edge binaries that are needed to run and render your app, including the implementation of the experimental APIs. +The Canary channel is recommended, because it offers the latest experimental APIs. -For more information about how SDK versions works in conjunction with the WebView2 Runtime or preview channels of Microsoft Edge, see [Understand the different WebView2 SDK versions](../concepts/versioning.md). + + +#### Interplay between the WebView2 Prerelease SDK and Microsoft Edge Preview Channels + +* **Prerelease SDK:** This version of the WebView2 SDK provides method signatures for experimental APIs, which allow you to write code using the experimental WebView2 APIs in your app. + +* **Microsoft Edge Preview Channels:** These channels (Edge Beta, Edge Dev, or Edge Canary) contain the necessary Microsoft Edge binaries. These channels allow your app to run and render using the experimental APIs. + +For more information about how SDK versions interact with the WebView2 Runtime and the Microsoft Edge preview channels, see [Understand the different WebView2 SDK versions](../concepts/versioning.md). + + + +#### Forward-compatibility testing by using the preview channel + +We recommend that you test upcoming changes using preview channels to ensure your app's forward compatibility, by following these best practices: + +* [Prerelease testing using preview channels](./prerelease-testing.md) +* [Self-host by deploying preview channels](./self-hosting.md) @@ -35,230 +56,373 @@ For more information about how SDK versions works in conjunction with the WebVie To use experimental APIs, download a prerelease version of the WebView2 SDK from [Microsoft.Web.WebView2 package](https://www.nuget.org/packages/Microsoft.Web.WebView2). -To download a Microsoft Edge preview channel, see [Microsoft Edge Insider Channels](https://www.microsoft.com/edge/download/insider). +Preview channels of Microsoft Edge include the preview WebView2 Runtime. Preview channels are also called _Insider channels_. After being installed, the preview channels stay up-to-date; the latest version of each preview channel is automatically installed. For example, this means the Canary channel will update itself almost daily. To download a Microsoft Edge preview channel (Canary, Dev, or Beta), go to [Become a Microsoft Edge Insider](https://www.microsoft.com/edge/download/insider). + +To deploy the preview channel to multiple machines, see [How to deploy preview channels](#how-to-deploy-preview-channels), below. - + ## Approaches to making your app use a specific browser channel -When a WebView2 is initialized, it will attempt to find a valid runtime on the machine to use. This can be the WebView2 Runtime, a preview channel of Microsoft Edge, or a specified location containing fixed version binaries. You can learn more about supported runtimes at [Distribute your app and the WebView2 Runtime](../concepts/distribution.md). +When a WebView2 is initialized, it will attempt to find a valid runtime on the machine to use. This can be the WebView2 Runtime, a preview channel of Microsoft Edge, or a specified location that contains Fixed Version binaries. For more information about supported runtimes, see [Distribute your app and the WebView2 Runtime](../concepts/distribution.md). -There are several ways to make your WebView2 app use a specified preview channel of Microsoft Edge: -* By calling a function. -* By using a registry override. -* By using an environment variable. -* By using a group policy. +There are two ways to make your WebView2 app use a specific preview channel of Microsoft Edge: + +* [Switching the channel search order (recommended)](#switching-the-channel-search-order-recommended). + +* [Setting the browser executable folder (for local testing)](#setting-the-browser-executable-folder-for-local-testing). These approaches are described below. -### Browser executable folder -One approach is to use a browser executable folder. In this approach, you specify a folder that contains runtime binaries. This folder can be any of the following locations: -* The installed location of the WebView2 Runtime. -* A preview channel of Microsoft Edge. -* A folder containing fixed version binaries that you have deployed to the machine yourself. + +## Switching the channel search order (recommended) -If you set the browser executable folder to a specific preview channel of Microsoft Edge, you will need to update the location when that preview channel updates to a newer version. This is because the location includes the version number as part of its path. Therefore, we recommend using this approach for local testing only. +This section applies to using an API, registry override, environment variable, or group policy. -### Default channel-search order +If a specific browser executable folder isn't specified, then the WebView2 will attempt to load a runtime from one of the known default locations. By default, the WebView2 loader searches for runtimes from most-stable to least-stable (Canary), using the first runtime that's found. -This section applies to using a group policy, registry override, or environment variable. +``` +WebView2 Runtime (Stable) -> Edge Beta -> Edge Dev -> Edge Canary +``` -If a specific browser executable folder isn't specified, then the WebView2 will attempt to load a runtime from one of the known default locations. +You can reverse the default search order by setting the `ChannelSearchKind` API to `LeastStable`, or by setting the `ChannelSearchKind` policy, registry key, or environment variable to `1`. Reversing the search order makes the WebView2 loader search from least-stable (Canary) to most-stable: -The default channel-search order is: -1. The WebView2 Runtime. -1. The Beta channel of Microsoft Edge. -1. The Dev channel of Microsoft Edge. -1. The Canary channel of Microsoft Edge. +``` +Edge Canary -> Edge Dev -> Edge Beta -> WebView2 Runtime (Stable) +``` -If you set the release channel preference to `1` by using a group policy, registry override, or environment variable, that will use the reverse of the default search order. +This must be done before the WebView2 control is initialized. +If you need a more specific order, see [How to use `ChannelSearchKind` to ensure that a particular channel is used](#how-to-use-channelsearchkind-to-ensure-that-a-particular-channel-is-used). - -## Calling a function -If you want to make your application use a specific runtime by calling a function, complete the following steps. +##### [API](#tab/api) -### Win32\/C++ +By default, the `CoreWebView2EnvironmentOptions.ChannelSearchKind` property is `CoreWebView2ChannelSearchKind.MostStable` (an enum value). Instead, reverse the search order by setting the `CoreWebView2EnvironmentOptions.ChannelSearchKind` property to `CoreWebView2ChannelSearchKind.LeastStable`. -We'll use the [WebView2APISample](https://github.com/MicrosoftEdge/WebView2Samples/tree/main/SampleApps/WebView2APISample) to demonstrate this procedure. +.NET: +* [CoreWebView2EnvironmentOptions.ChannelSearchKind Property](/dotnet/api/microsoft.web.webview2.core.corewebview2environmentoptions.channelsearchkind) +* [CoreWebView2ChannelSearchKind Enum](/dotnet/api/microsoft.web.webview2.core.corewebview2channelsearchkind) -1. On your development machine, find the path containing the Microsoft Edge preview channel. For example: +WinRT: +* [CoreWebView2EnvironmentOptions.ChannelSearchKind Property](/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2environmentoptions#channelsearchkind) +* [CoreWebView2ChannelSearchKind Enum](/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2channelsearchkind) - `C:\\Users\\myname\\AppData\\Local\\Microsoft\\Edge SxS\\Application\\93.0.929.0` +Win32: +* [ICoreWebView2EnvironmentOptions7::get_ChannelSearchKind](/microsoft-edge/webview2/reference/win32/icorewebview2environmentoptions7#get_channelsearchkind) +* [ICoreWebView2EnvironmentOptions7::put_ChannelSearchKind](/microsoft-edge/webview2/reference/win32/icorewebview2environmentoptions7#put_channelsearchkind) +* [COREWEBVIEW2_CHANNEL_SEARCH_KIND enum](/microsoft-edge/webview2/reference/win32/webview2-idl#corewebview2_channel_search_kind) -1. Clone the [WebView2Samples](https://github.com/MicrosoftEdge/WebView2Samples) repo. -1. Open the **WebView2APISample** project, and then in **Source Files**, open the `AppWindow.cpp` file. +##### [Registry key](#tab/registry-key) -1. Find where [CreateCoreWebView2EnvironmentWithOptions](/microsoft-edge/webview2/reference/win32/webview2-idl#createcorewebview2environmentwithoptions) is called. For example: +1. Open a PowerShell terminal or PowerShell-enabled command prompt. - ```cpp - HRESULT hr = CreateCoreWebView2EnvironmentWithOptions( - subFolder, m_userDataFolder.c_str(), options.Get(), - Callback( - this, &AppWindow::OnCreateEnvironmentCompleted) - .Get()); +1. Modify and then run the following command: + + ```reg + REG ADD \Software\Policies\Microsoft\Edge\WebView2\ChannelSearchKind /v WebView2APISample.exe /t REG_DWORD /d 1 ``` -1. Replace the `subFolder` variable by the folder path for the Microsoft Edge preview channel you want to use. For example: +Replace `WebView2APISample.exe` with your own app executable name or the application user model ID. Caution: If you instead use a wildcard (`*`), the override is applied to _all_ WebView2 apps on the machine, which can result in unexpected behavior. - ```cpp - HRESULT hr = CreateCoreWebView2EnvironmentWithOptions( - L"C:\\Users\\myname\\AppData\\Local\\Microsoft\\Edge SxS\\Application\\93.0.929.0", m_userDataFolder.c_str(), options.Get(), - Callback( - this, &AppWindow::OnCreateEnvironmentCompleted) - .Get()); - ``` +Use the value `1` for the reversed-search order, or `0` for the default search order. + + +##### [Environment variable](#tab/environment-variable) + +* Name: `WEBVIEW2_CHANNEL_SEARCH_KIND` +* Value: `1` + +The target app can't be specified when using the environment variable. Therefore, when set as a global environment, it will affect all apps that use WebView2 on the machine. + +Use the value `1` for the reversed-search order, or `0` for the default search order. + +See also: +* [How to set an environment variable](#how-to-set-an-environment-variable), below. -### WinForms - -WinForms uses an approach similar to the Win32/C++ approach described above. - -1. Set `CreationProperties.BrowserExecutableFolder` to point to the path that contains the Microsoft Edge Canary or Dev channel. To do this, in the **WebView2Samples** solution, in the **WebView2WpfBrowser** project, open the file `MainWindow.xaml.cs`. - -1. Find `CreationProperties.BrowserExecutableFolder`. For example: - - ```csharp - WebView2 GetReplacementControl(bool useNewEnvironment) - { - WebView2 replacementControl = new WebView2(); - ((System.ComponentModel.ISupportInitialize)(replacementControl)).BeginInit(); - // Setup properties and bindings. - if (useNewEnvironment) - { - // Create a new CoreWebView2CreationProperties instance so the environment - // is made anew. - replacementControl.CreationProperties = new CoreWebView2CreationProperties(); - replacementControl.CreationProperties.BrowserExecutableFolder = webView.CreationProperties.BrowserExecutableFolder; - replacementControl.CreationProperties.Language = webView.CreationProperties.Language; - replacementControl.CreationProperties.UserDataFolder = webView.CreationProperties.UserDataFolder; - shouldAttachEnvironmentEventHandlers = true; - } - ``` -### WPF +##### [Group policy](#tab/group-policy) -WPF uses an approach similar to the Win32/C++ approach described above. +Set the `ChannelSearchKind` policy. -Refer to [CoreWebView2CreationProperties.BrowserExecutableFolder Property](/dotnet/api/microsoft.web.webview2.wpf.corewebview2creationproperties.browserexecutablefolder#Microsoft_Web_WebView2_Wpf_CoreWebView2CreationProperties_BrowserExecutableFolder). +* Name: `` +* Value: `1` +Use the value `1` for the reversed-search order, or `0` for the default search order. - -## Using a registry override +Do either of the following: -When specifying a preview channel by using a registry override, there are two options: -* Change the browser executable folder. -* Change the release channel preference. +* Download the Microsoft Edge policy files, which include the WebView2 policy files, from [Download and configure Microsoft Edge for Business](https://www.microsoft.com/edge/business/download). For more information, see [Configure Microsoft Edge policy settings on Windows devices](/deployedge/configure-microsoft-edge). -These two approaches are described below. +* Use the built-in policy on Intune. See the following articles. The steps for WebView2 are the same as for Microsoft Edge, except use the category "Microsoft Edge WebView2" instead of "Microsoft Edge". + * [Configure Microsoft Edge policy settings in Microsoft Intune](/mem/intune/configuration/administrative-templates-configure-edge) in the Microsoft Intune documentation. + * [Configure Microsoft Edge policy settings with Microsoft Intune](/deployedge/configure-edge-with-intune) in the Microsoft Edge Enterprise documentation. -### Registry override: browser executable folder +--- + + + +## How to use `ChannelSearchKind` to ensure that a particular channel is used + +When using `ChannelSearchKind`, here's how you can make sure that a certain preview browser channel is used when you have multiple preview browser channels installed. + +In addition to reversing the channel search order, you can modify the set of release channels to include in the search, to provide further control over channel selection. The loader will search for channels on the device in the order specified by the channel search kind, but it will only consider channels that are in the specified set of release channels. + +This option is useful if you would like to target a particular channel, instead of simply choosing the most or least stable channel. By default, the release channels includes all channels: Stable (0), Beta (1), Dev (2), and Canary (3). + +Example: + +``` +Channel Search Kind: 1 (Least Stable) +Release Channels: 0 (Stable), 1 (Beta) +``` + +This example setting causes the loader to try to run the app with Edge Beta if Edge Beta is installed on the device, and otherwise fall back to using the Stable WebView2 Runtime. + +The release channels can similarly be set through the API, registry key, environment variable, or group policy. + + +##### [API](#tab/api) -To make your application use a Microsoft Edge preview channel by using a registry override that sets the browser executable folder: +By default, the loader considers all of the release channels. Set `ReleaseChannels` to a mask of the channels you would like the loader to search for. + +.NET: +* [CoreWebView2EnvironmentOptions.ReleaseChannels Property](/dotnet/api/microsoft.web.webview2.core.corewebview2environmentoptions.releasechannels) +* [CoreWebView2ReleaseChannels Enum](/dotnet/api/microsoft.web.webview2.core.corewebview2releasechannels) + +WinRT: +* [CoreWebView2EnvironmentOptions.ReleaseChannels Property](/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2environmentoptions#releasechannels) +* [CoreWebView2ChannelSearchKind Enum](/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2releasechannels) + +Win32: +* [ICoreWebView2EnvironmentOptions7::get_ReleaseChannels](/microsoft-edge/webview2/reference/win32/icorewebview2environmentoptions7#get_releasechannels) +* [ICoreWebView2EnvironmentOptions7::put_ReleaseChannels](/microsoft-edge/webview2/reference/win32/icorewebview2environmentoptions7#put_releasechannels) +* [COREWEBVIEW2_RELEASE_CHANNELS enum](/microsoft-edge/webview2/reference/win32/webview2-idl#corewebview2_release_channels) + + +##### [Registry key](#tab/registry-key) 1. Open a PowerShell terminal or PowerShell-enabled command prompt. 1. Modify and then run the following command: - `REG ADD HKLM\Software\Policies\Microsoft\Edge\WebView2\BrowserExecutableFolder /v WebView2APISample.exe /t REG_SZ /d "C:\Users\myname\AppData\Local\Microsoft\Edge SxS\Application\88.0.680.0"` + ```reg + REG ADD \Software\Policies\Microsoft\Edge\WebView2\ReleaseChannels /v WebView2APISample.exe /t REG_SZ /d "0,1" + ``` + +Replace `WebView2APISample.exe` with your own app executable name or the application user model ID. Using a wildcard (*) as the value name will apply the override to _all_ WebView2 apps on the machine, and can result in unexpected behavior. - Replace `WebView2APISample.exe` with the file name of your own app executable or the Application User Model ID. Using a wildcard (*) as the value name will apply the override to _all_ WebView2 apps on the machine and can result in unexpected behavior. - Replace `C:\Users\myname\AppData\Local\Microsoft\Edge SxS\Application\88.0.680.0` by the path to the desired Microsoft Edge preview channel. +##### [Environment variable](#tab/environment-variable) -#### Resuming using the default, WebView2 Evergreen Runtime +* Name: `WEBVIEW2_RELEASE_CHANNELS` +* Value: `` -To undo the above setting, run the following command: +The target app can't be set when using the environment variable approach. Therefore, when set as a global environment, this setting will affect all apps that use WebView2 on the machine. -`REG DELETE HKLM\Software\Policies\Microsoft\Edge\WebView2\BrowserExecutableFolder /f` +See also: +* [How to set an environment variable](#how-to-set-an-environment-variable), below. -### Registry override: release channel preference -To make your application use a Microsoft Edge preview channel by using a registry override that changes the release channel preference by changing the order of searching for a channel: +##### [Group policy](#tab/group-policy) + +Set the `ReleaseChannel` policy. + +* Name: `` +* Value: `` + +Do either of the following: + +* Download the Microsoft Edge policy files, which include the WebView2 policy files, from [Download and configure Microsoft Edge for Business](https://www.microsoft.com/edge/business/download). For more information, see [Configure Microsoft Edge policy settings on Windows devices](/deployedge/configure-microsoft-edge). + +* Use the built-in policy on Intune. For more information, see [Configure Microsoft Edge policy settings in Microsoft Intune](/mem/intune/configuration/administrative-templates-configure-edge). + +--- + + + +## Setting the browser executable folder (for local testing) + +An alternative approach is to use a browser executable folder. In this approach, you specify a folder that contains runtime binaries. This folder can be any of the following locations: +* The installed location of the WebView2 Runtime. +* A preview channel of Microsoft Edge. +* A folder containing Fixed Version binaries that you have deployed to the machine yourself. + +If you set the browser executable folder to a specific preview channel of Microsoft Edge, you will need to update the location when that preview channel updates to a newer version. This is because the location includes the version number as part of its path. Therefore, we recommend using this approach for local testing only. + + +##### [API](#tab/api) + +Pass the path to the browser executable folder during environment creation, by using the following APIs. + +.NET (WPF): +* [CreationProperties Property](/dotnet/api/microsoft.web.webview2.wpf.webview2.creationproperties) +* [CoreWebView2CreationProperties Class](/dotnet/api/microsoft.web.webview2.wpf.corewebview2creationproperties) + +.NET (WinForms): +* [CreationProperties Property](/dotnet/api/microsoft.web.webview2.winforms.webview2.creationproperties) +* [CoreWebView2CreationProperties Class](/dotnet/api/microsoft.web.webview2.winforms.corewebview2creationproperties) + +WinRT: +* [CoreWebView2Environment.CreateWithOptionsAsync Method](/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2environment#createwithoptionsasync) + +Win32: +* [CreateCoreWebView2EnvironmentWithOptions](/microsoft-edge/webview2/reference/win32/webview2-idl?#createcorewebview2environmentwithoptions) + + +##### [Registry key](#tab/registry-key) 1. Open a PowerShell terminal or PowerShell-enabled command prompt. 1. Modify and then run the following command: - `REG ADD HKLM\Software\Policies\Microsoft\Edge\WebView2\ReleaseChannelPreference /v WebView2APISample.exe /t REG_SZ /d "1"` + ```reg + REG ADD \Software\Policies\Microsoft\Edge\WebView2\BrowserExecutableFolder /v WebView2APISample.exe /t REG_SZ /d "C:\Users\myname\AppData\Local\Microsoft\Edge SxS\Application\88.0.680.0" + ``` + + * Replace `WebView2APISample.exe` with your own app executable name or the application user model ID. + * Replace the sample path with the path to the desired Microsoft Edge preview channel. + - Replace `WebView2APISample.exe` with the file name of your own app executable or the Application User Model ID. Using a wildcard (*) as the value name will apply the override to _all_ WebView2 apps on the machine and can result in unexpected behavior. +##### [Environment variable](#tab/environment-variable) -#### Resuming using the default, WebView2 Evergreen Runtime +* Name: `WEBVIEW2_BROWSER_EXECUTABLE_FOLDER` +* Value: `` -To delete the `ReleaseChannelPreference` registry override, run the command: +The target app can't be set when using the environment variable approach. Therefore, when set as a global environment, this setting will affect all apps that use WebView2 on the machine. -`REG DELETE HKLM\Software\Policies\Microsoft\Edge\WebView2\ReleaseChannelPreference /f` +See also: +* [How to set an environment variable](#how-to-set-an-environment-variable), below. - -## Using an environment variable +##### [Group policy](#tab/group-policy) -To make your application use a Microsoft Edge preview channel by using an environment variable: +Set the `BrowserExecutableFolder` policy. + +* Name: `` +* Value: `` + +Do either of the following: + +* Download the Microsoft Edge policy files, which include the WebView2 policy files, from [Download and configure Microsoft Edge for Business](https://www.microsoft.com/edge/business/download). See [Configure Microsoft Edge policy settings on Windows devices](/deployedge/configure-microsoft-edge). + +* Use the built-in policy on Intune. See [Configure Microsoft Edge policy settings in Microsoft Intune](/mem/intune/configuration/administrative-templates-configure-edge). + +--- -1. In the Windows search bar, enter "environment", and then select **Edit the system environment variables**. + + +## When the new runtime gets picked up + +If you are using an environment variable, registry key, or group policy, they are only applied to any new WebView2 Runtime browser processes that are created; they do not apply to WebView2 Runtime browser processes that are already running. For example, if you already have a WebView2 with a specific user data folder (and therefore a corresponding browser process) and change `ChannelSearchKind` before attempting to create a new WebView2 using that same user data folder, it will use the existing WebView2 Runtime browser process, and not search for a different runtime. + +To ensure that all processes use the environment variable, registry key, or group policy, you need to do any of the following: +* Restart the app. +* Re-create all of the WebView2 controls that share a user data folder. +* Create a new WebView2 that has a different user data folder than any other currently running WebView2 controls. + + + +## How to set an environment variable + +You can use multiple approaches to set environment variables: +* Setting environmental variables by using APIs, for a specific app. +* Setting environmental variables globally, for all apps. + +These approaches are described below. + + + +#### Setting environmental variables by using APIs, for a specific app + +You can set environment variables by using `SetEnvironmentVariable`. Calling this function from your host app limits the scope of the environment variable to just your host app and the WebView2 controls that it creates, and doesn't affect other apps on the system. + +* .NET: [Environment.SetEnvironmentVariable Method](/dotnet/api/system.environment.setenvironmentvariable) + +* WinRT: [EnvironmentManager.SetEnvironmentVariable Method](/windows/windows-app-sdk/api/winrt/microsoft.windows.system.environmentmanager.setenvironmentvariable) + +* Win32: [SetEnvironmentVariable function (winbase.h)](/windows/win32/api/winbase/nf-winbase-setenvironmentvariable) + + + +#### Setting environmental variables globally, for all apps + +You can set environment variables by using the Windows system UI. This approach makes the scope of the environment variable global for the current user or system, and affects all apps that create WebView2 controls. + +1. In the Windows search bar, enter "environment", and then select **Edit the system environment variables**: ![Using the Windows search bar to find where to edit environment variables](./set-preview-channel-images/search-bar-edit-sys-env-vars.png) -1. In the **System Properties** dialog, select the **Advanced** tab, and then select the **Environment Variables** button. + The **System Properties** dialog opens. + +1. Select the **Advanced** tab, and then click the **Environment Variables** button: ![The Environment Variables button in the System Properties dialog](./set-preview-channel-images/system-properties-env-vars.png) -1. In the **User variables** section of the **Environment Variables** dialog, select **New**. + The **Environment Variables** dialog opens. + +1. In the **User variables** section at the top, click the **New** button. The **New User Variable** dialog opens. -1. In the **New User Variable** dialog, set the **Variable name** to `WEBVIEW2_BROWSER_EXECUTABLE_FOLDER`, and set the **Variable value** to the path to your preferred browser channel or fixed version binaries. +1. In the **Variable name** text box, enter the environment variable name, either `WEBVIEW2_CHANNEL_SEARCH_KIND` or `WEBVIEW2_BROWSER_EXECUTABLE_FOLDER`. - Alternatively, set the **Variable name** to `WEBVIEW2_RELEASE_CHANNEL_PREFERENCE`, and set the **Variable value** to `1` to reverse the search order, to use preview channels (Beta, Dev, or Canary) first. Any value besides `1` indicates the default search order. +1. In the **Variable value** text box, do either of the following: -1. Click **OK** to close the dialogs. + * If setting the `ChannelSearchKind`, enter `1` to reverse the search order from the default, to use the preview channels first (Canary, Beta, then Dev), followed by the WebView2 Runtime. Any value other than `1` causes the default search order to be used (WebView2 Runtime, Edge Dev, Edge Beta, and then Edge Canary). - ![Adding a new environment variable, as a user variable](./set-preview-channel-images/env-vars-new-user-variable.png) + * If setting the `BrowserExecutableFolder`, enter the path to your preferred browser channel or fixed-version binaries. -### Which app is affected +1. Click the **OK** buttons to close the dialogs. -The above approach sets the environment variable for all WebView2 apps, not just the app you're testing. To set this environment variable for only the WebView2 app which you are testing, if you're running your app from the command prompt, set the environment variable `WEBVIEW2_RELEASE_CHANNEL_PREFERENCE=1`. That sets the environment variable just for the current `cmd.exe` command-prompt process and for any new child processes from that `cmd.exe` instance. Then the environment variable only applies to the WebView2 app that you're testing. -If you use the `WEBVIEW2_RELEASE_CHANNEL_PREFERENCE` environment variable, you can set it to the following values. + +## How to deploy preview channels + +To deploy the preview channels of Microsoft Edge to multiple machines, do either of the following: -| Value | Description | -|---|---| -| `1` | Reverses the search order, to use [preview channels](https://www.microsoft.com/edge/download/insider) first, before the WebView2 Runtime. | -| `0` or another value other than `1` | Uses the [default channel-search order](#default-channel-search-order), which is to use the WebView2 Runtime before the preview channels. | +* Option 1: Manually install preview channels on machines. -### Applying the new environment variable to running processes +* Option 2: Programmatically deploy preview channels via API endpoints. -After setting an environment variable, the environment variable is applied to any new processes that are created. The environment variable doesn't apply to processes which are already running. To ensure that all processes use the new environment variable, you may need to restart Visual Studio, or log out of Windows and then log in again. +These options are explained below. - -## Using a group policy + +#### Option 1: Manually install preview channels on machines -If you want to make your application use a Microsoft Edge preview channel by using a group policy, copy ADMX and ADML files to the `PolicyDefinitions` folder, as follows. +Preview channels can be manually installed (either manually or through a deployed custom script) through the following enterprise links: -1. Download the policy files from [Download and deploy Microsoft Edge for business](https://www.microsoft.com/edge/business/download). +| Channel | Link | +| --- | --- | +| Canary | [Download](https://go.microsoft.com/fwlink/?linkid=2084649&Channel=Canary&language=en) | +| Dev | [Download](https://go.microsoft.com/fwlink/?linkid=2093291) | +| Beta | [Download](https://go.microsoft.com/fwlink/?linkid=2093376) | -1. Copy the ADMX file into a Policy Definitions template folder, such as `C:\Windows\PolicyDefinitions`. +Manual installation only needs to be done once per machine. Prerelease channels are evergreen, so they will automatically get updated when newer versions are available. -1. Copy the ADML file into a matching locale folder within the `Policy Definitions` folder, such as a `C:\Windows\PolicyDefinitions\en-us` folder. -1. Open the **Local Group Policy Editor**. To do this, in the Windows search bar, type "group policy", and then select **Edit group policy**. + +#### Option 2: Programmatically deploy preview channels via API endpoints -1. Expand **Local Computer Policy**, then **Computer Configuration** or **User Configuration**. Then expand **Administrative Templates** > **Microsoft Edge WebView2**. +In your app's code, write your own custom logic to deploy the latest version of a preview channel of Microsoft Edge as follows: - ![Local Group Policy Editor dialog](./set-preview-channel-images/local-group-policy-editor.png) +1. Call the following API endpoint that corresponds to the preview channel that you want to deploy: -1. Select **Browser Executable Folder**. The following screenshots apply to setting the **Browser Executable Folder**. Alternatively, select **Release Channel Preference**, which uses similar dialogs. + | Channel | Link | + | --- | --- | + | Canary | [https://edgeupdates.microsoft.com/api/products/canary](https://edgeupdates.microsoft.com/api/products/canary)
[MSI Link](https://go.microsoft.com/fwlink/?linkid=2084649&Channel=Canary&language=en)| + | Dev | [https://edgeupdates.microsoft.com/api/products/dev](https://edgeupdates.microsoft.com/api/products/dev) | + | Beta | [https://edgeupdates.microsoft.com/api/products/beta](https://edgeupdates.microsoft.com/api/products/beta) | - ![Setting the Browser Executable Folder](./set-preview-channel-images/browser-executable-folder.png) + The Canary channel has a separate MSI link. The Dev and Beta channels contain MSI links. -1. Select the **Show** button. +1. Fetch the latest package to the device. -1. Fill-in the **Show Contents** dialog. In the **Value name** column, enter your app's `.exe` file name or Application User Model ID. Using a wildcard (*) as the value name will apply the override to _all_ WebView2 apps on the machine and can result in unexpected behavior. +1. Install the package. - ![The Show Contents dialog](./set-preview-channel-images/show-contents.png) -1. Select **OK** to close the dialogs. + +## See also -For more information, see [Configure Microsoft Edge policy settings](/deployedge/configure-microsoft-edge). +* [Phases of introducing APIs](../concepts/versioning.md#phases-of-introducing-apis) in _Understand the different WebView2 SDK versions_. diff --git a/microsoft-edge/webview2/how-to/webdriver.md b/microsoft-edge/webview2/how-to/webdriver.md index 17a4a24d67..9ed1622798 100644 --- a/microsoft-edge/webview2/how-to/webdriver.md +++ b/microsoft-edge/webview2/how-to/webdriver.md @@ -104,14 +104,18 @@ Microsoft Edge WebDriver launches your WebView2 app and automatically attaches t * The "attach" approach: In other scenarios, it's appropriate to attach Microsoft Edge WebDriver to a running WebView2 instance. You launch your app outside of Microsoft Edge WebDriver, and then attach Microsoft Edge WebDriver to a running WebView2 instance. This "attach" approach is for a WebView2 app that's not compatible with the "launch" approach. -### Approach 1: Letting Microsoft Edge WebDriver launch your WebView2 app + + +#### Approach 1: Letting Microsoft Edge WebDriver launch your WebView2 app If you have a simple app that creates a single WebView2 instance and that instance is active immediately upon launch, then you can use the "launch" approach; use [Step 4a: Letting Microsoft Edge WebDriver launch your WebView2 app](#step-4a-letting-microsoft-edge-webdriver-launch-your-webview2-app). In this scenario, there's one WebView2 instance, and it's available upon launch, without needing to navigate through any native UI. -### Approach 2: Attaching Microsoft Edge WebDriver to a running WebView2 app + + +#### Approach 2: Attaching Microsoft Edge WebDriver to a running WebView2 app If you have any situation that doesn't fit the "launch" scenario above, you should attach Microsoft Edge WebDriver to a running WebView2 instance (instead of letting Microsoft Edge WebDriver handle the WebView2 launch); use [Step 4b: Attaching Microsoft Edge WebDriver to a running WebView2 app](#step-4b-attaching-microsoft-edge-webdriver-to-a-running-webview2-app). @@ -202,7 +206,9 @@ Microsoft Edge WebDriver doesn't handle native UI automation, but here are some In addition to ensuring the WebView2 instance is activated, you need to set its `--remote-debugging-port` command-line parameter. We'll do this in the steps below. Microsoft Edge WebDriver will use this remote debugging port to connect to your WebView2 instance. -### Launching the WebView2 app with remote debugging enabled + + +#### Launching the WebView2 app with remote debugging enabled The next step happens when you're coding your app. You need to provide this extra command-line parameter when you're instantiating your WebView2 control. Enable remote debugging, as follows. @@ -212,7 +218,9 @@ The next step happens when you're coding your app. You need to provide this ext At this point, your app is running and its `--remote-debugging-port` command-line parameter has been set. Next, we'll attach Microsoft Edge WebDriver to the launched WebView2 app. -### Attaching Microsoft Edge WebDriver to the launched WebView2 app + + +#### Attaching Microsoft Edge WebDriver to the launched WebView2 app 1. Use the `EdgeOptions.DebuggerAddress` property to tell Microsoft Edge WebDriver to connect to the remote debugging port that you specified previously, instead of launching a new application: @@ -227,11 +235,13 @@ At `localhost:9222` above, the port number given on this line should match the p For more info about the `DebuggerAddress` property of the `EdgeOptions` object, see [EdgeOptions object](../../webdriver-chromium/capabilities-edge-options.md#edgeoptions-object). -### For UWP apps, attach Microsoft Edge WebDriver to WebView2 with Remote Tools -1. Complete the steps described in [Remote debugging UWP apps with Remote Tools for Microsoft Edge](./remote-debugging.md). + +#### For UWP apps, attach Microsoft Edge WebDriver to WebView2 with Remote Tools + +1. Do the steps in [Remote debugging UWP apps with Remote Tools for Microsoft Edge](./remote-debugging.md). - This WebView2 feature is currently only supported in the Canary preview channel of Microsoft Edge. Set the enviroment variable `WEBVIEW2_RELEASE_CHANNEL_PREFERENCE=1`, to ensure that the WebView2 version is Canary. For more information, see [Using an environment variable](./set-preview-channel.md#using-an-environment-variable) in _Test upcoming APIs and features_. + This WebView2 feature is currently only supported in the Canary preview channel of Microsoft Edge. Set the environment variable `WEBVIEW2_RELEASE_CHANNEL_PREFERENCE=1`, to ensure that the WebView2 version is Canary. For more information, see [How to set an environment variable](./set-preview-channel.md#how-to-set-an-environment-variable) in _Test upcoming APIs and features_. ![Settings for UWP app](./webdriver-images/sample-uwp-settings.png) @@ -260,7 +270,9 @@ For more information about launching a WebView2 UWP app with Remote Tools, see [ Congratulations! You've successfully attached Microsoft Edge WebDriver to a running WebView2 app. -### UWP projects and debugging + + +#### UWP projects and debugging To configure the debug settings on launch, you must use the registry to enable debugging for all WebView2 processes on startup. Because of the way that UWP projects are launched, the WebDriver2 control is unable to automatically configure the debug settings on launch. Note that setting this registry key enables debugging support for all launched WebView2 processes while this environment variable is configured. diff --git a/microsoft-edge/webview2/index.md b/microsoft-edge/webview2/index.md index 78e57e2218..ab089c31a3 100644 --- a/microsoft-edge/webview2/index.md +++ b/microsoft-edge/webview2/index.md @@ -11,7 +11,7 @@ ms.date: 10/31/2023 --- # Introduction to Microsoft Edge WebView2 -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](https://www.microsoft.com/edge/download/insider) as the rendering engine to display the web content in native apps. +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. @@ -117,3 +117,6 @@ See also: developer.microsoft.com: * [Microsoft Edge WebView2](https://developer.microsoft.com/microsoft-edge/webview2) - initial introduction to WebView2 features at developer.microsoft.com. + +Microsoft.com: +* [Become a Microsoft Edge Insider](https://www.microsoft.com/en-us/edge/download/insider) - download the preview channels of Microsoft Edge (Canary, Dev, and Beta). diff --git a/microsoft-edge/webview2/samples/webview2_sample_uwp.md b/microsoft-edge/webview2/samples/webview2_sample_uwp.md index 4829b2d3cd..e78f8cd576 100644 --- a/microsoft-edge/webview2/samples/webview2_sample_uwp.md +++ b/microsoft-edge/webview2/samples/webview2_sample_uwp.md @@ -117,7 +117,7 @@ Update the project's NuGet packages: 1. Select the **Include prerelease** check box. - A pre-release version of the **Microsoft.UI.Xaml** package is listed, indicating the WinUI 2 SDK. The **Microsoft.UI.Xaml** package includes the WebView2 SDK; **Microsoft.Web.WebView2** is listed in the **Dependencies** section of the **Microsoft.UI.Xaml** package. Updating the **Microsoft.UI.Xaml** package will also cause an update to the compatible WebView2 SDK. + A prerelease version of the **Microsoft.UI.Xaml** package is listed, indicating the WinUI 2 SDK. The **Microsoft.UI.Xaml** package includes the WebView2 SDK; **Microsoft.Web.WebView2** is listed in the **Dependencies** section of the **Microsoft.UI.Xaml** package. Updating the **Microsoft.UI.Xaml** package will also cause an update to the compatible WebView2 SDK. 1. In the **NuGet Package Manager**, click the **Updates** tab. diff --git a/microsoft-edge/webview2/samples/webview2apissample.md b/microsoft-edge/webview2/samples/webview2apissample.md index 71307dc09b..456450918b 100644 --- a/microsoft-edge/webview2/samples/webview2apissample.md +++ b/microsoft-edge/webview2/samples/webview2apissample.md @@ -176,7 +176,7 @@ Next, you'll update the WebView2 SDK and then re-build the project. If you want to quickly see which version of the WebView2 SDK is installed in the repo's copy of the **WebView2APISample** app at GitHub, see [packages.config](https://github.com/MicrosoftEdge/WebView2Samples/blob/main/SampleApps/WebView2APISample/packages.config). -The repo version of this sample has a pre-release version of the WebView2 SDK installed. Below, you'll update it to the latest pre-release version of the WebView2 SDK, or confirm that the latest SDK is installed. Using a pre-release SDK gives you access to the latest functionality. +The repo version of this sample has a prerelease version of the WebView2 SDK installed. Below, you'll update it to the latest prerelease version of the WebView2 SDK, or confirm that the latest SDK is installed. Using a prerelease SDK gives you access to the latest functionality. Examine and possibly update the installed NuGet packages, as follows: diff --git a/microsoft-edge/webview2/samples/webview2browser.md b/microsoft-edge/webview2/samples/webview2browser.md index fd63510951..ce36d78406 100644 --- a/microsoft-edge/webview2/samples/webview2browser.md +++ b/microsoft-edge/webview2/samples/webview2browser.md @@ -39,7 +39,7 @@ This sample is built as a Win32 [Visual Studio 2019](https://visualstudio.micros ## Step 1: Install a preview channel of Microsoft Edge -* If not installed yet, install a [preview channel of Microsoft Edge](https://www.microsoft.com/edge/download/insider/) on a supported OS. +* If not installed yet, install a preview channel of Microsoft Edge on a supported operating system. To do this, go to [Become a Microsoft Edge Insider](https://www.microsoft.com/edge/download/insider/).