From 0efe9f621874ae328d2db89d3ab1a270b63ab84f Mon Sep 17 00:00:00 2001 From: Luke Latham <1622880+guardrex@users.noreply.github.com> Date: Mon, 27 Apr 2026 09:15:15 -0400 Subject: [PATCH 1/4] Distribute fixed version of the Windows WebView2 Runtime Adding detailed instructions for using and distributing a fixed version of the Windows WebView2 Runtime, including steps for downloading, expanding, renaming, and setting up in the project. --- .../security/security-considerations.md | 62 ++++++++++++++++++- 1 file changed, 60 insertions(+), 2 deletions(-) diff --git a/aspnetcore/blazor/hybrid/security/security-considerations.md b/aspnetcore/blazor/hybrid/security/security-considerations.md index c8cb0deea564..0017003c4640 100644 --- a/aspnetcore/blazor/hybrid/security/security-considerations.md +++ b/aspnetcore/blazor/hybrid/security/security-considerations.md @@ -71,7 +71,7 @@ The control us Use one of the following approaches to keep the Web View current in deployed apps: * **On all platforms**: Check the Web View version and prompt the user to take any necessary steps to update it. -* **Only on Windows**: Package a fixed-version Web View within the app, using it in place of the system's shared Web View. +* **Only on Windows**: Package a fixed-version Web View within the app, using it in place of the system's shared Web View. For more information, see the [Use and distribute a fixed version of the Windows `Webview2` Runtime](#use-and-distribute-a-fixed-version-of-the-windows-webview2-runtime) section. ### Android @@ -90,10 +90,68 @@ iOS and :::no-loc text="Mac Catalyst"::: both use [`WKWebView`](https://develope On Windows, the Chromium-based [Microsoft Edge `WebView2`](/microsoft-edge/webview2/) is required to run Blazor Web Apps. -The newest installed version of `WebView2`, known as the *:::no-loc text="Evergreen distribution":::*, is used. If you wish to ship a specific version of `WebView2` with the app, use the *:::no-loc text="Fixed Version distribution":::*. +The newest installed version of `WebView2`, known as the *:::no-loc text="Evergreen distribution":::*, is used. If you wish to ship a specific version of `WebView2` with the app, use the *:::no-loc text="Fixed Version distribution":::* (see the [Use and distribute a fixed version of the Windows `Webview2` Runtime](#use-and-distribute-a-fixed-version-of-the-windows-webview2-runtime) section). For more information on checking the currently-installed `WebView2` version and the distribution modes, see the [`WebView2` distribution documentation](/microsoft-edge/webview2/concepts/distribution). +## Use and distribute a fixed version of the Windows `WebView2` Runtime + +Follow the guidance in this section to use and distribute a fixed version of the Chromium-based [Microsoft Edge `WebView2`](/microsoft-edge/webview2/) Runtime. + +Download the **Fixed Version** installer packages from [Microsoft Edge WebView2: Download the WebView2 Runtime](https://developer.microsoft.com/microsoft-edge/webview2). + +The following steps place the packages into `Runtimex86`, `Runtimex64`, and `RuntimeARM64` folders in the app's solution folder, maintaining the files outside of the project to keep the **Solution Explorer** view of the project focused on the app's developer assets. + +After downloading the runtime, use the [`expand` command](/windows-server/administration/windows-commands/expand) in a command shell to expand the `.cab` file from the system's `C:\Downloads` folder into the solution's root folder: + +```cli +expand {PATH TO THE PACKAGE} -F:* {PATH TO THE DESTINATION FOLDER} +``` + +Placeholders: + +* `{PATH TO THE PACKAGE}`: The path to the package. +* `{PATH TO THE DESTINATION FOLDER}`: The path to the destination folder, which is the project's solution folder. + +Example using a solution folder path of `C:\src\MySolution\`: + +```cli +expand "C:\Downloads\Microsoft.WebView2.FixedVersionRuntime.114.0.1823.79.x64.cab" -F:* C:\src\MySolution\ +``` + +Rename the folder to `Runtimex86` with the [`Rename-Item` PowerShell cmdlet](/powershell/module/microsoft.powershell.management/rename-item): + +```powershell +rename-item "C:\src\MySolution\Microsoft.WebView2.FixedVersionRuntime.114.0.1823.79.x64" "C:\src\MySolution\Runtimex86" +``` + +Copy the contents of the `Runtimex86` folder to the `Runtimex64` and `RuntimeARM64` folders. + +Add the following code to `CreateMauiApp` method in `MauiProgram.cs`: + +```csharp +#if WINDOWS + string relativePath = @"\Runtime"; + string basePath = AppContext.BaseDirectory; + string wvrPath = Path.Combine(basePath, relativePath); + Environment.SetEnvironmentVariable("WEBVIEW2_BROWSER_EXECUTABLE_FOLDER", wvrPath); +#endif +``` + +In the app's project file (`.csproj`), add the following after the existing `` element: + +```xml + + + +``` + ## Additional resources * From 3eefb15e74c7d01e902d56729552757b10254892 Mon Sep 17 00:00:00 2001 From: Luke Latham <1622880+guardrex@users.noreply.github.com> Date: Mon, 27 Apr 2026 09:46:58 -0400 Subject: [PATCH 2/4] Updates --- .../security/security-considerations.md | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/aspnetcore/blazor/hybrid/security/security-considerations.md b/aspnetcore/blazor/hybrid/security/security-considerations.md index 0017003c4640..6f88beab35f9 100644 --- a/aspnetcore/blazor/hybrid/security/security-considerations.md +++ b/aspnetcore/blazor/hybrid/security/security-considerations.md @@ -1,5 +1,6 @@ --- title: ASP.NET Core Blazor Hybrid security considerations +ai-usage: ai-assisted author: guardrex description: Learn about security considerations when developing apps in Blazor Hybrid. monikerRange: '>= aspnetcore-6.0' @@ -71,7 +72,7 @@ The control us Use one of the following approaches to keep the Web View current in deployed apps: * **On all platforms**: Check the Web View version and prompt the user to take any necessary steps to update it. -* **Only on Windows**: Package a fixed-version Web View within the app, using it in place of the system's shared Web View. For more information, see the [Use and distribute a fixed version of the Windows `Webview2` Runtime](#use-and-distribute-a-fixed-version-of-the-windows-webview2-runtime) section. +* **Only on Windows**: Package a fixed-version Web View within the app, using it in place of the system's shared Web View. For more information, see the [Use and distribute a fixed version of the Windows `WebView2` Runtime](#use-and-distribute-a-fixed-version-of-the-windows-webview2-runtime) section. ### Android @@ -90,7 +91,7 @@ iOS and :::no-loc text="Mac Catalyst"::: both use [`WKWebView`](https://develope On Windows, the Chromium-based [Microsoft Edge `WebView2`](/microsoft-edge/webview2/) is required to run Blazor Web Apps. -The newest installed version of `WebView2`, known as the *:::no-loc text="Evergreen distribution":::*, is used. If you wish to ship a specific version of `WebView2` with the app, use the *:::no-loc text="Fixed Version distribution":::* (see the [Use and distribute a fixed version of the Windows `Webview2` Runtime](#use-and-distribute-a-fixed-version-of-the-windows-webview2-runtime) section). +The newest installed version of `WebView2`, known as the *:::no-loc text="Evergreen distribution":::*, is used. If you wish to ship a specific version of `WebView2` with the app, use the *:::no-loc text="Fixed Version distribution":::* (see the [Use and distribute a fixed version of the Windows `WebView2` Runtime](#use-and-distribute-a-fixed-version-of-the-windows-webview2-runtime) section). For more information on checking the currently-installed `WebView2` version and the distribution modes, see the [`WebView2` distribution documentation](/microsoft-edge/webview2/concepts/distribution). @@ -102,7 +103,7 @@ Download the **Fixed Version** installer packages from [Microsoft Edge WebView2: The following steps place the packages into `Runtimex86`, `Runtimex64`, and `RuntimeARM64` folders in the app's solution folder, maintaining the files outside of the project to keep the **Solution Explorer** view of the project focused on the app's developer assets. -After downloading the runtime, use the [`expand` command](/windows-server/administration/windows-commands/expand) in a command shell to expand the `.cab` file from the system's `C:\Downloads` folder into the solution's root folder: +After downloading a runtime, use the [`expand` command](/windows-server/administration/windows-commands/expand) in a command shell to expand the `.cab` file from the system's `C:\Users\{USERNAME}\Downloads` folder into the solution's root folder: ```cli expand {PATH TO THE PACKAGE} -F:* {PATH TO THE DESTINATION FOLDER} @@ -113,10 +114,14 @@ Placeholders: * `{PATH TO THE PACKAGE}`: The path to the package. * `{PATH TO THE DESTINATION FOLDER}`: The path to the destination folder, which is the project's solution folder. -Example using a solution folder path of `C:\src\MySolution\`: +The following example uses: + +* The x86 runtime package `.cab` file (`Microsoft.WebView2.FixedVersionRuntime.114.0.1823.79.x86.cab`). +* A package path of `C:\Users\{USERNAME}\Downloads\`, where the `{USERNAME}` placeholder is the Windows user profile name. +* A solution folder path of `C:\src\MySolution\`. ```cli -expand "C:\Downloads\Microsoft.WebView2.FixedVersionRuntime.114.0.1823.79.x64.cab" -F:* C:\src\MySolution\ +expand "C:\Users\{USERNAME}\Downloads\Microsoft.WebView2.FixedVersionRuntime.114.0.1823.79.x86.cab" -F:* C:\src\MySolution\ ``` Rename the folder to `Runtimex86` with the [`Rename-Item` PowerShell cmdlet](/powershell/module/microsoft.powershell.management/rename-item): @@ -125,13 +130,13 @@ Rename the folder to `Runtimex86` with the [`Rename-Item` PowerShell cmdlet](/po rename-item "C:\src\MySolution\Microsoft.WebView2.FixedVersionRuntime.114.0.1823.79.x64" "C:\src\MySolution\Runtimex86" ``` -Copy the contents of the `Runtimex86` folder to the `Runtimex64` and `RuntimeARM64` folders. +Repeat the preceding steps for the x64 and ARM64 runtimes. Add the following code to `CreateMauiApp` method in `MauiProgram.cs`: ```csharp #if WINDOWS - string relativePath = @"\Runtime"; + string relativePath = @"Runtime"; string basePath = AppContext.BaseDirectory; string wvrPath = Path.Combine(basePath, relativePath); Environment.SetEnvironmentVariable("WEBVIEW2_BROWSER_EXECUTABLE_FOLDER", wvrPath); From 1331090debdb70a2a7186ace855a4de5fbf9d8c7 Mon Sep 17 00:00:00 2001 From: Luke Latham <1622880+guardrex@users.noreply.github.com> Date: Mon, 27 Apr 2026 09:57:06 -0400 Subject: [PATCH 3/4] Updates Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Co-authored-by: Luke Latham <1622880+guardrex@users.noreply.github.com> --- .../blazor/hybrid/security/security-considerations.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/aspnetcore/blazor/hybrid/security/security-considerations.md b/aspnetcore/blazor/hybrid/security/security-considerations.md index 6f88beab35f9..b6c6023afc47 100644 --- a/aspnetcore/blazor/hybrid/security/security-considerations.md +++ b/aspnetcore/blazor/hybrid/security/security-considerations.md @@ -101,9 +101,9 @@ Follow the guidance in this section to use and distribute a fixed version of the Download the **Fixed Version** installer packages from [Microsoft Edge WebView2: Download the WebView2 Runtime](https://developer.microsoft.com/microsoft-edge/webview2). -The following steps place the packages into `Runtimex86`, `Runtimex64`, and `RuntimeARM64` folders in the app's solution folder, maintaining the files outside of the project to keep the **Solution Explorer** view of the project focused on the app's developer assets. +The following steps place the packages into `Runtimex86`, `Runtimex64`, and `RuntimeARM64` folders in the parent folder of the app's solution folder, maintaining the files outside of the project to keep the **Solution Explorer** view of the project focused on the app's developer assets. -After downloading a runtime, use the [`expand` command](/windows-server/administration/windows-commands/expand) in a command shell to expand the `.cab` file from the system's `C:\Users\{USERNAME}\Downloads` folder into the solution's root folder: +After downloading a runtime, use the [`expand` command](/windows-server/administration/windows-commands/expand) in a command shell to expand the `.cab` file from the system's `C:\Users\{USER}\Downloads` folder into the solution's root folder: ```cli expand {PATH TO THE PACKAGE} -F:* {PATH TO THE DESTINATION FOLDER} @@ -117,17 +117,17 @@ Placeholders: The following example uses: * The x86 runtime package `.cab` file (`Microsoft.WebView2.FixedVersionRuntime.114.0.1823.79.x86.cab`). -* A package path of `C:\Users\{USERNAME}\Downloads\`, where the `{USERNAME}` placeholder is the Windows user profile name. +* A package path of `C:\Users\{USER}\Downloads\`, where the `{USER}` placeholder is the Windows user profile name. * A solution folder path of `C:\src\MySolution\`. ```cli -expand "C:\Users\{USERNAME}\Downloads\Microsoft.WebView2.FixedVersionRuntime.114.0.1823.79.x86.cab" -F:* C:\src\MySolution\ +expand "C:\Users\{USER}\Downloads\Microsoft.WebView2.FixedVersionRuntime.114.0.1823.79.x86.cab" -F:* C:\src\MySolution\ ``` Rename the folder to `Runtimex86` with the [`Rename-Item` PowerShell cmdlet](/powershell/module/microsoft.powershell.management/rename-item): ```powershell -rename-item "C:\src\MySolution\Microsoft.WebView2.FixedVersionRuntime.114.0.1823.79.x64" "C:\src\MySolution\Runtimex86" +rename-item "C:\src\MySolution\Microsoft.WebView2.FixedVersionRuntime.114.0.1823.79.x86" "C:\src\MySolution\Runtimex86" ``` Repeat the preceding steps for the x64 and ARM64 runtimes. From 9f71e1166c9432f036810337c85faa523b33603e Mon Sep 17 00:00:00 2001 From: Luke Latham <1622880+guardrex@users.noreply.github.com> Date: Mon, 27 Apr 2026 09:59:06 -0400 Subject: [PATCH 4/4] Updates Co-authored-by: Luke Latham <1622880+guardrex@users.noreply.github.com> --- aspnetcore/blazor/hybrid/security/security-considerations.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/aspnetcore/blazor/hybrid/security/security-considerations.md b/aspnetcore/blazor/hybrid/security/security-considerations.md index b6c6023afc47..584527d16eb3 100644 --- a/aspnetcore/blazor/hybrid/security/security-considerations.md +++ b/aspnetcore/blazor/hybrid/security/security-considerations.md @@ -89,7 +89,7 @@ iOS and :::no-loc text="Mac Catalyst"::: both use [`WKWebView`](https://develope ### Windows (.NET MAUI, WPF, Windows Forms) -On Windows, the Chromium-based [Microsoft Edge `WebView2`](/microsoft-edge/webview2/) is required to run Blazor Web Apps. +On Windows, the Chromium-based [Microsoft Edge `WebView2`](/microsoft-edge/webview2/) is required for Blazor Hybrid/`BlazorWebView` apps. The newest installed version of `WebView2`, known as the *:::no-loc text="Evergreen distribution":::*, is used. If you wish to ship a specific version of `WebView2` with the app, use the *:::no-loc text="Fixed Version distribution":::* (see the [Use and distribute a fixed version of the Windows `WebView2` Runtime](#use-and-distribute-a-fixed-version-of-the-windows-webview2-runtime) section). @@ -97,7 +97,7 @@ For more information on checking the currently-installed `WebView2` version and ## Use and distribute a fixed version of the Windows `WebView2` Runtime -Follow the guidance in this section to use and distribute a fixed version of the Chromium-based [Microsoft Edge `WebView2`](/microsoft-edge/webview2/) Runtime. +Follow the guidance in this section to use and distribute a fixed version of the Chromium-based [Microsoft Edge `WebView2`](/microsoft-edge/webview2/) Runtime for Blazor Hybrid/`BlazorWebView` apps. Download the **Fixed Version** installer packages from [Microsoft Edge WebView2: Download the WebView2 Runtime](https://developer.microsoft.com/microsoft-edge/webview2).