From e1c1f196e2190fde9bfa786b607aff934c3f30be Mon Sep 17 00:00:00 2001 From: Michael Hoffman <45407486+mikehoffms@users.noreply.github.com> Date: Tue, 18 Aug 2026 12:24:23 -0700 Subject: [PATCH 01/28] Update enterprise.md --- .../webview2/concepts/enterprise.md | 27 ++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/microsoft-edge/webview2/concepts/enterprise.md b/microsoft-edge/webview2/concepts/enterprise.md index 4f33d5e009..dddf993e10 100644 --- a/microsoft-edge/webview2/concepts/enterprise.md +++ b/microsoft-edge/webview2/concepts/enterprise.md @@ -6,15 +6,30 @@ ms.author: msedgedevrel ms.topic: article ms.service: microsoft-edge ms.subservice: webview -ms.date: 11/12/2021 +ms.date: 08/18/2026 --- # Enterprise management of WebView2 Runtimes + This article discusses how IT admins can manage WebView2 applications and the WebView2 Runtime. A developer can integrate the WebView2 component into their app, and then deploy the self-updating Evergreen WebView2 Runtime (along with the app) onto user devices, to power the latest WebView2 features of the app and get the latest security improvements. Feedback from IT admins and developers is welcome, through the [WebView2Feedback](https://github.com/MicrosoftEdge/WebViewFeedback) repo. +**Detailed contents:** +* [Group policies for WebView2](#group-policies-for-webview2) + * [Update policies](#update-policies) + * [Suppressing WebView2 Runtime updates](#suppressing-webview2-runtime-updates) + * [Enterprise management of WebView2 Runtimes](#enterprise-management-of-webview2-runtimes) + * [Evergreen Runtime is recommended, rather than a fixed version](#evergreen-runtime-is-recommended-rather-than-a-fixed-version) + * [Rapid Response to Chromium vulnerabilities](#rapid-response-to-chromium-vulnerabilities) + * [Microsoft Edge Lifecycle Policy](#microsoft-edge-lifecycle-policy) + * [Browser policies](#browser-policies) + * [WebView2-specific policies](#webview2-specific-policies) +* [Windows Server Update Services (WSUS)](#windows-server-update-services-wsus) + * [WebView2 deployment and update using Configuration Manager](#webview2-deployment-and-update-using-configuration-manager) +* [See also](#see-also) + ## Group policies for WebView2 @@ -38,6 +53,16 @@ An IT admin can suppress updating of the WebView2 Runtime, if auto-updating need However, users should not stop updating their WebView2 Runtime; users should not remain on an older version of the WebView2 Runtime. Using older versions of the WebView2 Runtime isn't recommended. Security updates and servicing updates are only available on the latest Stable channel release (Edge Stable) and the latest Beta channel release (Edge Beta). If you use older releases of the Microsoft WebView2 Runtime, you won't receive the latest quality and security updates. + +###### Enterprise downgrade of Runtime to previous version + +With the WebView2 152 release, the Enterprise Downgrade feature is generally available. + +Enterprise Downgrade is a temporary, IT admin-controlled capability that allows a specific WebView2 application to revert to a previous runtime version in the event of a critical regression. + +See [WebView2 Enterprise Downgrade Guide] (todo). + + ###### Evergreen Runtime is recommended, rather than a fixed version From 7c35503754ff49907ea3585ae4825f935015b960 Mon Sep 17 00:00:00 2001 From: Michael Hoffman <45407486+mikehoffms@users.noreply.github.com> Date: Tue, 18 Aug 2026 12:26:54 -0700 Subject: [PATCH 02/28] fix local toc --- microsoft-edge/webview2/concepts/enterprise.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/microsoft-edge/webview2/concepts/enterprise.md b/microsoft-edge/webview2/concepts/enterprise.md index dddf993e10..b703b50fe6 100644 --- a/microsoft-edge/webview2/concepts/enterprise.md +++ b/microsoft-edge/webview2/concepts/enterprise.md @@ -20,7 +20,7 @@ Feedback from IT admins and developers is welcome, through the [WebView2Feedback * [Group policies for WebView2](#group-policies-for-webview2) * [Update policies](#update-policies) * [Suppressing WebView2 Runtime updates](#suppressing-webview2-runtime-updates) - * [Enterprise management of WebView2 Runtimes](#enterprise-management-of-webview2-runtimes) + * [Enterprise downgrade of Runtime to previous version](#enterprise-downgrade-of-runtime-to-previous-version) * [Evergreen Runtime is recommended, rather than a fixed version](#evergreen-runtime-is-recommended-rather-than-a-fixed-version) * [Rapid Response to Chromium vulnerabilities](#rapid-response-to-chromium-vulnerabilities) * [Microsoft Edge Lifecycle Policy](#microsoft-edge-lifecycle-policy) From cde7e376414e6bc71eb376dcf7ae6a3bc83a16a4 Mon Sep 17 00:00:00 2001 From: Michael Hoffman <45407486+mikehoffms@users.noreply.github.com> Date: Tue, 18 Aug 2026 12:27:27 -0700 Subject: [PATCH 03/28] fix levels in local toc --- microsoft-edge/webview2/concepts/enterprise.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/microsoft-edge/webview2/concepts/enterprise.md b/microsoft-edge/webview2/concepts/enterprise.md index b703b50fe6..d6fed51574 100644 --- a/microsoft-edge/webview2/concepts/enterprise.md +++ b/microsoft-edge/webview2/concepts/enterprise.md @@ -20,10 +20,10 @@ Feedback from IT admins and developers is welcome, through the [WebView2Feedback * [Group policies for WebView2](#group-policies-for-webview2) * [Update policies](#update-policies) * [Suppressing WebView2 Runtime updates](#suppressing-webview2-runtime-updates) - * [Enterprise downgrade of Runtime to previous version](#enterprise-downgrade-of-runtime-to-previous-version) - * [Evergreen Runtime is recommended, rather than a fixed version](#evergreen-runtime-is-recommended-rather-than-a-fixed-version) - * [Rapid Response to Chromium vulnerabilities](#rapid-response-to-chromium-vulnerabilities) - * [Microsoft Edge Lifecycle Policy](#microsoft-edge-lifecycle-policy) + * [Enterprise downgrade of Runtime to previous version](#enterprise-downgrade-of-runtime-to-previous-version) + * [Evergreen Runtime is recommended, rather than a fixed version](#evergreen-runtime-is-recommended-rather-than-a-fixed-version) + * [Rapid Response to Chromium vulnerabilities](#rapid-response-to-chromium-vulnerabilities) + * [Microsoft Edge Lifecycle Policy](#microsoft-edge-lifecycle-policy) * [Browser policies](#browser-policies) * [WebView2-specific policies](#webview2-specific-policies) * [Windows Server Update Services (WSUS)](#windows-server-update-services-wsus) From f5d956e3bb95fa7c046fd05fb8fea83ac9ca30d1 Mon Sep 17 00:00:00 2001 From: Michael Hoffman <45407486+mikehoffms@users.noreply.github.com> Date: Wed, 19 Aug 2026 12:02:24 -0700 Subject: [PATCH 04/28] copy of draft doc --- microsoft-edge/toc.yml | 3 + .../webview2/how-to/enterprise-downgrade.md | 489 ++++++++++++++++++ 2 files changed, 492 insertions(+) create mode 100644 microsoft-edge/webview2/how-to/enterprise-downgrade.md diff --git a/microsoft-edge/toc.yml b/microsoft-edge/toc.yml index e391b10cc7..53f92dd080 100644 --- a/microsoft-edge/toc.yml +++ b/microsoft-edge/toc.yml @@ -2360,6 +2360,9 @@ href: ./webview2/concepts/enterprise.md displayName: Manage WebView2 applications # old title + - name: WebView2 Enterprise Downgrade Guide + href: ./webview2/how-to/enterprise-downgrade.md + - name: Distribute an app as a single executable file href: ./webview2/how-to/static.md displayName: Statically link the WebView2 loader library, single-file app # old title diff --git a/microsoft-edge/webview2/how-to/enterprise-downgrade.md b/microsoft-edge/webview2/how-to/enterprise-downgrade.md new file mode 100644 index 0000000000..2ea4842995 --- /dev/null +++ b/microsoft-edge/webview2/how-to/enterprise-downgrade.md @@ -0,0 +1,489 @@ +--- +title: WebView2 Enterprise Downgrade Guide +description: WebView2 Enterprise Downgrade Guide. +author: MSEdgeTeam +ms.author: msedgedevrel +ms.topic: article +ms.service: microsoft-edge +ms.subservice: webview +ms.date: 08/19/2026 +--- +# WebView2 Enterprise Downgrade Guide + +**Detailed contents:** +* [1. What Is Enterprise Downgrade?](#1-what-is-enterprise-downgrade) + * [Background](#background) + * [What Enterprise Downgrade Solves](#what-enterprise-downgrade-solves) + * [Why It Exists](#why-it-exists) + * [Applicable Applications](#applicable-applications) + * [Policy Configuration & Precedence](#policy-configuration--precedence) + * [Core Design Principles](#core-design-principles) +* [2. How to Downgrade — Steps](#2-how-to-downgrade--steps) + * [Option 1: Group Policy (GPO) — Recommended for Enterprise](#option-1-group-policy-gpo--recommended-for-enterprise) + * [Option 2: Registry Editor (regedit)](#option-2-registry-editor-regedit) + * [Important Notes](#important-notes) + * [Process Flow (How It Works Under the Hood)](#process-flow-how-it-works-under-the-hood) +* [3. Limitations of Downgrade](#3-limitations-of-downgrade) + * [Version Limitations](#version-limitations) + * [Scope Limitations](#scope-limitations) + * [Shared User Data Folder (UDF) Constraints](#shared-user-data-folder-udf-constraints) +* [4. Risks Associated with Downgrade](#4-risks-associated-with-downgrade) + * [Security Risks](#security-risks) + * [Data Integrity Risks](#data-integrity-risks) + * [Application Compatibility Risks](#application-compatibility-risks) + * [Operational Risks](#operational-risks) +* [5. Testing & Troubleshooting](#5-testing--troubleshooting) + * [Verifying Downgrade Applied](#verifying-downgrade-applied) + * [1. Check the versioned folder](#1-check-the-versioned-folder) + * [2. Check registry policy](#2-check-registry-policy) + * [3. Check BrowserExecutableFolder redirect](#3-check-browserexecutablefolder-redirect) + * [Triggering a Force Update](#triggering-a-force-update) + * [Diagnostics Tools (For Deeper Troubleshooting)](#diagnostics-tools-for-deeper-troubleshooting) + * [Common Issues & Resolution](#common-issues--resolution) +* [6. How to Revert from Downgrade](#6-how-to-revert-from-downgrade) + * [Option 1: Disable Group Policy (Recommended)](#option-1-disable-group-policy-recommended) + * [Option 2: Remove Policy via Registry](#option-2-remove-policy-via-registry) + * [Option 3: Automatic Expiry](#option-3-automatic-expiry) + * [Post-Revert Behavior](#post-revert-behavior) +* [7. Escalation & Contact](#7-escalation--contact) + +Policy Documentation: [DowngradeVersion](https://learn.microsoft.com/en-us/deployedge/microsoft-edge-webview-policies#downgradeversion) in _Microsoft Edge WebView2 - Policies_. + + + +## 1. What Is Enterprise Downgrade? + + + +#### Background + +**WebView2** is a browser control that allows Windows applications (such as Microsoft Teams, Outlook, and third-party enterprise software) to embed web content using the Microsoft Edge rendering engine. The **Evergreen** distribution model means the WebView2 runtime updates automatically alongside Edge — applications always run on the latest version without manual intervention. + +While Evergreen ensures applications get security patches and feature improvements automatically, it also means that if a new runtime version introduces a regression, each application and Windows component that uses them is likely to be impacted. Although enterprise administrators cannot uninstall the impacting update, Enterprise Downgrade offers a short-term mitigation approach to restore impacted productivity. + + + +#### What Enterprise Downgrade Solves + +The **DowngradeVersion** policy is a controlled version downgrade capability that allows enterprise IT administrators to temporarily revert specific WebView2 applications to a previous runtime version via Group Policy when a critical regression disrupts business operations. + +How it works at a high level: + +1. Admin identifies that a new WebView2 version has broken a specific application + +2. Admin sets a Group Policy specifying: "For this application, use version X instead of the latest". (Note: Only N-1 or N-2 relative to the current Evergreen version is supported. Downgrades to versions beyond N-2 are rejected.) + +3. The Edge Updater downloads and installs the older version **side-by-side** with the current one + +4. The WebView2 Loader redirects only the targeted application to the older runtime + +5. All other applications on the device continue using the latest version unaffected + +6. The downgrade automatically expires once the pinned version is no longer within the two most recent previous versions + + + +#### Why It Exists + +In mission-critical enterprise environments, for e.g. healthcare systems, financial trading platforms, retail point-of-sale, government services, unexpected regressions in the WebView2 runtime can halt business workflows with no immediate remedy. Even brief outages result in lost revenue, missed SLAs, and increased operational costs. + +Enterprise Downgrade provides a **temporary, admin-controlled version downgrade** for the specific application affected, while the platform team prepares a proper fix. + +🔑 Key Principle: Downgrade is a last-resort recovery tool — targeted, time-bound, and managed by enterprise admins in partnership with application owners. It is not a version-pinning mechanism. + + + +#### Applicable Applications + +Enterprise Downgrade does **not** automatically affect any application. It is a policy that an IT administrator must explicitly configure for specific applications. Only then does it apply. + +**Which apps can be targeted:** + +* Any WebView2 Evergreen application running on enterprise-managed Windows devices + +* The admin specifies the target by **executable** name (e.g., `teams.exe`) or **AUMID** (Application User Model ID, for packaged/MSIX apps) + +* If both an AUMID and exe name entry exist for the same application, the AUMID entry takes precedence + +**Which apps are NOT affected:** + +* Applications not named in the policy continue the latest Evergreen runtime + +* Consumer/unmanaged devices are entirely out of scope + +* App-bundled (Fixed Version) WebView2 runtimes are out of scope + + + +#### Policy Configuration & Precedence + + +| Location | Path | +|---|---| +| **Group Policy (recommended)** | Computer Configuration > Administrative Templates > Microsoft Edge WebView2 > Configure per-application WebView2 downgrade version | +| **Registry** | `HKLM\Software\Policies\Microsoft\Edge\WebView2\DowngradeVersion` | + +📄 Note: HKCU is not supported — this is a machine-level enterprise policy only. + +**Precedence when multiple policies exist (highest to lowest):** + +1. **DowngradeVersion policy** — always wins + +2. **BrowserExecutableFolder** — if set independently by the admin + +3. **Default Evergreen runtime** — lowest + +If both DowngradeVersion and BrowserExecutableFolder are independently configured, DowngradeVersion takes precedence and overrides the BrowserExecutableFolder redirect. + + + +#### Core Design Principles + +* **Enterprise IT Admin Driven:** Only IT administrators can initiate downgrade via Group Policy. Developers and end users cannot trigger it. + +* **Updater Service Compliance:** The Edge Updater downloads the required version if needed and continues normal updates for all other apps. + +* **Automatic Expiry:** A downgraded version remains valid only as long as it is within the two most recent previous versions (N-1 or N-2). Once two subsequent new major versions release beyond the downgraded version, the downgrade expires and the app automatically reverts to the latest runtime. Microsoft recommends admins to remove the stale policies once it auto-expires. + +* **Per-App Targeting:** Downgrade is applied per-application, not device-wide. Each application must be individually specified. + + + +## 2. How to Downgrade — Steps + + + +#### Option 1: Group Policy (GPO) — Recommended for Enterprise + +This is the recommended approach for enterprise environments. Group Policy ensures centralized, auditable management across managed devices. + +1. Open Group Policy Editor (`gpedit.msc`) + +2. Navigate to: **Computer Configuration > Administrative Templates > Microsoft Edge WebView2** + +3. Find "**Configure per-application WebView2 downgrade version**" + +4. Enable the policy and add entries: + + * **Name:** Application identifier (AUMID or exe name, e.g., `teams.exe`) + + * **Value:** Target four part version number (e.g., `145`) + + + +#### Option 2: Registry Editor (regedit) + +For targeted configuration on individual machines. Requires local administrator privileges. + +1. Open `regedit` as Administrator + +2. Navigate to: `HKEY_LOCAL_MACHINE\Software\Policies\Microsoft\Edge\WebView2` + +3. Create a new key named `DowngradeVersion` (if it doesn't exist) + +4. Inside the DowngradeVersion key, create a new **String Value (REG_SZ)**: + + * **Value name:** The AUMID or executable name (e.g., teams.exe) + + * **Value data:** The target major version number + * Set the value to the target full version string using the 4-part numeric format (for example, 151.0.2178.0) + * Admins can find the exact 4-part version number in the [Microsoft Edge release notes for Stable Channel](/deployedge/microsoft-edge-relnote-stable-channel) + * **Example value:** + o Name: teams.exe, Value: 151.0.2178.0 + o Name: outlook.exe, Value: 152.0.2164.0 + +5. Restart the WebView2 application for the policy to take effect + +**Example:** + +``` +Key: HKLM\Software\Policies\Microsoft\Edge\WebView2\DowngradeVersion +Value: teams.exe = "145" +Value: outlook.exe = "146" +``` + + + +#### Important Notes + +* Only **HKLM** is supported (HKCU is ignored) + +* Values that are Major-only values (for example, 151), wildcard values (for example, 151.*), and values that are not exact 4-part numeric versions are not supported. + +* The WebView2 loader resolves the runtime installation directory only when a folder that exactly matches the configured full version exists (for example, 151.0.2178.0 must match 151.0.2178.0 exactly). If no exact matching folder is found, the policy has no effect and the runtime defaults to the BrowserExecutableFolder policy or the Evergreen runtime (the default auto-updating runtime). + +* The updater will **automatically download** the required version if it satisfies N-1/N-2 conditions — admins do not need to pre-stage version folders on disk + +* No restart of the machine is needed, but the **WebView2 app must be restarted** and it may take upto 1 hr for the downgrade to take effect + +* Policy application latency: Changes take effect within **1 hour** of deployment (aligned with Edge/WebView2 update task cadence). To trigger a force update refer to step [here](#triggering-a-force-update). + +* Downgrade policy enforcement overrides maintenance windows, extended update intervals, and cached last-check timestamps + + + +#### Process Flow (How It Works Under the Hood) + +1. Admin sets policy using Group Policy, specifying AppId and TargetVersion + +2. Updater reads policy and validates that TargetVersion is within N-1 or N-2 + +3. Downloads the downgraded version if needed (side-by-side install) + +4. Sets `BrowserExecutableFolder` policy for the target app to redirect it to the specified runtime version + +5. Maintains mapping as long as the downgraded version stays within the supported range + +6. Cleans up and reverts app to latest version when the pinned version falls outside the supported range or the policy is removed + +📄 Note: If a downgrade policy is active but the target runtime version is not yet downloaded (e.g., due to network or disk constraints), applications will continue running on the currently available runtime until the downgraded bits are present. Applications will NOT fail to launch solely because downgraded bits are pending download. + + + +## 3. Limitations of Downgrade + + + +#### Version Limitations + +| Limitation | Detail | +|---|---| +| **Version range** | Only N-1 or N-2 relative to the current Evergreen version. Downgrades beyond two versions are rejected. | +| **Version format** | Only major version numbers (digits only). Full version strings, dots, or wildcards are invalid. | +| **Automatic expiry** | A downgraded version remains active only while it is within the two most recent previous versions. Once two subsequent new versions release beyond the pinned version, the downgrade automatically expires and the app reverts to the latest runtime. | +| **Availability** | Feature available from version 150 onwards only. | + + + +#### Scope Limitations + +| Limitation | Detail | +|---|---| +| **Enterprise-only** | Not supported on consumer or unmanaged devices. | +| **Machine-level only** | Policy set at HKLM only. HKCU is not supported. No user-level policy or individual user control. | +| **Per-app targeting** | Cannot perform enterprise-wide downgrade across all apps. Each app must be individually targeted. | +| **No developer control** | Only IT administrators can initiate downgrade. Developers cannot trigger downgrade via APIs. | +| **No indefinite pinning** | The solution does NOT support long-term or permanent version pinning. | + + + +#### Shared User Data Folder (UDF) Constraints + +Applications may share a WebView2 User Data Folder (UDF) to reuse browser state. Accessing the same UDF from different WebView2 runtime versions is **unsafe** and will result in failures: + +**If App A is downgraded and App B shares the same UDF but is not downgraded:** + +* Both App A and App B will fail fast on launch + +* Admin must downgrade all apps sharing the same UDF to the same version + +📄 Note: The number of apps sharing a UDF is currently very limited. As far as we know the only apps that share a UDF today are the Office Suite apps: Excel, Word and PowerPoint. + + + +## 4. Risks Associated with Downgrade + + + +#### Security Risks + +| Risk | Description | +|---|---| +| **Reintroduced vulnerabilities** | Downgrading reintroduces patched vulnerabilities that have been fixed in newer versions | +| **Compliance weakening** | Older versions may violate compliance in regulated environments | +| **Expanded attack surface** | Managing multiple downgraded versions increases the persistence of outdated clients | + + + +#### Data Integrity Risks + +| Risk | Description | +|---|---| +| **Storage corruption** | Downgrade can cause corruption or incompatibility if storage formats, schemas, or APIs have changed between versions (cookies, IndexedDB, Local Storage) | +| **Schema mismatches** | Unlike Edge browser which uses User Data Snapshots, WebView2 does not implement platform-level snapshotting | +| **User data loss** | Profile instability and potential data loss if storage formats are incompatible | + + + +#### Application Compatibility Risks + +| Risk | Description | +|---|---| +| **Feature dependency breaks** | Applications using newer WebView2 APIs or behaviours may fail or behave unpredictably after downgrade | +| **Performance regressions** | Older versions may introduce slower page loads, higher memory usage, and degraded experiences | +| **App malfunction** | Downgrades can cause applications to malfunction due to reliance on recently introduced features or rendering changes | + + + +#### Operational Risks + +| Risk | Description | +|---|---| +| **Version fragmentation** | Supporting downgrade at the app level can lead to version drift across apps on the same device | +| **Sedimentation** | Multiple older versions accumulate on devices over time, increasing complexity | +| **Increased disk usage** | An additional WebView2 runtime version is installed side-by-side with the current Evergreen version, consuming extra disk space on each device | +| **Coordination complexity** | Downgrade requires careful coordination between IT admins, application owners, and platform teams | + +⚠️ Given these risks, Enterprise Downgrade should only be used as a last-resort recovery measure — when a critical regression is actively disrupting business operations and no other mitigation (hotfix, feature flag, update pause) can resolve the issue in a timely manner. The downgrade buys time for the platform team to ship a proper fix; it is not a substitute for one. + + + +## 5. Testing & Troubleshooting + + + +#### Verifying Downgrade Applied + +After setting the policy and restarting the target WebView2 application: + + + +###### 1. Check the versioned folder + +* Navigate to: `C:\Program Files (x86)\Microsoft\EdgeWebView\Application\` + +* Confirm a new folder appears matching the downgraded version (e.g., `145.x.xxxx.xx`) + +* The presence of this versioned folder indicates the updater has fetched and staged the downgraded runtime + + + +###### 2. Check registry policy + +* Confirm the `DowngradeVersion` key is set under: `HKLM\Software\Policies\Microsoft\Edge\WebView2\DowngradeVersion` +* Verify entries match your configured AppId → TargetVersion + + + +###### 3. Check BrowserExecutableFolder redirect + +* The `BrowserExecutableFolder` policy should be set automatically to point the app to the downgraded runtime path + + + +#### Triggering a Force Update + +After setting the DowngradeVersion policy, the Edge Updater needs to download the target version. By default, this happens within ~1 hour (aligned with the Edge/WebView2 update task cadence). To trigger an immediate update, follow the below steps: + +1. Open PowerShell as Administrator + +2. Find the Edge Update task: + + `Get-ScheduledTask -TaskPath "\Microsoft\EdgeUpdate\*" | Select TaskName, TaskPath` + +3. Run the task: + + `Start-ScheduledTask -TaskName ""` + +4. Wait a few minutes for the download to complete + +5. Restart the WebView2 application + + + +#### Diagnostics Tools (For Deeper Troubleshooting) + +The following tools are for **troubleshooting issues** — they are not required for standard verification: + +| Tool | Purpose | +|---|---| +| **edge://webview2-internals** | View active WebView2 processes, runtime version in use | +| **ETW Tracing** | Capture low-level diagnostic logs for update/downgrade events | +| **Event Viewer** | Check Application logs for WebView2 update errors or policy enforcement failures | + + + +#### Common Issues & Resolution + +| Symptom | Likely Cause | Resolution | +|---|---|---| +| App still running on latest version | App not restarted | Restart the WebView2 application (not the machine) | +| Downgraded folder not appearing | Version outside N-1/N-2 range | Verify the target version is within the two most recent previous versions | +| App fails fast on launch (all apps sharing UDF) | Shared UDF version mismatch | Downgrade ALL apps using the same User Data Folder to the same version | +| Policy not taking effect | Incorrect key path or value format | Verify HKLM path, value name format (AUMID or exe), and 4 part value | +| Multiple apps impacted unexpectedly | Shared User Data Folder | Identify UDF sharing and ensure all affected apps are aligned | +| Downgrade auto-reverted unexpectedly | Pinned version fell outside supported range | Expected behavior — downgrade expires once the version is no longer within N-1/N-2 | + + + +## 6. How to Revert from Downgrade + + + +#### Option 1: Disable Group Policy (Recommended) + +If GPO was used to configure downgrade: + +1. Open Group Policy Editor (`gpedit.msc`) + +2. Navigate to: **Computer Configuration > Administrative Templates > Microsoft Edge WebView2** + +3. Set "**Configure per-application WebView2 downgrade version**" to **Disabled** or **Not Configured** + +4. Restart the WebView2 application + +5. The app will revert to the latest Evergreen runtime on next launch + +📄 Important: Do NOT delete registry keys directly. Always use GPO to disable the policy to ensure clean removal and avoid orphaned configuration. + + + +#### Option 2: Remove Policy via Registry + +If the policy was originally set directly via Registry (not recommended in production): + +1. Open `regedit` as Administrator + +2. Navigate to: `HKEY_LOCAL_MACHINE\Software\Policies\Microsoft\Edge\WebView2\DowngradeVersion` + +3. Delete the specific value (e.g., `teams.exe`) + +4. Restart the WebView2 application + +⚠️ Caution: Direct registry manipulation should only be used if the original policy was set via Registry Editor. If GPO was used, always revert using GPO to ensure consistency. + + + +#### Option 3: Automatic Expiry + +The downgrade expires automatically when the pinned version is no longer within the two most recent previous versions: + +* **Trigger:** Two subsequent new Evergreen versions release beyond the pinned version + +* **Behavior:** The updater automatically reverts applicable apps to the latest runtime. + +* **Admin action required:** Remove the stale policy once it auto-expires. + +* **Example:** If you downgrade to version 145 while 147 is current (145 is N-2), and then version 148 release, version 145 is now three versions behind → downgrade auto-expires + + + +#### Post-Revert Behavior + +| Action | What Happens | +|---|---| +| **Application restart** | App picks up the latest runtime on next launch | +| **BrowserExecutableFolder** | Automatically removed; app returns to default runtime path | +| **Downgraded runtime bits** | Cleaned up by the updater on a scheduled cadence | +| **User data** | Remains in place; no automatic data migration occurs | + + + +## 7. Escalation & Contact + +| Aspect | Value | +|---|---| +| **Area Path:** | Edge\Web Experience\WebView2\Distribution | +| **DL:** | [wv2addr@microsoft.com](mailto:wv2addr@microsoft.com) | + +**Escalation Path:** + +1. Enterprise Admin contacts Microsoft CSS + +2. CSS troubleshoots using this guide + +3. If unresolved → CSS escalates to WebView2 Platform team ICM + + Owning Service: Edge Browser customer incidents + + Owning Team: Edge WebView2 From 9b5233b9e4dca48b82a121ddc3b5050457188861 Mon Sep 17 00:00:00 2001 From: Michael Hoffman <45407486+mikehoffms@users.noreply.github.com> Date: Wed, 19 Aug 2026 13:36:58 -0700 Subject: [PATCH 05/28] 1st Writer/Editor pass --- microsoft-edge/toc.yml | 2 +- .../webview2/concepts/enterprise.md | 23 +- .../webview2/how-to/enterprise-downgrade.md | 408 ++++++++++-------- 3 files changed, 232 insertions(+), 201 deletions(-) diff --git a/microsoft-edge/toc.yml b/microsoft-edge/toc.yml index 53f92dd080..86a6a49481 100644 --- a/microsoft-edge/toc.yml +++ b/microsoft-edge/toc.yml @@ -2360,7 +2360,7 @@ href: ./webview2/concepts/enterprise.md displayName: Manage WebView2 applications # old title - - name: WebView2 Enterprise Downgrade Guide + - name: Enterprise downgrade of the WebView Runtime to a previous version href: ./webview2/how-to/enterprise-downgrade.md - name: Distribute an app as a single executable file diff --git a/microsoft-edge/webview2/concepts/enterprise.md b/microsoft-edge/webview2/concepts/enterprise.md index d6fed51574..0323071463 100644 --- a/microsoft-edge/webview2/concepts/enterprise.md +++ b/microsoft-edge/webview2/concepts/enterprise.md @@ -1,6 +1,6 @@ --- title: Enterprise management of WebView2 Runtimes -description: How IT admins can manage WebView2 applications and the WebView2 Runtime. +description: How IT Administrators can manage WebView2 applications and the WebView2 Runtime. author: MSEdgeTeam ms.author: msedgedevrel ms.topic: article @@ -12,9 +12,9 @@ ms.date: 08/18/2026 -This article discusses how IT admins can manage WebView2 applications and the WebView2 Runtime. A developer can integrate the WebView2 component into their app, and then deploy the self-updating Evergreen WebView2 Runtime (along with the app) onto user devices, to power the latest WebView2 features of the app and get the latest security improvements. +This article discusses how IT Administrators can manage WebView2 applications and the WebView2 Runtime. A developer can integrate the WebView2 component into their app, and then deploy the self-updating Evergreen WebView2 Runtime (along with the app) onto user devices, to power the latest WebView2 features of the app and get the latest security improvements. -Feedback from IT admins and developers is welcome, through the [WebView2Feedback](https://github.com/MicrosoftEdge/WebViewFeedback) repo. +Feedback from IT Admins and developers is welcome, through the [WebView2Feedback](https://github.com/MicrosoftEdge/WebViewFeedback) repo. **Detailed contents:** * [Group policies for WebView2](#group-policies-for-webview2) @@ -34,13 +34,13 @@ Feedback from IT admins and developers is welcome, through the [WebView2Feedback ## Group policies for WebView2 -IT admins can use group policy objects (GPO) to configure policy settings for WebView2. The following policies are relevant to WebView2. +IT Admins can use group policy objects (GPO) to configure policy settings for WebView2. The following policies are relevant to WebView2. #### Update policies -[Microsoft Edge - Update policies](/deployedge/microsoft-edge-update-policies) are available for IT admins to manage the installing and updating aspects of the WebView2 Runtime. The Microsoft Edge browser and WebView2 Runtime are updated using the same update mechanism. The policy applies to both Microsoft Edge and the WebView2 Runtime, unless the policy is channel-specific, such as [Update](/deployedge/microsoft-edge-update-policies#update) and [Update (WebView)](/deployedge/microsoft-edge-update-policies#update-webview). +[Microsoft Edge - Update policies](/deployedge/microsoft-edge-update-policies) are available for IT Admins to manage the installing and updating aspects of the WebView2 Runtime. The Microsoft Edge browser and WebView2 Runtime are updated using the same update mechanism. The policy applies to both Microsoft Edge and the WebView2 Runtime, unless the policy is channel-specific, such as [Update](/deployedge/microsoft-edge-update-policies#update) and [Update (WebView)](/deployedge/microsoft-edge-update-policies#update-webview). To configure update policies for Microsoft Edge (and the WebView2 Runtime), see [Configure Microsoft Edge policy settings on Windows devices](/deployedge/configure-microsoft-edge), in the Microsoft Edge Enterprise documentation. @@ -48,7 +48,7 @@ To configure update policies for Microsoft Edge (and the WebView2 Runtime), see #### Suppressing WebView2 Runtime updates -An IT admin can suppress updating of the WebView2 Runtime, if auto-updating needs to be suppressed for a short time. After the time period, updating of the WebView2 Runtime resumes. The [UpdatesSuppressed](/deployedge/microsoft-edge-update-policies#updatessuppressed) policy allows an IT admin to set the time during each day at which to suppress auto-update for both Microsoft Edge and the WebView2 Runtime. This enables an IT admin to configure preferences and proxies once for both the browser and the WebView2 Runtime, to control their network bandwidth and traffic, or for other purposes. +An IT Admin can suppress updating of the WebView2 Runtime, if auto-updating needs to be suppressed for a short time. After the time period, updating of the WebView2 Runtime resumes. The [UpdatesSuppressed](/deployedge/microsoft-edge-update-policies#updatessuppressed) policy allows an IT Admin to set the time during each day at which to suppress auto-update for both Microsoft Edge and the WebView2 Runtime. This enables an IT Admin to configure preferences and proxies once for both the browser and the WebView2 Runtime, to control their network bandwidth and traffic, or for other purposes. However, users should not stop updating their WebView2 Runtime; users should not remain on an older version of the WebView2 Runtime. Using older versions of the WebView2 Runtime isn't recommended. Security updates and servicing updates are only available on the latest Stable channel release (Edge Stable) and the latest Beta channel release (Edge Beta). If you use older releases of the Microsoft WebView2 Runtime, you won't receive the latest quality and security updates. @@ -58,7 +58,7 @@ However, users should not stop updating their WebView2 Runtime; users should not With the WebView2 152 release, the Enterprise Downgrade feature is generally available. -Enterprise Downgrade is a temporary, IT admin-controlled capability that allows a specific WebView2 application to revert to a previous runtime version in the event of a critical regression. +Enterprise Downgrade is a temporary, IT Admin-controlled capability that allows a specific WebView2 application to revert to a previous runtime version in the event of a critical regression. See [WebView2 Enterprise Downgrade Guide] (todo). @@ -102,21 +102,21 @@ See: #### Browser policies -[Microsoft Edge - Policies](/deployedge/microsoft-edge-policies) doesn't apply to WebView2 applications. This is by design, because apps and browsers have different use cases, and IT admins might not be aware of what applications use WebView2. +[Microsoft Edge - Policies](/deployedge/microsoft-edge-policies) doesn't apply to WebView2 applications. This is by design, because apps and browsers have different use cases, and IT Admins might not be aware of what applications use WebView2. -Applying browser policies on WebView2 would have unintended consequences. For example, IT admins can block JavaScript in the browser, and that would break WebView2 apps that use JavaScript. To prevent that, browser policies are separate from WebView2 policies. +Applying browser policies on WebView2 would have unintended consequences. For example, IT Admins can block JavaScript in the browser, and that would break WebView2 apps that use JavaScript. To prevent that, browser policies are separate from WebView2 policies. #### WebView2-specific policies -[Microsoft Edge WebView2 - Policies](/deployedge/microsoft-edge-webview-policies) are available to for you to manage WebView2 directly. However, we recommend that WebView2 app developers implement their own group policies to manage the use of WebView2, because it's easier for administrators to manage the app instead of managing WebView2 directly. +[Microsoft Edge WebView2 - Policies](/deployedge/microsoft-edge-webview-policies) are available to for you to manage WebView2 directly. However, we recommend that WebView2 app developers implement their own group policies to manage the use of WebView2, because it's easier for IT Admins to manage the app instead of managing WebView2 directly. ## Windows Server Update Services (WSUS) -Windows Server Update Services (WSUS) enables IT admins to deploy the latest Microsoft product updates. You can use WSUS to fully manage the distribution of updates of WebView2 that are released through Microsoft Update to computers on your network. +Windows Server Update Services (WSUS) enables IT Admins to deploy the latest Microsoft product updates. You can use WSUS to fully manage the distribution of updates of WebView2 that are released through Microsoft Update to computers on your network. See [Windows Server Update Services (WSUS) overview](/windows-server/administration/windows-server-update-services/get-started/windows-server-update-services-wsus). @@ -137,6 +137,7 @@ See [Update Microsoft Edge](/intune/configmgr/apps/deploy-use/deploy-edge#update * [Distribute your app and the WebView2 Runtime](./distribution.md) - Evergreen vs. fixed version of the WebView2 Runtime. +* [Enterprise downgrade of the WebView Runtime to a previous version](../how-to/enterprise-downgrade.md) Microsoft Edge Enterprise documentation: diff --git a/microsoft-edge/webview2/how-to/enterprise-downgrade.md b/microsoft-edge/webview2/how-to/enterprise-downgrade.md index 2ea4842995..1c6180798f 100644 --- a/microsoft-edge/webview2/how-to/enterprise-downgrade.md +++ b/microsoft-edge/webview2/how-to/enterprise-downgrade.md @@ -1,6 +1,6 @@ --- -title: WebView2 Enterprise Downgrade Guide -description: WebView2 Enterprise Downgrade Guide. +title: Enterprise downgrade of the WebView Runtime to a previous version +description: WebView2 Enterprise Downgrade guide. author: MSEdgeTeam ms.author: msedgedevrel ms.topic: article @@ -8,166 +8,171 @@ ms.service: microsoft-edge ms.subservice: webview ms.date: 08/19/2026 --- -# WebView2 Enterprise Downgrade Guide +# Enterprise downgrade of the WebView Runtime to a previous version + +In an enterprise, the IT Admin can downgrade the WebView Runtime to a previous version, as a temporary measure. **Detailed contents:** -* [1. What Is Enterprise Downgrade?](#1-what-is-enterprise-downgrade) - * [Background](#background) - * [What Enterprise Downgrade Solves](#what-enterprise-downgrade-solves) - * [Why It Exists](#why-it-exists) - * [Applicable Applications](#applicable-applications) - * [Policy Configuration & Precedence](#policy-configuration--precedence) - * [Core Design Principles](#core-design-principles) -* [2. How to Downgrade — Steps](#2-how-to-downgrade--steps) - * [Option 1: Group Policy (GPO) — Recommended for Enterprise](#option-1-group-policy-gpo--recommended-for-enterprise) +* [Overview](#overview) + * [What enterprise downgrade solves](#what-enterprise-downgrade-solves) + * [Why enterprise downgrade exists](#why-it-exists) + * [Applicable applications](#applicable-applications) + * [Policy configuration and precedence](#policy-configuration-and-precedence) + * [Core design principles](#core-design-principles) +* [Temporarily downgrading the WebView2 Runtime](#temporarily-downgrading-the-webview2-runtime) + * [Option 1: Group Policy (GPO)](#option-1-group-policy-gpo--recommended-for-enterprise) * [Option 2: Registry Editor (regedit)](#option-2-registry-editor-regedit) - * [Important Notes](#important-notes) - * [Process Flow (How It Works Under the Hood)](#process-flow-how-it-works-under-the-hood) -* [3. Limitations of Downgrade](#3-limitations-of-downgrade) - * [Version Limitations](#version-limitations) - * [Scope Limitations](#scope-limitations) - * [Shared User Data Folder (UDF) Constraints](#shared-user-data-folder-udf-constraints) -* [4. Risks Associated with Downgrade](#4-risks-associated-with-downgrade) - * [Security Risks](#security-risks) - * [Data Integrity Risks](#data-integrity-risks) - * [Application Compatibility Risks](#application-compatibility-risks) - * [Operational Risks](#operational-risks) -* [5. Testing & Troubleshooting](#5-testing--troubleshooting) - * [Verifying Downgrade Applied](#verifying-downgrade-applied) + * [Important notes](#important-notes) + * [Process flow: How downgrade is implemented](#process-flow-how-it-works-under-the-hood) +* [Limitations of downgrading the WebView2 Runtime](#limitations-of-downgrading-the-webview2-runtime) + * [Version limitations](#version-limitations) + * [Scope limitations](#scope-limitations) + * [Shared User Data Folder (UDF) constraints](#shared-user-data-folder-udf-constraints) +* [Risks of downgrading the WebView2 Runtime](#risks-of-downgrading-the-webview2-runtime) + * [Security risks](#security-risks) + * [Data integrity risks](#data-integrity-risks) + * [Application compatibility risks](#application-compatibility-risks) + * [Operational risks](#operational-risks) +* [Testing and troubleshooting downgrading of the Runtime](#testing-and-troubleshooting-downgrading-of-the-runtime) + * [Verifying that the Runtime downgrade was applied](#verifying-that-the-runtime-downgrade-was-applied) * [1. Check the versioned folder](#1-check-the-versioned-folder) * [2. Check registry policy](#2-check-registry-policy) - * [3. Check BrowserExecutableFolder redirect](#3-check-browserexecutablefolder-redirect) - * [Triggering a Force Update](#triggering-a-force-update) - * [Diagnostics Tools (For Deeper Troubleshooting)](#diagnostics-tools-for-deeper-troubleshooting) - * [Common Issues & Resolution](#common-issues--resolution) -* [6. How to Revert from Downgrade](#6-how-to-revert-from-downgrade) - * [Option 1: Disable Group Policy (Recommended)](#option-1-disable-group-policy-recommended) - * [Option 2: Remove Policy via Registry](#option-2-remove-policy-via-registry) - * [Option 3: Automatic Expiry](#option-3-automatic-expiry) - * [Post-Revert Behavior](#post-revert-behavior) -* [7. Escalation & Contact](#7-escalation--contact) + * [3. Check the `BrowserExecutableFolder` redirect](#3-check-browserexecutablefolder-redirect) + * [Triggering a force-update](#triggering-a-force-update) + * [Diagnostics tools for deeper troubleshooting)](#diagnostics-tools-for-deeper-troubleshooting) + * [Common issues and resolution](#common-issues-and-resolution) +* [Reverting downgrading the WebView Runtime](#reverting-downgrading-the-webview-runtime) + * [Option 1: Disable group policy (recommended)](#option-1-disable-group-policy-recommended) + * [Option 2: Remove the policy via the registry](#option-2-remove-the-policy-via-the-registry) + * [Option 3: Automatic expiry](#option-3-automatic-expiry) + * [Post-revert behavior](#post-revert-behavior) +* [Escalating and contacting the WebView2 team](#escalating-and-contacting-the-webview2-team) -Policy Documentation: [DowngradeVersion](https://learn.microsoft.com/en-us/deployedge/microsoft-edge-webview-policies#downgradeversion) in _Microsoft Edge WebView2 - Policies_. +Policy documentation: [DowngradeVersion](/deployedge/microsoft-edge-webview-policies#downgradeversion) in _Microsoft Edge WebView2 - Policies_. -## 1. What Is Enterprise Downgrade? - - - -#### Background +## Overview -**WebView2** is a browser control that allows Windows applications (such as Microsoft Teams, Outlook, and third-party enterprise software) to embed web content using the Microsoft Edge rendering engine. The **Evergreen** distribution model means the WebView2 runtime updates automatically alongside Edge — applications always run on the latest version without manual intervention. +**WebView2** is a browser control that allows Windows applications (such as Microsoft Teams, Outlook, and third-party enterprise software) to embed web content using the Microsoft Edge rendering engine. The **Evergreen** distribution model means the WebView2 Runtime updates automatically alongside Edge — applications always run on the latest version without manual intervention. -While Evergreen ensures applications get security patches and feature improvements automatically, it also means that if a new runtime version introduces a regression, each application and Windows component that uses them is likely to be impacted. Although enterprise administrators cannot uninstall the impacting update, Enterprise Downgrade offers a short-term mitigation approach to restore impacted productivity. +While Evergreen ensures applications get security patches and feature improvements automatically, it also means that if a new Runtime version introduces a regression, each application and Windows component that uses them is likely to be impacted. Although enterprise IT Admins cannot uninstall the impacting update, Enterprise Downgrade offers a short-term mitigation approach to restore impacted productivity. -#### What Enterprise Downgrade Solves +#### What enterprise downgrade solves -The **DowngradeVersion** policy is a controlled version downgrade capability that allows enterprise IT administrators to temporarily revert specific WebView2 applications to a previous runtime version via Group Policy when a critical regression disrupts business operations. +The [DowngradeVersion](/deployedge/microsoft-edge-webview-policies#downgradeversion) policy is a controlled version downgrade capability that allows an enterprise IT Admin to temporarily revert specific WebView2 applications to a previous Runtime version via Group Policy when a critical regression disrupts business operations. -How it works at a high level: +How enterprise downgrade works: -1. Admin identifies that a new WebView2 version has broken a specific application +1. The IT Admin identifies that a new WebView2 version has broken a specific application. -2. Admin sets a Group Policy specifying: "For this application, use version X instead of the latest". (Note: Only N-1 or N-2 relative to the current Evergreen version is supported. Downgrades to versions beyond N-2 are rejected.) +1. The IT Admin sets a Group Policy specifying: "For this application, use version X instead of the latest." -3. The Edge Updater downloads and installs the older version **side-by-side** with the current one + Only N-1 or N-2 relative to the current Evergreen version is supported. Downgrades to versions beyond N-2 are rejected. -4. The WebView2 Loader redirects only the targeted application to the older runtime +1. The Edge Updater downloads and installs the older WebView2 Runtime version **side-by-side** with the current WebView2 Runtime. -5. All other applications on the device continue using the latest version unaffected +1. The WebView2 Loader redirects only the targeted application to the older WebView2 Runtime. -6. The downgrade automatically expires once the pinned version is no longer within the two most recent previous versions +1. All other applications on the device continue using the latest version unaffected. + +1. The downgrade automatically expires once the pinned version is no longer within the two most recent previous versions. -#### Why It Exists +#### Why enterprise downgrade exists + +In mission-critical enterprise environments, unexpected regressions in the WebView2 Runtime can halt business workflows with no immediate remedy. Even brief outages result in lost revenue, missed SLAs, and increased operational costs. -In mission-critical enterprise environments, for e.g. healthcare systems, financial trading platforms, retail point-of-sale, government services, unexpected regressions in the WebView2 runtime can halt business workflows with no immediate remedy. Even brief outages result in lost revenue, missed SLAs, and increased operational costs. +Enterprise Downgrade provides a **temporary, Admin-controlled version downgrade** for the specific application affected, while the platform team prepares a proper fix. -Enterprise Downgrade provides a **temporary, admin-controlled version downgrade** for the specific application affected, while the platform team prepares a proper fix. +🔑 Key Principle: Enterprise Downgrade is a last-resort recovery tool — targeted, time-bound, and managed by the enterprise IT Admin in partnership with application owners. Enterprise Downgrade is not a version-pinning mechanism. -🔑 Key Principle: Downgrade is a last-resort recovery tool — targeted, time-bound, and managed by enterprise admins in partnership with application owners. It is not a version-pinning mechanism. +Mission-critical enterprise environments include, for example: +* Healthcare systems +* Financial trading platforms +* Retail point-of-sale +* Government services -#### Applicable Applications +#### Applicable applications -Enterprise Downgrade does **not** automatically affect any application. It is a policy that an IT administrator must explicitly configure for specific applications. Only then does it apply. +Enterprise Downgrade does **not** automatically affect any application. It is a policy that an IT Admin must explicitly configure for specific applications. Only then does it apply. **Which apps can be targeted:** -* Any WebView2 Evergreen application running on enterprise-managed Windows devices +* Any WebView2 Evergreen application running on enterprise-managed Windows devices. -* The admin specifies the target by **executable** name (e.g., `teams.exe`) or **AUMID** (Application User Model ID, for packaged/MSIX apps) +* The IT Admin specifies the target by **executable** name (such as `teams.exe`) or **AUMID** (Application User Model ID, for packaged/MSIX apps). -* If both an AUMID and exe name entry exist for the same application, the AUMID entry takes precedence +* If both an AUMID and exe name entry exist for the same application, the AUMID entry takes precedence. **Which apps are NOT affected:** -* Applications not named in the policy continue the latest Evergreen runtime +* Applications that are not named in the policy continue to use the latest Evergreen Runtime. -* Consumer/unmanaged devices are entirely out of scope +* Consumer or unmanaged devices are entirely out of scope. -* App-bundled (Fixed Version) WebView2 runtimes are out of scope +* App-bundled (Fixed Version) WebView2 Runtimes are out of scope. -#### Policy Configuration & Precedence +#### Policy configuration and precedence | Location | Path | |---|---| -| **Group Policy (recommended)** | Computer Configuration > Administrative Templates > Microsoft Edge WebView2 > Configure per-application WebView2 downgrade version | +| **Group Policy (recommended)** | Computer Configuration > Administrative Templates > Microsoft Edge WebView2 > Configure per-application WebView2 downgrade version. | | **Registry** | `HKLM\Software\Policies\Microsoft\Edge\WebView2\DowngradeVersion` | 📄 Note: HKCU is not supported — this is a machine-level enterprise policy only. **Precedence when multiple policies exist (highest to lowest):** -1. **DowngradeVersion policy** — always wins +1. **DowngradeVersion policy** — always wins. -2. **BrowserExecutableFolder** — if set independently by the admin +1. **BrowserExecutableFolder** — if set independently by the IT Admin. -3. **Default Evergreen runtime** — lowest +1. **Default Evergreen Runtime** — lowest. -If both DowngradeVersion and BrowserExecutableFolder are independently configured, DowngradeVersion takes precedence and overrides the BrowserExecutableFolder redirect. +If both `DowngradeVersion` and `BrowserExecutableFolder` are independently configured, `DowngradeVersion` takes precedence and overrides the `BrowserExecutableFolder` redirect. -#### Core Design Principles +#### Core design principles -* **Enterprise IT Admin Driven:** Only IT administrators can initiate downgrade via Group Policy. Developers and end users cannot trigger it. +* **Enterprise IT Admin Driven:** Only IT Admins can initiate downgrade via Group Policy. Developers and end users cannot trigger it. * **Updater Service Compliance:** The Edge Updater downloads the required version if needed and continues normal updates for all other apps. -* **Automatic Expiry:** A downgraded version remains valid only as long as it is within the two most recent previous versions (N-1 or N-2). Once two subsequent new major versions release beyond the downgraded version, the downgrade expires and the app automatically reverts to the latest runtime. Microsoft recommends admins to remove the stale policies once it auto-expires. +* **Automatic Expiry:** A downgraded version remains valid only as long as it is within the two most recent previous versions (N-1 or N-2). Once two subsequent new major versions release beyond the downgraded version, the downgrade expires and the app automatically reverts to the latest Runtime. Microsoft recommends that the IT Admin should remove the stale policy after it auto-expires. * **Per-App Targeting:** Downgrade is applied per-application, not device-wide. Each application must be individually specified. -## 2. How to Downgrade — Steps +## Temporarily downgrading the WebView2 Runtime -#### Option 1: Group Policy (GPO) — Recommended for Enterprise +#### Option 1: Group Policy (GPO) This is the recommended approach for enterprise environments. Group Policy ensures centralized, auditable management across managed devices. -1. Open Group Policy Editor (`gpedit.msc`) +1. Open the Group Policy Editor (`gpedit.msc`). -2. Navigate to: **Computer Configuration > Administrative Templates > Microsoft Edge WebView2** +1. Navigate to: **Computer Configuration > Administrative Templates > Microsoft Edge WebView2** -3. Find "**Configure per-application WebView2 downgrade version**" +1. Find **Configure per-application WebView2 downgrade version**. -4. Enable the policy and add entries: +1. Enable the policy, and enter this information: - * **Name:** Application identifier (AUMID or exe name, e.g., `teams.exe`) + * **Name:** The application identifier (AUMID or exe name, such as `teams.exe`). - * **Value:** Target four part version number (e.g., `145`) + * **Value:** The target four-part version number (such as 151.0.2178.0). @@ -175,24 +180,27 @@ This is the recommended approach for enterprise environments. Group Policy ensu For targeted configuration on individual machines. Requires local administrator privileges. -1. Open `regedit` as Administrator +1. Open `regedit` as Administrator. + +1. Navigate to: `HKEY_LOCAL_MACHINE\Software\Policies\Microsoft\Edge\WebView2` + +1. Create a new key named `DowngradeVersion` (if it doesn't exist). -2. Navigate to: `HKEY_LOCAL_MACHINE\Software\Policies\Microsoft\Edge\WebView2` +1. Inside the `DowngradeVersion` key, create a new `String Value (REG_SZ)`: -3. Create a new key named `DowngradeVersion` (if it doesn't exist) + * **Value name:** The AUMID or executable name (such as `teams.exe`). -4. Inside the DowngradeVersion key, create a new **String Value (REG_SZ)**: + * **Value data:** The target major version number. - * **Value name:** The AUMID or executable name (e.g., teams.exe) + * Set the value to the target full version string using the four-part numeric format (such as 151.0.2178.0). - * **Value data:** The target major version number - * Set the value to the target full version string using the 4-part numeric format (for example, 151.0.2178.0) - * Admins can find the exact 4-part version number in the [Microsoft Edge release notes for Stable Channel](/deployedge/microsoft-edge-relnote-stable-channel) - * **Example value:** - o Name: teams.exe, Value: 151.0.2178.0 - o Name: outlook.exe, Value: 152.0.2164.0 + * The IT Admin can find the exact four-part version number in the [Microsoft Edge release notes for Stable and Extended Stable Channels](/deployedge/microsoft-edge-relnote-stable-channel) -5. Restart the WebView2 application for the policy to take effect + * **Example values:** + * Name: `teams.exe`, Value: `151.0.2178.0` + * Name: `outlook.exe`, Value: `152.0.2164.0` + +1. Restart the WebView2 application, for the policy to take effect. **Example:** @@ -204,135 +212,143 @@ Value: outlook.exe = "146" -#### Important Notes +#### Important notes + +* Only **HKLM** is supported (HKCU is ignored). -* Only **HKLM** is supported (HKCU is ignored) +* The following values are not supported: + * Major-only values (such as 151). + * Wildcard values (such as 151.*). + * Values that are not exact four-part numeric versions. -* Values that are Major-only values (for example, 151), wildcard values (for example, 151.*), and values that are not exact 4-part numeric versions are not supported. +* The WebView2 loader resolves the Runtime installation directory only when a folder that exactly matches the configured full version exists. For example, 151.0.2178.0 must match 151.0.2178.0 exactly. -* The WebView2 loader resolves the runtime installation directory only when a folder that exactly matches the configured full version exists (for example, 151.0.2178.0 must match 151.0.2178.0 exactly). If no exact matching folder is found, the policy has no effect and the runtime defaults to the BrowserExecutableFolder policy or the Evergreen runtime (the default auto-updating runtime). + If no exact matching folder is found, the policy has no effect, and the Runtime defaults to the `BrowserExecutableFolder` policy or the Evergreen Runtime (the default auto-updating Runtime). -* The updater will **automatically download** the required version if it satisfies N-1/N-2 conditions — admins do not need to pre-stage version folders on disk +* The updater will **automatically download** the required version if it satisfies N-1/N-2 conditions. The IT Admin doesn't need to pre-stage version folders on disk. -* No restart of the machine is needed, but the **WebView2 app must be restarted** and it may take upto 1 hr for the downgrade to take effect +* No restart of the machine is needed, but the WebView2 app must be restarted, and it might take up to 1 hour for the downgrade to take effect. -* Policy application latency: Changes take effect within **1 hour** of deployment (aligned with Edge/WebView2 update task cadence). To trigger a force update refer to step [here](#triggering-a-force-update). +* Policy application latency: Changes take effect within **1 hour** of deployment. This is aligned with the Microsoft Edge and WebView2 update task cadence. To trigger a force update, see [Triggering a force update](#triggering-a-force-update), below. -* Downgrade policy enforcement overrides maintenance windows, extended update intervals, and cached last-check timestamps +* Downgrade policy enforcement overrides the following: + * Maintenance windows. + * Extended update intervals. + * Cached last-check timestamps. -#### Process Flow (How It Works Under the Hood) +#### Process flow: How downgrade is implemented -1. Admin sets policy using Group Policy, specifying AppId and TargetVersion +1. The IT Admin sets policy by using Group Policy, specifying the `AppId` and `TargetVersion`. -2. Updater reads policy and validates that TargetVersion is within N-1 or N-2 +1. The Updater reads the policy, and validates that `TargetVersion` is within N-1 or N-2. -3. Downloads the downgraded version if needed (side-by-side install) +1. Downloads the downgraded version if needed (side-by-side install). -4. Sets `BrowserExecutableFolder` policy for the target app to redirect it to the specified runtime version +1. Sets `BrowserExecutableFolder` policy for the target app to redirect it to the specified Runtime version. -5. Maintains mapping as long as the downgraded version stays within the supported range +1. Maintains mapping as long as the downgraded version stays within the supported range. -6. Cleans up and reverts app to latest version when the pinned version falls outside the supported range or the policy is removed +1. Cleans up and reverts the app to the latest Runtime version when the pinned Runtime version falls outside of the supported range or the policy is removed. -📄 Note: If a downgrade policy is active but the target runtime version is not yet downloaded (e.g., due to network or disk constraints), applications will continue running on the currently available runtime until the downgraded bits are present. Applications will NOT fail to launch solely because downgraded bits are pending download. +📄 Note: If a downgrade policy is active but the target Runtime version is not yet downloaded (such as due to network or disk constraints), applications will continue running on the currently available Runtime until the downgraded bits are present. Applications will NOT fail to launch solely because downgraded bits are pending download. -## 3. Limitations of Downgrade +## Limitations of downgrading the WebView2 Runtime -#### Version Limitations +#### Version limitations | Limitation | Detail | |---|---| | **Version range** | Only N-1 or N-2 relative to the current Evergreen version. Downgrades beyond two versions are rejected. | | **Version format** | Only major version numbers (digits only). Full version strings, dots, or wildcards are invalid. | -| **Automatic expiry** | A downgraded version remains active only while it is within the two most recent previous versions. Once two subsequent new versions release beyond the pinned version, the downgrade automatically expires and the app reverts to the latest runtime. | +| **Automatic expiry** | A downgraded version remains active only while it is within the two most recent previous versions. Once two subsequent new versions release beyond the pinned version, the downgrade automatically expires and the app reverts to the latest Runtime. | | **Availability** | Feature available from version 150 onwards only. | -#### Scope Limitations +#### Scope limitations | Limitation | Detail | |---|---| | **Enterprise-only** | Not supported on consumer or unmanaged devices. | | **Machine-level only** | Policy set at HKLM only. HKCU is not supported. No user-level policy or individual user control. | | **Per-app targeting** | Cannot perform enterprise-wide downgrade across all apps. Each app must be individually targeted. | -| **No developer control** | Only IT administrators can initiate downgrade. Developers cannot trigger downgrade via APIs. | +| **No developer control** | Only IT Admins can initiate downgrade. Developers cannot trigger downgrade via APIs. | | **No indefinite pinning** | The solution does NOT support long-term or permanent version pinning. | -#### Shared User Data Folder (UDF) Constraints +#### Shared User Data Folder (UDF) constraints -Applications may share a WebView2 User Data Folder (UDF) to reuse browser state. Accessing the same UDF from different WebView2 runtime versions is **unsafe** and will result in failures: +Applications may share a WebView2 User Data Folder (UDF) to reuse browser state. Accessing the same UDF from different WebView2 Runtime versions is **unsafe** and will result in failures: **If App A is downgraded and App B shares the same UDF but is not downgraded:** -* Both App A and App B will fail fast on launch +* Both App A and App B will fail fast on launch. -* Admin must downgrade all apps sharing the same UDF to the same version +* The IT Admin must downgrade all apps that share the same UDF to the same Runtime version. -📄 Note: The number of apps sharing a UDF is currently very limited. As far as we know the only apps that share a UDF today are the Office Suite apps: Excel, Word and PowerPoint. +📄 Note: Very few apps share a User Data Folder (UDF). The only known apps that share a UDF are the Office Suite apps: Excel, Word, and PowerPoint. -## 4. Risks Associated with Downgrade +## Risks of downgrading the WebView2 Runtime -#### Security Risks +#### Security risks | Risk | Description | |---|---| -| **Reintroduced vulnerabilities** | Downgrading reintroduces patched vulnerabilities that have been fixed in newer versions | -| **Compliance weakening** | Older versions may violate compliance in regulated environments | -| **Expanded attack surface** | Managing multiple downgraded versions increases the persistence of outdated clients | +| **Reintroduced vulnerabilities** | Downgrading reintroduces patched vulnerabilities that have been fixed in newer versions. | +| **Compliance weakening** | Older versions may violate compliance in regulated environments. | +| **Expanded attack surface** | Managing multiple downgraded versions increases the persistence of outdated clients. | -#### Data Integrity Risks +#### Data integrity risks | Risk | Description | |---|---| -| **Storage corruption** | Downgrade can cause corruption or incompatibility if storage formats, schemas, or APIs have changed between versions (cookies, IndexedDB, Local Storage) | -| **Schema mismatches** | Unlike Edge browser which uses User Data Snapshots, WebView2 does not implement platform-level snapshotting | -| **User data loss** | Profile instability and potential data loss if storage formats are incompatible | +| **Storage corruption** | Downgrade can cause corruption or incompatibility if storage formats, schemas, or APIs have changed between versions (cookies, IndexedDB, Local Storage). | +| **Schema mismatches** | Unlike Edge browser which uses User Data Snapshots, WebView2 does not implement platform-level snapshotting. | +| **User data loss** | Profile instability and potential data loss if storage formats are incompatible. | -#### Application Compatibility Risks +#### Application compatibility risks | Risk | Description | |---|---| -| **Feature dependency breaks** | Applications using newer WebView2 APIs or behaviours may fail or behave unpredictably after downgrade | -| **Performance regressions** | Older versions may introduce slower page loads, higher memory usage, and degraded experiences | -| **App malfunction** | Downgrades can cause applications to malfunction due to reliance on recently introduced features or rendering changes | +| **Feature dependency breaks** | Applications using newer WebView2 APIs or behaviours may fail or behave unpredictably after downgrade. | +| **Performance regressions** | Older versions may introduce slower page loads, higher memory usage, and degraded experiences. | +| **App malfunction** | Downgrades can cause applications to malfunction due to reliance on recently introduced features or rendering changes. | -#### Operational Risks +#### Operational risks | Risk | Description | |---|---| -| **Version fragmentation** | Supporting downgrade at the app level can lead to version drift across apps on the same device | -| **Sedimentation** | Multiple older versions accumulate on devices over time, increasing complexity | -| **Increased disk usage** | An additional WebView2 runtime version is installed side-by-side with the current Evergreen version, consuming extra disk space on each device | -| **Coordination complexity** | Downgrade requires careful coordination between IT admins, application owners, and platform teams | +| **Version fragmentation** | Supporting downgrade at the app level can lead to version drift across apps on the same device. | +| **Sedimentation** | Multiple older versions accumulate on devices over time, increasing complexity. | +| **Increased disk usage** | An additional WebView2 Runtime version is installed side-by-side with the current Evergreen version, consuming extra disk space on each device. | +| **Coordination complexity** | Downgrade requires careful coordination between IT Admins, application owners, and platform teams. | -⚠️ Given these risks, Enterprise Downgrade should only be used as a last-resort recovery measure — when a critical regression is actively disrupting business operations and no other mitigation (hotfix, feature flag, update pause) can resolve the issue in a timely manner. The downgrade buys time for the platform team to ship a proper fix; it is not a substitute for one. +⚠️ Given these risks, Enterprise Downgrade should only be used as a last-resort recovery measure — when a critical regression is actively disrupting business operations and no other mitigation (hotfix, feature flag, update pause) can resolve the issue in a timely manner. The downgrade buys time for the platform team to ship a proper fix; the downgrade is not a substitute for shipping a proper fix. -## 5. Testing & Troubleshooting +## Testing and troubleshooting downgrading of the Runtime -#### Verifying Downgrade Applied +#### Verifying that the Runtime downgrade was applied After setting the policy and restarting the target WebView2 application: @@ -340,64 +356,65 @@ After setting the policy and restarting the target WebView2 application: ###### 1. Check the versioned folder -* Navigate to: `C:\Program Files (x86)\Microsoft\EdgeWebView\Application\` +1. In File Explorer, navigate to: `C:\Program Files (x86)\Microsoft\EdgeWebView\Application\` -* Confirm a new folder appears matching the downgraded version (e.g., `145.x.xxxx.xx`) +1. Confirm that a new folder appears, matching the downgraded version (such as `145.x.xxxx.xx`). -* The presence of this versioned folder indicates the updater has fetched and staged the downgraded runtime + The presence of this versioned folder indicates that the updater has fetched and staged the downgraded Runtime. -###### 2. Check registry policy +###### 2. Check the registry policy -* Confirm the `DowngradeVersion` key is set under: `HKLM\Software\Policies\Microsoft\Edge\WebView2\DowngradeVersion` -* Verify entries match your configured AppId → TargetVersion +1. Confirm that the `DowngradeVersion` key is set, under: `HKLM\Software\Policies\Microsoft\Edge\WebView2\DowngradeVersion` + +1. Verify that entries match your configured `AppId` → `TargetVersion`. -###### 3. Check BrowserExecutableFolder redirect +###### 3. Check the `BrowserExecutableFolder` redirect -* The `BrowserExecutableFolder` policy should be set automatically to point the app to the downgraded runtime path +* The `BrowserExecutableFolder` policy should be set automatically to point the app to the downgraded Runtime path. -#### Triggering a Force Update +#### Triggering a force-update -After setting the DowngradeVersion policy, the Edge Updater needs to download the target version. By default, this happens within ~1 hour (aligned with the Edge/WebView2 update task cadence). To trigger an immediate update, follow the below steps: +After setting the `DowngradeVersion` policy, the Edge Updater needs to download the target version. By default, this happens within ~1 hour (aligned with the Edge/WebView2 update task cadence). To trigger an immediate update, follow the below steps: -1. Open PowerShell as Administrator +1. Open PowerShell as Administrator. -2. Find the Edge Update task: +1. Find the Edge Update task: `Get-ScheduledTask -TaskPath "\Microsoft\EdgeUpdate\*" | Select TaskName, TaskPath` -3. Run the task: +1. Run the task: `Start-ScheduledTask -TaskName ""` -4. Wait a few minutes for the download to complete +1. Wait a few minutes for the download to complete. -5. Restart the WebView2 application +1. Restart the WebView2 application. -#### Diagnostics Tools (For Deeper Troubleshooting) +#### Diagnostics tools for deeper troubleshooting The following tools are for **troubleshooting issues** — they are not required for standard verification: | Tool | Purpose | |---|---| -| **edge://webview2-internals** | View active WebView2 processes, runtime version in use | -| **ETW Tracing** | Capture low-level diagnostic logs for update/downgrade events | -| **Event Viewer** | Check Application logs for WebView2 update errors or policy enforcement failures | +| **edge://webview2-internals** | View active WebView2 processes, Runtime version in use. | +| **ETW Tracing** | Capture low-level diagnostic logs for update/downgrade events. | +| **Event Viewer** | Check Application logs for WebView2 update errors or policy enforcement failures. | -#### Common Issues & Resolution +#### Common issues and resolution | Symptom | Likely Cause | Resolution | |---|---|---| -| App still running on latest version | App not restarted | Restart the WebView2 application (not the machine) | +| App still running on latest version | App not restarted | Restart the WebView2 application (not the machine). | | Downgraded folder not appearing | Version outside N-1/N-2 range | Verify the target version is within the two most recent previous versions | | App fails fast on launch (all apps sharing UDF) | Shared UDF version mismatch | Downgrade ALL apps using the same User Data Folder to the same version | | Policy not taking effect | Incorrect key path or value format | Verify HKLM path, value name format (AUMID or exe), and 4 part value | @@ -406,70 +423,70 @@ The following tools are for **troubleshooting issues** — they are not required -## 6. How to Revert from Downgrade +## Reverting downgrading the WebView Runtime -#### Option 1: Disable Group Policy (Recommended) +#### Option 1: Disable group policy (recommended) If GPO was used to configure downgrade: -1. Open Group Policy Editor (`gpedit.msc`) +1. Open the Group Policy Editor (`gpedit.msc`). -2. Navigate to: **Computer Configuration > Administrative Templates > Microsoft Edge WebView2** +1. Navigate to: **Computer Configuration > Administrative Templates > Microsoft Edge WebView2** -3. Set "**Configure per-application WebView2 downgrade version**" to **Disabled** or **Not Configured** +1. Set "**Configure per-application WebView2 downgrade version**" to **Disabled** or **Not Configured**. -4. Restart the WebView2 application +1. Restart the WebView2 application. -5. The app will revert to the latest Evergreen runtime on next launch + The app will revert to the latest Evergreen Runtime on next launch. -📄 Important: Do NOT delete registry keys directly. Always use GPO to disable the policy to ensure clean removal and avoid orphaned configuration. +📄 Important: Do NOT delete registry keys directly. Always use Group Policy (GPO) to disable the policy, to ensure clean removal and avoid orphaned configuration. -#### Option 2: Remove Policy via Registry +#### Option 2: Remove the policy via the registry If the policy was originally set directly via Registry (not recommended in production): -1. Open `regedit` as Administrator +1. Open `regedit` as Administrator. -2. Navigate to: `HKEY_LOCAL_MACHINE\Software\Policies\Microsoft\Edge\WebView2\DowngradeVersion` +1. Navigate to: `HKEY_LOCAL_MACHINE\Software\Policies\Microsoft\Edge\WebView2\DowngradeVersion` -3. Delete the specific value (e.g., `teams.exe`) +1. Delete the specific value (such as`teams.exe`). -4. Restart the WebView2 application +1. Restart the WebView2 application. ⚠️ Caution: Direct registry manipulation should only be used if the original policy was set via Registry Editor. If GPO was used, always revert using GPO to ensure consistency. -#### Option 3: Automatic Expiry +#### Option 3: Automatic expiry The downgrade expires automatically when the pinned version is no longer within the two most recent previous versions: -* **Trigger:** Two subsequent new Evergreen versions release beyond the pinned version +* **Trigger:** Two subsequent new Evergreen versions release beyond the pinned version. -* **Behavior:** The updater automatically reverts applicable apps to the latest runtime. +* **Behavior:** The updater automatically reverts applicable apps to the latest Runtime. * **Admin action required:** Remove the stale policy once it auto-expires. -* **Example:** If you downgrade to version 145 while 147 is current (145 is N-2), and then version 148 release, version 145 is now three versions behind → downgrade auto-expires +* **Example:** If you downgrade to version 145 while 147 is current (145 is N-2), and then version 148 release, version 145 is now three versions behind → downgrade auto-expires. -#### Post-Revert Behavior +#### Post-revert behavior | Action | What Happens | |---|---| -| **Application restart** | App picks up the latest runtime on next launch | -| **BrowserExecutableFolder** | Automatically removed; app returns to default runtime path | -| **Downgraded runtime bits** | Cleaned up by the updater on a scheduled cadence | -| **User data** | Remains in place; no automatic data migration occurs | +| **Application restart** | App picks up the latest Runtime on next launch. | +| **BrowserExecutableFolder** | Automatically removed; app returns to default Runtime path. | +| **Downgraded Runtime bits** | Cleaned up by the updater on a scheduled cadence. | +| **User data** | Remains in place; no automatic data migration occurs. | -## 7. Escalation & Contact +## Escalating and contacting the WebView2 team | Aspect | Value | |---|---| @@ -478,12 +495,25 @@ The downgrade expires automatically when the pinned version is no longer within **Escalation Path:** -1. Enterprise Admin contacts Microsoft CSS +1. Enterprise Admin contacts Microsoft CSS. + +1. CSS troubleshoots using this guide. -2. CSS troubleshoots using this guide +1. If unresolved → CSS escalates to WebView2 Platform team ICM. -3. If unresolved → CSS escalates to WebView2 Platform team ICM + Owning Service: Edge Browser customer incidents. - Owning Service: Edge Browser customer incidents + Owning Team: Edge WebView2. + +See also: +* [Contact the WebView2 team](../contact.md) + + + +## See also + - Owning Team: Edge WebView2 +* [Enterprise management of WebView2 Runtimes](../concepts/enterprise.md) +* [DowngradeVersion](/deployedge/microsoft-edge-webview-policies#downgradeversion) in _Microsoft Edge WebView2 - Policies_. +* [Microsoft Edge release notes for Stable and Extended Stable Channels](/deployedge/microsoft-edge-relnote-stable-channel) +* [Contact the WebView2 team](../contact.md) From c128bad395c40a5df0880811bd24f0fd403d6548 Mon Sep 17 00:00:00 2001 From: Michael Hoffman <45407486+mikehoffms@users.noreply.github.com> Date: Wed, 19 Aug 2026 13:59:54 -0700 Subject: [PATCH 06/28] fix local toc --- .../webview2/how-to/enterprise-downgrade.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/microsoft-edge/webview2/how-to/enterprise-downgrade.md b/microsoft-edge/webview2/how-to/enterprise-downgrade.md index 1c6180798f..3a8a0fc661 100644 --- a/microsoft-edge/webview2/how-to/enterprise-downgrade.md +++ b/microsoft-edge/webview2/how-to/enterprise-downgrade.md @@ -15,15 +15,15 @@ In an enterprise, the IT Admin can downgrade the WebView Runtime to a previous v **Detailed contents:** * [Overview](#overview) * [What enterprise downgrade solves](#what-enterprise-downgrade-solves) - * [Why enterprise downgrade exists](#why-it-exists) + * [Why enterprise downgrade exists](#why-enterprise-downgrade-exists) * [Applicable applications](#applicable-applications) * [Policy configuration and precedence](#policy-configuration-and-precedence) * [Core design principles](#core-design-principles) * [Temporarily downgrading the WebView2 Runtime](#temporarily-downgrading-the-webview2-runtime) - * [Option 1: Group Policy (GPO)](#option-1-group-policy-gpo--recommended-for-enterprise) + * [Option 1: Group Policy (GPO)](#option-1-group-policy-gpo) * [Option 2: Registry Editor (regedit)](#option-2-registry-editor-regedit) * [Important notes](#important-notes) - * [Process flow: How downgrade is implemented](#process-flow-how-it-works-under-the-hood) + * [Process flow: How downgrade is implemented](#process-flow-how-downgrade-is-implemented) * [Limitations of downgrading the WebView2 Runtime](#limitations-of-downgrading-the-webview2-runtime) * [Version limitations](#version-limitations) * [Scope limitations](#scope-limitations) @@ -36,10 +36,10 @@ In an enterprise, the IT Admin can downgrade the WebView Runtime to a previous v * [Testing and troubleshooting downgrading of the Runtime](#testing-and-troubleshooting-downgrading-of-the-runtime) * [Verifying that the Runtime downgrade was applied](#verifying-that-the-runtime-downgrade-was-applied) * [1. Check the versioned folder](#1-check-the-versioned-folder) - * [2. Check registry policy](#2-check-registry-policy) - * [3. Check the `BrowserExecutableFolder` redirect](#3-check-browserexecutablefolder-redirect) + * [2. Check the registry policy](#2-check-the-registry-policy) + * [3. Check the BrowserExecutableFolder redirect](#3-check-the-browserexecutablefolder-redirect) * [Triggering a force-update](#triggering-a-force-update) - * [Diagnostics tools for deeper troubleshooting)](#diagnostics-tools-for-deeper-troubleshooting) + * [Diagnostics tools for deeper troubleshooting](#diagnostics-tools-for-deeper-troubleshooting) * [Common issues and resolution](#common-issues-and-resolution) * [Reverting downgrading the WebView Runtime](#reverting-downgrading-the-webview-runtime) * [Option 1: Disable group policy (recommended)](#option-1-disable-group-policy-recommended) @@ -47,6 +47,7 @@ In an enterprise, the IT Admin can downgrade the WebView Runtime to a previous v * [Option 3: Automatic expiry](#option-3-automatic-expiry) * [Post-revert behavior](#post-revert-behavior) * [Escalating and contacting the WebView2 team](#escalating-and-contacting-the-webview2-team) +* [See also](#see-also) Policy documentation: [DowngradeVersion](/deployedge/microsoft-edge-webview-policies#downgradeversion) in _Microsoft Edge WebView2 - Policies_. From 3cbe7de26825b022d4146853ee74d6b64e94967b Mon Sep 17 00:00:00 2001 From: Michael Hoffman <45407486+mikehoffms@users.noreply.github.com> Date: Thu, 20 Aug 2026 08:56:14 -0700 Subject: [PATCH 07/28] 2nd Writer/Editor pass --- .../webview2/how-to/enterprise-downgrade.md | 176 +++++++++--------- 1 file changed, 86 insertions(+), 90 deletions(-) diff --git a/microsoft-edge/webview2/how-to/enterprise-downgrade.md b/microsoft-edge/webview2/how-to/enterprise-downgrade.md index 3a8a0fc661..09aee1bc14 100644 --- a/microsoft-edge/webview2/how-to/enterprise-downgrade.md +++ b/microsoft-edge/webview2/how-to/enterprise-downgrade.md @@ -10,13 +10,14 @@ ms.date: 08/19/2026 --- # Enterprise downgrade of the WebView Runtime to a previous version -In an enterprise, the IT Admin can downgrade the WebView Runtime to a previous version, as a temporary measure. + +In an enterprise, the IT Admin can downgrade the WebView Runtime to a previous version, as a temporary measure, by using the `DowngradeVersion` policy. When using the Evergreen Runtime, if a new Runtime version introduces a regression, each WebView2 app and each Windows component that uses the WebView2 Runtime is likely to be impacted. Enterprise Downgrade offers a short-term mitigation approach for the IT Admin to restore impacted productivity. **Detailed contents:** -* [Overview](#overview) - * [What enterprise downgrade solves](#what-enterprise-downgrade-solves) +* [Overview of enterprise downgrade](#overview-of-enterprise-downgrade) + * [How enterprise downgrade works](#how-enterprise-downgrade-works) * [Why enterprise downgrade exists](#why-enterprise-downgrade-exists) - * [Applicable applications](#applicable-applications) + * [Applicable WebView2 apps](#applicable-webview2-apps) * [Policy configuration and precedence](#policy-configuration-and-precedence) * [Core design principles](#core-design-principles) * [Temporarily downgrading the WebView2 Runtime](#temporarily-downgrading-the-webview2-runtime) @@ -31,7 +32,7 @@ In an enterprise, the IT Admin can downgrade the WebView Runtime to a previous v * [Risks of downgrading the WebView2 Runtime](#risks-of-downgrading-the-webview2-runtime) * [Security risks](#security-risks) * [Data integrity risks](#data-integrity-risks) - * [Application compatibility risks](#application-compatibility-risks) + * [App compatibility risks](#app-compatibility-risks) * [Operational risks](#operational-risks) * [Testing and troubleshooting downgrading of the Runtime](#testing-and-troubleshooting-downgrading-of-the-runtime) * [Verifying that the Runtime downgrade was applied](#verifying-that-the-runtime-downgrade-was-applied) @@ -49,49 +50,46 @@ In an enterprise, the IT Admin can downgrade the WebView Runtime to a previous v * [Escalating and contacting the WebView2 team](#escalating-and-contacting-the-webview2-team) * [See also](#see-also) -Policy documentation: [DowngradeVersion](/deployedge/microsoft-edge-webview-policies#downgradeversion) in _Microsoft Edge WebView2 - Policies_. - -## Overview +## Overview of enterprise downgrade -**WebView2** is a browser control that allows Windows applications (such as Microsoft Teams, Outlook, and third-party enterprise software) to embed web content using the Microsoft Edge rendering engine. The **Evergreen** distribution model means the WebView2 Runtime updates automatically alongside Edge — applications always run on the latest version without manual intervention. + +In an enterprise, the IT Admin can downgrade the WebView Runtime to a previous version, as a temporary measure, by using the `DowngradeVersion` policy. When using the Evergreen Runtime, if a new Runtime version introduces a regression, each WebView2 app and each Windows component that uses the WebView2 Runtime is likely to be impacted. Enterprise Downgrade offers a short-term mitigation approach for the IT Admin to restore impacted productivity. -While Evergreen ensures applications get security patches and feature improvements automatically, it also means that if a new Runtime version introduces a regression, each application and Windows component that uses them is likely to be impacted. Although enterprise IT Admins cannot uninstall the impacting update, Enterprise Downgrade offers a short-term mitigation approach to restore impacted productivity. +See [DowngradeVersion](/deployedge/microsoft-edge-webview-policies#downgradeversion) in _Microsoft Edge WebView2 - Policies_. The `DowngradeVersion` policy is a controlled version downgrade capability that allows an enterprise IT Admin to temporarily revert a specific WebView2 application (WebView2 app) to use a previous version of the WebView2 Runtime via Group Policy when a critical regression disrupts business operations. +The **Evergreen** distribution model means that the WebView2 Runtime updates automatically alongside Microsoft Edge, so that the WebView2 app always runs on the latest version of the WebView2 Runtime, without manual intervention. The Evergreen WebView2 Runtime ensures that the WebView2 app gets security patches and feature improvements automatically. The enterprise IT Admin cannot uninstall the impacting WebView2 Runtime update. - -#### What enterprise downgrade solves +**WebView2** is a browser control that allows Windows applications (such as Microsoft Teams, Outlook, and third-party enterprise software) to embed web content by using the Microsoft Edge rendering engine. -The [DowngradeVersion](/deployedge/microsoft-edge-webview-policies#downgradeversion) policy is a controlled version downgrade capability that allows an enterprise IT Admin to temporarily revert specific WebView2 applications to a previous Runtime version via Group Policy when a critical regression disrupts business operations. -How enterprise downgrade works: + +#### How enterprise downgrade works -1. The IT Admin identifies that a new WebView2 version has broken a specific application. +1. The IT Admin identifies that a new WebView2 Runtime version has broken a specific WebView2 app. -1. The IT Admin sets a Group Policy specifying: "For this application, use version X instead of the latest." +1. The IT Admin sets a Group Policy that specifies that for this WebView2 app, use a specific previous version of the WebView2 Runtime, instead of the latest WebView2 Runtime. - Only N-1 or N-2 relative to the current Evergreen version is supported. Downgrades to versions beyond N-2 are rejected. + Only WebView2 Runtime version N-1 or N-2 relative to the current Evergreen WebView2 Runtime version is supported. Downgrading to a version of the WebView2 Runtime that's earlier than version N-2 is rejected. -1. The Edge Updater downloads and installs the older WebView2 Runtime version **side-by-side** with the current WebView2 Runtime. +1. The Edge Updater downloads and installs the older WebView2 Runtime version _side-by-side_ with the current WebView2 Runtime. -1. The WebView2 Loader redirects only the targeted application to the older WebView2 Runtime. +1. The WebView2 Loader redirects only the targeted WebView2 app to the older WebView2 Runtime. -1. All other applications on the device continue using the latest version unaffected. +1. All other WebView2 apps on the device continue using the latest WebView2 Runtime version; they are unaffected by the downgrade. -1. The downgrade automatically expires once the pinned version is no longer within the two most recent previous versions. +1. The downgrade automatically expires after the pinned version is no longer within the two most recent previous versions of the WebView2 Runtime. #### Why enterprise downgrade exists -In mission-critical enterprise environments, unexpected regressions in the WebView2 Runtime can halt business workflows with no immediate remedy. Even brief outages result in lost revenue, missed SLAs, and increased operational costs. - -Enterprise Downgrade provides a **temporary, Admin-controlled version downgrade** for the specific application affected, while the platform team prepares a proper fix. +Enterprise Downgrade is a last-resort recovery tool. Enterprise Downgrade is targeted, time-bound, and managed by the enterprise IT Admin in partnership with WebView2 app owners. Enterprise Downgrade is not a version-pinning mechanism. -🔑 Key Principle: Enterprise Downgrade is a last-resort recovery tool — targeted, time-bound, and managed by the enterprise IT Admin in partnership with application owners. Enterprise Downgrade is not a version-pinning mechanism. +Enterprise Downgrade provides a temporary, Admin-controlled version downgrade for the specific WebView2 app that's affected, while the platform team prepares a proper fix. Enterprise Downgrade should only be used as a last-resort recovery measure, when a critical regression is actively disrupting business operations and no other mitigation (such as a hotfix, feature flag, or update pause) can resolve the issue in a timely manner. The downgrade buys time for the platform team to ship a proper fix; the downgrade is not a substitute for shipping a proper fix. -Mission-critical enterprise environments include, for example: +In mission-critical enterprise environments, unexpected regressions in the WebView2 Runtime can halt business workflows with no immediate remedy. Even brief outages result in lost revenue, missed SLAs, and increased operational costs. Mission-critical enterprise environments include, for example: * Healthcare systems * Financial trading platforms * Retail point-of-sale @@ -99,38 +97,40 @@ Mission-critical enterprise environments include, for example: -#### Applicable applications +#### Applicable WebView2 apps -Enterprise Downgrade does **not** automatically affect any application. It is a policy that an IT Admin must explicitly configure for specific applications. Only then does it apply. +Enterprise Downgrade of the WebView2 Runtime doesn't automatically affect any WebView2 app. The IT Admin must explicitly configure the `DowngradeVersion` policy for a specific WebView2 app. The policy then applies only to that specific WebView2 app. -**Which apps can be targeted:** +The following types of WebView2 apps can be targeted: -* Any WebView2 Evergreen application running on enterprise-managed Windows devices. +* Any WebView2 Evergreen-Runtime app running on enterprise-managed Windows devices. -* The IT Admin specifies the target by **executable** name (such as `teams.exe`) or **AUMID** (Application User Model ID, for packaged/MSIX apps). + * The IT Admin specifies the target by either: + * The Application User Model ID (AUMID), for packaged/MSIX apps. + * The executable name (such as `teams.exe`). -* If both an AUMID and exe name entry exist for the same application, the AUMID entry takes precedence. + * If both an AUMID and `.exe` name entry exist for the same WebView2 app, the AUMID entry takes precedence. -**Which apps are NOT affected:** +The following types of WebView2 apps are not affected by the `DowngradeVersion` policy: -* Applications that are not named in the policy continue to use the latest Evergreen Runtime. +* WebView2 apps that aren't specified in the `DowngradeVersion` policy. + * Such apps continue to use the latest WebView2 Evergreen Runtime. -* Consumer or unmanaged devices are entirely out of scope. +* WebView2 apps on consumer devices or unmanaged devices. -* App-bundled (Fixed Version) WebView2 Runtimes are out of scope. +* WebView2 apps that use an app-bundled (Fixed Version) WebView2 Runtime. #### Policy configuration and precedence +HKEY_CURRENT_USER (HKCU) is not supported; this is a machine-level enterprise policy only (HKEY_LOCAL_MACHINE (HKLM)). | Location | Path | |---|---| -| **Group Policy (recommended)** | Computer Configuration > Administrative Templates > Microsoft Edge WebView2 > Configure per-application WebView2 downgrade version. | +| **Group Policy (recommended)** | **Computer Configuration** > **Administrative Templates** > **Microsoft Edge WebView2** > **Configure per-application WebView2 downgrade version** | | **Registry** | `HKLM\Software\Policies\Microsoft\Edge\WebView2\DowngradeVersion` | -📄 Note: HKCU is not supported — this is a machine-level enterprise policy only. - **Precedence when multiple policies exist (highest to lowest):** 1. **DowngradeVersion policy** — always wins. @@ -151,7 +151,7 @@ If both `DowngradeVersion` and `BrowserExecutableFolder` are independently confi * **Automatic Expiry:** A downgraded version remains valid only as long as it is within the two most recent previous versions (N-1 or N-2). Once two subsequent new major versions release beyond the downgraded version, the downgrade expires and the app automatically reverts to the latest Runtime. Microsoft recommends that the IT Admin should remove the stale policy after it auto-expires. -* **Per-App Targeting:** Downgrade is applied per-application, not device-wide. Each application must be individually specified. +* **Per-App Targeting:** Downgrade is applied per-app, not device-wide. Each WebView2 app must be individually specified in the policy. @@ -171,7 +171,7 @@ This is the recommended approach for enterprise environments. Group Policy ensu 1. Enable the policy, and enter this information: - * **Name:** The application identifier (AUMID or exe name, such as `teams.exe`). + * **Name:** The application identifier (AUMID). Or, the `.exe` name, such as `teams.exe`. * **Value:** The target four-part version number (such as 151.0.2178.0). @@ -201,7 +201,7 @@ For targeted configuration on individual machines. Requires local administrator * Name: `teams.exe`, Value: `151.0.2178.0` * Name: `outlook.exe`, Value: `152.0.2164.0` -1. Restart the WebView2 application, for the policy to take effect. +1. Restart the WebView2 app, for the policy to take effect. **Example:** @@ -226,13 +226,13 @@ Value: outlook.exe = "146" If no exact matching folder is found, the policy has no effect, and the Runtime defaults to the `BrowserExecutableFolder` policy or the Evergreen Runtime (the default auto-updating Runtime). -* The updater will **automatically download** the required version if it satisfies N-1/N-2 conditions. The IT Admin doesn't need to pre-stage version folders on disk. +* The updater will **automatically download** the required version if it satisfies the N-1 and/or N-2 conditions. The IT Admin doesn't need to pre-stage version folders on disk. * No restart of the machine is needed, but the WebView2 app must be restarted, and it might take up to 1 hour for the downgrade to take effect. -* Policy application latency: Changes take effect within **1 hour** of deployment. This is aligned with the Microsoft Edge and WebView2 update task cadence. To trigger a force update, see [Triggering a force update](#triggering-a-force-update), below. +* Policy latency for the WebView2 app: Changes take effect within **1 hour** of deployment. This is aligned with the Microsoft Edge and WebView2 update task cadence. To trigger a force update, see [Triggering a force update](#triggering-a-force-update), below. -* Downgrade policy enforcement overrides the following: +* Runtime downgrade policy enforcement overrides the following: * Maintenance windows. * Extended update intervals. * Cached last-check timestamps. @@ -243,17 +243,17 @@ Value: outlook.exe = "146" 1. The IT Admin sets policy by using Group Policy, specifying the `AppId` and `TargetVersion`. -1. The Updater reads the policy, and validates that `TargetVersion` is within N-1 or N-2. +1. The Updater reads the policy, and validates that `TargetVersion` is within N-1 or N-2. -1. Downloads the downgraded version if needed (side-by-side install). +1. Downloads the downgraded version of the WebView2 Runtime, if needed, as a side-by-side install. -1. Sets `BrowserExecutableFolder` policy for the target app to redirect it to the specified Runtime version. +1. Sets `BrowserExecutableFolder` policy for the target app to redirect it to the specified Runtime version. -1. Maintains mapping as long as the downgraded version stays within the supported range. +1. Maintains mapping as long as the downgraded version stays within the supported range. -1. Cleans up and reverts the app to the latest Runtime version when the pinned Runtime version falls outside of the supported range or the policy is removed. +1. Cleans up and reverts the app to the latest Runtime version when the pinned Runtime version falls outside of the supported range or the policy is removed. -📄 Note: If a downgrade policy is active but the target Runtime version is not yet downloaded (such as due to network or disk constraints), applications will continue running on the currently available Runtime until the downgraded bits are present. Applications will NOT fail to launch solely because downgraded bits are pending download. +If a WebView2 Runtime downgrade policy is active but the target WebView2 Runtime version is not yet downloaded (such as due to network or disk constraints), the WebView2 app continues running on the currently available WebView2 Runtime until the earlier WebView2 Runtime is present. The WebView2 app will _not_ fail to launch solely because the downgraded version of the WebView2 Runtime is pending download. @@ -265,10 +265,10 @@ Value: outlook.exe = "146" | Limitation | Detail | |---|---| -| **Version range** | Only N-1 or N-2 relative to the current Evergreen version. Downgrades beyond two versions are rejected. | +| **Version range** | Only version N-1 or N-2 of the WebView2 Runtime relative to the current Evergreen Runtime version is supported. Downgrading to an WebView2 Runtime that's earlier than the two previous Runtime versions is rejected. | | **Version format** | Only major version numbers (digits only). Full version strings, dots, or wildcards are invalid. | -| **Automatic expiry** | A downgraded version remains active only while it is within the two most recent previous versions. Once two subsequent new versions release beyond the pinned version, the downgrade automatically expires and the app reverts to the latest Runtime. | -| **Availability** | Feature available from version 150 onwards only. | +| **Automatic expiry** | A downgraded version of the WebView2 Runtime remains active only while it is within the two most recent previous versions. After two subsequent new versions of the Runtime release beyond the pinned version, the downgrade automatically expires, and the app reverts to the latest WebView2 Runtime. | +| **Availability** | The downgrade feature is available for Microsoft Edge WebView2 version 150 or later, only. | @@ -277,24 +277,20 @@ Value: outlook.exe = "146" | Limitation | Detail | |---|---| | **Enterprise-only** | Not supported on consumer or unmanaged devices. | -| **Machine-level only** | Policy set at HKLM only. HKCU is not supported. No user-level policy or individual user control. | -| **Per-app targeting** | Cannot perform enterprise-wide downgrade across all apps. Each app must be individually targeted. | -| **No developer control** | Only IT Admins can initiate downgrade. Developers cannot trigger downgrade via APIs. | +| **Machine-level only** | Policy can only be set at the level of the local machine (HKEY_LOCAL_MACHINE (HKLM)). Setting the downgrade policy for the current user (HKEY_CURRENT_USER (HKCU)) is not supported; there's no user-level policy, or individual user-level control. | +| **Per-app targeting** | Cannot perform enterprise-wide downgrade across all WebView2 apps. Each WebView2 app must be individually targeted. | +| **No developer control** | Only an IT Admin can initiate downgrading the WebView2 Runtime. A Developer cannot trigger downgrade of the WebView2 Runtime, such as via an API. | | **No indefinite pinning** | The solution does NOT support long-term or permanent version pinning. | #### Shared User Data Folder (UDF) constraints -Applications may share a WebView2 User Data Folder (UDF) to reuse browser state. Accessing the same UDF from different WebView2 Runtime versions is **unsafe** and will result in failures: - -**If App A is downgraded and App B shares the same UDF but is not downgraded:** - -* Both App A and App B will fail fast on launch. +The IT Admin must downgrade all WebView2 apps that share the same User Data Folder (UDF), to use the same WebView2 Runtime version. -* The IT Admin must downgrade all apps that share the same UDF to the same Runtime version. +WebView2 apps can share a WebView2 User Data Folder (UDF) to reuse browser state. Very few apps share a User Data Folder (UDF); the only known apps that share a UDF are the Office Suite apps: Excel, Word, and PowerPoint. -📄 Note: Very few apps share a User Data Folder (UDF). The only known apps that share a UDF are the Office Suite apps: Excel, Word, and PowerPoint. +Accessing the same UDF from different WebView2 Runtime versions is unsafe. If WebView2 app A is downgraded, and WebView2 app B shares the same UDF but is not downgraded, both WebView2 app A and WebView2 app B will fail fast on launch. @@ -322,13 +318,13 @@ Applications may share a WebView2 User Data Folder (UDF) to reuse browser state. -#### Application compatibility risks +#### App compatibility risks | Risk | Description | |---|---| -| **Feature dependency breaks** | Applications using newer WebView2 APIs or behaviours may fail or behave unpredictably after downgrade. | -| **Performance regressions** | Older versions may introduce slower page loads, higher memory usage, and degraded experiences. | -| **App malfunction** | Downgrades can cause applications to malfunction due to reliance on recently introduced features or rendering changes. | +| **Feature dependency breaks** | A WebView2 app that uses newer WebView2 APIs or behaviors might fail or behave unpredictably after downgrading the WebView2 Runtime. | +| **Performance regressions** | Older versions of the WebView2 Runtime might introduce slower page loads, higher memory usage, and degraded experiences. | +| **App malfunction** | Downgrading the WebView2 Runtime can cause a WebView2 app to malfunction, due to reliance on recently introduced features or rendering changes. | @@ -338,10 +334,8 @@ Applications may share a WebView2 User Data Folder (UDF) to reuse browser state. |---|---| | **Version fragmentation** | Supporting downgrade at the app level can lead to version drift across apps on the same device. | | **Sedimentation** | Multiple older versions accumulate on devices over time, increasing complexity. | -| **Increased disk usage** | An additional WebView2 Runtime version is installed side-by-side with the current Evergreen version, consuming extra disk space on each device. | -| **Coordination complexity** | Downgrade requires careful coordination between IT Admins, application owners, and platform teams. | - -⚠️ Given these risks, Enterprise Downgrade should only be used as a last-resort recovery measure — when a critical regression is actively disrupting business operations and no other mitigation (hotfix, feature flag, update pause) can resolve the issue in a timely manner. The downgrade buys time for the platform team to ship a proper fix; the downgrade is not a substitute for shipping a proper fix. +| **Increased disk usage** | An additional WebView2 Runtime version is installed side-by-side with the current Evergreen WebView2 Runtime version, consuming extra disk space on each device. | +| **Coordination complexity** | Downgrade requires careful coordination between the IT Admin, the WebView2 app owner, and the platform team. | @@ -351,7 +345,7 @@ Applications may share a WebView2 User Data Folder (UDF) to reuse browser state. #### Verifying that the Runtime downgrade was applied -After setting the policy and restarting the target WebView2 application: +After setting the WebView2 Runtime downgrade policy and restarting the target WebView2 app, do the following. @@ -361,7 +355,7 @@ After setting the policy and restarting the target WebView2 application: 1. Confirm that a new folder appears, matching the downgraded version (such as `145.x.xxxx.xx`). - The presence of this versioned folder indicates that the updater has fetched and staged the downgraded Runtime. + The presence of this versioned folder indicates that the updater has fetched and staged the downgraded WebView2 Runtime. @@ -381,7 +375,9 @@ After setting the policy and restarting the target WebView2 application: #### Triggering a force-update -After setting the `DowngradeVersion` policy, the Edge Updater needs to download the target version. By default, this happens within ~1 hour (aligned with the Edge/WebView2 update task cadence). To trigger an immediate update, follow the below steps: +After setting the `DowngradeVersion` policy, the Edge Updater needs to download the target version. By default, this happens within approximately 1 hour (aligned with the Edge/WebView2 update task cadence). + +To trigger an immediate update: 1. Open PowerShell as Administrator. @@ -395,7 +391,7 @@ After setting the `DowngradeVersion` policy, the Edge Updater needs to download 1. Wait a few minutes for the download to complete. -1. Restart the WebView2 application. +1. Restart the WebView2 app. @@ -415,12 +411,12 @@ The following tools are for **troubleshooting issues** — they are not required | Symptom | Likely Cause | Resolution | |---|---|---| -| App still running on latest version | App not restarted | Restart the WebView2 application (not the machine). | -| Downgraded folder not appearing | Version outside N-1/N-2 range | Verify the target version is within the two most recent previous versions | -| App fails fast on launch (all apps sharing UDF) | Shared UDF version mismatch | Downgrade ALL apps using the same User Data Folder to the same version | -| Policy not taking effect | Incorrect key path or value format | Verify HKLM path, value name format (AUMID or exe), and 4 part value | -| Multiple apps impacted unexpectedly | Shared User Data Folder | Identify UDF sharing and ensure all affected apps are aligned | -| Downgrade auto-reverted unexpectedly | Pinned version fell outside supported range | Expected behavior — downgrade expires once the version is no longer within N-1/N-2 | +| App still running on latest version | App not restarted. | Restart the WebView2 app (not the machine). | +| Downgraded folder not appearing | Version is outside the "N-1 or N-2" range. | Verify that the target version is within the two most recent previous versions. | +| App fails fast on launch (all apps sharing a User Data Folder (UDF)). | Shared UDF version mismatch. | Downgrade all apps that use the same UDF to the same version. | +| Policy not taking effect. | Incorrect key path or value format. | Verify the HKLM path, the value name format (AUMID or `exe`), and four-part numeric format (such as 151.0.2178.0). | +| Multiple apps are impacted unexpectedly. | Shared User Data Folder | Identify User Data Folder (UDF) sharing, and make sure all affected apps are aligned. | +| The downgrade auto-reverted unexpectedly. | Pinned version fell outside supported range | Expected behavior — downgrade expires once the version is no longer within N-1/N-2 | @@ -430,6 +426,8 @@ The following tools are for **troubleshooting issues** — they are not required #### Option 1: Disable group policy (recommended) +Important: Do not delete registry keys directly. Always use Group Policy (GPO) to disable the policy, to ensure clean removal and avoid orphaned configuration. + If GPO was used to configure downgrade: 1. Open the Group Policy Editor (`gpedit.msc`). @@ -438,16 +436,16 @@ If GPO was used to configure downgrade: 1. Set "**Configure per-application WebView2 downgrade version**" to **Disabled** or **Not Configured**. -1. Restart the WebView2 application. +1. Restart the WebView2 app. The app will revert to the latest Evergreen Runtime on next launch. -📄 Important: Do NOT delete registry keys directly. Always use Group Policy (GPO) to disable the policy, to ensure clean removal and avoid orphaned configuration. - #### Option 2: Remove the policy via the registry +Caution: Direct registry manipulation should only be used if the original policy was set via Registry Editor. If Group Policy (GPO) was used, always revert by using GPO, to ensure consistency. + If the policy was originally set directly via Registry (not recommended in production): 1. Open `regedit` as Administrator. @@ -456,9 +454,7 @@ If the policy was originally set directly via Registry (not recommended in produ 1. Delete the specific value (such as`teams.exe`). -1. Restart the WebView2 application. - -⚠️ Caution: Direct registry manipulation should only be used if the original policy was set via Registry Editor. If GPO was used, always revert using GPO to ensure consistency. +1. Restart the WebView2 app. @@ -480,8 +476,8 @@ The downgrade expires automatically when the pinned version is no longer within | Action | What Happens | |---|---| -| **Application restart** | App picks up the latest Runtime on next launch. | -| **BrowserExecutableFolder** | Automatically removed; app returns to default Runtime path. | +| **Application restart** | The WebView2 app picks up the latest WebView Runtime during the next launch of the app. | +| **BrowserExecutableFolder** | Automatically removed; the WebView2 app returns to using the default WebView2 Runtime path. | | **Downgraded Runtime bits** | Cleaned up by the updater on a scheduled cadence. | | **User data** | Remains in place; no automatic data migration occurs. | From 25e202a44fe3d88408a11ceb437c26d511d908aa Mon Sep 17 00:00:00 2001 From: Michael Hoffman <45407486+mikehoffms@users.noreply.github.com> Date: Thu, 20 Aug 2026 09:02:58 -0700 Subject: [PATCH 08/28] previous->earlier --- microsoft-edge/toc.yml | 2 +- microsoft-edge/webview2/concepts/enterprise.md | 2 +- microsoft-edge/webview2/how-to/enterprise-downgrade.md | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/microsoft-edge/toc.yml b/microsoft-edge/toc.yml index 86a6a49481..da575754d1 100644 --- a/microsoft-edge/toc.yml +++ b/microsoft-edge/toc.yml @@ -2360,7 +2360,7 @@ href: ./webview2/concepts/enterprise.md displayName: Manage WebView2 applications # old title - - name: Enterprise downgrade of the WebView Runtime to a previous version + - name: Enterprise downgrade of the WebView Runtime to an earlier version href: ./webview2/how-to/enterprise-downgrade.md - name: Distribute an app as a single executable file diff --git a/microsoft-edge/webview2/concepts/enterprise.md b/microsoft-edge/webview2/concepts/enterprise.md index 0323071463..17797646a0 100644 --- a/microsoft-edge/webview2/concepts/enterprise.md +++ b/microsoft-edge/webview2/concepts/enterprise.md @@ -137,7 +137,7 @@ See [Update Microsoft Edge](/intune/configmgr/apps/deploy-use/deploy-edge#update * [Distribute your app and the WebView2 Runtime](./distribution.md) - Evergreen vs. fixed version of the WebView2 Runtime. -* [Enterprise downgrade of the WebView Runtime to a previous version](../how-to/enterprise-downgrade.md) +* [Enterprise downgrade of the WebView Runtime to an earlier version](../how-to/enterprise-downgrade.md) Microsoft Edge Enterprise documentation: diff --git a/microsoft-edge/webview2/how-to/enterprise-downgrade.md b/microsoft-edge/webview2/how-to/enterprise-downgrade.md index 09aee1bc14..e76429dcb2 100644 --- a/microsoft-edge/webview2/how-to/enterprise-downgrade.md +++ b/microsoft-edge/webview2/how-to/enterprise-downgrade.md @@ -1,5 +1,5 @@ --- -title: Enterprise downgrade of the WebView Runtime to a previous version +title: Enterprise downgrade of the WebView Runtime to an earlier version description: WebView2 Enterprise Downgrade guide. author: MSEdgeTeam ms.author: msedgedevrel @@ -8,7 +8,7 @@ ms.service: microsoft-edge ms.subservice: webview ms.date: 08/19/2026 --- -# Enterprise downgrade of the WebView Runtime to a previous version +# Enterprise downgrade of the WebView Runtime to an earlier version In an enterprise, the IT Admin can downgrade the WebView Runtime to a previous version, as a temporary measure, by using the `DowngradeVersion` policy. When using the Evergreen Runtime, if a new Runtime version introduces a regression, each WebView2 app and each Windows component that uses the WebView2 Runtime is likely to be impacted. Enterprise Downgrade offers a short-term mitigation approach for the IT Admin to restore impacted productivity. From e7f322aaf4e391373cf97e2300f046994f05390c Mon Sep 17 00:00:00 2001 From: Michael Hoffman <45407486+mikehoffms@users.noreply.github.com> Date: Thu, 20 Aug 2026 09:43:00 -0700 Subject: [PATCH 09/28] task-oriented title --- microsoft-edge/toc.yml | 2 +- microsoft-edge/webview2/concepts/enterprise.md | 2 +- .../webview2/how-to/enterprise-downgrade.md | 12 +++++------- 3 files changed, 7 insertions(+), 9 deletions(-) diff --git a/microsoft-edge/toc.yml b/microsoft-edge/toc.yml index da575754d1..d796ee67fb 100644 --- a/microsoft-edge/toc.yml +++ b/microsoft-edge/toc.yml @@ -2360,7 +2360,7 @@ href: ./webview2/concepts/enterprise.md displayName: Manage WebView2 applications # old title - - name: Enterprise downgrade of the WebView Runtime to an earlier version + - name: Downgrade the WebView Runtime to an earlier version href: ./webview2/how-to/enterprise-downgrade.md - name: Distribute an app as a single executable file diff --git a/microsoft-edge/webview2/concepts/enterprise.md b/microsoft-edge/webview2/concepts/enterprise.md index 17797646a0..0793e4ef0d 100644 --- a/microsoft-edge/webview2/concepts/enterprise.md +++ b/microsoft-edge/webview2/concepts/enterprise.md @@ -137,7 +137,7 @@ See [Update Microsoft Edge](/intune/configmgr/apps/deploy-use/deploy-edge#update * [Distribute your app and the WebView2 Runtime](./distribution.md) - Evergreen vs. fixed version of the WebView2 Runtime. -* [Enterprise downgrade of the WebView Runtime to an earlier version](../how-to/enterprise-downgrade.md) +* [Downgrade the WebView Runtime to an earlier version](../how-to/enterprise-downgrade.md) Microsoft Edge Enterprise documentation: diff --git a/microsoft-edge/webview2/how-to/enterprise-downgrade.md b/microsoft-edge/webview2/how-to/enterprise-downgrade.md index e76429dcb2..7f3e42ff35 100644 --- a/microsoft-edge/webview2/how-to/enterprise-downgrade.md +++ b/microsoft-edge/webview2/how-to/enterprise-downgrade.md @@ -1,6 +1,6 @@ --- -title: Enterprise downgrade of the WebView Runtime to an earlier version -description: WebView2 Enterprise Downgrade guide. +title: Downgrade the WebView Runtime to an earlier version +description: If a new version of the WebView2 Runtime version introduces a regression in a specific WebView2 app, an IT Admin can downgrade the WebView Runtime to a previous version, by using the DowngradeVersion policy, as a temporary solution. author: MSEdgeTeam ms.author: msedgedevrel ms.topic: article @@ -8,10 +8,9 @@ ms.service: microsoft-edge ms.subservice: webview ms.date: 08/19/2026 --- -# Enterprise downgrade of the WebView Runtime to an earlier version +# Downgrade the WebView Runtime to an earlier version - -In an enterprise, the IT Admin can downgrade the WebView Runtime to a previous version, as a temporary measure, by using the `DowngradeVersion` policy. When using the Evergreen Runtime, if a new Runtime version introduces a regression, each WebView2 app and each Windows component that uses the WebView2 Runtime is likely to be impacted. Enterprise Downgrade offers a short-term mitigation approach for the IT Admin to restore impacted productivity. +If a new version of the WebView2 Runtime version introduces a regression in a specific WebView2 app, an IT Admin can downgrade the WebView Runtime to a previous version, by using the `DowngradeVersion` policy, as a temporary solution. **Detailed contents:** * [Overview of enterprise downgrade](#overview-of-enterprise-downgrade) @@ -54,7 +53,6 @@ In an enterprise, the IT Admin can downgrade the WebView Runtime to a previous v ## Overview of enterprise downgrade - In an enterprise, the IT Admin can downgrade the WebView Runtime to a previous version, as a temporary measure, by using the `DowngradeVersion` policy. When using the Evergreen Runtime, if a new Runtime version introduces a regression, each WebView2 app and each Windows component that uses the WebView2 Runtime is likely to be impacted. Enterprise Downgrade offers a short-term mitigation approach for the IT Admin to restore impacted productivity. See [DowngradeVersion](/deployedge/microsoft-edge-webview-policies#downgradeversion) in _Microsoft Edge WebView2 - Policies_. The `DowngradeVersion` policy is a controlled version downgrade capability that allows an enterprise IT Admin to temporarily revert a specific WebView2 application (WebView2 app) to use a previous version of the WebView2 Runtime via Group Policy when a critical regression disrupts business operations. @@ -416,7 +414,7 @@ The following tools are for **troubleshooting issues** — they are not required | App fails fast on launch (all apps sharing a User Data Folder (UDF)). | Shared UDF version mismatch. | Downgrade all apps that use the same UDF to the same version. | | Policy not taking effect. | Incorrect key path or value format. | Verify the HKLM path, the value name format (AUMID or `exe`), and four-part numeric format (such as 151.0.2178.0). | | Multiple apps are impacted unexpectedly. | Shared User Data Folder | Identify User Data Folder (UDF) sharing, and make sure all affected apps are aligned. | -| The downgrade auto-reverted unexpectedly. | Pinned version fell outside supported range | Expected behavior — downgrade expires once the version is no longer within N-1/N-2 | +| The downgrade auto-reverted unexpectedly. | Pinned version fell outside supported range | It is expected behavior, that the downgrade of the WebView2 Runtime expires after the Runtime version is no longer within version N-1 or N-2 (the two earlier versions of the Runtime). | From 9cd39d260a8c983af67d34377ab9027a5b5b0ff9 Mon Sep 17 00:00:00 2001 From: Michael Hoffman <45407486+mikehoffms@users.noreply.github.com> Date: Thu, 20 Aug 2026 09:58:04 -0700 Subject: [PATCH 10/28] section in enterprise.md --- .../webview2/concepts/enterprise.md | 20 +++++++++---------- .../webview2/how-to/enterprise-downgrade.md | 8 ++++---- 2 files changed, 13 insertions(+), 15 deletions(-) diff --git a/microsoft-edge/webview2/concepts/enterprise.md b/microsoft-edge/webview2/concepts/enterprise.md index 0793e4ef0d..35d9944452 100644 --- a/microsoft-edge/webview2/concepts/enterprise.md +++ b/microsoft-edge/webview2/concepts/enterprise.md @@ -20,8 +20,8 @@ Feedback from IT Admins and developers is welcome, through the [WebView2Feedback * [Group policies for WebView2](#group-policies-for-webview2) * [Update policies](#update-policies) * [Suppressing WebView2 Runtime updates](#suppressing-webview2-runtime-updates) - * [Enterprise downgrade of Runtime to previous version](#enterprise-downgrade-of-runtime-to-previous-version) * [Evergreen Runtime is recommended, rather than a fixed version](#evergreen-runtime-is-recommended-rather-than-a-fixed-version) + * [Downgrading the WebView Runtime to an earlier version](#downgrading-the-webview-runtime-to-an-earlier-version) * [Rapid Response to Chromium vulnerabilities](#rapid-response-to-chromium-vulnerabilities) * [Microsoft Edge Lifecycle Policy](#microsoft-edge-lifecycle-policy) * [Browser policies](#browser-policies) @@ -53,16 +53,6 @@ An IT Admin can suppress updating of the WebView2 Runtime, if auto-updating need However, users should not stop updating their WebView2 Runtime; users should not remain on an older version of the WebView2 Runtime. Using older versions of the WebView2 Runtime isn't recommended. Security updates and servicing updates are only available on the latest Stable channel release (Edge Stable) and the latest Beta channel release (Edge Beta). If you use older releases of the Microsoft WebView2 Runtime, you won't receive the latest quality and security updates. - -###### Enterprise downgrade of Runtime to previous version - -With the WebView2 152 release, the Enterprise Downgrade feature is generally available. - -Enterprise Downgrade is a temporary, IT Admin-controlled capability that allows a specific WebView2 application to revert to a previous runtime version in the event of a critical regression. - -See [WebView2 Enterprise Downgrade Guide] (todo). - - ###### Evergreen Runtime is recommended, rather than a fixed version @@ -77,6 +67,14 @@ See also: * [Evergreen vs. fixed version of the WebView2 Runtime](./evergreen-vs-fixed-version.md) + +###### Downgrading the WebView Runtime to an earlier version + +Enterprise Downgrade is a temporary, IT Admin-controlled capability that allows a specific WebView2 application to revert to a previous runtime version in the event of a critical regression. + +See [Downgrade the WebView Runtime to an earlier version](../how-to/enterprise-downgrade.md). + + ###### Rapid Response to Chromium vulnerabilities diff --git a/microsoft-edge/webview2/how-to/enterprise-downgrade.md b/microsoft-edge/webview2/how-to/enterprise-downgrade.md index 7f3e42ff35..eaac7531ee 100644 --- a/microsoft-edge/webview2/how-to/enterprise-downgrade.md +++ b/microsoft-edge/webview2/how-to/enterprise-downgrade.md @@ -1,6 +1,6 @@ --- title: Downgrade the WebView Runtime to an earlier version -description: If a new version of the WebView2 Runtime version introduces a regression in a specific WebView2 app, an IT Admin can downgrade the WebView Runtime to a previous version, by using the DowngradeVersion policy, as a temporary solution. +description: If a new version of the WebView2 Runtime introduces a critical regression in a specific WebView2 app, an IT Admin can downgrade the WebView Runtime for that app to a previous version, by using the DowngradeVersion policy, as a temporary solution. author: MSEdgeTeam ms.author: msedgedevrel ms.topic: article @@ -10,7 +10,7 @@ ms.date: 08/19/2026 --- # Downgrade the WebView Runtime to an earlier version -If a new version of the WebView2 Runtime version introduces a regression in a specific WebView2 app, an IT Admin can downgrade the WebView Runtime to a previous version, by using the `DowngradeVersion` policy, as a temporary solution. +If a new version of the WebView2 Runtime introduces a critical regression in a specific WebView2 app, an IT Admin can downgrade the WebView Runtime for that app to a previous version, by using the `DowngradeVersion` policy, as a temporary solution. **Detailed contents:** * [Overview of enterprise downgrade](#overview-of-enterprise-downgrade) @@ -53,9 +53,9 @@ If a new version of the WebView2 Runtime version introduces a regression in a sp ## Overview of enterprise downgrade -In an enterprise, the IT Admin can downgrade the WebView Runtime to a previous version, as a temporary measure, by using the `DowngradeVersion` policy. When using the Evergreen Runtime, if a new Runtime version introduces a regression, each WebView2 app and each Windows component that uses the WebView2 Runtime is likely to be impacted. Enterprise Downgrade offers a short-term mitigation approach for the IT Admin to restore impacted productivity. +In an enterprise, the IT Admin can downgrade the WebView Runtime to a previous version, as a temporary measure, by using the `DowngradeVersion` policy. When using the Evergreen Runtime, if a new Runtime version introduces a critical regression, each WebView2 app and each Windows component that uses the WebView2 Runtime is likely to be impacted. Enterprise Downgrade offers a short-term mitigation approach for the IT Admin to restore impacted productivity. -See [DowngradeVersion](/deployedge/microsoft-edge-webview-policies#downgradeversion) in _Microsoft Edge WebView2 - Policies_. The `DowngradeVersion` policy is a controlled version downgrade capability that allows an enterprise IT Admin to temporarily revert a specific WebView2 application (WebView2 app) to use a previous version of the WebView2 Runtime via Group Policy when a critical regression disrupts business operations. +The `DowngradeVersion` policy is a controlled version downgrade capability that allows an enterprise IT Admin to temporarily revert a specific WebView2 application (WebView2 app) to use a previous version of the WebView2 Runtime via Group Policy when a critical regression disrupts business operations. See [DowngradeVersion](/deployedge/microsoft-edge-webview-policies#downgradeversion) in _Microsoft Edge WebView2 - Policies_. The **Evergreen** distribution model means that the WebView2 Runtime updates automatically alongside Microsoft Edge, so that the WebView2 app always runs on the latest version of the WebView2 Runtime, without manual intervention. The Evergreen WebView2 Runtime ensures that the WebView2 app gets security patches and feature improvements automatically. The enterprise IT Admin cannot uninstall the impacting WebView2 Runtime update. From ff08f906ed6482ee8c1f7012d85e9fe86003966f Mon Sep 17 00:00:00 2001 From: Michael Hoffman <45407486+mikehoffms@users.noreply.github.com> Date: Thu, 20 Aug 2026 10:04:11 -0700 Subject: [PATCH 11/28] clarify "a previous runtime version" --- microsoft-edge/webview2/concepts/enterprise.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/microsoft-edge/webview2/concepts/enterprise.md b/microsoft-edge/webview2/concepts/enterprise.md index 35d9944452..267984302e 100644 --- a/microsoft-edge/webview2/concepts/enterprise.md +++ b/microsoft-edge/webview2/concepts/enterprise.md @@ -70,7 +70,7 @@ See also: ###### Downgrading the WebView Runtime to an earlier version -Enterprise Downgrade is a temporary, IT Admin-controlled capability that allows a specific WebView2 application to revert to a previous runtime version in the event of a critical regression. +Enterprise Downgrade is a temporary, IT Admin-controlled capability that allows a specific WebView2 app to revert to using an earlier version of the WebView2 Runtime, in the event of a critical regression in the WebView2 app when using the latest version of the WebView2 Runtime. See [Downgrade the WebView Runtime to an earlier version](../how-to/enterprise-downgrade.md). From 67292e3b27dff7e1129272319574c060b0cd14e1 Mon Sep 17 00:00:00 2001 From: Michael Hoffman <45407486+mikehoffms@users.noreply.github.com> Date: Thu, 20 Aug 2026 20:58:48 -0700 Subject: [PATCH 12/28] 2 --- microsoft-edge/toc.yml | 2 +- microsoft-edge/webview2/concepts/enterprise.md | 4 ++-- microsoft-edge/webview2/how-to/enterprise-downgrade.md | 4 ++-- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/microsoft-edge/toc.yml b/microsoft-edge/toc.yml index d796ee67fb..68912e797e 100644 --- a/microsoft-edge/toc.yml +++ b/microsoft-edge/toc.yml @@ -2360,7 +2360,7 @@ href: ./webview2/concepts/enterprise.md displayName: Manage WebView2 applications # old title - - name: Downgrade the WebView Runtime to an earlier version + - name: Downgrade the WebView2 Runtime to an earlier version href: ./webview2/how-to/enterprise-downgrade.md - name: Distribute an app as a single executable file diff --git a/microsoft-edge/webview2/concepts/enterprise.md b/microsoft-edge/webview2/concepts/enterprise.md index 267984302e..d7632ab101 100644 --- a/microsoft-edge/webview2/concepts/enterprise.md +++ b/microsoft-edge/webview2/concepts/enterprise.md @@ -72,7 +72,7 @@ See also: Enterprise Downgrade is a temporary, IT Admin-controlled capability that allows a specific WebView2 app to revert to using an earlier version of the WebView2 Runtime, in the event of a critical regression in the WebView2 app when using the latest version of the WebView2 Runtime. -See [Downgrade the WebView Runtime to an earlier version](../how-to/enterprise-downgrade.md). +See [Downgrade the WebView2 Runtime to an earlier version](../how-to/enterprise-downgrade.md). @@ -135,7 +135,7 @@ See [Update Microsoft Edge](/intune/configmgr/apps/deploy-use/deploy-edge#update * [Distribute your app and the WebView2 Runtime](./distribution.md) - Evergreen vs. fixed version of the WebView2 Runtime. -* [Downgrade the WebView Runtime to an earlier version](../how-to/enterprise-downgrade.md) +* [Downgrade the WebView2 Runtime to an earlier version](../how-to/enterprise-downgrade.md) Microsoft Edge Enterprise documentation: diff --git a/microsoft-edge/webview2/how-to/enterprise-downgrade.md b/microsoft-edge/webview2/how-to/enterprise-downgrade.md index eaac7531ee..97e2a50f95 100644 --- a/microsoft-edge/webview2/how-to/enterprise-downgrade.md +++ b/microsoft-edge/webview2/how-to/enterprise-downgrade.md @@ -1,5 +1,5 @@ --- -title: Downgrade the WebView Runtime to an earlier version +title: Downgrade the WebView2 Runtime to an earlier version description: If a new version of the WebView2 Runtime introduces a critical regression in a specific WebView2 app, an IT Admin can downgrade the WebView Runtime for that app to a previous version, by using the DowngradeVersion policy, as a temporary solution. author: MSEdgeTeam ms.author: msedgedevrel @@ -8,7 +8,7 @@ ms.service: microsoft-edge ms.subservice: webview ms.date: 08/19/2026 --- -# Downgrade the WebView Runtime to an earlier version +# Downgrade the WebView2 Runtime to an earlier version If a new version of the WebView2 Runtime introduces a critical regression in a specific WebView2 app, an IT Admin can downgrade the WebView Runtime for that app to a previous version, by using the `DowngradeVersion` policy, as a temporary solution. From 3e0a2e155bac448672c1a5ce437b6c6ed5887a7b Mon Sep 17 00:00:00 2001 From: Michael Hoffman <45407486+mikehoffms@users.noreply.github.com> Date: Thu, 20 Aug 2026 21:10:58 -0700 Subject: [PATCH 13/28] local vs. ext links --- .../webview2/how-to/enterprise-downgrade.md | 30 +++++++++++-------- 1 file changed, 17 insertions(+), 13 deletions(-) diff --git a/microsoft-edge/webview2/how-to/enterprise-downgrade.md b/microsoft-edge/webview2/how-to/enterprise-downgrade.md index 97e2a50f95..c913580cd1 100644 --- a/microsoft-edge/webview2/how-to/enterprise-downgrade.md +++ b/microsoft-edge/webview2/how-to/enterprise-downgrade.md @@ -1,6 +1,6 @@ --- title: Downgrade the WebView2 Runtime to an earlier version -description: If a new version of the WebView2 Runtime introduces a critical regression in a specific WebView2 app, an IT Admin can downgrade the WebView Runtime for that app to a previous version, by using the DowngradeVersion policy, as a temporary solution. +description: If a new version of the WebView2 Runtime introduces a critical regression in a specific WebView2 app, an IT Admin can downgrade the WebView2 Runtime for that app to a previous version, by using the DowngradeVersion policy, as a temporary solution. author: MSEdgeTeam ms.author: msedgedevrel ms.topic: article @@ -9,8 +9,9 @@ ms.subservice: webview ms.date: 08/19/2026 --- # Downgrade the WebView2 Runtime to an earlier version + -If a new version of the WebView2 Runtime introduces a critical regression in a specific WebView2 app, an IT Admin can downgrade the WebView Runtime for that app to a previous version, by using the `DowngradeVersion` policy, as a temporary solution. +If a new version of the WebView2 Runtime introduces a critical regression in a specific WebView2 app, an IT Admin can downgrade the WebView2 Runtime for that app to a previous version, by using the `DowngradeVersion` policy, as a temporary solution. **Detailed contents:** * [Overview of enterprise downgrade](#overview-of-enterprise-downgrade) @@ -41,7 +42,7 @@ If a new version of the WebView2 Runtime introduces a critical regression in a s * [Triggering a force-update](#triggering-a-force-update) * [Diagnostics tools for deeper troubleshooting](#diagnostics-tools-for-deeper-troubleshooting) * [Common issues and resolution](#common-issues-and-resolution) -* [Reverting downgrading the WebView Runtime](#reverting-downgrading-the-webview-runtime) +* [Reverting downgrading the WebView2 Runtime](#reverting-downgrading-the-webview2-runtime) * [Option 1: Disable group policy (recommended)](#option-1-disable-group-policy-recommended) * [Option 2: Remove the policy via the registry](#option-2-remove-the-policy-via-the-registry) * [Option 3: Automatic expiry](#option-3-automatic-expiry) @@ -53,7 +54,7 @@ If a new version of the WebView2 Runtime introduces a critical regression in a s ## Overview of enterprise downgrade -In an enterprise, the IT Admin can downgrade the WebView Runtime to a previous version, as a temporary measure, by using the `DowngradeVersion` policy. When using the Evergreen Runtime, if a new Runtime version introduces a critical regression, each WebView2 app and each Windows component that uses the WebView2 Runtime is likely to be impacted. Enterprise Downgrade offers a short-term mitigation approach for the IT Admin to restore impacted productivity. +In an enterprise, the IT Admin can downgrade the WebView2 Runtime to a previous version, as a temporary measure, by using the `DowngradeVersion` policy. When using the Evergreen Runtime, if a new Runtime version introduces a critical regression, each WebView2 app and each Windows component that uses the WebView2 Runtime is likely to be impacted. Enterprise Downgrade offers a short-term mitigation approach for the IT Admin to restore impacted productivity. The `DowngradeVersion` policy is a controlled version downgrade capability that allows an enterprise IT Admin to temporarily revert a specific WebView2 application (WebView2 app) to use a previous version of the WebView2 Runtime via Group Policy when a critical regression disrupts business operations. See [DowngradeVersion](/deployedge/microsoft-edge-webview-policies#downgradeversion) in _Microsoft Edge WebView2 - Policies_. @@ -193,7 +194,7 @@ For targeted configuration on individual machines. Requires local administrator * Set the value to the target full version string using the four-part numeric format (such as 151.0.2178.0). - * The IT Admin can find the exact four-part version number in the [Microsoft Edge release notes for Stable and Extended Stable Channels](/deployedge/microsoft-edge-relnote-stable-channel) + * The IT Admin can find the exact four-part version number in the [Microsoft Edge release notes for Stable Channel](/deployedge/microsoft-edge-relnote-stable-channel). * **Example values:** * Name: `teams.exe`, Value: `151.0.2178.0` @@ -418,7 +419,7 @@ The following tools are for **troubleshooting issues** — they are not required -## Reverting downgrading the WebView Runtime +## Reverting downgrading the WebView2 Runtime @@ -474,7 +475,7 @@ The downgrade expires automatically when the pinned version is no longer within | Action | What Happens | |---|---| -| **Application restart** | The WebView2 app picks up the latest WebView Runtime during the next launch of the app. | +| **Application restart** | The WebView2 app picks up the latest WebView2 Runtime during the next launch of the app. | | **BrowserExecutableFolder** | Automatically removed; the WebView2 app returns to using the default WebView2 Runtime path. | | **Downgraded Runtime bits** | Cleaned up by the updater on a scheduled cadence. | | **User data** | Remains in place; no automatic data migration occurs. | @@ -486,15 +487,15 @@ The downgrade expires automatically when the pinned version is no longer within | Aspect | Value | |---|---| | **Area Path:** | Edge\Web Experience\WebView2\Distribution | -| **DL:** | [wv2addr@microsoft.com](mailto:wv2addr@microsoft.com) | +| **DL:** | [wv2addr@microsoft.com](mailto:wv2addr@microsoft.com) | **Escalation Path:** -1. Enterprise Admin contacts Microsoft CSS. +1. The Enterprise Admin contacts Microsoft CSS. -1. CSS troubleshoots using this guide. +1. CSS troubleshoots the issue by using this article. -1. If unresolved → CSS escalates to WebView2 Platform team ICM. +1. If unresolved, CSS escalates the issue to the WebView2 Platform team ICM. Owning Service: Edge Browser customer incidents. @@ -508,7 +509,10 @@ See also: ## See also + * [Enterprise management of WebView2 Runtimes](../concepts/enterprise.md) -* [DowngradeVersion](/deployedge/microsoft-edge-webview-policies#downgradeversion) in _Microsoft Edge WebView2 - Policies_. -* [Microsoft Edge release notes for Stable and Extended Stable Channels](/deployedge/microsoft-edge-relnote-stable-channel) * [Contact the WebView2 team](../contact.md) + +External: +* [DowngradeVersion](/deployedge/microsoft-edge-webview-policies#downgradeversion) in _Microsoft Edge WebView2 - Policies_. +* [Microsoft Edge release notes for Stable Channel](/deployedge/microsoft-edge-relnote-stable-channel) From 4c153aa850b0407a241dfface84de7d5294bd437 Mon Sep 17 00:00:00 2001 From: Michael Hoffman <45407486+mikehoffms@users.noreply.github.com> Date: Thu, 20 Aug 2026 22:03:13 -0700 Subject: [PATCH 14/28] expand hklm --- microsoft-edge/webview2/how-to/enterprise-downgrade.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/microsoft-edge/webview2/how-to/enterprise-downgrade.md b/microsoft-edge/webview2/how-to/enterprise-downgrade.md index c913580cd1..3f0879dc26 100644 --- a/microsoft-edge/webview2/how-to/enterprise-downgrade.md +++ b/microsoft-edge/webview2/how-to/enterprise-downgrade.md @@ -214,7 +214,7 @@ Value: outlook.exe = "146" #### Important notes -* Only **HKLM** is supported (HKCU is ignored). +* Only `HKEY_LOCAL_MACHINE` (HKLM) is supported; `HKEY_CURRENT_USER` (HKCU) is ignored. * The following values are not supported: * Major-only values (such as 151). From 8169e693386c64e010b48f64c1b604c68d1f05ab Mon Sep 17 00:00:00 2001 From: Michael Hoffman <45407486+mikehoffms@users.noreply.github.com> Date: Thu, 20 Aug 2026 22:13:10 -0700 Subject: [PATCH 15/28] link to new article in Admin Docs repo --- microsoft-edge/webview2/concepts/enterprise.md | 2 +- microsoft-edge/webview2/how-to/enterprise-downgrade.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/microsoft-edge/webview2/concepts/enterprise.md b/microsoft-edge/webview2/concepts/enterprise.md index d7632ab101..22145a60ad 100644 --- a/microsoft-edge/webview2/concepts/enterprise.md +++ b/microsoft-edge/webview2/concepts/enterprise.md @@ -72,7 +72,7 @@ See also: Enterprise Downgrade is a temporary, IT Admin-controlled capability that allows a specific WebView2 app to revert to using an earlier version of the WebView2 Runtime, in the event of a critical regression in the WebView2 app when using the latest version of the WebView2 Runtime. -See [Downgrade the WebView2 Runtime to an earlier version](../how-to/enterprise-downgrade.md). +See [Downgrade the WebView2 Runtime to an earlier version](/deployedge/webview2-downgrade-runtime). diff --git a/microsoft-edge/webview2/how-to/enterprise-downgrade.md b/microsoft-edge/webview2/how-to/enterprise-downgrade.md index 3f0879dc26..93f5ad0e12 100644 --- a/microsoft-edge/webview2/how-to/enterprise-downgrade.md +++ b/microsoft-edge/webview2/how-to/enterprise-downgrade.md @@ -413,7 +413,7 @@ The following tools are for **troubleshooting issues** — they are not required | App still running on latest version | App not restarted. | Restart the WebView2 app (not the machine). | | Downgraded folder not appearing | Version is outside the "N-1 or N-2" range. | Verify that the target version is within the two most recent previous versions. | | App fails fast on launch (all apps sharing a User Data Folder (UDF)). | Shared UDF version mismatch. | Downgrade all apps that use the same UDF to the same version. | -| Policy not taking effect. | Incorrect key path or value format. | Verify the HKLM path, the value name format (AUMID or `exe`), and four-part numeric format (such as 151.0.2178.0). | +| Policy not taking effect. | Incorrect key path or value format. | Verify the HKEY_LOCAL_MACHINE (HKLM) path, the value name format (AUMID or `exe`), and the four-part numeric format (such as 151.0.2178.0). | | Multiple apps are impacted unexpectedly. | Shared User Data Folder | Identify User Data Folder (UDF) sharing, and make sure all affected apps are aligned. | | The downgrade auto-reverted unexpectedly. | Pinned version fell outside supported range | It is expected behavior, that the downgrade of the WebView2 Runtime expires after the Runtime version is no longer within version N-1 or N-2 (the two earlier versions of the Runtime). | @@ -427,7 +427,7 @@ The following tools are for **troubleshooting issues** — they are not required Important: Do not delete registry keys directly. Always use Group Policy (GPO) to disable the policy, to ensure clean removal and avoid orphaned configuration. -If GPO was used to configure downgrade: +If GPO was used to configure the downgrade: 1. Open the Group Policy Editor (`gpedit.msc`). From 3e998e842025aa10ab0f5a7c4aa50034ee47f5d5 Mon Sep 17 00:00:00 2001 From: Michael Hoffman <45407486+mikehoffms@users.noreply.github.com> Date: Fri, 21 Aug 2026 07:36:57 -0700 Subject: [PATCH 16/28] incorp rvw --- .../webview2/how-to/enterprise-downgrade.md | 107 ++++++++++++++---- 1 file changed, 87 insertions(+), 20 deletions(-) diff --git a/microsoft-edge/webview2/how-to/enterprise-downgrade.md b/microsoft-edge/webview2/how-to/enterprise-downgrade.md index 93f5ad0e12..bb91861e61 100644 --- a/microsoft-edge/webview2/how-to/enterprise-downgrade.md +++ b/microsoft-edge/webview2/how-to/enterprise-downgrade.md @@ -106,10 +106,18 @@ The following types of WebView2 apps can be targeted: * The IT Admin specifies the target by either: * The Application User Model ID (AUMID), for packaged/MSIX apps. - * The executable name (such as `teams.exe`). + * The executable name (such as `ms-teams.exe`). * If both an AUMID and `.exe` name entry exist for the same WebView2 app, the AUMID entry takes precedence. +To find the `.exe` name: + +1. Open Task Manager, and then on the left, select **Details**. + +1. Find the running WebView2 app. + +1. Examine the **Name** column for the WebView2 app, such as `ms-teams.exe` or `olk.exe`. + The following types of WebView2 apps are not affected by the `DowngradeVersion` policy: * WebView2 apps that aren't specified in the `DowngradeVersion` policy. @@ -157,6 +165,65 @@ If both `DowngradeVersion` and `BrowserExecutableFolder` are independently confi ## Temporarily downgrading the WebView2 Runtime + +#### Updating the policy template + +To update the policy template: + +1. Go to [Download and deploy Microsoft Edge for Business](https://explore.microsoft.com/edge/business/download). + +1. In the **Download the latest** section, click one of the following buttons: + + * Windows + * macOS + * Linux + +1. Click a **Download ... Policy** link, such as: + + * **Download Windows 64-bit Policy** + * **Download Windows 32-bit Policy** + * **Download Windows ARM64 Policy** + * **Download macOS Universal Policy** + * **Download Linux (.rpm) Policy** + * **Download Linux (.deb) Policy** + + The **Download Microsoft Edge Policy File** dialog opens. + +1. Click the **Accept and download** button. + + A file is downloaded, such as `MicrosoftEdgePolicyTemplates.cab`. + +1. In Microsoft Edge, select **Settings and more** (**...**), select **Downloads**, and then for the downloaded file, click **Open containing folder**. + + On Windows, File Explorer opens, with the file `MicrosoftEdgePolicyTemplates.cab` selected. + +1. Right-click `MicrosoftEdgePolicyTemplates.cab`, and then select **Open**. + + `MicrosoftEdgePolicyTemplates.zip` appears. + +1. Right-click `MicrosoftEdgePolicyTemplates.zip`, and then select **Extract**. + + The **Select a Destination** dialog opens. + +1. Select the directory such as `C:\Users\local-account\Downloads`, and then click the **Extract** button. + + A folder is created, such as: `C:\Users\local-account\Downloads\MicrosoftEdgePolicyTemplates.zip` + +1. On the left, select `MicrosoftEdgePolicyTemplates.zip`, and then on the right, open the `/windows/` directory. + + The folders `/adm/` and `/admx/` are listed. + +1. Copy the folders `/adm/` and `/admx/` to a `/PolicyDefinitions/` directory. For example, for Windows, copy the `/adm/` and `/admx/` folders to `C:\Windows\PolicyDefinitions\`. + + The **Destination Folder Access Denies** dialog opens, saying "You'll need to provide administrator permission to copy to this folder". + +1. Click the **Continue** button. + + The **User Account Control** dialog opens. + +1. Enter admin credentials. + + #### Option 1: Group Policy (GPO) @@ -170,7 +237,7 @@ This is the recommended approach for enterprise environments. Group Policy ensu 1. Enable the policy, and enter this information: - * **Name:** The application identifier (AUMID). Or, the `.exe` name, such as `teams.exe`. + * **Name:** The application identifier (AUMID). Or, the `.exe` name, such as `ms-teams.exe`. * **Value:** The target four-part version number (such as 151.0.2178.0). @@ -188,7 +255,7 @@ For targeted configuration on individual machines. Requires local administrator 1. Inside the `DowngradeVersion` key, create a new `String Value (REG_SZ)`: - * **Value name:** The AUMID or executable name (such as `teams.exe`). + * **Value name:** The AUMID or executable name (such as `ms-teams.exe`). * **Value data:** The target major version number. @@ -197,8 +264,8 @@ For targeted configuration on individual machines. Requires local administrator * The IT Admin can find the exact four-part version number in the [Microsoft Edge release notes for Stable Channel](/deployedge/microsoft-edge-relnote-stable-channel). * **Example values:** - * Name: `teams.exe`, Value: `151.0.2178.0` - * Name: `outlook.exe`, Value: `152.0.2164.0` + * Name: `ms-teams.exe`, Value: `151.0.2178.0` + * Name: `olk.exe`, Value: `152.0.2164.0` 1. Restart the WebView2 app, for the policy to take effect. @@ -206,8 +273,8 @@ For targeted configuration on individual machines. Requires local administrator ``` Key: HKLM\Software\Policies\Microsoft\Edge\WebView2\DowngradeVersion -Value: teams.exe = "145" -Value: outlook.exe = "146" +Value: ms-teams.exe = "151.0.2178.0" +Value: olk.exe = "152.0.2164.0" ``` @@ -225,7 +292,7 @@ Value: outlook.exe = "146" If no exact matching folder is found, the policy has no effect, and the Runtime defaults to the `BrowserExecutableFolder` policy or the Evergreen Runtime (the default auto-updating Runtime). -* The updater will **automatically download** the required version if it satisfies the N-1 and/or N-2 conditions. The IT Admin doesn't need to pre-stage version folders on disk. +* The Edge Updater will **automatically download** the required version if it satisfies the N-1 and/or N-2 conditions. The IT Admin doesn't need to pre-stage version folders on disk. * No restart of the machine is needed, but the WebView2 app must be restarted, and it might take up to 1 hour for the downgrade to take effect. @@ -242,17 +309,17 @@ Value: outlook.exe = "146" 1. The IT Admin sets policy by using Group Policy, specifying the `AppId` and `TargetVersion`. -1. The Updater reads the policy, and validates that `TargetVersion` is within N-1 or N-2. +1. The Edge Updater reads the policy, and validates that `TargetVersion` is within N-1 or N-2. -1. Downloads the downgraded version of the WebView2 Runtime, if needed, as a side-by-side install. +1. The Edge Updater downloads the downgraded version of the WebView2 Runtime, if needed, as a side-by-side install. -1. Sets `BrowserExecutableFolder` policy for the target app to redirect it to the specified Runtime version. +1. The Edge Updater sets `BrowserExecutableFolder` policy for the target app, to redirect it to the specified version of the WebView2 Runtime. -1. Maintains mapping as long as the downgraded version stays within the supported range. +1. The Edge Updater maintains the mapping as long as the downgraded version of the WebView2 Runtime stays within the supported range. -1. Cleans up and reverts the app to the latest Runtime version when the pinned Runtime version falls outside of the supported range or the policy is removed. +1. When the pinned version of the WebView2 Runtime falls outside of the supported range, or the policy is removed, the Edge Updater cleans up and reverts the WebView2 app to using the latest version of the WebView2 Runtime. -If a WebView2 Runtime downgrade policy is active but the target WebView2 Runtime version is not yet downloaded (such as due to network or disk constraints), the WebView2 app continues running on the currently available WebView2 Runtime until the earlier WebView2 Runtime is present. The WebView2 app will _not_ fail to launch solely because the downgraded version of the WebView2 Runtime is pending download. +If a WebView2 Runtime downgrade policy is active, but the target WebView2 Runtime version is not yet downloaded (such as due to network or disk constraints), the WebView2 app continues using the latest WebView2 Runtime, until the earlier WebView2 Runtime is present. The WebView2 app will _not_ fail to launch solely because the downgraded version of the WebView2 Runtime is pending download. @@ -352,9 +419,9 @@ After setting the WebView2 Runtime downgrade policy and restarting the target We 1. In File Explorer, navigate to: `C:\Program Files (x86)\Microsoft\EdgeWebView\Application\` -1. Confirm that a new folder appears, matching the downgraded version (such as `145.x.xxxx.xx`). +1. Confirm that a new folder appears, matching the downgraded version (such as `150.0.2178.0`). - The presence of this versioned folder indicates that the updater has fetched and staged the downgraded WebView2 Runtime. + The presence of this versioned folder indicates that the Edge Updater has fetched and staged the downgraded WebView2 Runtime. @@ -413,7 +480,7 @@ The following tools are for **troubleshooting issues** — they are not required | App still running on latest version | App not restarted. | Restart the WebView2 app (not the machine). | | Downgraded folder not appearing | Version is outside the "N-1 or N-2" range. | Verify that the target version is within the two most recent previous versions. | | App fails fast on launch (all apps sharing a User Data Folder (UDF)). | Shared UDF version mismatch. | Downgrade all apps that use the same UDF to the same version. | -| Policy not taking effect. | Incorrect key path or value format. | Verify the HKEY_LOCAL_MACHINE (HKLM) path, the value name format (AUMID or `exe`), and the four-part numeric format (such as 151.0.2178.0). | +| Policy not taking effect. | Incorrect key path or value format. | Verify the HKEY_LOCAL_MACHINE (HKLM) path, the value name format (AUMID or `.exe`), and the four-part numeric format (such as 151.0.2178.0). | | Multiple apps are impacted unexpectedly. | Shared User Data Folder | Identify User Data Folder (UDF) sharing, and make sure all affected apps are aligned. | | The downgrade auto-reverted unexpectedly. | Pinned version fell outside supported range | It is expected behavior, that the downgrade of the WebView2 Runtime expires after the Runtime version is no longer within version N-1 or N-2 (the two earlier versions of the Runtime). | @@ -451,7 +518,7 @@ If the policy was originally set directly via Registry (not recommended in produ 1. Navigate to: `HKEY_LOCAL_MACHINE\Software\Policies\Microsoft\Edge\WebView2\DowngradeVersion` -1. Delete the specific value (such as`teams.exe`). +1. Delete the specific value (such as`ms-teams.exe`). 1. Restart the WebView2 app. @@ -463,7 +530,7 @@ The downgrade expires automatically when the pinned version is no longer within * **Trigger:** Two subsequent new Evergreen versions release beyond the pinned version. -* **Behavior:** The updater automatically reverts applicable apps to the latest Runtime. +* **Behavior:** The Edge Updater automatically reverts applicable apps to the latest Runtime. * **Admin action required:** Remove the stale policy once it auto-expires. @@ -477,7 +544,7 @@ The downgrade expires automatically when the pinned version is no longer within |---|---| | **Application restart** | The WebView2 app picks up the latest WebView2 Runtime during the next launch of the app. | | **BrowserExecutableFolder** | Automatically removed; the WebView2 app returns to using the default WebView2 Runtime path. | -| **Downgraded Runtime bits** | Cleaned up by the updater on a scheduled cadence. | +| **Downgraded Runtime bits** | Cleaned up by the Edge Updater on a scheduled cadence. | | **User data** | Remains in place; no automatic data migration occurs. | From b2beca399402631d9b64b111e30477f3f96f4f8b Mon Sep 17 00:00:00 2001 From: Michael Hoffman <45407486+mikehoffms@users.noreply.github.com> Date: Fri, 21 Aug 2026 08:07:07 -0700 Subject: [PATCH 17/28] Removing the downgrading of --- microsoft-edge/webview2/how-to/enterprise-downgrade.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/microsoft-edge/webview2/how-to/enterprise-downgrade.md b/microsoft-edge/webview2/how-to/enterprise-downgrade.md index bb91861e61..20f6bf5c5c 100644 --- a/microsoft-edge/webview2/how-to/enterprise-downgrade.md +++ b/microsoft-edge/webview2/how-to/enterprise-downgrade.md @@ -42,7 +42,7 @@ If a new version of the WebView2 Runtime introduces a critical regression in a s * [Triggering a force-update](#triggering-a-force-update) * [Diagnostics tools for deeper troubleshooting](#diagnostics-tools-for-deeper-troubleshooting) * [Common issues and resolution](#common-issues-and-resolution) -* [Reverting downgrading the WebView2 Runtime](#reverting-downgrading-the-webview2-runtime) +* [Removing the downgrading of the WebView2 Runtime](#removing-the-downgrading-of-the-webview2-runtime) * [Option 1: Disable group policy (recommended)](#option-1-disable-group-policy-recommended) * [Option 2: Remove the policy via the registry](#option-2-remove-the-policy-via-the-registry) * [Option 3: Automatic expiry](#option-3-automatic-expiry) @@ -486,7 +486,7 @@ The following tools are for **troubleshooting issues** — they are not required -## Reverting downgrading the WebView2 Runtime +## Removing the downgrading of the WebView2 Runtime From 7480427674af4b1f13e8d5a4305eba060621bc71 Mon Sep 17 00:00:00 2001 From: Michael Hoffman <45407486+mikehoffms@users.noreply.github.com> Date: Fri, 21 Aug 2026 08:14:34 -0700 Subject: [PATCH 18/28] Escalation path: --- microsoft-edge/webview2/how-to/enterprise-downgrade.md | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/microsoft-edge/webview2/how-to/enterprise-downgrade.md b/microsoft-edge/webview2/how-to/enterprise-downgrade.md index 20f6bf5c5c..6a41a4a733 100644 --- a/microsoft-edge/webview2/how-to/enterprise-downgrade.md +++ b/microsoft-edge/webview2/how-to/enterprise-downgrade.md @@ -551,12 +551,7 @@ The downgrade expires automatically when the pinned version is no longer within ## Escalating and contacting the WebView2 team -| Aspect | Value | -|---|---| -| **Area Path:** | Edge\Web Experience\WebView2\Distribution | -| **DL:** | [wv2addr@microsoft.com](mailto:wv2addr@microsoft.com) | - -**Escalation Path:** +Escalation path: 1. The Enterprise Admin contacts Microsoft CSS. @@ -564,6 +559,8 @@ The downgrade expires automatically when the pinned version is no longer within 1. If unresolved, CSS escalates the issue to the WebView2 Platform team ICM. + Area Path: `Edge\Web Experience\WebView2\Distribution` + Owning Service: Edge Browser customer incidents. Owning Team: Edge WebView2. From 66832313f89294c010b3f689b2ba4bfa53f3862a Mon Sep 17 00:00:00 2001 From: Michael Hoffman <45407486+mikehoffms@users.noreply.github.com> Date: Fri, 21 Aug 2026 08:53:33 -0700 Subject: [PATCH 19/28] fix outline placement of Downgrade --- microsoft-edge/webview2/concepts/enterprise.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/microsoft-edge/webview2/concepts/enterprise.md b/microsoft-edge/webview2/concepts/enterprise.md index 22145a60ad..634efbd870 100644 --- a/microsoft-edge/webview2/concepts/enterprise.md +++ b/microsoft-edge/webview2/concepts/enterprise.md @@ -21,11 +21,11 @@ Feedback from IT Admins and developers is welcome, through the [WebView2Feedback * [Update policies](#update-policies) * [Suppressing WebView2 Runtime updates](#suppressing-webview2-runtime-updates) * [Evergreen Runtime is recommended, rather than a fixed version](#evergreen-runtime-is-recommended-rather-than-a-fixed-version) - * [Downgrading the WebView Runtime to an earlier version](#downgrading-the-webview-runtime-to-an-earlier-version) * [Rapid Response to Chromium vulnerabilities](#rapid-response-to-chromium-vulnerabilities) * [Microsoft Edge Lifecycle Policy](#microsoft-edge-lifecycle-policy) * [Browser policies](#browser-policies) * [WebView2-specific policies](#webview2-specific-policies) + * [Downgrading the WebView Runtime to an earlier version](#downgrading-the-webview-runtime-to-an-earlier-version) * [Windows Server Update Services (WSUS)](#windows-server-update-services-wsus) * [WebView2 deployment and update using Configuration Manager](#webview2-deployment-and-update-using-configuration-manager) * [See also](#see-also) @@ -67,14 +67,6 @@ See also: * [Evergreen vs. fixed version of the WebView2 Runtime](./evergreen-vs-fixed-version.md) - -###### Downgrading the WebView Runtime to an earlier version - -Enterprise Downgrade is a temporary, IT Admin-controlled capability that allows a specific WebView2 app to revert to using an earlier version of the WebView2 Runtime, in the event of a critical regression in the WebView2 app when using the latest version of the WebView2 Runtime. - -See [Downgrade the WebView2 Runtime to an earlier version](/deployedge/webview2-downgrade-runtime). - - ###### Rapid Response to Chromium vulnerabilities @@ -111,6 +103,14 @@ Applying browser policies on WebView2 would have unintended consequences. For e [Microsoft Edge WebView2 - Policies](/deployedge/microsoft-edge-webview-policies) are available to for you to manage WebView2 directly. However, we recommend that WebView2 app developers implement their own group policies to manage the use of WebView2, because it's easier for IT Admins to manage the app instead of managing WebView2 directly. + +###### Downgrading the WebView Runtime to an earlier version + +The Enterprise Downgrade feature is controlled via the `DowngradeVersion` policy. Enterprise Downgrade is a temporary, IT Admin-controlled capability that allows a specific WebView2 app to revert to using an earlier version of the WebView2 Runtime. This policy is useful if there's a critical regression in the WebView2 app when using the latest version of the WebView2 Runtime. + +See [Downgrade the WebView2 Runtime to an earlier version](/deployedge/webview2-downgrade-runtime). + + ## Windows Server Update Services (WSUS) From 560606cfdf85bb0804916226bfef2c0200f28965 Mon Sep 17 00:00:00 2001 From: Michael Hoffman <45407486+mikehoffms@users.noreply.github.com> Date: Fri, 21 Aug 2026 09:03:41 -0700 Subject: [PATCH 20/28] remove Downgrade article --- microsoft-edge/toc.yml | 5 +- .../webview2/how-to/enterprise-downgrade.md | 582 ------------------ 2 files changed, 1 insertion(+), 586 deletions(-) delete mode 100644 microsoft-edge/webview2/how-to/enterprise-downgrade.md diff --git a/microsoft-edge/toc.yml b/microsoft-edge/toc.yml index 68912e797e..5c40edd95d 100644 --- a/microsoft-edge/toc.yml +++ b/microsoft-edge/toc.yml @@ -2357,12 +2357,9 @@ href: ./webview2/concepts/distribution.md - name: Enterprise management of WebView2 Runtimes - href: ./webview2/concepts/enterprise.md + href: ./webview2/concepts/enterprise.md # todo: move to Admin docs repo per AB#63688884 displayName: Manage WebView2 applications # old title - - name: Downgrade the WebView2 Runtime to an earlier version - href: ./webview2/how-to/enterprise-downgrade.md - - name: Distribute an app as a single executable file href: ./webview2/how-to/static.md displayName: Statically link the WebView2 loader library, single-file app # old title diff --git a/microsoft-edge/webview2/how-to/enterprise-downgrade.md b/microsoft-edge/webview2/how-to/enterprise-downgrade.md deleted file mode 100644 index 6a41a4a733..0000000000 --- a/microsoft-edge/webview2/how-to/enterprise-downgrade.md +++ /dev/null @@ -1,582 +0,0 @@ ---- -title: Downgrade the WebView2 Runtime to an earlier version -description: If a new version of the WebView2 Runtime introduces a critical regression in a specific WebView2 app, an IT Admin can downgrade the WebView2 Runtime for that app to a previous version, by using the DowngradeVersion policy, as a temporary solution. -author: MSEdgeTeam -ms.author: msedgedevrel -ms.topic: article -ms.service: microsoft-edge -ms.subservice: webview -ms.date: 08/19/2026 ---- -# Downgrade the WebView2 Runtime to an earlier version - - -If a new version of the WebView2 Runtime introduces a critical regression in a specific WebView2 app, an IT Admin can downgrade the WebView2 Runtime for that app to a previous version, by using the `DowngradeVersion` policy, as a temporary solution. - -**Detailed contents:** -* [Overview of enterprise downgrade](#overview-of-enterprise-downgrade) - * [How enterprise downgrade works](#how-enterprise-downgrade-works) - * [Why enterprise downgrade exists](#why-enterprise-downgrade-exists) - * [Applicable WebView2 apps](#applicable-webview2-apps) - * [Policy configuration and precedence](#policy-configuration-and-precedence) - * [Core design principles](#core-design-principles) -* [Temporarily downgrading the WebView2 Runtime](#temporarily-downgrading-the-webview2-runtime) - * [Option 1: Group Policy (GPO)](#option-1-group-policy-gpo) - * [Option 2: Registry Editor (regedit)](#option-2-registry-editor-regedit) - * [Important notes](#important-notes) - * [Process flow: How downgrade is implemented](#process-flow-how-downgrade-is-implemented) -* [Limitations of downgrading the WebView2 Runtime](#limitations-of-downgrading-the-webview2-runtime) - * [Version limitations](#version-limitations) - * [Scope limitations](#scope-limitations) - * [Shared User Data Folder (UDF) constraints](#shared-user-data-folder-udf-constraints) -* [Risks of downgrading the WebView2 Runtime](#risks-of-downgrading-the-webview2-runtime) - * [Security risks](#security-risks) - * [Data integrity risks](#data-integrity-risks) - * [App compatibility risks](#app-compatibility-risks) - * [Operational risks](#operational-risks) -* [Testing and troubleshooting downgrading of the Runtime](#testing-and-troubleshooting-downgrading-of-the-runtime) - * [Verifying that the Runtime downgrade was applied](#verifying-that-the-runtime-downgrade-was-applied) - * [1. Check the versioned folder](#1-check-the-versioned-folder) - * [2. Check the registry policy](#2-check-the-registry-policy) - * [3. Check the BrowserExecutableFolder redirect](#3-check-the-browserexecutablefolder-redirect) - * [Triggering a force-update](#triggering-a-force-update) - * [Diagnostics tools for deeper troubleshooting](#diagnostics-tools-for-deeper-troubleshooting) - * [Common issues and resolution](#common-issues-and-resolution) -* [Removing the downgrading of the WebView2 Runtime](#removing-the-downgrading-of-the-webview2-runtime) - * [Option 1: Disable group policy (recommended)](#option-1-disable-group-policy-recommended) - * [Option 2: Remove the policy via the registry](#option-2-remove-the-policy-via-the-registry) - * [Option 3: Automatic expiry](#option-3-automatic-expiry) - * [Post-revert behavior](#post-revert-behavior) -* [Escalating and contacting the WebView2 team](#escalating-and-contacting-the-webview2-team) -* [See also](#see-also) - - - -## Overview of enterprise downgrade - -In an enterprise, the IT Admin can downgrade the WebView2 Runtime to a previous version, as a temporary measure, by using the `DowngradeVersion` policy. When using the Evergreen Runtime, if a new Runtime version introduces a critical regression, each WebView2 app and each Windows component that uses the WebView2 Runtime is likely to be impacted. Enterprise Downgrade offers a short-term mitigation approach for the IT Admin to restore impacted productivity. - -The `DowngradeVersion` policy is a controlled version downgrade capability that allows an enterprise IT Admin to temporarily revert a specific WebView2 application (WebView2 app) to use a previous version of the WebView2 Runtime via Group Policy when a critical regression disrupts business operations. See [DowngradeVersion](/deployedge/microsoft-edge-webview-policies#downgradeversion) in _Microsoft Edge WebView2 - Policies_. - -The **Evergreen** distribution model means that the WebView2 Runtime updates automatically alongside Microsoft Edge, so that the WebView2 app always runs on the latest version of the WebView2 Runtime, without manual intervention. The Evergreen WebView2 Runtime ensures that the WebView2 app gets security patches and feature improvements automatically. The enterprise IT Admin cannot uninstall the impacting WebView2 Runtime update. - -**WebView2** is a browser control that allows Windows applications (such as Microsoft Teams, Outlook, and third-party enterprise software) to embed web content by using the Microsoft Edge rendering engine. - - - -#### How enterprise downgrade works - -1. The IT Admin identifies that a new WebView2 Runtime version has broken a specific WebView2 app. - -1. The IT Admin sets a Group Policy that specifies that for this WebView2 app, use a specific previous version of the WebView2 Runtime, instead of the latest WebView2 Runtime. - - Only WebView2 Runtime version N-1 or N-2 relative to the current Evergreen WebView2 Runtime version is supported. Downgrading to a version of the WebView2 Runtime that's earlier than version N-2 is rejected. - -1. The Edge Updater downloads and installs the older WebView2 Runtime version _side-by-side_ with the current WebView2 Runtime. - -1. The WebView2 Loader redirects only the targeted WebView2 app to the older WebView2 Runtime. - -1. All other WebView2 apps on the device continue using the latest WebView2 Runtime version; they are unaffected by the downgrade. - -1. The downgrade automatically expires after the pinned version is no longer within the two most recent previous versions of the WebView2 Runtime. - - - -#### Why enterprise downgrade exists - -Enterprise Downgrade is a last-resort recovery tool. Enterprise Downgrade is targeted, time-bound, and managed by the enterprise IT Admin in partnership with WebView2 app owners. Enterprise Downgrade is not a version-pinning mechanism. - -Enterprise Downgrade provides a temporary, Admin-controlled version downgrade for the specific WebView2 app that's affected, while the platform team prepares a proper fix. Enterprise Downgrade should only be used as a last-resort recovery measure, when a critical regression is actively disrupting business operations and no other mitigation (such as a hotfix, feature flag, or update pause) can resolve the issue in a timely manner. The downgrade buys time for the platform team to ship a proper fix; the downgrade is not a substitute for shipping a proper fix. - -In mission-critical enterprise environments, unexpected regressions in the WebView2 Runtime can halt business workflows with no immediate remedy. Even brief outages result in lost revenue, missed SLAs, and increased operational costs. Mission-critical enterprise environments include, for example: -* Healthcare systems -* Financial trading platforms -* Retail point-of-sale -* Government services - - - -#### Applicable WebView2 apps - -Enterprise Downgrade of the WebView2 Runtime doesn't automatically affect any WebView2 app. The IT Admin must explicitly configure the `DowngradeVersion` policy for a specific WebView2 app. The policy then applies only to that specific WebView2 app. - -The following types of WebView2 apps can be targeted: - -* Any WebView2 Evergreen-Runtime app running on enterprise-managed Windows devices. - - * The IT Admin specifies the target by either: - * The Application User Model ID (AUMID), for packaged/MSIX apps. - * The executable name (such as `ms-teams.exe`). - - * If both an AUMID and `.exe` name entry exist for the same WebView2 app, the AUMID entry takes precedence. - -To find the `.exe` name: - -1. Open Task Manager, and then on the left, select **Details**. - -1. Find the running WebView2 app. - -1. Examine the **Name** column for the WebView2 app, such as `ms-teams.exe` or `olk.exe`. - -The following types of WebView2 apps are not affected by the `DowngradeVersion` policy: - -* WebView2 apps that aren't specified in the `DowngradeVersion` policy. - * Such apps continue to use the latest WebView2 Evergreen Runtime. - -* WebView2 apps on consumer devices or unmanaged devices. - -* WebView2 apps that use an app-bundled (Fixed Version) WebView2 Runtime. - - - -#### Policy configuration and precedence - -HKEY_CURRENT_USER (HKCU) is not supported; this is a machine-level enterprise policy only (HKEY_LOCAL_MACHINE (HKLM)). - -| Location | Path | -|---|---| -| **Group Policy (recommended)** | **Computer Configuration** > **Administrative Templates** > **Microsoft Edge WebView2** > **Configure per-application WebView2 downgrade version** | -| **Registry** | `HKLM\Software\Policies\Microsoft\Edge\WebView2\DowngradeVersion` | - -**Precedence when multiple policies exist (highest to lowest):** - -1. **DowngradeVersion policy** — always wins. - -1. **BrowserExecutableFolder** — if set independently by the IT Admin. - -1. **Default Evergreen Runtime** — lowest. - -If both `DowngradeVersion` and `BrowserExecutableFolder` are independently configured, `DowngradeVersion` takes precedence and overrides the `BrowserExecutableFolder` redirect. - - - -#### Core design principles - -* **Enterprise IT Admin Driven:** Only IT Admins can initiate downgrade via Group Policy. Developers and end users cannot trigger it. - -* **Updater Service Compliance:** The Edge Updater downloads the required version if needed and continues normal updates for all other apps. - -* **Automatic Expiry:** A downgraded version remains valid only as long as it is within the two most recent previous versions (N-1 or N-2). Once two subsequent new major versions release beyond the downgraded version, the downgrade expires and the app automatically reverts to the latest Runtime. Microsoft recommends that the IT Admin should remove the stale policy after it auto-expires. - -* **Per-App Targeting:** Downgrade is applied per-app, not device-wide. Each WebView2 app must be individually specified in the policy. - - - -## Temporarily downgrading the WebView2 Runtime - - - -#### Updating the policy template - -To update the policy template: - -1. Go to [Download and deploy Microsoft Edge for Business](https://explore.microsoft.com/edge/business/download). - -1. In the **Download the latest** section, click one of the following buttons: - - * Windows - * macOS - * Linux - -1. Click a **Download ... Policy** link, such as: - - * **Download Windows 64-bit Policy** - * **Download Windows 32-bit Policy** - * **Download Windows ARM64 Policy** - * **Download macOS Universal Policy** - * **Download Linux (.rpm) Policy** - * **Download Linux (.deb) Policy** - - The **Download Microsoft Edge Policy File** dialog opens. - -1. Click the **Accept and download** button. - - A file is downloaded, such as `MicrosoftEdgePolicyTemplates.cab`. - -1. In Microsoft Edge, select **Settings and more** (**...**), select **Downloads**, and then for the downloaded file, click **Open containing folder**. - - On Windows, File Explorer opens, with the file `MicrosoftEdgePolicyTemplates.cab` selected. - -1. Right-click `MicrosoftEdgePolicyTemplates.cab`, and then select **Open**. - - `MicrosoftEdgePolicyTemplates.zip` appears. - -1. Right-click `MicrosoftEdgePolicyTemplates.zip`, and then select **Extract**. - - The **Select a Destination** dialog opens. - -1. Select the directory such as `C:\Users\local-account\Downloads`, and then click the **Extract** button. - - A folder is created, such as: `C:\Users\local-account\Downloads\MicrosoftEdgePolicyTemplates.zip` - -1. On the left, select `MicrosoftEdgePolicyTemplates.zip`, and then on the right, open the `/windows/` directory. - - The folders `/adm/` and `/admx/` are listed. - -1. Copy the folders `/adm/` and `/admx/` to a `/PolicyDefinitions/` directory. For example, for Windows, copy the `/adm/` and `/admx/` folders to `C:\Windows\PolicyDefinitions\`. - - The **Destination Folder Access Denies** dialog opens, saying "You'll need to provide administrator permission to copy to this folder". - -1. Click the **Continue** button. - - The **User Account Control** dialog opens. - -1. Enter admin credentials. - - - -#### Option 1: Group Policy (GPO) - -This is the recommended approach for enterprise environments. Group Policy ensures centralized, auditable management across managed devices. - -1. Open the Group Policy Editor (`gpedit.msc`). - -1. Navigate to: **Computer Configuration > Administrative Templates > Microsoft Edge WebView2** - -1. Find **Configure per-application WebView2 downgrade version**. - -1. Enable the policy, and enter this information: - - * **Name:** The application identifier (AUMID). Or, the `.exe` name, such as `ms-teams.exe`. - - * **Value:** The target four-part version number (such as 151.0.2178.0). - - - -#### Option 2: Registry Editor (regedit) - -For targeted configuration on individual machines. Requires local administrator privileges. - -1. Open `regedit` as Administrator. - -1. Navigate to: `HKEY_LOCAL_MACHINE\Software\Policies\Microsoft\Edge\WebView2` - -1. Create a new key named `DowngradeVersion` (if it doesn't exist). - -1. Inside the `DowngradeVersion` key, create a new `String Value (REG_SZ)`: - - * **Value name:** The AUMID or executable name (such as `ms-teams.exe`). - - * **Value data:** The target major version number. - - * Set the value to the target full version string using the four-part numeric format (such as 151.0.2178.0). - - * The IT Admin can find the exact four-part version number in the [Microsoft Edge release notes for Stable Channel](/deployedge/microsoft-edge-relnote-stable-channel). - - * **Example values:** - * Name: `ms-teams.exe`, Value: `151.0.2178.0` - * Name: `olk.exe`, Value: `152.0.2164.0` - -1. Restart the WebView2 app, for the policy to take effect. - -**Example:** - -``` -Key: HKLM\Software\Policies\Microsoft\Edge\WebView2\DowngradeVersion -Value: ms-teams.exe = "151.0.2178.0" -Value: olk.exe = "152.0.2164.0" -``` - - - -#### Important notes - -* Only `HKEY_LOCAL_MACHINE` (HKLM) is supported; `HKEY_CURRENT_USER` (HKCU) is ignored. - -* The following values are not supported: - * Major-only values (such as 151). - * Wildcard values (such as 151.*). - * Values that are not exact four-part numeric versions. - -* The WebView2 loader resolves the Runtime installation directory only when a folder that exactly matches the configured full version exists. For example, 151.0.2178.0 must match 151.0.2178.0 exactly. - - If no exact matching folder is found, the policy has no effect, and the Runtime defaults to the `BrowserExecutableFolder` policy or the Evergreen Runtime (the default auto-updating Runtime). - -* The Edge Updater will **automatically download** the required version if it satisfies the N-1 and/or N-2 conditions. The IT Admin doesn't need to pre-stage version folders on disk. - -* No restart of the machine is needed, but the WebView2 app must be restarted, and it might take up to 1 hour for the downgrade to take effect. - -* Policy latency for the WebView2 app: Changes take effect within **1 hour** of deployment. This is aligned with the Microsoft Edge and WebView2 update task cadence. To trigger a force update, see [Triggering a force update](#triggering-a-force-update), below. - -* Runtime downgrade policy enforcement overrides the following: - * Maintenance windows. - * Extended update intervals. - * Cached last-check timestamps. - - - -#### Process flow: How downgrade is implemented - -1. The IT Admin sets policy by using Group Policy, specifying the `AppId` and `TargetVersion`. - -1. The Edge Updater reads the policy, and validates that `TargetVersion` is within N-1 or N-2. - -1. The Edge Updater downloads the downgraded version of the WebView2 Runtime, if needed, as a side-by-side install. - -1. The Edge Updater sets `BrowserExecutableFolder` policy for the target app, to redirect it to the specified version of the WebView2 Runtime. - -1. The Edge Updater maintains the mapping as long as the downgraded version of the WebView2 Runtime stays within the supported range. - -1. When the pinned version of the WebView2 Runtime falls outside of the supported range, or the policy is removed, the Edge Updater cleans up and reverts the WebView2 app to using the latest version of the WebView2 Runtime. - -If a WebView2 Runtime downgrade policy is active, but the target WebView2 Runtime version is not yet downloaded (such as due to network or disk constraints), the WebView2 app continues using the latest WebView2 Runtime, until the earlier WebView2 Runtime is present. The WebView2 app will _not_ fail to launch solely because the downgraded version of the WebView2 Runtime is pending download. - - - -## Limitations of downgrading the WebView2 Runtime - - - -#### Version limitations - -| Limitation | Detail | -|---|---| -| **Version range** | Only version N-1 or N-2 of the WebView2 Runtime relative to the current Evergreen Runtime version is supported. Downgrading to an WebView2 Runtime that's earlier than the two previous Runtime versions is rejected. | -| **Version format** | Only major version numbers (digits only). Full version strings, dots, or wildcards are invalid. | -| **Automatic expiry** | A downgraded version of the WebView2 Runtime remains active only while it is within the two most recent previous versions. After two subsequent new versions of the Runtime release beyond the pinned version, the downgrade automatically expires, and the app reverts to the latest WebView2 Runtime. | -| **Availability** | The downgrade feature is available for Microsoft Edge WebView2 version 150 or later, only. | - - - -#### Scope limitations - -| Limitation | Detail | -|---|---| -| **Enterprise-only** | Not supported on consumer or unmanaged devices. | -| **Machine-level only** | Policy can only be set at the level of the local machine (HKEY_LOCAL_MACHINE (HKLM)). Setting the downgrade policy for the current user (HKEY_CURRENT_USER (HKCU)) is not supported; there's no user-level policy, or individual user-level control. | -| **Per-app targeting** | Cannot perform enterprise-wide downgrade across all WebView2 apps. Each WebView2 app must be individually targeted. | -| **No developer control** | Only an IT Admin can initiate downgrading the WebView2 Runtime. A Developer cannot trigger downgrade of the WebView2 Runtime, such as via an API. | -| **No indefinite pinning** | The solution does NOT support long-term or permanent version pinning. | - - - -#### Shared User Data Folder (UDF) constraints - -The IT Admin must downgrade all WebView2 apps that share the same User Data Folder (UDF), to use the same WebView2 Runtime version. - -WebView2 apps can share a WebView2 User Data Folder (UDF) to reuse browser state. Very few apps share a User Data Folder (UDF); the only known apps that share a UDF are the Office Suite apps: Excel, Word, and PowerPoint. - -Accessing the same UDF from different WebView2 Runtime versions is unsafe. If WebView2 app A is downgraded, and WebView2 app B shares the same UDF but is not downgraded, both WebView2 app A and WebView2 app B will fail fast on launch. - - - -## Risks of downgrading the WebView2 Runtime - - - -#### Security risks - -| Risk | Description | -|---|---| -| **Reintroduced vulnerabilities** | Downgrading reintroduces patched vulnerabilities that have been fixed in newer versions. | -| **Compliance weakening** | Older versions may violate compliance in regulated environments. | -| **Expanded attack surface** | Managing multiple downgraded versions increases the persistence of outdated clients. | - - - -#### Data integrity risks - -| Risk | Description | -|---|---| -| **Storage corruption** | Downgrade can cause corruption or incompatibility if storage formats, schemas, or APIs have changed between versions (cookies, IndexedDB, Local Storage). | -| **Schema mismatches** | Unlike Edge browser which uses User Data Snapshots, WebView2 does not implement platform-level snapshotting. | -| **User data loss** | Profile instability and potential data loss if storage formats are incompatible. | - - - -#### App compatibility risks - -| Risk | Description | -|---|---| -| **Feature dependency breaks** | A WebView2 app that uses newer WebView2 APIs or behaviors might fail or behave unpredictably after downgrading the WebView2 Runtime. | -| **Performance regressions** | Older versions of the WebView2 Runtime might introduce slower page loads, higher memory usage, and degraded experiences. | -| **App malfunction** | Downgrading the WebView2 Runtime can cause a WebView2 app to malfunction, due to reliance on recently introduced features or rendering changes. | - - - -#### Operational risks - -| Risk | Description | -|---|---| -| **Version fragmentation** | Supporting downgrade at the app level can lead to version drift across apps on the same device. | -| **Sedimentation** | Multiple older versions accumulate on devices over time, increasing complexity. | -| **Increased disk usage** | An additional WebView2 Runtime version is installed side-by-side with the current Evergreen WebView2 Runtime version, consuming extra disk space on each device. | -| **Coordination complexity** | Downgrade requires careful coordination between the IT Admin, the WebView2 app owner, and the platform team. | - - - -## Testing and troubleshooting downgrading of the Runtime - - - -#### Verifying that the Runtime downgrade was applied - -After setting the WebView2 Runtime downgrade policy and restarting the target WebView2 app, do the following. - - - -###### 1. Check the versioned folder - -1. In File Explorer, navigate to: `C:\Program Files (x86)\Microsoft\EdgeWebView\Application\` - -1. Confirm that a new folder appears, matching the downgraded version (such as `150.0.2178.0`). - - The presence of this versioned folder indicates that the Edge Updater has fetched and staged the downgraded WebView2 Runtime. - - - -###### 2. Check the registry policy - -1. Confirm that the `DowngradeVersion` key is set, under: `HKLM\Software\Policies\Microsoft\Edge\WebView2\DowngradeVersion` - -1. Verify that entries match your configured `AppId` → `TargetVersion`. - - - -###### 3. Check the `BrowserExecutableFolder` redirect - -* The `BrowserExecutableFolder` policy should be set automatically to point the app to the downgraded Runtime path. - - - -#### Triggering a force-update - -After setting the `DowngradeVersion` policy, the Edge Updater needs to download the target version. By default, this happens within approximately 1 hour (aligned with the Edge/WebView2 update task cadence). - -To trigger an immediate update: - -1. Open PowerShell as Administrator. - -1. Find the Edge Update task: - - `Get-ScheduledTask -TaskPath "\Microsoft\EdgeUpdate\*" | Select TaskName, TaskPath` - -1. Run the task: - - `Start-ScheduledTask -TaskName ""` - -1. Wait a few minutes for the download to complete. - -1. Restart the WebView2 app. - - - -#### Diagnostics tools for deeper troubleshooting - -The following tools are for **troubleshooting issues** — they are not required for standard verification: - -| Tool | Purpose | -|---|---| -| **edge://webview2-internals** | View active WebView2 processes, Runtime version in use. | -| **ETW Tracing** | Capture low-level diagnostic logs for update/downgrade events. | -| **Event Viewer** | Check Application logs for WebView2 update errors or policy enforcement failures. | - - - -#### Common issues and resolution - -| Symptom | Likely Cause | Resolution | -|---|---|---| -| App still running on latest version | App not restarted. | Restart the WebView2 app (not the machine). | -| Downgraded folder not appearing | Version is outside the "N-1 or N-2" range. | Verify that the target version is within the two most recent previous versions. | -| App fails fast on launch (all apps sharing a User Data Folder (UDF)). | Shared UDF version mismatch. | Downgrade all apps that use the same UDF to the same version. | -| Policy not taking effect. | Incorrect key path or value format. | Verify the HKEY_LOCAL_MACHINE (HKLM) path, the value name format (AUMID or `.exe`), and the four-part numeric format (such as 151.0.2178.0). | -| Multiple apps are impacted unexpectedly. | Shared User Data Folder | Identify User Data Folder (UDF) sharing, and make sure all affected apps are aligned. | -| The downgrade auto-reverted unexpectedly. | Pinned version fell outside supported range | It is expected behavior, that the downgrade of the WebView2 Runtime expires after the Runtime version is no longer within version N-1 or N-2 (the two earlier versions of the Runtime). | - - - -## Removing the downgrading of the WebView2 Runtime - - - -#### Option 1: Disable group policy (recommended) - -Important: Do not delete registry keys directly. Always use Group Policy (GPO) to disable the policy, to ensure clean removal and avoid orphaned configuration. - -If GPO was used to configure the downgrade: - -1. Open the Group Policy Editor (`gpedit.msc`). - -1. Navigate to: **Computer Configuration > Administrative Templates > Microsoft Edge WebView2** - -1. Set "**Configure per-application WebView2 downgrade version**" to **Disabled** or **Not Configured**. - -1. Restart the WebView2 app. - - The app will revert to the latest Evergreen Runtime on next launch. - - - -#### Option 2: Remove the policy via the registry - -Caution: Direct registry manipulation should only be used if the original policy was set via Registry Editor. If Group Policy (GPO) was used, always revert by using GPO, to ensure consistency. - -If the policy was originally set directly via Registry (not recommended in production): - -1. Open `regedit` as Administrator. - -1. Navigate to: `HKEY_LOCAL_MACHINE\Software\Policies\Microsoft\Edge\WebView2\DowngradeVersion` - -1. Delete the specific value (such as`ms-teams.exe`). - -1. Restart the WebView2 app. - - - -#### Option 3: Automatic expiry - -The downgrade expires automatically when the pinned version is no longer within the two most recent previous versions: - -* **Trigger:** Two subsequent new Evergreen versions release beyond the pinned version. - -* **Behavior:** The Edge Updater automatically reverts applicable apps to the latest Runtime. - -* **Admin action required:** Remove the stale policy once it auto-expires. - -* **Example:** If you downgrade to version 145 while 147 is current (145 is N-2), and then version 148 release, version 145 is now three versions behind → downgrade auto-expires. - - - -#### Post-revert behavior - -| Action | What Happens | -|---|---| -| **Application restart** | The WebView2 app picks up the latest WebView2 Runtime during the next launch of the app. | -| **BrowserExecutableFolder** | Automatically removed; the WebView2 app returns to using the default WebView2 Runtime path. | -| **Downgraded Runtime bits** | Cleaned up by the Edge Updater on a scheduled cadence. | -| **User data** | Remains in place; no automatic data migration occurs. | - - - -## Escalating and contacting the WebView2 team - -Escalation path: - -1. The Enterprise Admin contacts Microsoft CSS. - -1. CSS troubleshoots the issue by using this article. - -1. If unresolved, CSS escalates the issue to the WebView2 Platform team ICM. - - Area Path: `Edge\Web Experience\WebView2\Distribution` - - Owning Service: Edge Browser customer incidents. - - Owning Team: Edge WebView2. - -See also: -* [Contact the WebView2 team](../contact.md) - - - -## See also - - - -* [Enterprise management of WebView2 Runtimes](../concepts/enterprise.md) -* [Contact the WebView2 team](../contact.md) - -External: -* [DowngradeVersion](/deployedge/microsoft-edge-webview-policies#downgradeversion) in _Microsoft Edge WebView2 - Policies_. -* [Microsoft Edge release notes for Stable Channel](/deployedge/microsoft-edge-relnote-stable-channel) From 78d070d675e2de2ca10a84dac44f5ab077adba91 Mon Sep 17 00:00:00 2001 From: Michael Hoffman <45407486+mikehoffms@users.noreply.github.com> Date: Fri, 21 Aug 2026 15:11:49 -0700 Subject: [PATCH 21/28] flatten & reseq outline --- .../webview2/concepts/enterprise.md | 45 +++++++++---------- 1 file changed, 20 insertions(+), 25 deletions(-) diff --git a/microsoft-edge/webview2/concepts/enterprise.md b/microsoft-edge/webview2/concepts/enterprise.md index 634efbd870..d0ddc60c09 100644 --- a/microsoft-edge/webview2/concepts/enterprise.md +++ b/microsoft-edge/webview2/concepts/enterprise.md @@ -6,39 +6,34 @@ ms.author: msedgedevrel ms.topic: article ms.service: microsoft-edge ms.subservice: webview -ms.date: 08/18/2026 +ms.date: 08/21/2026 --- # Enterprise management of WebView2 Runtimes -This article discusses how IT Administrators can manage WebView2 applications and the WebView2 Runtime. A developer can integrate the WebView2 component into their app, and then deploy the self-updating Evergreen WebView2 Runtime (along with the app) onto user devices, to power the latest WebView2 features of the app and get the latest security improvements. +IT Admins can use group policy objects (GPO) to configure policy settings for WebView2, to manage WebView2 applications and the WebView2 Runtime. The following policies are relevant to WebView2. + +Many policies are about updating the WebView2 Runtime. A developer can integrate the WebView2 component into their app, and then deploy the self-updating Evergreen WebView2 Runtime (along with the app) onto user devices, to power the latest WebView2 features of the app and get the latest security improvements. Feedback from IT Admins and developers is welcome, through the [WebView2Feedback](https://github.com/MicrosoftEdge/WebViewFeedback) repo. **Detailed contents:** -* [Group policies for WebView2](#group-policies-for-webview2) - * [Update policies](#update-policies) +* [Update policies](#update-policies) * [Suppressing WebView2 Runtime updates](#suppressing-webview2-runtime-updates) * [Evergreen Runtime is recommended, rather than a fixed version](#evergreen-runtime-is-recommended-rather-than-a-fixed-version) * [Rapid Response to Chromium vulnerabilities](#rapid-response-to-chromium-vulnerabilities) * [Microsoft Edge Lifecycle Policy](#microsoft-edge-lifecycle-policy) - * [Browser policies](#browser-policies) - * [WebView2-specific policies](#webview2-specific-policies) - * [Downgrading the WebView Runtime to an earlier version](#downgrading-the-webview-runtime-to-an-earlier-version) +* [WebView2-specific policies](#webview2-specific-policies) + * [Downgrading the WebView Runtime to an earlier version](#downgrading-the-webview-runtime-to-an-earlier-version) +* [Browser policies](#browser-policies) * [Windows Server Update Services (WSUS)](#windows-server-update-services-wsus) * [WebView2 deployment and update using Configuration Manager](#webview2-deployment-and-update-using-configuration-manager) * [See also](#see-also) -## Group policies for WebView2 - -IT Admins can use group policy objects (GPO) to configure policy settings for WebView2. The following policies are relevant to WebView2. - - - -#### Update policies +## Update policies [Microsoft Edge - Update policies](/deployedge/microsoft-edge-update-policies) are available for IT Admins to manage the installing and updating aspects of the WebView2 Runtime. The Microsoft Edge browser and WebView2 Runtime are updated using the same update mechanism. The policy applies to both Microsoft Edge and the WebView2 Runtime, unless the policy is channel-specific, such as [Update](/deployedge/microsoft-edge-update-policies#update) and [Update (WebView)](/deployedge/microsoft-edge-update-policies#update-webview). @@ -89,26 +84,26 @@ See: * [Microsoft Edge Lifecycle Policy](/deployedge/microsoft-edge-support-lifecycle), in the Microsoft Edge Enterprise documentation. - -#### Browser policies - -[Microsoft Edge - Policies](/deployedge/microsoft-edge-policies) doesn't apply to WebView2 applications. This is by design, because apps and browsers have different use cases, and IT Admins might not be aware of what applications use WebView2. + +## WebView2-specific policies -Applying browser policies on WebView2 would have unintended consequences. For example, IT Admins can block JavaScript in the browser, and that would break WebView2 apps that use JavaScript. To prevent that, browser policies are separate from WebView2 policies. +[Microsoft Edge WebView2 - Policies](/deployedge/microsoft-edge-webview-policies) are available to IT Admins, to manage WebView2 directly. Generally, we recommend that WebView2 app developers implement their own group policies to manage the use of WebView2, because it's easier for IT Admins to manage the app instead of managing WebView2 directly. -#### WebView2-specific policies +#### Downgrading the WebView Runtime to an earlier version -[Microsoft Edge WebView2 - Policies](/deployedge/microsoft-edge-webview-policies) are available to for you to manage WebView2 directly. However, we recommend that WebView2 app developers implement their own group policies to manage the use of WebView2, because it's easier for IT Admins to manage the app instead of managing WebView2 directly. +The Enterprise Downgrade feature is controlled via the `DowngradeVersion` policy. Enterprise Downgrade is a temporary, IT Admin-controlled capability that allows a specific WebView2 app to revert to using an earlier version of the WebView2 Runtime. This policy is useful if there's a critical regression in the WebView2 app when using the latest version of the WebView2 Runtime. +See [Downgrade the WebView2 Runtime to an earlier version](/deployedge/webview2-downgrade-runtime). - -###### Downgrading the WebView Runtime to an earlier version -The Enterprise Downgrade feature is controlled via the `DowngradeVersion` policy. Enterprise Downgrade is a temporary, IT Admin-controlled capability that allows a specific WebView2 app to revert to using an earlier version of the WebView2 Runtime. This policy is useful if there's a critical regression in the WebView2 app when using the latest version of the WebView2 Runtime. + +## Browser policies -See [Downgrade the WebView2 Runtime to an earlier version](/deployedge/webview2-downgrade-runtime). +[Microsoft Edge - Policies](/deployedge/microsoft-edge-policies) doesn't apply to WebView2 applications. This is by design, because apps and browsers have different use cases, and IT Admins might not be aware of what applications use WebView2. + +Applying browser policies on WebView2 would have unintended consequences. For example, IT Admins can block JavaScript in the browser, and that would break WebView2 apps that use JavaScript. To prevent that, browser policies are separate from WebView2 policies. From 2bf7d97ca0c9058ec25b8f57beaf0114e06d5eae Mon Sep 17 00:00:00 2001 From: Michael Hoffman <45407486+mikehoffms@users.noreply.github.com> Date: Sat, 22 Aug 2026 09:12:44 -0700 Subject: [PATCH 22/28] Update enterprise.md structural edit, flatten outline, highlight headings for a policy --- .../webview2/concepts/enterprise.md | 60 ++++++++++++------- 1 file changed, 39 insertions(+), 21 deletions(-) diff --git a/microsoft-edge/webview2/concepts/enterprise.md b/microsoft-edge/webview2/concepts/enterprise.md index d0ddc60c09..7e8fc2a05f 100644 --- a/microsoft-edge/webview2/concepts/enterprise.md +++ b/microsoft-edge/webview2/concepts/enterprise.md @@ -16,19 +16,18 @@ IT Admins can use group policy objects (GPO) to configure policy settings for We Many policies are about updating the WebView2 Runtime. A developer can integrate the WebView2 component into their app, and then deploy the self-updating Evergreen WebView2 Runtime (along with the app) onto user devices, to power the latest WebView2 features of the app and get the latest security improvements. -Feedback from IT Admins and developers is welcome, through the [WebView2Feedback](https://github.com/MicrosoftEdge/WebViewFeedback) repo. - **Detailed contents:** * [Update policies](#update-policies) - * [Suppressing WebView2 Runtime updates](#suppressing-webview2-runtime-updates) - * [Evergreen Runtime is recommended, rather than a fixed version](#evergreen-runtime-is-recommended-rather-than-a-fixed-version) - * [Rapid Response to Chromium vulnerabilities](#rapid-response-to-chromium-vulnerabilities) - * [Microsoft Edge Lifecycle Policy](#microsoft-edge-lifecycle-policy) + * [Suppressing WebView2 Runtime updates (`UpdatesSuppressed`)](#suppressing-webview2-runtime-updates-updatessuppressed) + * [Evergreen Runtime is recommended, rather than a fixed version](#evergreen-runtime-is-recommended-rather-than-a-fixed-version) + * [Rapid Response to Chromium vulnerabilities](#rapid-response-to-chromium-vulnerabilities) + * [Microsoft Edge Lifecycle Policy](#microsoft-edge-lifecycle-policy) * [WebView2-specific policies](#webview2-specific-policies) - * [Downgrading the WebView Runtime to an earlier version](#downgrading-the-webview-runtime-to-an-earlier-version) + * [Downgrading the WebView Runtime to an earlier version (`DowngradeVersion`)](#downgrading-the-webview-runtime-to-an-earlier-version-downgradeversion) * [Browser policies](#browser-policies) * [Windows Server Update Services (WSUS)](#windows-server-update-services-wsus) * [WebView2 deployment and update using Configuration Manager](#webview2-deployment-and-update-using-configuration-manager) +* [Feedback](#feedback) * [See also](#see-also) @@ -41,15 +40,15 @@ To configure update policies for Microsoft Edge (and the WebView2 Runtime), see -#### Suppressing WebView2 Runtime updates +#### Suppressing WebView2 Runtime updates (`UpdatesSuppressed`) An IT Admin can suppress updating of the WebView2 Runtime, if auto-updating needs to be suppressed for a short time. After the time period, updating of the WebView2 Runtime resumes. The [UpdatesSuppressed](/deployedge/microsoft-edge-update-policies#updatessuppressed) policy allows an IT Admin to set the time during each day at which to suppress auto-update for both Microsoft Edge and the WebView2 Runtime. This enables an IT Admin to configure preferences and proxies once for both the browser and the WebView2 Runtime, to control their network bandwidth and traffic, or for other purposes. However, users should not stop updating their WebView2 Runtime; users should not remain on an older version of the WebView2 Runtime. Using older versions of the WebView2 Runtime isn't recommended. Security updates and servicing updates are only available on the latest Stable channel release (Edge Stable) and the latest Beta channel release (Edge Beta). If you use older releases of the Microsoft WebView2 Runtime, you won't receive the latest quality and security updates. - -###### Evergreen Runtime is recommended, rather than a fixed version + +#### Evergreen Runtime is recommended, rather than a fixed version Using the Evergreen WebView2 Runtime is recommended, unless business-critical requirements necessitate using a fixed version of the WebView2 Runtime. Using the Evergreen WebView2 Runtime: * Helps minimize exposure to known vulnerabilities. @@ -62,24 +61,24 @@ See also: * [Evergreen vs. fixed version of the WebView2 Runtime](./evergreen-vs-fixed-version.md) - -###### Rapid Response to Chromium vulnerabilities + +#### Rapid Response to Chromium vulnerabilities -To help maintain a secure browsing environment, Microsoft Edge addresses Chromium engine-level vulnerabilities soon after the vulnerabilities are disclosed. +To help maintain a secure browsing environment, Microsoft Edge addresses vulnerabilities in the Chromium browser engine soon after the vulnerabilities are disclosed. -Security fixes address vulnerabilities such as: +Security fixes in the Chromium browser engine address vulnerabilities such as: * **Remote code execution** – Mitigates risks of arbitrary code execution via malicious content. * **Privilege escalation** – Reduces chances of unauthorized system access. * **Information disclosure and spoofing** – Protects sensitive data, and helps prevent phishing attacks. - -###### Microsoft Edge Lifecycle Policy + +#### Microsoft Edge Lifecycle Policy Microsoft WebView2 follows the Modern Lifecycle Policy. -See: +See also: * [Modern Lifecycle Policy](/lifecycle/policies/modern), in the Modern Lifecycle Policy documentation. * [Microsoft Edge Lifecycle Policy](/deployedge/microsoft-edge-support-lifecycle), in the Microsoft Edge Enterprise documentation. @@ -87,15 +86,22 @@ See: ## WebView2-specific policies -[Microsoft Edge WebView2 - Policies](/deployedge/microsoft-edge-webview-policies) are available to IT Admins, to manage WebView2 directly. Generally, we recommend that WebView2 app developers implement their own group policies to manage the use of WebView2, because it's easier for IT Admins to manage the app instead of managing WebView2 directly. +Policies that are specific to the WebView2 Runtime are available to the IT Admin, to manage the WebView2 Runtime directly. However, we recommend that the WebView2 app developer implement their own group policies to manage the use of the WebView2 Runtime, because it's easier for the IT Admin to manage a WebView2 app, rather than managing the WebView2 Runtime directly. + +See also: +* [Microsoft Edge WebView2 - Policies](/deployedge/microsoft-edge-webview-policies), in the Microsoft Edge Enterprise documentation. -#### Downgrading the WebView Runtime to an earlier version +#### Downgrading the WebView Runtime to an earlier version (`DowngradeVersion`) -The Enterprise Downgrade feature is controlled via the `DowngradeVersion` policy. Enterprise Downgrade is a temporary, IT Admin-controlled capability that allows a specific WebView2 app to revert to using an earlier version of the WebView2 Runtime. This policy is useful if there's a critical regression in the WebView2 app when using the latest version of the WebView2 Runtime. +Enterprise Downgrade is a temporary, IT Admin-controlled capability that allows a specific WebView2 app to revert to using an earlier version of the WebView2 Runtime, if there's a critical regression in the WebView2 app when using the latest version of the WebView2 Runtime. -See [Downgrade the WebView2 Runtime to an earlier version](/deployedge/webview2-downgrade-runtime). +The Enterprise Downgrade feature is controlled via the `DowngradeVersion` policy. + +See also: +* [Downgrade the WebView2 Runtime to an earlier version](/deployedge/webview2-downgrade-runtime), in the Microsoft Edge Enterprise documentation. +* [DowngradeVersion](/deployedge/microsoft-edge-webview-policies#downgradeversion) in _Microsoft Edge WebView2 - Policies_. @@ -125,12 +131,22 @@ In Configuration Manager, WebView2 options exist under the **Microsoft Edge Mana See [Update Microsoft Edge](/intune/configmgr/apps/deploy-use/deploy-edge#update-microsoft-edge) in _Microsoft Edge Management_, in the App management documentation. + +## Feedback + +Feedback from IT Admins and developers is welcome, through the [WebView2Feedback](https://github.com/MicrosoftEdge/WebViewFeedback) repo. + +See also: +* [Contact the WebView2 team](../contact.md) + + ## See also * [Distribute your app and the WebView2 Runtime](./distribution.md) - Evergreen vs. fixed version of the WebView2 Runtime. * [Downgrade the WebView2 Runtime to an earlier version](../how-to/enterprise-downgrade.md) +* [Contact the WebView2 team](../contact.md) Microsoft Edge Enterprise documentation: @@ -138,12 +154,14 @@ Microsoft Edge Enterprise documentation: * [Microsoft Edge release schedule](/deployedge/microsoft-edge-release-schedule) * [Release notes for Microsoft Edge Security Updates](/deployedge/microsoft-edge-relnotes-security) * [Configure Microsoft Edge policy settings on Windows devices](/deployedge/configure-microsoft-edge) +* [Downgrade the WebView2 Runtime to an earlier version](/deployedge/webview2-downgrade-runtime) * [Microsoft Edge - Policies](/deployedge/microsoft-edge-policies) * [Microsoft Edge - Update policies](/deployedge/microsoft-edge-update-policies) * [Update](/deployedge/microsoft-edge-update-policies#update) * [UpdatesSuppressed](/deployedge/microsoft-edge-update-policies#updatessuppressed) * [Update (WebView)](/deployedge/microsoft-edge-update-policies#update-webview) * [Microsoft Edge WebView2 - Policies](/deployedge/microsoft-edge-webview-policies) + * [DowngradeVersion](/deployedge/microsoft-edge-webview-policies#downgradeversion) Modern Lifecycle Policy documentation: * [Modern Lifecycle Policy](/lifecycle/policies/modern) From da1eb473c609c87203bfd7861ae4020a8b829752 Mon Sep 17 00:00:00 2001 From: Michael Hoffman <45407486+mikehoffms@users.noreply.github.com> Date: Sat, 22 Aug 2026 09:31:23 -0700 Subject: [PATCH 23/28] heading reflects content --- microsoft-edge/webview2/concepts/enterprise.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/microsoft-edge/webview2/concepts/enterprise.md b/microsoft-edge/webview2/concepts/enterprise.md index 7e8fc2a05f..55ca3b0d73 100644 --- a/microsoft-edge/webview2/concepts/enterprise.md +++ b/microsoft-edge/webview2/concepts/enterprise.md @@ -24,7 +24,7 @@ Many policies are about updating the WebView2 Runtime. A developer can integrat * [Microsoft Edge Lifecycle Policy](#microsoft-edge-lifecycle-policy) * [WebView2-specific policies](#webview2-specific-policies) * [Downgrading the WebView Runtime to an earlier version (`DowngradeVersion`)](#downgrading-the-webview-runtime-to-an-earlier-version-downgradeversion) -* [Browser policies](#browser-policies) +* [Browser policies vs. WebView2 policies](#browser-policies-vs-webview2-policies) * [Windows Server Update Services (WSUS)](#windows-server-update-services-wsus) * [WebView2 deployment and update using Configuration Manager](#webview2-deployment-and-update-using-configuration-manager) * [Feedback](#feedback) @@ -105,11 +105,15 @@ See also: -## Browser policies +## Browser policies vs. WebView2 policies -[Microsoft Edge - Policies](/deployedge/microsoft-edge-policies) doesn't apply to WebView2 applications. This is by design, because apps and browsers have different use cases, and IT Admins might not be aware of what applications use WebView2. +Browser policies are separate from WebView2 policies. Policies for Microsoft Edge don't apply to the WebView2 Runtime and WebView2 apps. This is by design, because apps and browsers have different use cases, and an IT Admin might not know which apps use WebView2. -Applying browser policies on WebView2 would have unintended consequences. For example, IT Admins can block JavaScript in the browser, and that would break WebView2 apps that use JavaScript. To prevent that, browser policies are separate from WebView2 policies. +Applying browser policies on the WebView2 Runtime would have unintended consequences. For example, the IT Admin can block JavaScript in the browser, and that would break WebView2 apps that use JavaScript. To prevent that, browser policies are separate from WebView2 policies. + +See also: +* [Microsoft Edge - Policies](/deployedge/microsoft-edge-policies), in the Microsoft Edge Enterprise documentation. +* [Microsoft Edge WebView2 - Policies](/deployedge/microsoft-edge-webview-policies), in the Microsoft Edge Enterprise documentation. From 9855030755d42c0ee81465c4a99066ff4be1d21e Mon Sep 17 00:00:00 2001 From: Michael Hoffman <45407486+mikehoffms@users.noreply.github.com> Date: Sat, 22 Aug 2026 09:35:11 -0700 Subject: [PATCH 24/28] move Suppress down --- microsoft-edge/webview2/concepts/enterprise.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/microsoft-edge/webview2/concepts/enterprise.md b/microsoft-edge/webview2/concepts/enterprise.md index 55ca3b0d73..d0fd6bb4d1 100644 --- a/microsoft-edge/webview2/concepts/enterprise.md +++ b/microsoft-edge/webview2/concepts/enterprise.md @@ -18,10 +18,10 @@ Many policies are about updating the WebView2 Runtime. A developer can integrat **Detailed contents:** * [Update policies](#update-policies) - * [Suppressing WebView2 Runtime updates (`UpdatesSuppressed`)](#suppressing-webview2-runtime-updates-updatessuppressed) * [Evergreen Runtime is recommended, rather than a fixed version](#evergreen-runtime-is-recommended-rather-than-a-fixed-version) * [Rapid Response to Chromium vulnerabilities](#rapid-response-to-chromium-vulnerabilities) * [Microsoft Edge Lifecycle Policy](#microsoft-edge-lifecycle-policy) + * [Suppressing WebView2 Runtime updates (`UpdatesSuppressed`)](#suppressing-webview2-runtime-updates-updatessuppressed) * [WebView2-specific policies](#webview2-specific-policies) * [Downgrading the WebView Runtime to an earlier version (`DowngradeVersion`)](#downgrading-the-webview-runtime-to-an-earlier-version-downgradeversion) * [Browser policies vs. WebView2 policies](#browser-policies-vs-webview2-policies) @@ -39,14 +39,6 @@ Many policies are about updating the WebView2 Runtime. A developer can integrat To configure update policies for Microsoft Edge (and the WebView2 Runtime), see [Configure Microsoft Edge policy settings on Windows devices](/deployedge/configure-microsoft-edge), in the Microsoft Edge Enterprise documentation. - -#### Suppressing WebView2 Runtime updates (`UpdatesSuppressed`) - -An IT Admin can suppress updating of the WebView2 Runtime, if auto-updating needs to be suppressed for a short time. After the time period, updating of the WebView2 Runtime resumes. The [UpdatesSuppressed](/deployedge/microsoft-edge-update-policies#updatessuppressed) policy allows an IT Admin to set the time during each day at which to suppress auto-update for both Microsoft Edge and the WebView2 Runtime. This enables an IT Admin to configure preferences and proxies once for both the browser and the WebView2 Runtime, to control their network bandwidth and traffic, or for other purposes. - -However, users should not stop updating their WebView2 Runtime; users should not remain on an older version of the WebView2 Runtime. Using older versions of the WebView2 Runtime isn't recommended. Security updates and servicing updates are only available on the latest Stable channel release (Edge Stable) and the latest Beta channel release (Edge Beta). If you use older releases of the Microsoft WebView2 Runtime, you won't receive the latest quality and security updates. - - #### Evergreen Runtime is recommended, rather than a fixed version @@ -83,6 +75,14 @@ See also: * [Microsoft Edge Lifecycle Policy](/deployedge/microsoft-edge-support-lifecycle), in the Microsoft Edge Enterprise documentation. + +#### Suppressing WebView2 Runtime updates (`UpdatesSuppressed`) + +An IT Admin can suppress updating of the WebView2 Runtime, if auto-updating needs to be suppressed for a short time. After the time period, updating of the WebView2 Runtime resumes. The [UpdatesSuppressed](/deployedge/microsoft-edge-update-policies#updatessuppressed) policy allows an IT Admin to set the time during each day at which to suppress auto-update for both Microsoft Edge and the WebView2 Runtime. This enables an IT Admin to configure preferences and proxies once for both the browser and the WebView2 Runtime, to control their network bandwidth and traffic, or for other purposes. + +However, users should not stop updating their WebView2 Runtime; users should not remain on an older version of the WebView2 Runtime. Using older versions of the WebView2 Runtime isn't recommended. Security updates and servicing updates are only available on the latest Stable channel release (Edge Stable) and the latest Beta channel release (Edge Beta). If you use older releases of the Microsoft WebView2 Runtime, you won't receive the latest quality and security updates. + + ## WebView2-specific policies From 365e5a875620aac088c0197f536898c22b486151 Mon Sep 17 00:00:00 2001 From: Michael Hoffman <45407486+mikehoffms@users.noreply.github.com> Date: Sat, 22 Aug 2026 09:41:50 -0700 Subject: [PATCH 25/28] linkfix --- microsoft-edge/webview2/concepts/enterprise.md | 5 ++--- .../webview2/release-notes/sdk/1-0-721-prerelease.md | 2 +- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/microsoft-edge/webview2/concepts/enterprise.md b/microsoft-edge/webview2/concepts/enterprise.md index d0fd6bb4d1..12105315fc 100644 --- a/microsoft-edge/webview2/concepts/enterprise.md +++ b/microsoft-edge/webview2/concepts/enterprise.md @@ -27,7 +27,7 @@ Many policies are about updating the WebView2 Runtime. A developer can integrat * [Browser policies vs. WebView2 policies](#browser-policies-vs-webview2-policies) * [Windows Server Update Services (WSUS)](#windows-server-update-services-wsus) * [WebView2 deployment and update using Configuration Manager](#webview2-deployment-and-update-using-configuration-manager) -* [Feedback](#feedback) +* [Providing feedback](#providing-feedback) * [See also](#see-also) @@ -136,7 +136,7 @@ See [Update Microsoft Edge](/intune/configmgr/apps/deploy-use/deploy-edge#update -## Feedback +## Providing feedback Feedback from IT Admins and developers is welcome, through the [WebView2Feedback](https://github.com/MicrosoftEdge/WebViewFeedback) repo. @@ -149,7 +149,6 @@ See also: * [Distribute your app and the WebView2 Runtime](./distribution.md) - Evergreen vs. fixed version of the WebView2 Runtime. -* [Downgrade the WebView2 Runtime to an earlier version](../how-to/enterprise-downgrade.md) * [Contact the WebView2 team](../contact.md) diff --git a/microsoft-edge/webview2/release-notes/sdk/1-0-721-prerelease.md b/microsoft-edge/webview2/release-notes/sdk/1-0-721-prerelease.md index dcb55cce80..4030d4af27 100644 --- a/microsoft-edge/webview2/release-notes/sdk/1-0-721-prerelease.md +++ b/microsoft-edge/webview2/release-notes/sdk/1-0-721-prerelease.md @@ -27,7 +27,7 @@ This Prerelease version of the WebView2 SDK requires Microsoft Edge version 86.0 #### Features -* Added [WebView2 Group Policies](/deployedge/microsoft-edge-webview-policies). For best practices, see [group policies for WebView2](../../concepts/enterprise.md#group-policies-for-webview2). +* Added [WebView2 Group Policies](/deployedge/microsoft-edge-webview-policies). For best practices for using group policies, see [Enterprise management of WebView2 Runtimes](../../concepts/enterprise.md). * > [!IMPORTANT] > **Breaking Change**: Deprecated the old registry location. From e62e72d134c307d5a333c6305be326b87dd3f751 Mon Sep 17 00:00:00 2001 From: Michael Hoffman <45407486+mikehoffms@users.noreply.github.com> Date: Sat, 22 Aug 2026 10:00:25 -0700 Subject: [PATCH 26/28] annot links instead of mid-sent --- .../webview2/concepts/enterprise.md | 36 +++++++++++++------ 1 file changed, 25 insertions(+), 11 deletions(-) diff --git a/microsoft-edge/webview2/concepts/enterprise.md b/microsoft-edge/webview2/concepts/enterprise.md index 12105315fc..b36d0d7cd0 100644 --- a/microsoft-edge/webview2/concepts/enterprise.md +++ b/microsoft-edge/webview2/concepts/enterprise.md @@ -34,9 +34,17 @@ Many policies are about updating the WebView2 Runtime. A developer can integrat ## Update policies -[Microsoft Edge - Update policies](/deployedge/microsoft-edge-update-policies) are available for IT Admins to manage the installing and updating aspects of the WebView2 Runtime. The Microsoft Edge browser and WebView2 Runtime are updated using the same update mechanism. The policy applies to both Microsoft Edge and the WebView2 Runtime, unless the policy is channel-specific, such as [Update](/deployedge/microsoft-edge-update-policies#update) and [Update (WebView)](/deployedge/microsoft-edge-update-policies#update-webview). +Microsoft Edge update policies are available for IT Admins to manage the installing and updating aspects of the WebView2 Runtime. The Microsoft Edge browser and WebView2 Runtime are updated using the same update mechanism. -To configure update policies for Microsoft Edge (and the WebView2 Runtime), see [Configure Microsoft Edge policy settings on Windows devices](/deployedge/configure-microsoft-edge), in the Microsoft Edge Enterprise documentation. +A Microsoft Edge update policy applies to both Microsoft Edge and the WebView2 Runtime, unless the policy is channel-specific, such as: +* [Update](/deployedge/microsoft-edge-update-policies#update), in _Microsoft Edge - Update policies_. +* [Update (WebView)](/deployedge/microsoft-edge-update-policies#update-webview), in _Microsoft Edge - Update policies_. + +To configure update policies for Microsoft Edge and the WebView2 Runtime, see: +* [Configure Microsoft Edge policy settings on Windows devices](/deployedge/configure-microsoft-edge), in the Microsoft Edge Enterprise documentation. + +See: +* [Microsoft Edge - Update policies](/deployedge/microsoft-edge-update-policies), in the Microsoft Edge Enterprise documentation. @@ -47,9 +55,10 @@ 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 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. +For details about security fixes in Microsoft Edge (which also apply to WebView2), see: +* [Release notes for Microsoft Edge Security Updates](/deployedge/microsoft-edge-relnotes-security), in the Microsoft Edge Enterprise documentation. -See also: +See: * [Evergreen vs. fixed version of the WebView2 Runtime](./evergreen-vs-fixed-version.md) @@ -70,7 +79,7 @@ Security fixes in the Chromium browser engine address vulnerabilities such as: Microsoft WebView2 follows the Modern Lifecycle Policy. -See also: +See: * [Modern Lifecycle Policy](/lifecycle/policies/modern), in the Modern Lifecycle Policy documentation. * [Microsoft Edge Lifecycle Policy](/deployedge/microsoft-edge-support-lifecycle), in the Microsoft Edge Enterprise documentation. @@ -78,17 +87,20 @@ See also: #### Suppressing WebView2 Runtime updates (`UpdatesSuppressed`) -An IT Admin can suppress updating of the WebView2 Runtime, if auto-updating needs to be suppressed for a short time. After the time period, updating of the WebView2 Runtime resumes. The [UpdatesSuppressed](/deployedge/microsoft-edge-update-policies#updatessuppressed) policy allows an IT Admin to set the time during each day at which to suppress auto-update for both Microsoft Edge and the WebView2 Runtime. This enables an IT Admin to configure preferences and proxies once for both the browser and the WebView2 Runtime, to control their network bandwidth and traffic, or for other purposes. +An IT Admin can suppress updating of the WebView2 Runtime, if auto-updating needs to be suppressed for a short time. After the time period, updating of the WebView2 Runtime resumes. The `UpdatesSuppressed` policy allows an IT Admin to set the time during each day at which to suppress auto-update for both Microsoft Edge and the WebView2 Runtime. This enables an IT Admin to configure preferences and proxies once for both the browser and the WebView2 Runtime, to control their network bandwidth and traffic, or for other purposes. However, users should not stop updating their WebView2 Runtime; users should not remain on an older version of the WebView2 Runtime. Using older versions of the WebView2 Runtime isn't recommended. Security updates and servicing updates are only available on the latest Stable channel release (Edge Stable) and the latest Beta channel release (Edge Beta). If you use older releases of the Microsoft WebView2 Runtime, you won't receive the latest quality and security updates. +See: +* [UpdatesSuppressed](/deployedge/microsoft-edge-update-policies#updatessuppressed), in _Microsoft Edge - Update policies_. + ## WebView2-specific policies Policies that are specific to the WebView2 Runtime are available to the IT Admin, to manage the WebView2 Runtime directly. However, we recommend that the WebView2 app developer implement their own group policies to manage the use of the WebView2 Runtime, because it's easier for the IT Admin to manage a WebView2 app, rather than managing the WebView2 Runtime directly. -See also: +See: * [Microsoft Edge WebView2 - Policies](/deployedge/microsoft-edge-webview-policies), in the Microsoft Edge Enterprise documentation. @@ -99,7 +111,7 @@ Enterprise Downgrade is a temporary, IT Admin-controlled capability that allows The Enterprise Downgrade feature is controlled via the `DowngradeVersion` policy. -See also: +See: * [Downgrade the WebView2 Runtime to an earlier version](/deployedge/webview2-downgrade-runtime), in the Microsoft Edge Enterprise documentation. * [DowngradeVersion](/deployedge/microsoft-edge-webview-policies#downgradeversion) in _Microsoft Edge WebView2 - Policies_. @@ -111,7 +123,7 @@ Browser policies are separate from WebView2 policies. Policies for Microsoft Ed Applying browser policies on the WebView2 Runtime would have unintended consequences. For example, the IT Admin can block JavaScript in the browser, and that would break WebView2 apps that use JavaScript. To prevent that, browser policies are separate from WebView2 policies. -See also: +See: * [Microsoft Edge - Policies](/deployedge/microsoft-edge-policies), in the Microsoft Edge Enterprise documentation. * [Microsoft Edge WebView2 - Policies](/deployedge/microsoft-edge-webview-policies), in the Microsoft Edge Enterprise documentation. @@ -121,7 +133,8 @@ See also: Windows Server Update Services (WSUS) enables IT Admins to deploy the latest Microsoft product updates. You can use WSUS to fully manage the distribution of updates of WebView2 that are released through Microsoft Update to computers on your network. -See [Windows Server Update Services (WSUS) overview](/windows-server/administration/windows-server-update-services/get-started/windows-server-update-services-wsus). +See: +* [Windows Server Update Services (WSUS) overview](/windows-server/administration/windows-server-update-services/get-started/windows-server-update-services-wsus) The recommended way of receiving WebView2 updates is by using the default Microsoft Edge updater. Any modification of update and servicing paths should be done with caution. @@ -132,7 +145,8 @@ The recommended way of receiving WebView2 updates is by using the default Micros In Configuration Manager, WebView2 options exist under the **Microsoft Edge Management** node. -See [Update Microsoft Edge](/intune/configmgr/apps/deploy-use/deploy-edge#update-microsoft-edge) in _Microsoft Edge Management_, in the App management documentation. +See: +* [Update Microsoft Edge](/intune/configmgr/apps/deploy-use/deploy-edge#update-microsoft-edge) in _Microsoft Edge Management_, in the App management documentation. From 6ddad740d9b8214e55aeffa67a7589f211b8662f Mon Sep 17 00:00:00 2001 From: Michael Hoffman <45407486+mikehoffms@users.noreply.github.com> Date: Sat, 22 Aug 2026 10:11:49 -0700 Subject: [PATCH 27/28] re-seq security link --- microsoft-edge/webview2/concepts/enterprise.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/microsoft-edge/webview2/concepts/enterprise.md b/microsoft-edge/webview2/concepts/enterprise.md index b36d0d7cd0..dc1022b68d 100644 --- a/microsoft-edge/webview2/concepts/enterprise.md +++ b/microsoft-edge/webview2/concepts/enterprise.md @@ -55,12 +55,12 @@ 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 details about security fixes in Microsoft Edge (which also apply to WebView2), see: -* [Release notes for Microsoft Edge Security Updates](/deployedge/microsoft-edge-relnotes-security), in the Microsoft Edge Enterprise documentation. - See: * [Evergreen vs. fixed version of the WebView2 Runtime](./evergreen-vs-fixed-version.md) +For details about security fixes in Microsoft Edge (which also apply to WebView2), see: +* [Release notes for Microsoft Edge Security Updates](/deployedge/microsoft-edge-relnotes-security), in the Microsoft Edge Enterprise documentation. + #### Rapid Response to Chromium vulnerabilities @@ -73,6 +73,9 @@ Security fixes in the Chromium browser engine address vulnerabilities such as: * **Privilege escalation** – Reduces chances of unauthorized system access. * **Information disclosure and spoofing** – Protects sensitive data, and helps prevent phishing attacks. +For details about security fixes in Microsoft Edge (which also apply to WebView2), see: +* [Release notes for Microsoft Edge Security Updates](/deployedge/microsoft-edge-relnotes-security), in the Microsoft Edge Enterprise documentation. + #### Microsoft Edge Lifecycle Policy From e149c606e370cfbf666198dfae8dada1a9a6ddbd Mon Sep 17 00:00:00 2001 From: Michael Hoffman <45407486+mikehoffms@users.noreply.github.com> Date: Sat, 22 Aug 2026 10:13:49 -0700 Subject: [PATCH 28/28] Rapid response --- microsoft-edge/webview2/concepts/enterprise.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/microsoft-edge/webview2/concepts/enterprise.md b/microsoft-edge/webview2/concepts/enterprise.md index dc1022b68d..ec984afa50 100644 --- a/microsoft-edge/webview2/concepts/enterprise.md +++ b/microsoft-edge/webview2/concepts/enterprise.md @@ -19,7 +19,7 @@ Many policies are about updating the WebView2 Runtime. A developer can integrat **Detailed contents:** * [Update policies](#update-policies) * [Evergreen Runtime is recommended, rather than a fixed version](#evergreen-runtime-is-recommended-rather-than-a-fixed-version) - * [Rapid Response to Chromium vulnerabilities](#rapid-response-to-chromium-vulnerabilities) + * [Rapid response to Chromium vulnerabilities](#rapid-response-to-chromium-vulnerabilities) * [Microsoft Edge Lifecycle Policy](#microsoft-edge-lifecycle-policy) * [Suppressing WebView2 Runtime updates (`UpdatesSuppressed`)](#suppressing-webview2-runtime-updates-updatessuppressed) * [WebView2-specific policies](#webview2-specific-policies) @@ -63,12 +63,11 @@ For details about security fixes in Microsoft Edge (which also apply to WebView2 -#### Rapid Response to Chromium vulnerabilities +#### Rapid response to Chromium vulnerabilities To help maintain a secure browsing environment, Microsoft Edge addresses vulnerabilities in the Chromium browser engine soon after the vulnerabilities are disclosed. Security fixes in the Chromium browser engine address vulnerabilities such as: - * **Remote code execution** – Mitigates risks of arbitrary code execution via malicious content. * **Privilege escalation** – Reduces chances of unauthorized system access. * **Information disclosure and spoofing** – Protects sensitive data, and helps prevent phishing attacks.