Skip to content

Commit

Permalink
Merge pull request #3053 from MicrosoftDocs/user/mikehoffms/prereleas…
Browse files Browse the repository at this point in the history 
…e-testing-self-hosting

Add articles "Prerelease testing" & "Self-hosting", use new API
  • Loading branch information
@captainbrosset
captainbrosset authored Apr 25, 2024
2 parents 0547542 + 7798b65 commit 36272b6
Show file tree
Hide file tree
Showing 16 changed files with 550 additions and 186 deletions.
24 changes: 17 additions & 7 deletions microsoft-edge/toc.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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:
Expand Down
6 changes: 4 additions & 2 deletions microsoft-edge/webview2/concepts/developer-guide.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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).


<!-- ====================================================================== -->
Expand Down
31 changes: 23 additions & 8 deletions microsoft-edge/webview2/concepts/distribution.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,7 @@ Cons:


<!-- ------------------------------ -->
#### Windows 11 devices and Windows 10 devices
<!-- #### Which devices already have WebView2 Runtime installed and how to distribute for edge cases -->

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.
Expand Down Expand Up @@ -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.

Expand All @@ -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:
Expand All @@ -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:
Expand Down Expand Up @@ -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)
<!-- #### Evergreen WebView2 Runtime is preinstalled on Win11 devices and most Win10 devices -->

The vast majority of Windows 10 devices have the WebView2 Runtime installed already, as described in [Delivering Microsoft Edge WebView2 Runtime to managed Windows 10 devices](https://blogs.windows.com/msedgedev/2022/12/14/delivering-microsoft-edge-webview2-runtime-to-managed-windows-10-devices/). A small number of Windows 10 devices don't have the WebView2 Runtime installed. We recommend that you handle this edge case, by using either of the following approaches:
Expand All @@ -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.
Expand All @@ -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.<!-- (instead of using the Evergreen Bootstrapper, Evergreen Standalone Installer, or Fixed Version (Self-Contained) distribution).--> 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.
Expand All @@ -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:
Expand All @@ -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.
Expand Down Expand Up @@ -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.

Expand All @@ -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

<!-- the main section about QueryInterface is in versioning.md, so limit this section to a couple paragraphs -->
Expand Down Expand Up @@ -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.
Expand Down
10 changes: 7 additions & 3 deletions microsoft-edge/webview2/concepts/versioning.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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.

Expand Down
14 changes: 4 additions & 10 deletions microsoft-edge/webview2/get-started/winui.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

<!--
Or, install the WebView2 Runtime, as follows:
1. In a new window or tab, see [Install the WebView2 Runtime](../how-to/machine-setup.md#install-the-webview2-runtime) in _Set up your Dev environment for WebView2_.
Return here and continue with the steps below.
-->
Then continue with the steps below.


<!-- ====================================================================== -->
Expand Down
Loading

0 comments on commit 36272b6

Please sign in to comment.