Update 'dotnet watch' doc to detail new .NET 7 behavior

[DamianEdwards]

@MackinnonBuck

The browser refresh middleware used by dotnet watch and Visual Studio to auto-refresh the browser when code changes are detected was updated in .NET 7 to make it more resilient to failures under certain app configurations, including when response compression is enabled.

In these cases it will log a warning to the application output like the following:

warn: Microsoft.AspNetCore.Watch.BrowserRefresh.BrowserRefreshMiddleware[4]
      Unable to configure browser refresh script injection on the response. This may have been caused by the response's Content-Encoding: 'br'. Consider disabling response compression.

We should update this doc (and perhaps the VS Hot Reload docs too) with the details of this change, including that folks can manually add the browser refresh JavaScript reference to their app's pages to get browser refresh working, e.g.:

@if (Environment.GetEnvironmentVariable("__ASPNETCORE_BROWSER_TOOLS") is not null)
{
<script src="/_framework/aspnetcore-browser-refresh.js"></script>
}

---

Document Details

⚠ Do not edit this section. It is required for learn.microsoft.com ➟ GitHub issue linking.

• ID: 16f49f1b-261c-8cd0-a024-32c2535d0a0f
• Version Independent ID: 218d2a4d-2ff3-8e4d-1f06-bbb3710878fe
• Content: dotnet watch command - .NET CLI
• Content Source: docs/core/tools/dotnet-watch.md
• Product: dotnet-fundamentals
• Technology: dotnet-cli
• GitHub Login: @tdykstra
• Microsoft Alias: tdykstra

---

Associated WorkItem - 34608

[tdykstra]

cc @Mikejo5000

[Mikejo5000]

@tdykstra Thanks. I'll do a pass on the Hot Reload doc in the next Sprint, and likely call this out.

[shapeh]

Got this error in .NET 7 ASP.NET MVC project. Spent a few hours and finally found this issue, so thanks @DamianEdwards for this.

warn: Microsoft.AspNetCore.Watch.BrowserRefresh.BrowserRefreshMiddleware[4]
Unable to configure browser refresh script injection on the response. This may have been caused by the response's Content-Encoding: 'br'. Consider disabling response compression.

The information on both these links are outdated:

• https://learn.microsoft.com/en-us/aspnet/core/client-side/using-browserlink?view=aspnetcore-7.0#browser-link-setup
  This link says to do the following:
  app.UseBrowserLink();

• https://learn.microsoft.com/en-us/aspnet/core/mvc/views/view-compilation?view=aspnetcore-7.0&tabs=visual-studio#enable-runtime-compilation-conditionally
  This link says do the following:

var builder = WebApplication.CreateBuilder(args);
var mvcBuilder = builder.Services.AddRazorPages();
if (builder.Environment.IsDevelopment())
{
    mvcBuilder.AddRazorRuntimeCompilation();
}

Neither of these links solve the problem.
For me, what works is to remove the following from Program.cs / Startup.cs:
app.UseResponseCompression();

Or even better to put it in Program.cs / Startup.cs conditionally like so:

if (!app.Environment.IsDevelopment()) {
    app.UseResponseCompression();
}

[changhuixu]

Should we still disable UseResponseCompression? Would .NET fix it internally? Thank you.

[tdykstra]

@changhuixu Yes, you still need to disable response compression, or manually add the browser refresh JavaScript reference to the app's pages, as explained in the dotnet watch article.

[lonix1]

I'm not using response compression, and see a similar warning:

warn: Microsoft.AspNetCore.Watch.BrowserRefresh.BrowserRefreshMiddleware[3]
Unable to configure browser refresh script injection on the response. Consider manually adding '<script src="/_framework/aspnetcore-browser-refresh.js"></script>' to the body of the page.

This is the only issue I could find on this matter. Are they related? And if so, do I use the same approach as above?

[tdykstra]

This error message is outside the scope of this article, but the message itself recommends the same resolution, so that would be worth a try.