From 1c057e8f57041f4f31342dbbb4a5d4bec8d2bcdb Mon Sep 17 00:00:00 2001 From: Michael Hoffman <45407486+mikehoffms@users.noreply.github.com> Date: Tue, 14 Oct 2025 10:45:05 -0700 Subject: [PATCH] Break out article "Evergreen vs. fixed version of the WebView2 Runtime" (#3601) * break out article * linkfix * add to wv2 landing page * toc linkfix * update evergreen article link * x-link overview vs details h2s * our * update ext link #download-the-webview2-runtime * details (details) * remove RT comment --- microsoft-edge/toc.yml | 3 + .../webview2/concepts/data-privacy.md | 2 +- .../webview2/concepts/developer-guide.md | 74 ++++++-- .../webview2/concepts/distribution.md | 178 ++++++++---------- .../webview2/concepts/enterprise.md | 5 +- .../concepts/environment-controller-core.md | 28 +-- .../runtime-distrib-options.png | Bin .../concepts/evergreen-vs-fixed-version.md | 114 +++++++++++ .../concepts/overview-features-apis.md | 4 +- .../webview2/concepts/versioning.md | 68 +++++-- microsoft-edge/webview2/landing/index.yml | 3 + .../webview2/release-notes/about.md | 2 +- .../webview2/release-notes/archive.md | 2 +- 13 files changed, 341 insertions(+), 142 deletions(-) rename microsoft-edge/webview2/concepts/{distribution-images => evergreen-vs-fixed-version-images}/runtime-distrib-options.png (100%) create mode 100644 microsoft-edge/webview2/concepts/evergreen-vs-fixed-version.md diff --git a/microsoft-edge/toc.yml b/microsoft-edge/toc.yml index 0e4a836949..59e667fb8c 100644 --- a/microsoft-edge/toc.yml +++ b/microsoft-edge/toc.yml @@ -1573,6 +1573,9 @@ href: ./webview2/concepts/versioning.md displayName: experimental APIs, Understand WebView2 SDK versions, Understand the different WebView2 SDK versions # old titles + - name: Evergreen vs. fixed version of the WebView2 Runtime + href: ./webview2/concepts/evergreen-vs-fixed-version.md + - name: Distribute your app and the WebView2 Runtime href: ./webview2/concepts/distribution.md diff --git a/microsoft-edge/webview2/concepts/data-privacy.md b/microsoft-edge/webview2/concepts/data-privacy.md index 1f2c5ba9e2..e2a4014035 100644 --- a/microsoft-edge/webview2/concepts/data-privacy.md +++ b/microsoft-edge/webview2/concepts/data-privacy.md @@ -10,7 +10,7 @@ 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 WebView2 Runtime Terms and Conditions License, WebView2 developers acknowledge that WebView2 will collect the data that's described in this article. To view the license, go to [Download the WebView2 Runtime](https://developer.microsoft.com/microsoft-edge/webview2#download-the-webview2-runtime), where clicking any of the download buttons, such as **Get the Link**, **Download**, or **x64**, shows the license in a dialog. 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/developer-guide.md b/microsoft-edge/webview2/concepts/developer-guide.md index 744b80f9fd..16001d8fc3 100644 --- a/microsoft-edge/webview2/concepts/developer-guide.md +++ b/microsoft-edge/webview2/concepts/developer-guide.md @@ -20,7 +20,7 @@ We recommend using the Evergreen WebView2 Runtime for most WebView2 apps, rather The Evergreen runtime updates automatically on the client, so that the latest features and security patches are available to your WebView2 app. The Evergreen runtime also requires less storage space on the disk than the Fixed Version runtime. Fixed Version runtime distribution is only recommended for apps that have strict compatibility requirements. -For more information about the benefits of the Evergreen Runtime, see [Details about the Evergreen Runtime distribution mode](../concepts/distribution.md#details-about-the-evergreen-runtime-distribution-mode) in _Distribute your app and the WebView2 Runtime_. +See [Evergreen vs. fixed version of the WebView2 Runtime](./evergreen-vs-fixed-version.md). To help ensure that your WebView2 app works well with the Evergreen WebView2 Runtime, use the recommended practices in the subsections below: * [Check to make sure the WebView2 Runtime is installed](#check-to-make-sure-the-webview2-runtime-is-installed). @@ -34,7 +34,7 @@ To help ensure that your WebView2 app works well with the Evergreen WebView2 Run When using the Evergreen WebView2 Runtime, before your app uses the WebView2 control, programmatically check to make sure that the Evergreen WebView2 Runtime is installed on the client. -See [Detect if a WebView2 Runtime is already installed](../concepts/distribution.md#detect-if-a-webview2-runtime-is-already-installed) in _Distribute your app and the WebView2 Runtime_. +See [Detect if a WebView2 Runtime is already installed](./distribution.md#detect-if-a-webview2-runtime-is-already-installed) in _Distribute your app and the WebView2 Runtime_. @@ -42,7 +42,7 @@ See [Detect if a WebView2 Runtime is already installed](../concepts/distribution When using the Evergreen WebView2 Runtime, handle Evergreen WebView2 Runtime updates. Updates of the Evergreen WebView2 Runtime are automatically downloaded, but a running WebView2 app will continue using its current version of the WebView2 Runtime, potentially missing security updates. To adopt the new version, an app must release all references to previous WebView2 objects or restart. Implementing a `NewBrowserVersionAvailable` event handler can prompt users to restart the app for updates, with a recommendation to save user state before exiting for a seamless transition. -See [Handle Evergreen WebView2 Runtime updates](../concepts/distribution.md#handle-evergreen-webview2-runtime-updates) in _Distribute your app and the WebView2 Runtime_. +See [Handle Evergreen WebView2 Runtime updates](./distribution.md#handle-evergreen-webview2-runtime-updates) in _Distribute your app and the WebView2 Runtime_. @@ -62,7 +62,7 @@ When using the Evergreen WebView2 Runtime, use feature detection to test whether When using the Evergreen WebView2 Runtime, there are some scenarios where the runtime on a client hasn't been automatically updated to the latest version. Additionally, some group policies pause updating of the runtime. As a result, when you push an update to your WebView2 app, the app might not work if it tries to call newer APIs that aren't available in the client's installed runtime. Therefore, you should use feature detection to make sure that the newer APIs that are used by your WebView2 app are supported by the WebView2 Runtime that's installed on the client. -See [Feature-detecting to test whether the installed Runtime supports recently added APIs](../concepts/versioning.md#feature-detecting-to-test-whether-the-installed-runtime-supports-recently-added-apis) in _Prerelease and Release SDKs for WebView2_. +See [Feature-detecting to test whether the installed Runtime supports recently added APIs](./versioning.md#feature-detecting-to-test-whether-the-installed-runtime-supports-recently-added-apis) in _Prerelease and Release SDKs for WebView2_. @@ -70,7 +70,9 @@ See [Feature-detecting to test whether the installed Runtime supports recently a If you use the Fixed Version WebView2 Runtime, make sure you regularly update the WebView2 Runtime that's packaged with your app, to reduce security risks. To determine how often you should update the Fixed Version Runtime, you should consider your app's threat model. For example, when using third-party content in Webview2 apps, always consider the content to be untrusted. -See [Details about the Fixed Version runtime distribution mode](../concepts/distribution.md#details-about-the-fixed-version-runtime-distribution-mode) in _Distribute your app and the WebView2 Runtime_. +See: +* [Evergreen vs. fixed version of the WebView2 Runtime](./evergreen-vs-fixed-version.md) +* [The Fixed Version runtime distribution mode](./distribution.md#the-fixed-version-runtime-distribution-mode) in _Distribute your app and the WebView2 Runtime_. @@ -78,7 +80,8 @@ See [Details about the Fixed Version runtime distribution mode](../concepts/dist WebView2 apps create a user data folder to store data such as cookies, credentials, and permissions. After creating the user data folder, your app is responsible for managing the lifetime of the user data folder. For example, your app must do cleanup when the app is uninstalled. -See [Manage user data folders](../concepts/user-data-folder.md) for further guidance on managing the user data folder. +See: +* [Manage user data folders](./user-data-folder.md) @@ -86,13 +89,30 @@ See [Manage user data folders](../concepts/user-data-folder.md) for further guid WebView2 apps are supported by a collection of runtime processes that run alongside the app process. These supporting runtime processes can fail for various reasons, such as running out of memory, or being terminated by the user. Your WebView2 app should handle these process-related events, to ensure that the app can recover from failures and continue to run smoothly. -See [Handling process-related events in WebView2](../concepts/process-related-events.md). +See [Handling process-related events in WebView2](./process-related-events.md). ## Event handlers on the environment object -If any of your app's event handlers on the [environment object](/microsoft-edge/webview2/reference/win32/webview2-idl#createcorewebview2environment) hold a reference to the environment object, and the app simply releases the reference to the environment and event handlers without removing the event handlers, there might be a circular reference between the environment object and handler objects, which will leak memory. +If any of your app's event handlers on the `CoreWebView2Environment` object hold a reference to the environment object, and the app simply releases the reference to the environment and event handlers without removing the event handlers, there might be a circular reference between the environment object and handler objects, which will leak memory. + +##### [.NET/C#](#tab/dotnetcsharp) + +* [CoreWebView2Environment](/dotnet/api/microsoft.web.webview2.core.corewebview2environment) + * [CoreWebView2Environment.CreateAsync Method](/dotnet/api/microsoft.web.webview2.core.corewebview2environment.createasync) + +##### [WinRT/C#](#tab/winrtcsharp) + +* [CoreWebView2Environment](/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2environment) + * [CoreWebView2Environment.CreateAsync Method](/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2environment) + +##### [Win32/C++](#tab/win32cpp) + +* [ICoreWebView2Environment](/microsoft-edge/webview2/reference/win32/icorewebview2environment) +* [CreateCoreWebView2Environment](/microsoft-edge/webview2/reference/win32/webview2-idl#createcorewebview2environment) in _Globals_. + +--- To prevent such a memory leak: @@ -110,12 +130,42 @@ WebView2 enables you to host web content in your native applications, providing However, hosting web content can also introduce vulnerabilities. To avoid vulnerabilities that can arise from hosting web content within a native application, make sure to design your WebView2 application to closely monitor interactions between the web content and the host application. -Follow the guidance in [Develop secure WebView2 apps](../concepts/security.md). +Follow the guidance in [Develop secure WebView2 apps](./security.md). ## See also - + + + +* [Handling process-related events in WebView2](./process-related-events.md) +* [Feature-detecting to test whether the installed Runtime supports recently added APIs](./versioning.md#feature-detecting-to-test-whether-the-installed-runtime-supports-recently-added-apis) in _Prerelease and Release SDKs for WebView2_. +* [Evergreen vs. fixed version of the WebView2 Runtime](./evergreen-vs-fixed-version.md) +* [Distribute your app and the WebView2 Runtime](./distribution.md) + * [Detect if a WebView2 Runtime is already installed](./distribution.md#detect-if-a-webview2-runtime-is-already-installed) in _Distribute your app and the WebView2 Runtime_. + * [The Fixed Version runtime distribution mode](./distribution.md#the-fixed-version-runtime-distribution-mode) in _Distribute your app and the WebView2 Runtime_. + * [Handle Evergreen WebView2 Runtime updates](./distribution.md#handle-evergreen-webview2-runtime-updates) in _Distribute your app and the WebView2 Runtime_. +* [Develop secure WebView2 apps](./security.md) +* [Prerelease testing using preview channels](../how-to/prerelease-testing.md) +* [Self-host by deploying preview channels](../how-to/self-hosting.md) +* [Manage user data folders](./user-data-folder.md) + +WebView2 Reference: + +##### [.NET/C#](#tab/dotnetcsharp) + +* [CoreWebView2Environment](/dotnet/api/microsoft.web.webview2.core.corewebview2environment) + +##### [WinRT/C#](#tab/winrtcsharp) + +* [CoreWebView2Environment](/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2environment) + +##### [Win32/C++](#tab/win32cpp) + +* [ICoreWebView2Environment](/microsoft-edge/webview2/reference/win32/icorewebview2environment) +* [CreateCoreWebView2Environment](/microsoft-edge/webview2/reference/win32/webview2-idl#createcorewebview2environment) in _Globals_. + +--- - -* [Microsoft Edge release schedule](/deployedge/microsoft-edge-release-schedule) +Microsoft Edge Enterprise documentation: +* [Microsoft Edge release schedule](/deployedge/microsoft-edge-release-schedule) diff --git a/microsoft-edge/webview2/concepts/distribution.md b/microsoft-edge/webview2/concepts/distribution.md index a6bc0d9c03..5641272361 100644 --- a/microsoft-edge/webview2/concepts/distribution.md +++ b/microsoft-edge/webview2/concepts/distribution.md @@ -9,97 +9,21 @@ ms.subservice: webview ms.date: 06/27/2024 --- # Distribute your app and the WebView2 Runtime - + -When releasing an app that uses Microsoft Edge WebView2, you need to distribute the WebView2 Runtime, either by distributing the automatically updated _Evergreen_ Runtime, or by distributing a _Fixed Version_ of the Runtime. - -A WebView2 app depends on the WebView2 Runtime on client machines. When you distribute your WebView2 app, you need to take into account how the WebView2 Runtime is distributed to and updated on client machines. - - - -## The WebView2 Runtime - -The WebView2 Runtime is a redistributable runtime and serves as the underlying (or _backing_) web platform for WebView2 apps. The concept is similar to Visual C++ or the .NET Runtime for C++/.NET apps. The WebView2 Runtime contains modified Microsoft Edge binaries that are fine-tuned and tested for WebView2 apps. After the WebView2 Runtime is installed, it doesn't appear as a user-visible browser app. For example, a user doesn't have a browser desktop shortcut or an entry in the **Start** menu. - -There are two different ways of distributing and updating the WebView2 Runtime to client machines: the Evergreen distribution mode, and the Fixed Version distribution mode. - - - -## The Evergreen Runtime distribution mode - -In the _Evergreen_ distribution mode, the WebView2 Runtime isn't packaged with your app, but is initially installed onto clients using an online bootstrapper or an offline installer. Afterwards, the WebView2 Runtime is automatically updated on client machines. You can then distribute updates of your WebView2 app that use the latest WebView2 APIs, from the latest WebView2 SDK. The Evergreen distribution mode is recommended for most developers. - -Pros: - -* The underlying web platform (WebView2 Runtime) updates automatically without more effort from you. - -* Less disk space is required for the WebView2 Runtime on client systems, because the WebView2 Runtime is shared by all WebView2 apps that are on the client. - -* On eligible systems, binaries for Microsoft Edge and the Evergreen WebView2 Runtime are hard-linked together when they are on the same version. This linking provides benefits for disk footprint, memory, and performance. - -Cons: - -* Your WebView2 app cannot specify that a particular version of the WebView2 Runtime is required. - - - -#### 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. - - - -## The Fixed Version runtime distribution mode - -In the _Fixed Version_ distribution mode, you download a specific version of the WebView2 Runtime and package it together with your WebView2 app in your app package. The WebView2 Runtime that you package with your app is used only by your WebView2 app, not by any other apps on the client's machine. - -Pros: -* You have more control over versioning of the WebView2 Runtime. You know which WebView2 APIs are available to your app, because you control which version of the WebView2 Runtime is available to your app. Your app doesn't need to test whether the latest APIs are present. - -Cons: - -* You need to manage the WebView2 Runtime yourself. The WebView2 Runtime isn't automatically updated on clients, so to use the latest WebView2 APIs, you must periodically update your app together with the updated WebView2 Runtime. - -* More disk space is required on the client, if there are multiple WebView2 apps installed. - -* The Fixed Version runtime can't be installed by using an installer. - - - -## 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. - -![Options for distributing and updating the WebView2 Runtime](./distribution-images/runtime-distrib-options.png) - -The Evergreen distribution mode is recommended for most apps. - -* The **Evergreen Bootstrapper** section of the page provides a small Evergreen Runtime bootstrapper that runs on the client machine, for online users. The bootstrapper downloads and installs the appropriate Evergreen WebView2 Runtime onto the client. You can use the bootstrapper a couple different ways: - - * Link to the bootstrapper, using a link that you obtain from the **Get the Link** button. Your app uses this link to programmatically download the bootstrapper onto the client and invoke the bootstrapper. This approach avoids the need to package the bootstrapper with your app. This approach has a dependency on Microsoft's Content Delivery Network (CDN), to get the bootstrapper. - - * Download the bootstrapper (using the **Download** button in the **Bootstrapper** section) and then distribute the bootstrapper with your app. In this approach, you package the bootstrapper with your app installer/updater or with your app itself, and invoke the bootstrapper that you included with your app. This approach avoids dependency on Microsoft's CDN, to get the bootstrapper. - -* The **Evergreen Standalone Installer** section of the page provides a large, standalone Evergreen installer, primarily for offline users. In this approach, you package the standalone installer with your app installer/updater or app itself, and invoke the Evergreen Standalone installer. This approach avoids dependency on Microsoft's CDN, to get the Runtime. - -* The **Fixed Version** section of the page provides a Fixed Version runtime, which is a specific version of the WebView2 Runtime that you distribute along with your app. - - - -## Details about the WebView2 Runtime - When distributing your WebView2 app, make sure that the WebView2 Runtime is present on the client machine. This requirement applies to both the Evergreen and Fixed Version distribution modes. -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). +For introductory information, see [Evergreen vs. fixed version of the WebView2 Runtime](./evergreen-vs-fixed-version.md). -#### Servicing the WebView2 Runtime through Windows Server Update Services (WSUS) +#### Servicing the WebView2 Runtime through Windows Server Update Services (WSUS) -See [Windows Server Update Services (WSUS)](enterprise.md#windows-server-update-services-wsus) in _Enterprise management of WebView2 Runtimes_. +See [Windows Server Update Services (WSUS)](./enterprise.md#windows-server-update-services-wsus) in _Enterprise management of WebView2 Runtimes_. @@ -131,9 +55,11 @@ Before your app creates a WebView2, the app should check whether the WebView2 Ru -## Details about the Evergreen Runtime distribution mode +## The Evergreen Runtime distribution mode + +The Evergreen distribution mode ensures that your WebView2 app is taking advantage of the latest WebView2 features and security updates. For introductory information, see [The Evergreen Runtime distribution mode](./evergreen-vs-fixed-version.md#the-evergreen-runtime-distribution-mode) in _Evergreen vs. fixed version of the WebView2 Runtime_. -The Evergreen distribution mode ensures that your WebView2 app is taking advantage of the latest WebView2 features and security updates. The Evergreen distribution mode has the following characteristics: +The Evergreen distribution mode has the following characteristics: * The WebView2 Runtime updates automatically without requiring any action from you. It receives the same Microsoft Edge updates that are described in [Release notes for Microsoft Edge Stable Channel](/deployedge/microsoft-edge-relnote-stable-channel) and [Release notes for Microsoft Edge Security Updates](/deployedge/microsoft-edge-relnotes-security). @@ -147,6 +73,8 @@ When you use the Evergreen distribution mode of the WebView2 Runtime, your WebVi #### Windows 11 devices and Windows 10 devices (details) +For introductory information, see [Windows 11 devices and Windows 10 devices](./evergreen-vs-fixed-version.md#windows-11-devices-and-windows-10-devices) in _Evergreen vs. fixed version of the WebView2 Runtime_. + The vast majority of Windows 10 devices have the WebView2 Runtime installed already, as described in [Delivering Microsoft Edge WebView2 Runtime to managed Windows 10 devices](https://blogs.windows.com/msedgedev/2022/12/14/delivering-microsoft-edge-webview2-runtime-to-managed-windows-10-devices/). A small number of Windows 10 devices don't have the WebView2 Runtime installed. We recommend that you handle this edge case, by using either of the following approaches: * Programmatically deploy the Evergreen Runtime with your app. See [Deploying the Evergreen WebView2 Runtime](#deploying-the-evergreen-webview2-runtime) below. @@ -154,14 +82,13 @@ 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: -* [Prerelease and Release SDKs for WebView2](versioning.md) - Use a Prerelease version of the SDK along with a preview channel of Microsoft Edge; or use a Release version of the SDK along with the Evergreen WebView2 Runtime. -* [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/). +* [Prerelease and Release SDKs for WebView2](./versioning.md) - Use a Prerelease version of the SDK along with a preview channel of Microsoft Edge; or use a Release version of the SDK along with the Evergreen WebView2 Runtime. #### 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 [Download the WebView2 Runtime](https://developer.microsoft.com/microsoft-edge/webview2#download-the-webview2-runtime) to help you deploy the Evergreen Runtime. * For online clients: _WebView2 Runtime Bootstrapper_ is a tiny (approximately 2 MB) installer. The WebView2 Runtime Bootstrapper downloads and installs the Evergreen Runtime from Microsoft servers that matches the user's device architecture. @@ -250,7 +177,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 [Download the WebView2 Runtime](https://developer.microsoft.com/microsoft-edge/webview2#download-the-webview2-runtime) 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. @@ -305,15 +232,15 @@ For best practices about how to test your app for forward-compatibility, see [Pr When using Evergreen mode in WebView2 apps, it's crucial to check for the presence of new APIs on the client's machine, by using methods like `QueryInterface` or `try-catch`, because the client machine might not have the latest WebView2 Runtime, containing the new APIs. Updates to the WebView2 Runtime might not occur if an IT Admin disables updating, or if the client is offline. -For details, see [Feature-detecting to test whether the installed Runtime supports recently added APIs](../concepts/versioning.md#feature-detecting-to-test-whether-the-installed-runtime-supports-recently-added-apis) in _Prerelease and Release SDKs for WebView2_. +For details, see [Feature-detecting to test whether the installed Runtime supports recently added APIs](./versioning.md#feature-detecting-to-test-whether-the-installed-runtime-supports-recently-added-apis) in _Prerelease and Release SDKs for WebView2_. There are separate update policies for Microsoft Edge and the WebView2 Runtime. Disabling updates for Microsoft Edge doesn't impact the availability of the latest WebView2 APIs, because the WebView2 Runtime can still update automatically (unless updating the WebView2 Runtime is disabled by an Admin). -## Details about the Fixed Version runtime distribution mode +## The Fixed Version runtime distribution mode -For constrained environments that have strict compatibility requirements, consider using the Fixed Version distribution mode. (The Fixed Version distribution mode was previously called _bring-your-own_.) +For constrained environments that have strict compatibility requirements, consider using the Fixed Version distribution mode. (The Fixed Version distribution mode was previously called _bring-your-own_.) For introductory information, see [The Fixed Version runtime distribution mode](./evergreen-vs-fixed-version.md#the-fixed-version-runtime-distribution-mode) in _Evergreen vs. fixed version of the WebView2 Runtime_. In the Fixed Version distribution mode, you control the timing of updates to the WebView2 Runtime for your app. You download a specific version of the WebView2 Runtime and then package it with your WebView2 app. The WebView2 Runtime on the client isn't automatically updated. Instead, you periodically update the WebView2 Runtime that's packaged and distributed together with your updated app. The Fixed Version approach doesn't use a registry key for the WebView2 Runtime. @@ -321,7 +248,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 [Download the WebView2 Runtime](https://developer.microsoft.com/microsoft-edge/webview2#download-the-webview2-runtime), 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. @@ -392,7 +319,7 @@ To use the Fixed Version distribution mode: ## Files to ship with the app -The `WebView2Loader` code needs to be shipped with the app. This can be done by [statically linking](../how-to/static.md) `WebView2Loader.lib` into the app binaries, or by including the `WebView2Loader.dll` that matches the app's architecture. Usually this is handled automatically for you by Visual Studio when using the `.targets` file in the WebView2 SDK, but there might be cases when you need to manually specify what files to publish with your app. +The `WebView2Loader` code needs to be shipped with the app. This can be done by statically linking `WebView2Loader.lib` into the app binaries, or by including the `WebView2Loader.dll` that matches the app's architecture. Usually this is handled automatically for you by Visual Studio when using the `.targets` file in the WebView2 SDK, but there might be cases when you need to manually specify what files to publish with your app. To statically link the WebView2 loader library, see [Distribute a WebView2 app as a single executable file](../how-to/static.md). `WebView2Loader.dll` is a native and architecture-specific binary, so you need to include all flavors of this binary that you expect your app to run in. For example: @@ -425,6 +352,65 @@ Example managed app folder structure: ## See also + + + +* [Prerelease and Release SDKs for WebView2](./versioning.md) + * [Feature-detecting to test whether the installed Runtime supports recently added APIs](./versioning.md#feature-detecting-to-test-whether-the-installed-runtime-supports-recently-added-apis) in _Prerelease and Release SDKs for WebView2_. +* [Evergreen vs. fixed version of the WebView2 Runtime](./evergreen-vs-fixed-version.md) +* [Windows Server Update Services (WSUS)](./enterprise.md#windows-server-update-services-wsus) in _Enterprise management of WebView2 Runtimes_. +* [Test upcoming APIs and features](../how-to/set-preview-channel.md) +* [Prerelease testing using preview channels](../how-to/prerelease-testing.md) +* [Self-host by deploying preview channels](../how-to/self-hosting.md) +* [Distribute a WebView2 app as a single executable file](../how-to/static.md) - statically linking the WebView2 loader library. + +Enterprise docs: +* [Microsoft Edge release schedule](/deployedge/microsoft-edge-release-schedule) +* [Release notes for Microsoft Edge Stable Channel](/deployedge/microsoft-edge-relnote-stable-channel) +* [Release notes for Microsoft Edge Security Updates](/deployedge/microsoft-edge-relnotes-security) + +developer.microsoft.com: +* [Download the WebView2 Runtime](https://developer.microsoft.com/microsoft-edge/webview2#download) - Developers. +* [Download Microsoft Edge WebView2](https://developer.microsoft.com/microsoft-edge/webview2/consumer/) - End users. + +Blogs: +* [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/) +* [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/) + +Windows: +* [Install Windows 10 apps with App Installer](/windows/msix/app-installer/app-installer-root) - -* [Microsoft Edge release schedule](/deployedge/microsoft-edge-release-schedule) +GitHub: +* [Samples repo](https://github.com/MicrosoftEdge/WebView2Samples#webview2-deployment) + +Windows Runtime API: +* [win32dependencies:ExternalDependency (Windows 10, Windows 11)](/uwp/schemas/appxpackage/uapmanifestschema/element-win32dependencies-externaldependency) in the App package manifest docs. + +API Reference: + +##### [.NET/C#](#tab/dotnetcsharp) + +* The `CreationProperties` property on the `WebView2` element: ([WPF](/dotnet/api/microsoft.web.webview2.wpf.webview2.creationproperties)/[WinForms](/dotnet/api/microsoft.web.webview2.winforms.webview2)) +* The `BrowserExecutableFolder` member in the `CoreWebView2CreationProperties` ([WPF](/dotnet/api/microsoft.web.webview2.wpf.corewebview2creationproperties)/[WinForms](/dotnet/api/microsoft.web.webview2.winforms)) +* `EnsureCoreWebView2Async` ([WPF](/dotnet/api/microsoft.web.webview2.wpf.webview2.ensurecorewebview2async)/[WinForms](/dotnet/api/microsoft.web.webview2.winforms.webview2.ensurecorewebview2async)) + +* `CoreWebView2Environment` Class: + * [CoreWebView2Environment.CreateAsync](/dotnet/api/microsoft.web.webview2.core.corewebview2environment.createasync) including the `browserExecutableFolder` parameter. + * [CoreWebView2Environment.NewBrowserVersionAvailable Event](/dotnet/api/microsoft.web.webview2.core.corewebview2environment.newbrowserversionavailable) + +##### [WinRT/C#](#tab/winrtcsharp) + +* `CoreWebView2Environment` Class: + * [NewBrowserVersionAvailable Event](/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2environment#newbrowserversionavailable) + +##### [Win32/C++](#tab/win32cpp) + +* [ICoreWebView2Environment](/microsoft-edge/webview2/reference/win32/icorewebview2environment) + * [add_NewBrowserVersionAvailable](/microsoft-edge/webview2/reference/win32/icorewebview2environment#add_newbrowserversionavailable) + * [remove_NewBrowserVersionAvailable](/microsoft-edge/webview2/reference/win32/icorewebview2environment#remove_newbrowserversionavailable) + +Globals: +* [GetAvailableCoreWebView2BrowserVersionString](/microsoft-edge/webview2/reference/win32/webview2-idl#getavailablecorewebview2browserversionstring) +* [CreateCoreWebView2EnvironmentWithOptions](/microsoft-edge/webview2/reference/win32/webview2-idl#createcorewebview2environmentwithoptions) + +--- diff --git a/microsoft-edge/webview2/concepts/enterprise.md b/microsoft-edge/webview2/concepts/enterprise.md index 2c53be66be..e8df7ef307 100644 --- a/microsoft-edge/webview2/concepts/enterprise.md +++ b/microsoft-edge/webview2/concepts/enterprise.md @@ -46,10 +46,11 @@ Using the Evergreen WebView2 Runtime is recommended, unless business-critical re * Ensures timely security improvements. * Ensures that WebView2 benefits from continuous security updates that are delivered through Microsoft Edge releases. -For information about Evergreen vs. fixed version of the Runtime, see [Distribute your app and the WebView2 Runtime](./distribution.md). - For details about security fixes in Microsoft Edge (which apply to WebView2 as well), see [Release notes for Microsoft Edge Security Updates](/deployedge/microsoft-edge-relnotes-security), in the Microsoft Edge Enterprise documentation. +See also: +* [Evergreen vs. fixed version of the WebView2 Runtime](./evergreen-vs-fixed-version.md) + ###### Rapid Response to Chromium vulnerabilities diff --git a/microsoft-edge/webview2/concepts/environment-controller-core.md b/microsoft-edge/webview2/concepts/environment-controller-core.md index 45630c43be..7de00576ba 100644 --- a/microsoft-edge/webview2/concepts/environment-controller-core.md +++ b/microsoft-edge/webview2/concepts/environment-controller-core.md @@ -18,10 +18,12 @@ ms.date: 06/24/2022 The `CoreWebView2Environment`, `CoreWebView2Controller`, and `CoreWebView2` classes (or equivalent interfaces) work together so your app can host a WebView2 browser control and access its browser features. These three large classes expose a wide range of APIs that your host app can access to provide many categories of browser-related features for your users. * The `CoreWebView2Environment` class represents a group of WebView2 controls that share the same WebView2 browser process, user data folder, and renderer. From this `CoreWebView2Environment` class, you create pairs of `CoreWebView2Controller` and `CoreWebView2` instances. + * The `CoreWebView2Controller` class is responsible for hosting-related functionality such as window focus, visibility, size, and input, where your app hosts the WebView2 control. + * The `CoreWebView2` class is for the web-specific parts of the WebView2 control, including networking, navigation, script, and parsing and rendering HTML. - + ##### [.NET/C#](#tab/dotnetcsharp) @@ -44,10 +46,14 @@ The `CoreWebView2Environment`, `CoreWebView2Controller`, and `CoreWebView2` clas --- -Cross-platform API implementation: Most of the WebView2 APIs are initially developed for C++, and then most of the C++ APIs are wrapped as C# APIs. This way, there is a consistent parallelism and equivalence across platforms and programming languages. + +## Cross-platform API implementation +Most of the WebView2 APIs are initially developed for C++, and then most of the C++ APIs are wrapped as C# APIs. This way, there is a consistent parallelism and equivalence across platforms and programming languages. -#### Overview of the top-level classes + + +## Overview of the top-level classes Overview of: * `CoreWebView2Environment` @@ -69,17 +75,11 @@ From the `CoreWebView2Environment`, you create `CoreWebView2Controller` and `Cor * The `CoreWebView2` is for the web-specific parts of the WebView2 control, including networking, navigation, script, and parsing and rendering HTML. -#### UI framework-specific WebView2 element class such as WPF, WinForms, or WinUI WebView2 classes - -It's different if you are using a UI framework-specific WebView2 element class like our WPF, WinForms, or WinUI WebView2 classes. + +## UI framework-specific WebView2 element class such as WPF, WinForms, or WinUI WebView2 classes -Then, the WebView2 class can optionally take a `CoreWebView2Environment` to use, and otherwise it will create a default `CoreWebView2Environment`. Internally, the WebView2 class creates its `CoreWebView2Controller` and `CoreWebView2` from the `CoreWebView2Environment`. The `WebView2` exposes its `CoreWebView2` as a `CoreWebView2` property, but the `CoreWebView2Controller` is kept private to the `WebView2` class. This is because the `WebView2` class is responsible for connecting all of the `CoreWebView2Controller` functionality to the UI framework. +It's different if you are using a UI framework-specific WebView2 element class such as the WPF, WinForms, or WinUI WebView2 classes. +Then, the WebView2 class can optionally take a `CoreWebView2Environment` to use; otherwise, it creates a default `CoreWebView2Environment`. Internally, the WebView2 class creates its `CoreWebView2Controller` and `CoreWebView2` from the `CoreWebView2Environment`. - - - - +The `WebView2` exposes its `CoreWebView2` as a `CoreWebView2` property, but the `CoreWebView2Controller` is kept private to the `WebView2` class. This is because the `WebView2` class is responsible for connecting all of the `CoreWebView2Controller` functionality to the UI framework. diff --git a/microsoft-edge/webview2/concepts/distribution-images/runtime-distrib-options.png b/microsoft-edge/webview2/concepts/evergreen-vs-fixed-version-images/runtime-distrib-options.png similarity index 100% rename from microsoft-edge/webview2/concepts/distribution-images/runtime-distrib-options.png rename to microsoft-edge/webview2/concepts/evergreen-vs-fixed-version-images/runtime-distrib-options.png diff --git a/microsoft-edge/webview2/concepts/evergreen-vs-fixed-version.md b/microsoft-edge/webview2/concepts/evergreen-vs-fixed-version.md new file mode 100644 index 0000000000..5e97ce8506 --- /dev/null +++ b/microsoft-edge/webview2/concepts/evergreen-vs-fixed-version.md @@ -0,0 +1,114 @@ +--- +title: Evergreen vs. fixed version of the WebView2 Runtime +description: About the Evergreen vs. fixed version of the WebView2 Runtime. +author: MSEdgeTeam +ms.author: msedgedevrel +ms.topic: conceptual +ms.service: microsoft-edge +ms.subservice: webview +ms.date: 10/10/2025 +--- +# Evergreen vs. fixed version of the WebView2 Runtime + +When releasing an app that uses Microsoft Edge WebView2, you need to distribute the WebView2 Runtime, either by distributing the automatically updated _Evergreen_ Runtime, or by distributing a _Fixed Version_ of the Runtime. + +A WebView2 app depends on the WebView2 Runtime on client machines. When you distribute your WebView2 app, you need to take into account how the WebView2 Runtime is distributed to and updated on client machines. + +For details about how to distribute the Runtime, see [Distribute your app and the WebView2 Runtime](./distribution.md). + + + +## The WebView2 Runtime + +The WebView2 Runtime is a redistributable runtime and serves as the underlying (or _backing_) web platform for WebView2 apps. The concept is similar to Visual C++ or the .NET Runtime for C++/.NET apps. The WebView2 Runtime contains modified Microsoft Edge binaries that are fine-tuned and tested for WebView2 apps. After the WebView2 Runtime is installed, it doesn't appear as a user-visible browser app. For example, a user doesn't have a browser desktop shortcut or an entry in the **Start** menu. + +There are two different ways of distributing and updating the WebView2 Runtime to client machines: the Evergreen distribution mode, and the Fixed Version distribution mode. + + + +## The Evergreen Runtime distribution mode + +In the _Evergreen_ distribution mode, the WebView2 Runtime isn't packaged with your app, but is initially installed onto clients using an online bootstrapper or an offline installer. Afterwards, the WebView2 Runtime is automatically updated on client machines. You can then distribute updates of your WebView2 app that use the latest WebView2 APIs, from the latest WebView2 SDK. The Evergreen distribution mode is recommended for most developers. + +Pros: + +* The underlying web platform (WebView2 Runtime) updates automatically without more effort from you. + +* Less disk space is required for the WebView2 Runtime on client systems, because the WebView2 Runtime is shared by all WebView2 apps that are on the client. + +* On eligible systems, binaries for Microsoft Edge and the Evergreen WebView2 Runtime are hard-linked together when they are on the same version. This linking provides benefits for disk footprint, memory, and performance. + +Cons: + +* Your WebView2 app cannot specify that a particular version of the WebView2 Runtime is required. + +See also: +* [The Evergreen Runtime distribution mode](./distribution.md#the-evergreen-runtime-distribution-mode) in _Distribute your app and the WebView2 Runtime_. + + + +#### 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: +* [Windows 11 devices and Windows 10 devices (details)](./distribution.md#windows-11-devices-and-windows-10-devices-details) in _Distribute your app and the WebView2 Runtime_. + + + +## The Fixed Version runtime distribution mode + +In the _Fixed Version_ distribution mode, you download a specific version of the WebView2 Runtime and package it together with your WebView2 app in your app package. The WebView2 Runtime that you package with your app is used only by your WebView2 app, not by any other apps on the client's machine. + +Pros: +* You have more control over versioning of the WebView2 Runtime. You know which WebView2 APIs are available to your app, because you control which version of the WebView2 Runtime is available to your app. Your app doesn't need to test whether the latest APIs are present. + +Cons: + +* You need to manage the WebView2 Runtime yourself. The WebView2 Runtime isn't automatically updated on clients, so to use the latest WebView2 APIs, you must periodically update your app together with the updated WebView2 Runtime. + +* More disk space is required on the client, if there are multiple WebView2 apps installed. + +* The Fixed Version runtime can't be installed by using an installer. + +See also: +* [The Fixed Version runtime distribution mode](./distribution.md#the-fixed-version-runtime-distribution-mode) in _Distribute your app and the WebView2 Runtime_. + + + +## Understanding the options at the Runtime download page + +The [Download the WebView2 Runtime](https://developer.microsoft.com/microsoft-edge/webview2#download-the-webview2-runtime) 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](./evergreen-vs-fixed-version-images/runtime-distrib-options.png) + +The Evergreen distribution mode is recommended for most apps. + +* The **Evergreen Bootstrapper** section of the page provides a small Evergreen Runtime bootstrapper that runs on the client machine, for online users. The bootstrapper downloads and installs the appropriate Evergreen WebView2 Runtime onto the client. You can use the bootstrapper a couple different ways: + + * Link to the bootstrapper, using a link that you obtain from the **Get the Link** button. Your app uses this link to programmatically download the bootstrapper onto the client and invoke the bootstrapper. This approach avoids the need to package the bootstrapper with your app. This approach has a dependency on Microsoft's Content Delivery Network (CDN), to get the bootstrapper. + + * Download the bootstrapper (using the **Download** button in the **Bootstrapper** section) and then distribute the bootstrapper with your app. In this approach, you package the bootstrapper with your app installer/updater or with your app itself, and invoke the bootstrapper that you included with your app. This approach avoids dependency on Microsoft's CDN, to get the bootstrapper. + +* The **Evergreen Standalone Installer** section of the page provides a large, standalone Evergreen installer, primarily for offline users. In this approach, you package the standalone installer with your app installer/updater or app itself, and invoke the Evergreen Standalone installer. This approach avoids dependency on Microsoft's CDN, to get the Runtime. + +* The **Fixed Version** section of the page provides a Fixed Version runtime, which is a specific version of the WebView2 Runtime that you distribute along with your app. + + + +## See also + + +* [Distribute your app and the WebView2 Runtime](./distribution.md) + * [The Evergreen Runtime distribution mode](./distribution.md#the-evergreen-runtime-distribution-mode) in _Distribute your app and the WebView2 Runtime_. + * [The Fixed Version runtime distribution mode](./distribution.md#the-fixed-version-runtime-distribution-mode) in _Distribute your app and the WebView2 Runtime_. + +External: +* [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/) +* [Download the WebView2 Runtime](https://developer.microsoft.com/microsoft-edge/webview2#download-the-webview2-runtime) section of the **Microsoft Edge WebView2** page +* [Microsoft Edge release schedule](/deployedge/microsoft-edge-release-schedule) diff --git a/microsoft-edge/webview2/concepts/overview-features-apis.md b/microsoft-edge/webview2/concepts/overview-features-apis.md index d7dbff982d..8ece0c1013 100644 --- a/microsoft-edge/webview2/concepts/overview-features-apis.md +++ b/microsoft-edge/webview2/concepts/overview-features-apis.md @@ -138,10 +138,12 @@ This page only lists APIs that are in Release SDKs; it doesn't list Experimental The `CoreWebView2Environment`, `CoreWebView2Controller`, and `CoreWebView2` classes (or equivalent interfaces) work together so your app can host a WebView2 browser control and access its browser features. These three large classes expose a wide range of APIs that your host app can access to provide many categories of browser-related features for your users. * The `CoreWebView2Environment` class represents a group of WebView2 controls that share the same WebView2 browser process, user data folder, and renderer processes. From this `CoreWebView2Environment` class, you create pairs of `CoreWebView2Controller` and `CoreWebView2` instances. + * The `CoreWebView2Controller` class is responsible for hosting-related functionality such as window focus, visibility, size, and input, where your app hosts the WebView2 control. + * The `CoreWebView2` class is for the web-specific parts of the WebView2 control, including networking, navigation, script, and parsing and rendering HTML. - + See also: * [Main classes for WebView2: Environment, Controller, and Core](environment-controller-core.md) diff --git a/microsoft-edge/webview2/concepts/versioning.md b/microsoft-edge/webview2/concepts/versioning.md index 0e5b8af26c..b226c52aa8 100644 --- a/microsoft-edge/webview2/concepts/versioning.md +++ b/microsoft-edge/webview2/concepts/versioning.md @@ -66,6 +66,7 @@ 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: +* [Evergreen vs. fixed version of the WebView2 Runtime](./evergreen-vs-fixed-version.md) * [Prerelease testing using preview channels](../how-to/prerelease-testing.md) * [Self-host by deploying preview channels](../how-to/self-hosting.md) @@ -75,13 +76,14 @@ See also: 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. +The Release SDK package contains all of the Stable 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. -The Release SDK package contains the following components: -* [Win32 C/C++ APIs](/microsoft-edge/webview2/reference/win32). -* .NET APIs: [WPF](/dotnet/api/microsoft.web.webview2.wpf), [WinForms](/dotnet/api/microsoft.web.webview2.winforms), and [Core](/dotnet/api/microsoft.web.webview2.core). +See also: +* [WebView2 API Reference](../webview2-api-reference.md) -For more information about automatic updating of the Evergreen Runtime, see [Distribute your app and the WebView2 Runtime](distribution.md). +For more information about automatic updating of the Evergreen Runtime, see: +* [Evergreen vs. fixed version of the WebView2 Runtime](./evergreen-vs-fixed-version.md) +* [Distribute your app and the WebView2 Runtime](./distribution.md) @@ -143,6 +145,9 @@ The WebView2 team is seeking feedback on Experimental WebView2 APIs that might b To help you evaluate the Experimental APIs and share your feedback, use the [WebView2Feedback](https://github.com/MicrosoftEdge/WebViewFeedback) repo. +See also: +* [Evergreen vs. fixed version of the WebView2 Runtime](./evergreen-vs-fixed-version.md) + #### Moving from Experimental APIs to Stable APIs @@ -163,7 +168,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, see [Download the WebView2 Runtime](https://developer.microsoft.com/microsoft-edge/webview2#download-the-webview2-runtime) in the _Microsoft Edge WebView2_ page at developer.microsoft.com. The minimum required Runtime version to support the General Availability release of the SDK (build 616) is older than for the latest Runtime. The latest Runtime supports all APIs that are in the latest Release SDK. 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). @@ -171,22 +176,57 @@ To check the compatibility between specific build numbers of the SDK and the Run ## Feature-detecting to test whether the installed Runtime supports recently added APIs +If your app uses the Evergreen Runtime rather than Fixed Version, you should wrap any calls to relatively new WebView2 APIs by using `QueryInterface` or `try-catch`. There are edge cases where a client's Evergreen Runtime isn't the latest build and therefore falls behind the SDK build number, because the Admin might have temporarily suppressed updating of the WebView2 Runtime, or the client might be offline. + +When you develop a WebView2 app using a recent version of the WebView2 SDK, if you use a recently added API, you should test or "feature-detect" whether that API is present in the client's installed WebView2 Runtime. How your app programmatically tests for API support depends on the coding platform: + + + +#### .NET and WinUI, and WinRT + +Use `try/catch` and check for a `No such interface supported` exception when using methods, properties, and events that were added to more recent versions of the WebView2 SDK. This exception likely indicates that the client's WebView2 Runtime is an older version that doesn't support that API. + -If your app uses the Evergreen Runtime rather than Fixed Version, you should wrap any calls to relatively new WebView2 APIs by using `QueryInterface` or `try-catch`. There are edge cases where a client's Evergreen Runtime isn't the latest build and therefore falls behind the SDK build number, because the Admin might have turned off updating of the WebView2 Runtime, or the client might be offline. + +#### Win32 C/C++ -When you develop a WebView2 app using a recent version of the WebView2 SDK, if you use a recently added API, you should test or "feature-detect" whether that API is present in the client's installed WebView2 Runtime. How your app programmatically tests for API support depends on the coding platform. +When requesting the DLL export `CreateCoreWebView2Environment` and when running `QueryInterface` on any `CoreWebView2` object, test for a return value of `E_NOINTERFACE`. That return value likely indicates that the client's WebView2 Runtime is an older version that doesn't support that interface. -* **Win32 C/C++**. When requesting the DLL export `CreateCoreWebView2Environment` and when running `QueryInterface` on any `CoreWebView2` object, test for a return value of `E_NOINTERFACE`. That return value likely indicates that the client's WebView2 Runtime is an older version that doesn't support that interface. +For an example of checking for the existence of specific WebView2 APIs in the Runtime, find `try_query` in [AppWindow.cpp](https://github.com/MicrosoftEdge/WebView2Samples/blob/8ec7de9d3e80a942bc7025cffad98eee75e11e64/SampleApps/WebView2APISample/AppWindow.cpp#L622). This file wraps WebView2 API calls in the `CHECK_FAILURE` macro function, defined in `CheckFailure.h`. - For an example of checking for the existence of specific WebView2 APIs in the Runtime, find `try_query` in [AppWindow.cpp](https://github.com/MicrosoftEdge/WebView2Samples/blob/8ec7de9d3e80a942bc7025cffad98eee75e11e64/SampleApps/WebView2APISample/AppWindow.cpp#L622). This file wraps WebView2 API calls in the `CHECK_FAILURE` macro function, defined in `CheckFailure.h`. -* **.NET and WinUI**. Use `try/catch` and check for a `No such interface supported` exception when using methods, properties, and events that were added to more recent versions of the WebView2 SDK. This exception likely indicates that the client's WebView2 Runtime is an older version that doesn't support that API. + +#### Provide graceful fallback If your code determines that an API is unavailable in the client's installed WebView2 Runtime, you should provide graceful fallback for the associated feature, or inform the user that they must update the WebView2 Runtime to use the feature. ## See also - - -* [Microsoft Edge release schedule](/deployedge/microsoft-edge-release-schedule) + + + +* [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_. +* [Evergreen vs. fixed version of the WebView2 Runtime](./evergreen-vs-fixed-version.md) +* [Distribute your app and the WebView2 Runtime](./distribution.md) +* [Test upcoming APIs and features](../how-to/set-preview-channel.md) +* [Prerelease testing using preview channels](../how-to/prerelease-testing.md) +* [Self-host by deploying preview channels](../how-to/self-hosting.md) +* [Phases of adding APIs](../release-notes/about.md#phases-of-adding-apis) in _About Release Notes for the WebView2 SDK_. +* [Release Notes for the WebView2 SDK](../release-notes/index.md) +* [WebView2 API Reference](../webview2-api-reference.md) + + +Microsoft Edge Enterprise documentation: +* [Microsoft Edge release schedule](/deployedge/microsoft-edge-release-schedule) + +Downloads: +* [Microsoft.Web.WebView2](https://www.nuget.org/packages/Microsoft.Web.WebView2) - SDK. +* [Download the WebView2 Runtime](https://developer.microsoft.com/microsoft-edge/webview2#download-the-webview2-runtime) + +GitHub: +* [WebView2Feedback](https://github.com/MicrosoftEdge/WebViewFeedback) repo. + diff --git a/microsoft-edge/webview2/landing/index.yml b/microsoft-edge/webview2/landing/index.yml index e3ac9024b9..3365dbb5e5 100644 --- a/microsoft-edge/webview2/landing/index.yml +++ b/microsoft-edge/webview2/landing/index.yml @@ -242,6 +242,9 @@ landingContent: - text: Prerelease and Release SDKs for WebView2 url: ../concepts/versioning.md + - text: Evergreen vs. fixed version of the WebView2 Runtime + url: ../concepts/evergreen-vs-fixed-version.md + - text: Distribute your app and the WebView2 Runtime url: ../concepts/distribution.md diff --git a/microsoft-edge/webview2/release-notes/about.md b/microsoft-edge/webview2/release-notes/about.md index 80cc7907ff..222114280b 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, see [Download the WebView2 Runtime](https://developer.microsoft.com/microsoft-edge/webview2#download-the-webview2-runtime) in the _Microsoft Edge WebView2_ page at developer.microsoft.com. * To 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/release-notes/archive.md b/microsoft-edge/webview2/release-notes/archive.md index c08a7532fc..cc2bd042aa 100644 --- a/microsoft-edge/webview2/release-notes/archive.md +++ b/microsoft-edge/webview2/release-notes/archive.md @@ -3675,7 +3675,7 @@ For full API compatibility, this Release version of the WebView2 SDK requires We #### Breaking changes > [!IMPORTANT] -> **Breaking Change**: If you're developing an unpackaged Win32 app using Fixed Version Runtime v120 or above and targeting Windows 10 devices, you need to run a couple of ACL shell commands (`icacls`), to avoid crashing, because of a new security feature implemented in WebView2. See [[Breaking Change] Unpackaged Win32 app using Fixed Version v120+ on Win10 need ACL](https://github.com/MicrosoftEdge/WebView2Announcements/issues/82). The fix is in the article _Distribute your app and the WebView2 Runtime_, section [Details about the Fixed Version runtime distribution mode](../concepts/distribution.md#details-about-the-fixed-version-runtime-distribution-mode), step "On Windows 10 devices, starting with Fixed Version 120, developers of unpackaged Win32 applications using Fixed Version are required to run the following commands." +> **Breaking Change**: If you're developing an unpackaged Win32 app using Fixed Version Runtime v120 or above and targeting Windows 10 devices, you need to run a couple of ACL shell commands (`icacls`), to avoid crashing, because of a new security feature implemented in WebView2. See [[Breaking Change] Unpackaged Win32 app using Fixed Version v120+ on Win10 need ACL](https://github.com/MicrosoftEdge/WebView2Announcements/issues/82). The fix is in the article _Distribute your app and the WebView2 Runtime_, section [The Fixed Version runtime distribution mode](../concepts/distribution.md#the-fixed-version-runtime-distribution-mode), step "On Windows 10 devices, starting with Fixed Version 120, developers of unpackaged Win32 applications using Fixed Version are required to run the following commands."