Document WebView2/BlazorWebView/HybridWebView issues with Program Files installation (#3035)

* Initial plan

* Add Windows Program Files warning for WebView2/BlazorWebView/HybridWebView

Co-authored-by: jfversluis <939291+jfversluis@users.noreply.github.com>

* Extract WebView2 Program Files warning into reusable include snippet

Co-authored-by: jfversluis <939291+jfversluis@users.noreply.github.com>

* Fix markdown linting errors in webview2-program-files-warning.md

Co-authored-by: jfversluis <939291+jfversluis@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: jfversluis <939291+jfversluis@users.noreply.github.com>
Co-authored-by: Gerald Versluis <gerald.versluis@microsoft.com>

Author: Copilot

docs/user-interface/controls/blazorwebview.md

@@ -1,7 +1,7 @@
 ---
 title: "Host a Blazor web app in a .NET MAUI app using BlazorWebView"
 description: "The .NET MAUI BlazorWebView control enables you to host a Blazor web app in your .NET MAUI app, and integrate the app with device features."
-ms.date: 05/13/2025
+ms.date: 09/19/2025
 ---
 
 # Host a Blazor web app in a .NET MAUI app using BlazorWebView
@@ -33,6 +33,8 @@ Browser developer tools can be used to inspect .NET MAUI Blazor apps. For more i
 > [!NOTE]
 > While Visual Studio installs all the required tooling to develop .NET MAUI Blazor apps, end users of .NET MAUI Blazor apps on Windows must install the [WebView2](https://developer.microsoft.com/microsoft-edge/webview2/) runtime.
 
+[!INCLUDE [WebView2 Program Files warning](includes/webview2-program-files-warning.md)]
+
 For more information about Blazor Hybrid apps, see [ASP.NET Core Blazor Hybrid](/aspnet/core/blazor/hybrid).
 
 [!INCLUDE [browser-engines](includes/browser-engines.md)]

docs/user-interface/controls/hybridwebview.md

@@ -2,7 +2,7 @@
 title: HybridWebView
 description: Learn how to use a HybridWebView to host HTML/JS/CSS content in a WebView, and communicate between that content and .NET.
 ms.topic: concept-article
-ms.date: 08/20/2025
+ms.date: 09/19/2025
 monikerRange: ">=net-maui-9.0"
 
 #customer intent: As a developer, I want to host HTML/JS/CSS content in a web view so that I can publish the web app as a mobile app.
@@ -34,6 +34,8 @@ The entire app, including the web content, is packaged and runs locally on a dev
 > [!IMPORTANT]
 > By default, the <xref:Microsoft.Maui.Controls.HybridWebView> control won't be available when full trimming or Native AOT is enabled. To change this behavior, see [Trimming feature switches](~/deployment/trimming.md#trimming-feature-switches).
 
+[!INCLUDE [WebView2 Program Files warning](includes/webview2-program-files-warning.md)]
+
 [!INCLUDE [browser-engines](includes/browser-engines.md)]
 
 ## Create a .NET MAUI HybridWebView app

docs/user-interface/controls/includes/webview2-program-files-warning.md

@@ -0,0 +1,16 @@
+---
+ms.topic: include
+ms.date: 09/19/2025
+---
+
+> [!WARNING]
+> On Windows, apps using WebView2-based controls that are installed to the `Program Files` directory may fail to render content properly. This occurs because WebView2 attempts to write its cache and user data files to the app's installation directory, which has restricted write permissions in `Program Files`. To resolve this issue, set the `WEBVIEW2_USER_DATA_FOLDER` environment variable before any WebView control is initialized:
+>
+> ```csharp
+> #if WINDOWS
+> var userDataFolder = Path.Combine(FileSystem.AppDataDirectory, "WebView2");
+> Environment.SetEnvironmentVariable("WEBVIEW2_USER_DATA_FOLDER", userDataFolder);
+> #endif
+> ```
+>
+> Place this code in your `App.xaml.cs` constructor or in `Platforms\Windows\App.xaml.cs` before any WebView control is created. This directs WebView2 to use a writable location in the user's AppData directory instead of the restricted Program Files location.

docs/user-interface/controls/webview.md

@@ -1,7 +1,7 @@
 ---
 title: "WebView"
 description: "This article explains how to use the .NET MAUI WebView to display remote web pages, local HTML files, and HTML strings."
-ms.date: 08/19/2025
+ms.date: 09/19/2025
 zone_pivot_groups: devices-platforms
 ---
 
@@ -40,6 +40,8 @@ The `Source` property can be set to an `UrlWebViewSource` object or a `HtmlWebVi
 > [!IMPORTANT]
 > A <xref:Microsoft.Maui.Controls.WebView> must specify its <xref:Microsoft.Maui.Controls.VisualElement.HeightRequest> and <xref:Microsoft.Maui.Controls.VisualElement.WidthRequest> properties when contained in a <xref:Microsoft.Maui.Controls.HorizontalStackLayout>, <xref:Microsoft.Maui.Controls.StackLayout>, or <xref:Microsoft.Maui.Controls.VerticalStackLayout>. If you fail to specify these properties, the <xref:Microsoft.Maui.Controls.WebView> will not render.
 
+[!INCLUDE [WebView2 Program Files warning](includes/webview2-program-files-warning.md)]
+
 [!INCLUDE [browser-engines](includes/browser-engines.md)]
 
 ## Display a web page