diff --git a/.openpublishing.redirection.json b/.openpublishing.redirection.json index 374242ff1603..bb2d0991f928 100644 --- a/.openpublishing.redirection.json +++ b/.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 } ] } diff --git a/aspnetcore/blazor/fundamentals/startup.md b/aspnetcore/blazor/fundamentals/startup.md index 09ea29ba9b94..3348e9b62a2d 100644 --- a/aspnetcore/blazor/fundamentals/startup.md +++ b/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 . -For more information, see . +For more information, see . ## Control headers in C# code diff --git a/aspnetcore/blazor/host-and-deploy/webassembly/Integrity-check-failures.md b/aspnetcore/blazor/host-and-deploy/webassembly/bundle-caching-and-integrity-check-failures.md similarity index 91% rename from aspnetcore/blazor/host-and-deploy/webassembly/Integrity-check-failures.md rename to aspnetcore/blazor/host-and-deploy/webassembly/bundle-caching-and-integrity-check-failures.md index 3a1a7f89a816..7be4b53dfe8a 100644 --- a/aspnetcore/blazor/host-and-deploy/webassembly/Integrity-check-failures.md +++ b/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. diff --git a/aspnetcore/blazor/host-and-deploy/webassembly/github-pages.md b/aspnetcore/blazor/host-and-deploy/webassembly/github-pages.md index 529645d63aba..1dc660d888c7 100644 --- a/aspnetcore/blazor/host-and-deploy/webassembly/github-pages.md +++ b/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 . 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 . 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): diff --git a/aspnetcore/blazor/host-and-deploy/webassembly/runtime-and-app-bundle-caching.md b/aspnetcore/blazor/host-and-deploy/webassembly/runtime-and-app-bundle-caching.md deleted file mode 100644 index 0fda2cbd587c..000000000000 --- a/aspnetcore/blazor/host-and-deploy/webassembly/runtime-and-app-bundle-caching.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: ASP.NET Core Blazor WebAssembly .NET runtime and app bundle caching -author: guardrex -description: Learn how Blazor WebAssembly caches the WebAssembly .NET runtime and app bundle, how to disable caching, and how to diagnose integrity failures. -monikerRange: '>= aspnetcore-3.1' -ms.author: riande -ms.custom: mvc -ms.date: 11/12/2024 -uid: blazor/host-and-deploy/webassembly/runtime-and-app-bundle-caching ---- -# ASP.NET Core Blazor WebAssembly .NET runtime and app bundle caching - -[!INCLUDE[](~/includes/not-latest-version.md)] - -This article explains how Blazor WebAssembly caches the WebAssembly .NET runtime and app bundle, how to disable caching, and how to diagnose 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. 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. - -Blazor's algorithm for managing file integrity: - -* Ensures that the app doesn't risk loading an inconsistent set of files, for example if a new deployment is applied to your web server while the user is in the process of downloading the application files. Inconsistent files can result in a malfunctioning app. -* Ensures the user's browser never caches inconsistent or invalid responses, which can prevent the app from starting even if the user manually refreshes the page. -* Makes it safe to cache the responses and not check for server-side changes until the expected SHA-256 hashes themselves change, so subsequent page loads involve fewer requests and complete faster. - -If the web server returns responses that don't match the expected SHA-256 hashes, an error similar to the following example appears in the browser's developer console: - -> Failed to find a valid digest in the 'integrity' attribute for resource 'https://myapp.example.com/\_framework/MyBlazorApp.dll' with computed SHA-256 integrity 'IIa70iwvmEg5WiDV17OpQ5eCztNYqL186J56852RpJY='. The resource has been blocked. - -In most cases, the warning doesn't indicate a problem with integrity checking. Instead, the warning usually means that some other problem exists. - -[!INCLUDE[](~/includes/aspnetcore-repo-ref-source-links.md)] - -## Diagnosing integrity problems - -For more information, see . The article includes guidance on disabling resource caching and integrity checks for non-PWA and PWA apps. - -## Additional resources - -* [Boot resource loading](xref:blazor/fundamentals/startup#load-client-side-boot-resources) -* diff --git a/aspnetcore/blazor/progressive-web-app.md b/aspnetcore/blazor/progressive-web-app.md index adc93c025b43..b021416a53ef 100644 --- a/aspnetcore/blazor/progressive-web-app.md +++ b/aspnetcore/blazor/progressive-web-app.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) diff --git a/aspnetcore/toc.yml b/aspnetcore/toc.yml index 0a319a892a1d..df7e26b07dd9 100644 --- a/aspnetcore/toc.yml +++ b/aspnetcore/toc.yml @@ -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 diff --git a/aspnetcore/whats-new/dotnet-AspNetCore.Docs-mod4.md b/aspnetcore/whats-new/dotnet-AspNetCore.Docs-mod4.md index 437235ed2ba8..09dd8756e895 100644 --- a/aspnetcore/whats-new/dotnet-AspNetCore.Docs-mod4.md +++ b/aspnetcore/whats-new/dotnet-AspNetCore.Docs-mod4.md @@ -13,7 +13,7 @@ Welcome to what's new in the ASP.NET Core docs for April 2024. This article list ### New articles -- +- - - -