Merge pull request #36123 from dotnet/main

Author: guardrex

aspnetcore/blazor/host-and-deploy/configure-trimmer.md

@@ -83,20 +83,20 @@ Consider the following example that performs JSON deserialization into a <xref:S
 
 The preceding component executes normally when the app is run locally and produces the following rendered list:
 
-> • 1:T1, 1:T2
+> • 1:T1, 1:T2  
 > • 2:T2, 2:T2
 
 When the app is published, <xref:System.Tuple%602> is trimmed from the app, even in spite of setting the `<PublishTrimmed>` property to `false` in the project file. Accessing the component throws the following exception:
 
-> :::no-loc text="crit: Microsoft.AspNetCore.Components.WebAssembly.Rendering.WebAssemblyRenderer[100]":::
-> :::no-loc text="Unhandled exception rendering component: ConstructorContainsNullParameterNames, System.Tuple`2[System.String,System.String]":::
+> :::no-loc text="crit: Microsoft.AspNetCore.Components.WebAssembly.Rendering.WebAssemblyRenderer[100]":::  
+> :::no-loc text="Unhandled exception rendering component: ConstructorContainsNullParameterNames, System.Tuple`2[System.String,System.String]":::  
 > :::no-loc text="System.NotSupportedException: ConstructorContainsNullParameterNames, System.Tuple`2[System.String,System.String]":::
 
 To address lost types, consider adopting one of the following approaches.
 
 ### Custom types
 
-Custom types aren't trimmed by Blazor when an app is published, so we recommend using custom types for JS interop, JSON serialization/deserialization, and other operations that rely on reflection.
+Custom types aren't trimmed by Blazor when an app is published (unless explicitly opted in), so we recommend using custom types for JS interop, JSON serialization/deserialization, and other operations that rely on reflection.
 
 The following modifications create a `StringTuple` type for use by the component.
 
@@ -123,7 +123,7 @@ The component is modified to use the `StringTuple` type:
 + items = JsonSerializer.Deserialize<List<StringTuple>>(data, options)!;
 ```
 
-Because custom types are never trimmed by Blazor when an app is published, the component works as designed after the app is published.
+Because custom types aren't trimmed by Blazor when an app is published (unless explicitly opted in), the component works as designed after the app is published.
 
 :::moniker range=">= aspnetcore-10.0"
 

aspnetcore/blazor/host-and-deploy/index.md

@@ -137,6 +137,17 @@ Demonstration sample apps for Blazor WebAssembly in a React app (`BlazorWebAssem
 
 :::moniker-end
 
+:::moniker range=">= aspnetcore-8.0"
+
+## Aspects of Blazor WebAssembly caching apply to Blazor Web Apps
+
+Blazor bundle caching and HTTP caching guidance in the *Blazor WebAssembly* node focus on standalone Blazor WebAssembly apps, but several aspects of client-side caching in these articles also apply to Blazor Web Apps that adopt Interactive WebAssembly or Interactive Auto render modes. If a Blazor Web App that renders content client-side encounters a static asset or bundle caching problem, see the guidance in these articles to troubleshoot the problem:
+
+* <xref:blazor/host-and-deploy/webassembly/bundle-caching-and-integrity-check-failures>
+* <xref:blazor/host-and-deploy/webassembly/http-caching-issues>
+
+:::moniker-end
+
 ## Blazor Server `MapFallbackToPage` configuration
 
 *This section only applies to Blazor Server apps. <xref:Microsoft.AspNetCore.Builder.RazorPagesEndpointRouteBuilderExtensions.MapFallbackToPage%2A> isn't supported in Blazor Web Apps and Blazor WebAssembly apps.*

aspnetcore/blazor/host-and-deploy/webassembly/http-caching-issues.md

@@ -21,7 +21,7 @@ While future Blazor releases might provide better solutions for dealing with HTT
 Common problems that negatively impact the user upgrade experience include:
 
 * **Incorrect handling of project and package updates**: This happens if you don't update all of the app's deployed projects to use the same major framework version or if you use packages from a previous version when a newer version is available as part of the major upgrade.
-* **Incorrect configuration of caching headers**: HTTP caching headers control how, where, and for how long the app's responses are cached. If headers aren't configured correctly, users might receive stale content.
+* **Incorrect configuration of caching headers**: HTTP caching headers control how, where, and for how long the app's responses are cached. If headers aren't configured correctly, users might receive stale or mismatched files. This includes [Blazor bundle assets caching](xref:blazor/host-and-deploy/webassembly/bundle-caching-and-integrity-check-failures), where server caching headers must be properly set to avoid caching problems on the client.
 * **Incorrect configuration of other layers**: Content Delivery Networks (CDNs) and other layers of the deployed app can cause issues if incorrectly configured. For example, CDNs are designed to cache and deliver content to improve performance and reduce latency. If a CDN is incorrectly serving cached versions of assets, it can lead to stale content delivery to the user.
 
 ## Detect and diagnose upgrade issues
