dotnet watch and Hot Reload

Analogy categoryAnalogies

dotnet watch run launches your application and keeps a file-system watcher active on your project's source files for as long as the process runs. The moment you save a change to a .cs, .razor, or .cshtml file, dotnet watch detects it and reacts, either applying the change live via Hot Reload or triggering a full rebuild-and-restart cycle, without you needing to manually stop and rerun dotnet run after every edit.

🏏

Cricket analogy: A team's video analyst reviews footage between overs and immediately signals tactical adjustments to the captain without waiting for the innings to end, similar to dotnet watch detecting a saved file change and immediately triggering a rebuild without the developer manually restarting the app.

Hot Reload: Applying Edits Without Restarting

Hot Reload, integrated into dotnet watch since .NET 6, applies many code edits to an already-running process using the runtime's Edit-and-Continue (EnC) machinery: the changed method bodies are compiled into metadata deltas and applied directly to the loaded assembly in memory. Because the process itself isn't restarted, in-memory application state, like the current items in a shopping cart, the currently rendered Blazor page, or data loaded from a database, is preserved across the edit, dramatically speeding up the edit-test loop compared to a full restart.

🏏

Cricket analogy: A bowler adjusting their grip mid-over after a chat with the bowling coach doesn't have to walk back to the top of their mark and restart the entire spell, similar to Hot Reload applying a code edit to the running process without restarting the app and losing its current state.

When Hot Reload Falls Back to a Full Restart

Not every kind of edit can be applied via Hot Reload. Adding a new field to an existing type, changing a method's signature, or modifying certain attributes are examples of 'rude edits' that the runtime's EnC support can't apply to a running process, so dotnet watch automatically falls back to a full rebuild and restart for that change instead. Developers can also explicitly disable Hot Reload entirely and force dotnet watch to always fully restart on any change with the dotnet watch --no-hot-reload flag, useful when debugging Hot Reload-specific issues.

🏏

Cricket analogy: Some tactical changes, like swapping out an injured player for a substitute, require a formal stoppage and paperwork rather than a quiet mid-over adjustment, similar to Hot Reload falling back to a full app restart when an edit, like adding a new type, can't be applied to the running process.

bash

# Run with dotnet watch, letting Hot Reload apply eligible edits live
dotnet watch run

# Force a full restart on every change instead of Hot Reload
dotnet watch run --no-hot-reload

# csproj: opt a project's watch behavior into ASP.NET Core-aware profile
# <PropertyGroup>
#   <HotReloadProfile>ASP.NET Core</HotReloadProfile>
# </PropertyGroup>

Hot Reload in ASP.NET Core and Blazor

For ASP.NET Core and Blazor apps, dotnet watch goes a step further by injecting a small piece of JavaScript into the served HTML that opens a WebSocket connection back to the running app. When a Razor component or page changes and is Hot Reloaded (or the app is restarted), the dev server pushes a message over that WebSocket that tells the open browser tab to refresh automatically, so you see UI changes reflected in the browser the moment you save, without manually hitting F5.

🏏

Cricket analogy: A stadium's giant screen instantly updates the scoreboard the moment a run is scored, without the crowd needing to check a printed scorecard, similar to dotnet watch's browser refresh middleware pushing a websocket message that reloads the page the instant a Razor component changes.

Both Visual Studio and JetBrains Rider have their own Hot Reload integrations (the 'Hot Reload' toolbar button) that work independently of the CLI's dotnet watch, applying the same EnC-based metadata deltas without you needing a terminal running dotnet watch at all.

Static field values and other process-wide state are lost whenever dotnet watch has to fall back to a full restart. If you're relying on in-memory state that survived several Hot Reload cycles, a single 'rude edit' can silently reset it, which is easy to mistake for a bug in your own code.

dotnet watch monitors source files and automatically rebuilds or Hot Reloads the app when you save a change.
Hot Reload applies metadata deltas to a running process via Edit-and-Continue, preserving in-memory state.
Rude edits, like changing a method signature or adding a new field, can't be Hot Reloaded and trigger a full restart.
dotnet watch --no-hot-reload forces a full restart on every change for troubleshooting purposes.
ASP.NET Core and Blazor apps get automatic browser refresh via an injected WebSocket-based script.
Visual Studio and Rider offer their own Hot Reload UI independent of the dotnet watch CLI command.
A full restart discards static field state, which can look like unexpected behavior after a rude edit.