Events
Power BI DataViz World Championships
Feb 14, 4 PM - Mar 31, 4 PM
With 4 chances to enter, you could win a conference package and make it to the LIVE Grand Finale in Las Vegas
Learn moreThis browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
Note
This isn't the latest version of this article. For the current release, see the .NET 9 version of this article.
Warning
This version of ASP.NET Core is no longer supported. For more information, see the .NET and .NET Core Support Policy. For the current release, see the .NET 9 version of this article.
Important
This information relates to a pre-release product that may be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
For the current release, see the .NET 9 version of this article.
When a Blazor WebAssembly app loads in the browser, the app downloads boot resources from the server:
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:
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.
Note
Documentation links to .NET reference source usually load the repository's default branch, which represents the current development for the next release of .NET. To select a tag for a specific release, use the Switch branches or tags dropdown list. For more information, see How to select a version tag of ASP.NET Core source code (dotnet/AspNetCore.Docs #26205).
When an app is built, the generated blazor.boot.json
manifest describes the SHA-256 hashes of boot resources at the time that the build output is produced. The integrity check passes as long as the SHA-256 hashes in blazor.boot.json
match the files delivered to the browser.
Common reasons why this fails include:
.gitattributes
to treat build artifacts as binary
files.blazor.boot.json
file fails to load properly or is improperly cached on the client. Common causes include either of the following:
To diagnose which of these applies in your case:
index.html
data even for other files. Make sure that responses to .wasm
requests are WebAssembly binaries and that responses to .dll
requests are .NET assembly binaries. If not, you have a server-side routing problem to diagnose.If you confirm that the server is returning plausibly correct data, there must be something else modifying the contents in between build and delivery of the file. To investigate this:
content-encoding: br
or content-encoding: gzip
), since this doesn't affect the result after decompression. However, it's not fine for the web server to modify the uncompressed data.Use the integrity.ps1
PowerShell script to validate a published and deployed Blazor app. The script is provided for PowerShell Core 7 or later as a starting point when the app has integrity issues that the Blazor framework can't identify. Customization of the script might be required for your apps, including if running on version of PowerShell later than version 7.2.0.
The script checks the files in the publish
folder and downloaded from the deployed app to detect issues in the different manifests that contain integrity hashes. These checks should detect the most common problems:
Invoke the script with the following command in a PowerShell command shell:
.\integrity.ps1 {BASE URL} {PUBLISH OUTPUT FOLDER}
In the following example, the script is executed on a locally-running app at https://localhost:5001/
:
.\integrity.ps1 https://localhost:5001/ C:\TestApps\BlazorSample\bin\Release\net6.0\publish\
Placeholders:
{BASE URL}
: The URL of the deployed app. A trailing slash (/
) is required.{PUBLISH OUTPUT FOLDER}
: The path to the app's publish
folder or location where the app is published for deployment.Note
When cloning the dotnet/AspNetCore.Docs
GitHub repository, the integrity.ps1
script might be quarantined by Bitdefender or another virus scanner present on the system. Usually, the file is trapped by a virus scanner's heuristic scanning technology, which merely looks for patterns in files that might indicate the presence of malware. To prevent the virus scanner from quarantining the file, add an exception to the virus scanner prior to cloning the repo. The following example is a typical path to the script on a Windows system. Adjust the path as needed for other systems. The {USER}
placeholder is the user's path segment.
C:\Users\{USER}\Documents\GitHub\AspNetCore.Docs\aspnetcore\blazor\host-and-deploy\webassembly\_samples\integrity.ps1
Warning: Creating virus scanner exceptions is dangerous and should only be performed when you're certain that the file is safe.
Comparing the checksum of a file to a valid checksum value doesn't guarantee file safety, but modifying a file in a way that maintains a checksum value isn't trivial for malicious users. Therefore, checksums are useful as a general security approach. Compare the checksum of the local integrity.ps1
file to one of the following values:
32c24cb667d79a701135cb72f6bae490d81703323f61b8af2c7e5e5dc0f0c2bb
9cee7d7ec86ee809a329b5406fbf21a8
Obtain the file's checksum on Windows OS with the following command. Provide the path and file name for the {PATH AND FILE NAME}
placeholder and indicate the type of checksum to produce for the {SHA512|MD5}
placeholder, either SHA256
or MD5
:
CertUtil -hashfile {PATH AND FILE NAME} {SHA256|MD5}
If you have any cause for concern that checksum validation isn't secure enough in your environment, consult your organization's security leadership for guidance.
For more information, see Overview of threat protection by Microsoft Defender Antivirus.
In most cases, don't disable integrity checking. Disabling integrity checking doesn't solve the underlying problem that has caused the unexpected responses and results in losing the benefits listed earlier.
There may be cases where the web server can't be relied upon to return consistent responses, and you have no choice but to temporarily disable integrity checks until the underlying problem is resolved.
To disable integrity checks, add the following to a property group in the Blazor WebAssembly app's project file (.csproj
):
<BlazorCacheBootResources>false</BlazorCacheBootResources>
BlazorCacheBootResources
also disables Blazor's default behavior of caching the .dll
, .wasm
, and other files based on their SHA-256 hashes because the property indicates that the SHA-256 hashes can't be relied upon for correctness. Even with this setting, the browser's normal HTTP cache may still cache those files, but whether or not this happens depends on your web server configuration and the cache-control
headers that it serves.
Note
The BlazorCacheBootResources
property doesn't disable integrity checks for Progressive Web Applications (PWAs). For guidance pertaining to PWAs, see the Disable integrity checking for PWAs section.
We can't provide an exhaustive list of scenarios where disabling integrity checking is required. Servers can answer a request in arbitrary ways outside of the scope of the Blazor framework. The framework provides the BlazorCacheBootResources
setting to make the app runnable at the cost of losing a guarantee of integrity that the app can provide. Again, we don't recommend disabling integrity checking, especially for production deployments. Developers should seek to solve the underlying integrity problem that's causing integrity checking to fail.
A few general cases that can cause integrity issues are:
Blazor's Progressive Web Application (PWA) template contains a suggested service-worker.published.js
file that's responsible for fetching and storing application files for offline use. This is a separate process from the normal app startup mechanism and has its own separate integrity checking logic.
Inside the service-worker.published.js
file, following line is present:
.map(asset => new Request(asset.url, { integrity: asset.hash }));
To disable integrity checking, remove the integrity
parameter by changing the line to the following:
.map(asset => new Request(asset.url));
Again, disabling integrity checking means that you lose the safety guarantees offered by integrity checking. For example, there is a risk that if the user's browser is caching the app at the exact moment that you deploy a new version, it could cache some files from the old deployment and some from the new deployment. If that happens, the app becomes stuck in a broken state until you deploy a further update.
ASP.NET Core feedback
ASP.NET Core is an open source project. Select a link to provide feedback:
Events
Power BI DataViz World Championships
Feb 14, 4 PM - Mar 31, 4 PM
With 4 chances to enter, you could win a conference package and make it to the LIVE Grand Finale in Las Vegas
Learn moreTraining
Learning path
Use advance techniques in canvas apps to perform custom updates and optimization - Training
Use advance techniques in canvas apps to perform custom updates and optimization
Documentation
Avoid HTTP caching issues when upgrading ASP.NET Core Blazor apps
Learn how to avoid HTTP caching issues when upgrading Blazor apps.
Host and deploy ASP.NET Core Blazor WebAssembly
Learn how to host and deploy Blazor WebAssembly using ASP.NET Core, Content Delivery Networks (CDN), file servers, and GitHub Pages.
Deployment layout for ASP.NET Core hosted Blazor WebAssembly apps
Learn how to enable hosted Blazor WebAssembly deployments in environments that block the download and execution of dynamic-link library (DLL) files.