Control asset caching
If your project defines the ServiceWorkerAssetsManifest MSBuild property, Blazor’s build tooling generates a service worker assets manifest with the specified name. The default PWA template produces a project file containing the following property:XMLKopiëren
<ServiceWorkerAssetsManifest>service-worker-assets.js</ServiceWorkerAssetsManifest>The file is placed in the wwwroot output directory, so the browser can retrieve this file by requesting /service-worker-assets.js. To see the contents of this file, open /bin/Debug/{TARGET FRAMEWORK}/wwwroot/service-worker-assets.js in a text editor. However, don’t edit the file, as it’s regenerated on each build.
By default, this manifest lists:
- Any Blazor-managed resources, such as .NET assemblies and the .NET WebAssembly runtime files required to function offline.
- All resources for publishing to the app’s
wwwrootdirectory, such as images, stylesheets, and JavaScript files, including static web assets supplied by external projects and NuGet packages.
You can control which of these resources are fetched and cached by the service worker by editing the logic in onInstall in service-worker.published.js. By default, the service worker fetches and caches files matching typical web filename extensions such as .html, .css, .js, and .wasm, plus file types specific to Blazor WebAssembly (.dll, .pdb).
Users may run any historical version of the app
Web developers habitually expect that users only run the latest deployed version of their web app, since that’s normal within the traditional web distribution model. However, an offline-first PWA is more akin to a native mobile app, where users aren’t necessarily running the latest version.
As explained in the Background updates section, after you deploy an update to your app, each existing user continues to use a previous version for at least one further visit because the update occurs in the background and isn’t activated until the user thereafter navigates away. Plus, the previous version being used isn’t necessarily the previous one you deployed. The previous version can be any historical version, depending on when the user last completed an update.
This can be an issue if the frontend and backend parts of your app require agreement about the schema for API requests. You must not deploy backward-incompatible API schema changes until you can be sure that all users have upgraded. Alternatively, block users from using incompatible older versions of the app. This scenario requirement is the same as for native mobile apps. If you deploy a breaking change in server APIs, the client app is broken for users who haven’t yet updated.
If possible, don’t deploy breaking changes to your backend APIs. If you must do so, consider using standard Service Worker APIs such as ServiceWorkerRegistration to determine whether the app is up-to-date, and if not, to prevent usage.
All service worker asset manifest contents are cached by default
As described in the Control asset caching section, the file service-worker-assets.js is generated during build and lists all assets the service worker should fetch and cache.
Since this list by default includes everything emitted to wwwroot, including content supplied by external packages and projects, you must be careful not to put too much content there. If the wwwroot directory contains millions of images, the service worker tries to fetch and cache them all, consuming excessive bandwidth and most likely not completing successfully.
Implement arbitrary logic to control which subset of the manifest’s contents should be fetched and cached by editing the onInstall function in service-worker.published.js.
Comments