Add Windows Program Files warning for WebView2/BlazorWebView/HybridWebView

Co-authored-by: jfversluis <939291+jfversluis@users.noreply.github.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,18 @@ 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.
 
+> [!WARNING]
+> On Windows, apps using <xref:Microsoft.AspNetCore.Components.WebView.Maui.BlazorWebView> 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 the <xref:Microsoft.AspNetCore.Components.WebView.Maui.BlazorWebView> 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 <xref:Microsoft.AspNetCore.Components.WebView.Maui.BlazorWebView> is created. This directs WebView2 to use a writable location in the user's AppData directory instead of the restricted Program Files location.
+
 For more information about Blazor Hybrid apps, see [ASP.NET Core Blazor Hybrid](/aspnet/core/blazor/hybrid).
 
 ## Create a .NET MAUI Blazor app

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,18 @@ 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).
 
+> [!WARNING]
+> On Windows, apps using <xref:Microsoft.Maui.Controls.HybridWebView> 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 the <xref:Microsoft.Maui.Controls.HybridWebView> 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 <xref:Microsoft.Maui.Controls.HybridWebView> is created. This directs WebView2 to use a writable location in the user's AppData directory instead of the restricted Program Files location.
+
 ## Create a .NET MAUI HybridWebView app
 
 To create a .NET MAUI app with a <xref:Microsoft.Maui.Controls.HybridWebView>:

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,18 @@ 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.
 
+> [!WARNING]
+> On Windows, apps using <xref:Microsoft.Maui.Controls.WebView> 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 the <xref:Microsoft.Maui.Controls.WebView> 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 <xref:Microsoft.Maui.Controls.WebView> is created. This directs WebView2 to use a writable location in the user's AppData directory instead of the restricted Program Files location.
+
 ## Display a web page
 
 To display a remote web page, set the `Source` property to a `string` that specifies the URI: