Skip to content

Commit 1c057e8

Browse files
authored
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
1 parent c9773fa commit 1c057e8

File tree

13 files changed

+341
-142
lines changed

13 files changed

+341
-142
lines changed

microsoft-edge/toc.yml

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1573,6 +1573,9 @@
15731573
href: ./webview2/concepts/versioning.md
15741574
displayName: experimental APIs, Understand WebView2 SDK versions, Understand the different WebView2 SDK versions # old titles
15751575

1576+
- name: Evergreen vs. fixed version of the WebView2 Runtime
1577+
href: ./webview2/concepts/evergreen-vs-fixed-version.md
1578+
15761579
- name: Distribute your app and the WebView2 Runtime
15771580
href: ./webview2/concepts/distribution.md
15781581

microsoft-edge/webview2/concepts/data-privacy.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ ms.date: 06/02/2023
1010
---
1111
# Data and privacy in WebView2
1212

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

1515
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).
1616

microsoft-edge/webview2/concepts/developer-guide.md

Lines changed: 62 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ We recommend using the Evergreen WebView2 Runtime for most WebView2 apps, rather
2020

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

23-
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_.
23+
See [Evergreen vs. fixed version of the WebView2 Runtime](./evergreen-vs-fixed-version.md).
2424

2525
To help ensure that your WebView2 app works well with the Evergreen WebView2 Runtime, use the recommended practices in the subsections below:
2626
* [Check to make sure the WebView2 Runtime is installed](#check-to-make-sure-the-webview2-runtime-is-installed).
@@ -34,15 +34,15 @@ To help ensure that your WebView2 app works well with the Evergreen WebView2 Run
3434

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

37-
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_.
37+
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_.
3838

3939

4040
<!-- ------------------------------ -->
4141
#### Handle updates of the WebView2 Runtime
4242

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

45-
See [Handle Evergreen WebView2 Runtime updates](../concepts/distribution.md#handle-evergreen-webview2-runtime-updates) in _Distribute your app and the WebView2 Runtime_.
45+
See [Handle Evergreen WebView2 Runtime updates](./distribution.md#handle-evergreen-webview2-runtime-updates) in _Distribute your app and the WebView2 Runtime_.
4646

4747

4848
<!-- ------------------------------ -->
@@ -62,37 +62,57 @@ When using the Evergreen WebView2 Runtime, use feature detection to test whether
6262

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

65-
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_.
65+
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_.
6666

6767

6868
<!-- ====================================================================== -->
6969
## Update regularly if using the Fixed Version Runtime
7070

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

73-
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_.
73+
See:
74+
* [Evergreen vs. fixed version of the WebView2 Runtime](./evergreen-vs-fixed-version.md)
75+
* [The Fixed Version runtime distribution mode](./distribution.md#the-fixed-version-runtime-distribution-mode) in _Distribute your app and the WebView2 Runtime_.
7476

7577

7678
<!-- ====================================================================== -->
7779
## Manage the lifetime of the user data folder
7880

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

81-
See [Manage user data folders](../concepts/user-data-folder.md) for further guidance on managing the user data folder.
83+
See:
84+
* [Manage user data folders](./user-data-folder.md)
8285

8386

8487
<!-- ====================================================================== -->
8588
## Handle runtime-process failures or exits
8689

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

89-
See [Handling process-related events in WebView2](../concepts/process-related-events.md).
92+
See [Handling process-related events in WebView2](./process-related-events.md).
9093

9194

9295
<!-- ====================================================================== -->
9396
## Event handlers on the environment object
9497

95-
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.
98+
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.
99+
100+
##### [.NET/C#](#tab/dotnetcsharp)
101+
102+
* [CoreWebView2Environment](/dotnet/api/microsoft.web.webview2.core.corewebview2environment)
103+
* [CoreWebView2Environment.CreateAsync Method](/dotnet/api/microsoft.web.webview2.core.corewebview2environment.createasync)
104+
105+
##### [WinRT/C#](#tab/winrtcsharp)
106+
107+
* [CoreWebView2Environment](/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2environment)
108+
* [CoreWebView2Environment.CreateAsync Method](/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2environment)
109+
110+
##### [Win32/C++](#tab/win32cpp)
111+
112+
* [ICoreWebView2Environment](/microsoft-edge/webview2/reference/win32/icorewebview2environment)
113+
* [CreateCoreWebView2Environment](/microsoft-edge/webview2/reference/win32/webview2-idl#createcorewebview2environment) in _Globals_.<!-- the original lone link instead of this tabset -->
114+
115+
---
96116

97117
To prevent such a memory leak:
98118

@@ -110,12 +130,42 @@ WebView2 enables you to host web content in your native applications, providing
110130

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

113-
Follow the guidance in [Develop secure WebView2 apps](../concepts/security.md).
133+
Follow the guidance in [Develop secure WebView2 apps](./security.md).
114134

115135

116136
<!-- ====================================================================== -->
117137
## See also
118-
<!-- todo: all links in article body -->
138+
<!-- all links in article body -->
139+
140+
<!-- toc order -->
141+
* [Handling process-related events in WebView2](./process-related-events.md)<!-- bucket 3 -->
142+
* [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_.<!-- bucket 6 -->
143+
* [Evergreen vs. fixed version of the WebView2 Runtime](./evergreen-vs-fixed-version.md)<!-- bucket 6 middle -->
144+
* [Distribute your app and the WebView2 Runtime](./distribution.md)<!-- link not in article --><!-- bucket 6 middle -->
145+
* [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_.
146+
* [The Fixed Version runtime distribution mode](./distribution.md#the-fixed-version-runtime-distribution-mode) in _Distribute your app and the WebView2 Runtime_.
147+
* [Handle Evergreen WebView2 Runtime updates](./distribution.md#handle-evergreen-webview2-runtime-updates) in _Distribute your app and the WebView2 Runtime_.
148+
* [Develop secure WebView2 apps](./security.md)<!-- bucket 7 -->
149+
* [Prerelease testing using preview channels](../how-to/prerelease-testing.md)<!-- bucket 8 bottom -->
150+
* [Self-host by deploying preview channels](../how-to/self-hosting.md)<!-- bucket 8 very bottom -->
151+
* [Manage user data folders](./user-data-folder.md)<!-- bucket 11 -->
152+
153+
WebView2 Reference:
154+
155+
##### [.NET/C#](#tab/dotnetcsharp)
156+
157+
* [CoreWebView2Environment](/dotnet/api/microsoft.web.webview2.core.corewebview2environment)
158+
159+
##### [WinRT/C#](#tab/winrtcsharp)
160+
161+
* [CoreWebView2Environment](/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2environment)
162+
163+
##### [Win32/C++](#tab/win32cpp)
164+
165+
* [ICoreWebView2Environment](/microsoft-edge/webview2/reference/win32/icorewebview2environment)
166+
* [CreateCoreWebView2Environment](/microsoft-edge/webview2/reference/win32/webview2-idl#createcorewebview2environment) in _Globals_.
167+
168+
---
119169

120-
<!-- External: -->
121-
* [Microsoft Edge release schedule](/deployedge/microsoft-edge-release-schedule)
170+
Microsoft Edge Enterprise documentation:
171+
* [Microsoft Edge release schedule](/deployedge/microsoft-edge-release-schedule)<!-- link not in article body -->

0 commit comments

Comments
 (0)