@@ -42,7 +42,7 @@ Ensure that framework packages line up with the framework version. Using package
 
 ### Verify the presence of correct caching headers
 
-The correct caching headers should be present on responses to resource requests. This includes `ETag`, `Cache-Control`, and other caching headers. The configuration of these headers is dependent on the hosting service or hosting server platform. They are particularly important for assets such as the Blazor script (`blazor.webassembly.js`) and anything the script downloads.
+The correct caching headers should be present on responses to resource requests. This includes `ETag`, `Cache-Control`, and other caching headers. The configuration of these headers is dependent on the hosting service or hosting server platform. They are particularly important for assets such as the [Blazor script](xref:blazor/project-structure#location-of-the-blazor-script) and anything the script downloads.
 
 Incorrect HTTP caching headers may also impact service workers. Service workers rely on caching headers to manage cached resources effectively. Therefore, incorrect or missing headers can disrupt the service worker's functionality.
 

aspnetcore/blazor/hybrid/tutorials/maui-blazor-web-app.md

@@ -5,7 +5,7 @@ description: Learn how to build a .NET MAUI Blazor Hybrid app with a Blazor Web
 monikerRange: '>= aspnetcore-8.0'
 ms.author: wpickett
 ms.custom: mvc
-ms.date: 11/12/2024
+ms.date: 09/17/2025
 uid: blazor/hybrid/tutorials/maui-blazor-web-app
 ---
 # Build a .NET MAUI Blazor Hybrid app with a Blazor Web App
@@ -30,18 +30,24 @@ If you haven't already installed the .NET MAUI workload, install it now. The .NE
 dotnet workload install maui
 ```
 
-Create a solution from the project template with the following .NET CLI command:
+Create a solution from the project template with the following .NET CLI command, replacing the `{INTERACTIVITY}` placeholder with the Blazor render mode that you desire to use:
+
+* `Server`: Adopts the Interactive Server render mode and produces a single-project Blazor app.
+* `WebAssembly`: Adopts the Interactive WebAssembly render mode and produces two Blazor projects, a server project and a `.Client` project.
+* `Auto`: Adopts the Interactive Auto render mode and produces two Blazor projects, a server project and a `.Client` project.
+
+For more information on the preceding render modes and the projects produced, see <xref:blazor/components/render-modes#render-modes> and the [Use Blazor render modes](#use-blazor-render-modes) section later in this article.
 
 ```dotnetcli
-dotnet new maui-blazor-web -o MauiBlazorWeb -I Server
+dotnet new maui-blazor-web -o MauiBlazorWeb -I {INTERACTIVITY}
 ```
 
 In the preceding command:
 
 * The `-o|--output` option creates a new folder for the app named `MauiBlazorWeb`.
-* The `-I|--InteractivityPlatform` option sets the interactivity render mode to Interactive Server (`InteractiveServer`). All three interactive Blazor render modes (`Server`, `WebAssembly`, and `Auto`) are supported by the project template. For more information, see the [Use Blazor render modes](#use-blazor-render-modes) section.
+* The `-I|--InteractivityPlatform` option sets the interactivity render mode. The `{INTERACTIVITY}` placeholder is the interactive Blazor render mode. All three interactive Blazor render modes (`Server`, `WebAssembly`, and `Auto`) are supported by the project template. For more information, see <xref:blazor/components/render-modes#render-modes> and the [Use Blazor render modes](#use-blazor-render-modes) section.
 
-The app automatically adopts global interactivity, which is important because MAUI apps always run interactively and throw errors on Razor component pages that explicitly specify a render mode. For more information, see [BlazorWebView needs a way to enable overriding ResolveComponentForRenderMode (`dotnet/aspnetcore` #51235)](https://github.com/dotnet/aspnetcore/issues/51235).
+The preceding command produces a Blazor app that adopts global interactivity, which is important because MAUI apps always run interactively and throw errors on Razor component pages that explicitly specify a render mode. For more information, see [BlazorWebView needs a way to enable overriding ResolveComponentForRenderMode (`dotnet/aspnetcore` #51235)](https://github.com/dotnet/aspnetcore/issues/51235).
 
 :::moniker-end