| 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 |
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 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.
For more information, see xref:blazor/host-and-deploy/webassembly/integrity-check-failures. The article includes guidance on disabling resource caching and integrity checks for non-PWA and PWA apps.
- Boot resource loading
- xref:blazor/host-and-deploy/webassembly/integrity-check-failures