[release/9.0] [Blazor WASM standalone] Avoid caching index.html during development

[MackinnonBuck]

Avoid caching index.html during development

Backport of #59340

Fixes an issue where running a Blazor WebAssembly standalone app with hot reload enabled doesn't work if the app had been previously run with hot reload disabled.

Description

Background

The Microsoft.AspNetCore.Components.WebAssembly.DevServer package provides a server for running Blazor WebAssembly standalone apps in development, and it's what gets used by default in new Blazor WebAssembly standalone projects. One of its responsibilities is serving static files, and this includes the app's index.html.

Hot reload functionality depends on an additional <script /> element being dynamically injected into the response for index.html. A development-only middleware provides this behavior.

The problem

The development server was serving index.html with a Cache-Control header that allowed the browser to cache the response. This meant that if the app was initially run with hot reload disabled, the browser would cache a version of index.html without the injected script. After enabling hot reload, the server would not detect that the cached index.html was invalid, because the file on disk had not changed. As a result, the hot reload script injection middleware would be skipped, and the cached response (without the injected script) would be used. This prevented any hot reload functionality from working.

The fix

The fix is simple: change the development server to serve index.html with a Cache-Control: no-store header, which prevents the browser from caching the response. This always gives the script injection middleware a chance to inject the hot reload script.

Fixes#59276

Customer Impact

Customers relying on the dotnet CLI to run their Blazor WebAssembly standalone app are very likely to encounter this issue. The problem can be reproduced by first running the app using dotnet run, then subsequently with dotnet watch. While less common, the bug can also be reproduced in Visual Studio by explicitly disabling hot reload, running the app, then re-enabling hot reload.

Workarounds do exist:

• Make an arbitrary change to index.html so that the server recognizes that the file has changed
• Clear the browser cache between runs

However, the user may not be aware of these workarounds, and being forced to manually clear the browser cache creates a frustrating development experience.

Note

Only Blazor WebAssembly standalone apps are affected. The bug does not reproduce on other types of Blazor apps (Web, Server, Hybrid).

Regression?

• Yes
• No

This bug has existed since .NET 6, and possibly earlier than that.

Risk

• High
• Medium
• Low

The change is small and only impacts how the index.html file is served during development.

Verification

• Manual (required)
• Automated

Packaging changes reviewed?

• Yes
• No
• N/A

[MackinnonBuck]

/backport to release/8.0

[github-actions]

Started backporting to release/8.0: https://github.com/dotnet/aspnetcore/actions/runs/12188985946

[pavelsavara]

cc @maraf we have another copy of this code, right ?

[mkArtakMSFT]

Thanks @MackinnonBuck.
Why aren't there any tests for this? Is this one of the We don't have infrastructure for testing this particular area and Manual Testing has better RoI? cases?

[MackinnonBuck]

Is this one of the "We don't have infrastructure for testing this particular area and Manual Testing has better RoI" cases?

Right, we currently don't have the infrastructure to automatically test the full E2E hot reload experience, although there were some recent internal discussions around investing in this.

[halter73]

• Make an arbitrary change to index.html so that the server recognizes that the file has changed

Is this a complete workaround, or do you still need to clear the browser cache if you do this?

[MackinnonBuck]

• Make an arbitrary change to index.html so that the server recognizes that the file has changed

Is this a complete workaround, or do you still need to clear the browser cache if you do this?

This is a complete workaround. Since the file on disk changed, the server doesn't get tricked into thinking it can return a 304. This allows the script injection middleware to run and modify the response.