Merge pull request #35139 from dotnet/main

Author: guardrex

.openpublishing.redirection.json

@@ -1387,6 +1387,16 @@
             "source_path": "aspnetcore/blazor/host-and-deploy/server.md",
             "redirect_url": "/aspnet/core/blazor/host-and-deploy/server/",
             "redirect_document_id": false
+        },
+        {
+            "source_path": "aspnetcore/blazor/host-and-deploy/webassembly/runtime-and-app-bundle-caching.md",
+            "redirect_url": "/aspnet/core/blazor/host-and-deploy/webassembly/bundle-caching-and-integrity-check-failures",
+            "redirect_document_id": false
+        },
+        {
+            "source_path": "aspnetcore/blazor/host-and-deploy/webassembly/integrity-check-failures.md",
+            "redirect_url": "/aspnet/core/blazor/host-and-deploy/webassembly/bundle-caching-and-integrity-check-failures",
+            "redirect_document_id": false
         }
     ]
 }

aspnetcore/blazor/fundamentals/startup.md

@@ -489,7 +489,7 @@ When the `loadBootResource` function returns `null`, Blazor uses the default loa
 
 The `loadBootResource` function can also return a [`Response` promise](https://developer.mozilla.org/docs/Web/API/Response). For an example, see <xref:blazor/host-and-deploy/webassembly/index#compression>.
 
-For more information, see <xref:blazor/host-and-deploy/webassembly/runtime-and-app-bundle-caching>.
+For more information, see <xref:blazor/host-and-deploy/webassembly/bundle-caching-and-integrity-check-failures>.
 
 ## Control headers in C# code
 

aspnetcore/blazor/host-and-deploy/webassembly/Integrity-check-failures.md renamed to aspnetcore/blazor/host-and-deploy/webassembly/bundle-caching-and-integrity-check-failures.md

@@ -1,18 +1,26 @@
 ---
-title: Resolve integrity check failures in ASP.NET Core Blazor WebAssembly apps
+title: ASP.NET Core Blazor WebAssembly .NET bundle caching and integrity check failures
 author: guardrex
-description: Learn how to resolve integrity check failures in Blazor WebAssembly apps.
+description: Learn about WebAssembly .NET app and runtime bundle caching and how to resolve integrity check failures in Blazor WebAssembly apps.
 monikerRange: '>= aspnetcore-3.1'
 ms.author: riande
 ms.custom: mvc
-ms.date: 03/31/2025
-uid: blazor/host-and-deploy/webassembly/integrity-check-failures
+ms.date: 04/03/2025
+uid: blazor/host-and-deploy/webassembly/bundle-caching-and-integrity-check-failures
 ---
-# Resolve integrity check failures in ASP.NET Core Blazor WebAssembly apps
+# ASP.NET Core Blazor WebAssembly .NET bundle caching and integrity check failures
 
 [!INCLUDE[](~/includes/not-latest-version.md)]
 
-This article explains how to resolve integrity check failures in Blazor WebAssembly apps.
+This article explains how Blazor WebAssembly caches the WebAssembly .NET runtime and app bundle and how to diagnose and resolve integrity failures.
+
+When a Blazor WebAssembly app loads in the browser, the app downloads boot resources from the server:
+
+* JavaScript code to bootstrap the app
+* .NET runtime and assemblies
+* Locale specific data
+
+Except for Blazor's boot resources file (`blazor.boot.json`), WebAssembly .NET runtime and app bundle files are cached on clients. The `blazor.boot.json` file contains a manifest of the files that make up the app that must be downloaded along with a hash of the file's content that's used to detect whether any of the boot resources have changed. Blazor caches downloaded files using the browser [Cache](https://developer.mozilla.org/docs/Web/API/Cache) API.
 
 When Blazor WebAssembly downloads an app's startup files, it instructs the browser to perform integrity checks on the responses. Blazor sends SHA-256 hash values for DLL (`.dll`), WebAssembly (`.wasm`), and other files in the `blazor.boot.json` file, which isn't cached on clients. The file hashes of cached files are compared to the hashes in the `blazor.boot.json` file. For cached files with a matching hash, Blazor uses the cached files. Otherwise, files are requested from the server. After a file is downloaded, its hash is checked again for integrity validation. An error is generated by the browser if any downloaded file's integrity check fails.
 

aspnetcore/blazor/host-and-deploy/webassembly/github-pages.md

@@ -69,7 +69,7 @@ The GitHub-hosted Ubuntu (latest) server has a version of the .NET SDK pre-insta
 
 The default GitHub Action, which deploys pages, skips deployment of folders starting with underscore, the `_framework` folder for example. To deploy folders starting with underscore, add an empty `.nojekyll` file to the root of the app's repository. Example: [Xref Generator `.nojekyll` file](https://github.com/dotnet/blazor-samples/blob/main/BlazorWebAssemblyXrefGenerator/.nojekyll)
 
-***Perform this step before the first app deployment:*** Git treats JavaScript (JS) files, such as `blazor.webassembly.js`, as text and converts line endings from CRLF (carriage return-line feed) to LF (line feed) in the deployment pipeline. These changes to JS files produce different file hashes than Blazor sends to the client in the `blazor.boot.json` file. The mismatches result in integrity check failures on the client. One approach to solving this problem is to add a `.gitattributes` file with `*.js binary` line before adding the app's assets to the Git branch. The `*.js binary` line configures Git to treat JS files as binary files, which avoids processing the files in the deployment pipeline. The file hashes of the unprocessed files match the entries in the `blazor.boot.json` file, and client-side integrity checks pass. For more information, see <xref:blazor/host-and-deploy/webassembly/runtime-and-app-bundle-caching>. Example: [Xref Generator `.gitattributes` file](https://github.com/dotnet/blazor-samples/blob/main/BlazorWebAssemblyXrefGenerator/.gitattributes)
+***Perform this step before the first app deployment:*** Git treats JavaScript (JS) files, such as `blazor.webassembly.js`, as text and converts line endings from CRLF (carriage return-line feed) to LF (line feed) in the deployment pipeline. These changes to JS files produce different file hashes than Blazor sends to the client in the `blazor.boot.json` file. The mismatches result in integrity check failures on the client. One approach to solving this problem is to add a `.gitattributes` file with `*.js binary` line before adding the app's assets to the Git branch. The `*.js binary` line configures Git to treat JS files as binary files, which avoids processing the files in the deployment pipeline. The file hashes of the unprocessed files match the entries in the `blazor.boot.json` file, and client-side integrity checks pass. For more information, see <xref:blazor/host-and-deploy/webassembly/bundle-caching-and-integrity-check-failures>. Example: [Xref Generator `.gitattributes` file](https://github.com/dotnet/blazor-samples/blob/main/BlazorWebAssemblyXrefGenerator/.gitattributes)
 
 To handle URL rewrites based on [Single Page Apps for GitHub Pages (`rafrex/spa-github-pages` GitHub repository)](https://github.com/rafrex/spa-github-pages):
 

aspnetcore/blazor/host-and-deploy/webassembly/runtime-and-app-bundle-caching.md

@@ -405,5 +405,5 @@ The [`CarChecker`](https://github.com/SteveSandersonMS/CarChecker) sample app de
 
 ## Additional resources
 
-* [Troubleshoot integrity PowerShell script](xref:blazor/host-and-deploy/webassembly/runtime-and-app-bundle-caching#troubleshoot-integrity-powershell-script)
+* [Troubleshoot integrity PowerShell script](xref:blazor/host-and-deploy/webassembly/bundle-caching-and-integrity-check-failures#troubleshoot-integrity-powershell-script)
 * [Client-side SignalR cross-origin negotiation for authentication](xref:blazor/fundamentals/signalr#client-side-signalr-cross-origin-negotiation-for-authentication)

aspnetcore/blazor/progressive-web-app.md

@@ -684,10 +684,8 @@ items:
                     uid: blazor/host-and-deploy/webassembly/apache
                   - name: Deploy to GitHub Pages
                     uid: blazor/host-and-deploy/webassembly/github-pages
-                  - name: Runtime and app bundle caching
-                    uid: blazor/host-and-deploy/webassembly/runtime-and-app-bundle-caching
-                  - name: Integrity check failures
-                    uid: blazor/host-and-deploy/webassembly/integrity-check-failures
+                  - name: Bundle caching and integrity check failures
+                    uid: blazor/host-and-deploy/webassembly/bundle-caching-and-integrity-check-failures
                   - name: HTTP caching issues
                     uid: blazor/host-and-deploy/webassembly/http-caching-issues
                   - name: Multiple hosted WebAssembly apps

aspnetcore/toc.yml

@@ -13,7 +13,7 @@ Welcome to what's new in the ASP.NET Core docs for April 2024. This article list
 
 ### New articles
 
-- <xref:blazor/host-and-deploy/webassembly/runtime-and-app-bundle-caching>
+- <xref:blazor/host-and-deploy/webassembly/bundle-caching-and-integrity-check-failures>
 - <xref:blazor/tooling/webassembly>
 - <xref:blazor/security/qrcodes-for-authenticator-apps>
 - <xref:blazor/js-interop/javascript-location>