What is .NET Hot Reload, how does it work under the hood, and when does it fall back to a restart?

1. The end-to-end pipeline

  edit + save
      |
      v
 IDE or dotnet watch notices the change
      |
      v
 Roslyn: compare the new compilation with the one the process is running
      |
      +-- rude edit? --yes--> report it --> rebuild + restart (state lost)
      |
      no
      v
 delta = metadata delta + IL delta + PDB delta
      |   sent to the process (debugger channel, or the dotnet watch agent)
      v
 runtime: MetadataUpdater.ApplyUpdate(assembly, metadataDelta, ilDelta, pdbDelta)
      |   throws if the assembly isn't modifiable or the delta doesn't match
      v
 [MetadataUpdateHandler] ClearCache(types)  --> framework and your caches
 [MetadataUpdateHandler] UpdateApplication(types) --> UI refresh (Blazor etc.)
      |
      v
 next call to a changed method runs the new IL

Nothing is reloaded or recompiled from scratch. The runtime adds a new generation of metadata on top of the loaded assembly, and the JIT compiles the new IL the next time the method is called.

2. The pieces and what each one does

3. Edit and Continue versus Hot Reload

In Visual Studio both are the same feature from the user's point of view. The distinction matters when you use dotnet watch or a process without a debugger attached.

4. What is supported and what is rude

The exact list depends on the runtime's capabilities, and it has grown with each release since .NET 6. As a guide for .NET 10 on CoreCLR:

The last row is the most common source of confusion: an edit to Program.cs applies without error, but the code that uses it has already run.

Rude edits exist because the runtime is patching a live type system. Objects on the heap were laid out for the old type, JIT-compiled callers were built against the old signatures, and reflection data was cached. An edit that would make those inconsistent can't be applied safely, so Roslyn refuses it rather than corrupting the process.

5. Running code keeps the old version

 Thread A is inside ProcessOrder() (old IL) when you save
         |
         +-- the current call finishes on the OLD code
         |
         v
 next call to ProcessOrder() --> JIT compiles NEW IL --> new behaviour

A long-running loop such as a BackgroundService ExecuteAsync method may therefore never pick up the change, because it never returns. Move the loop body into a separate method that is called on each iteration, or restart.

6. Why caches go stale

Hot Reload replaces method bodies. It doesn't re-run constructors, static initialisers, Program.cs or the DI container build. Anything computed once from the old code keeps the old result:

Frameworks register their own handlers. Your own caches need one, as in the code example.

7. dotnet watch behaviour

8. Diagnosing "Hot Reload isn't working"

1. Check the IDE's Hot Reload output pane, or the dotnet watch console, for "changes applied" or a rude edit message.
2. Confirm it's a Debug build. Release builds are not a supported target.
3. Put a breakpoint in the edited method. If it isn't hit, the code isn't being called: look for a cache or for start-up code.
4. Check whether the code runs in a loop that never returns (section 5).
5. Check the target framework and runtime are supported by your IDE version.
6. Restart. If the change works after a restart, it was a cache, start-up code or a rude edit, not a bug in your change.

9. Performance and security

• Applying a delta is usually quick, but a hot-reloaded process isn't representative of production: it's a Debug build, modifiable assemblies lose some optimisations, and each update adds metadata that stays in memory. Never profile or benchmark a session that has been hot reloaded; restart in Release first.
• In a long session with many edits, memory use creeps up. Restart occasionally.
• Never set DOTNET_MODIFIABLE_ASSEMBLIES or a dotnet watch startup hook in production or container images. A process whose code can be patched at run time is a larger attack surface and no longer runs exactly the build you shipped and scanned.
• Use dotnet watch on developer machines only, not on shared servers.

10. .NET 11 awareness

Hot Reload support keeps growing with each release, mostly through new runtime capabilities and better Razor and Blazor support. Check the .NET 11 release notes for newly supported edits rather than relying on an old list of rude edits.

11. Try it yourself

1. Create dotnet new web -n HotDemo -f net10.0 and map /price to PricingRules.Calculate(100m).
2. Run dotnet watch, change the rule, and refresh to see the new value without a restart.
3. Cache the result in a static dictionary and see that the change no longer shows.
4. Add the MetadataUpdateHandler from the code example and confirm it works again.
5. Add a new method and call it: it applies in place.
6. Change the class's base type and watch dotnet watch report a rude edit and offer to restart.
7. Change a value read in Program.cs at start-up and see that nothing changes until you press Ctrl+R.

Run with Hot Reload from the CLI:

dotnet new web -n HotDemo -f net10.0
cd HotDemo
dotnet watch

PricingRules.cs, a cache that must be cleared when code changes:

using System.Collections.Concurrent;
using System.Reflection.Metadata;

[assembly: MetadataUpdateHandler(typeof(HotDemo.PricingRulesHotReload))]

namespace HotDemo;

public static class PricingRules
{
    private static readonly ConcurrentDictionary<decimal, decimal> Cache = new();

    public static decimal Calculate(decimal basePrice) =>
        Cache.GetOrAdd(basePrice, price => Math.Round(price * 1.10m, 2)); // add 10% GST

    internal static void Clear() => Cache.Clear();
}

internal static class PricingRulesHotReload
{
    // Called by the runtime after a Hot Reload update is applied.
    public static void ClearCache(Type[]? updatedTypes) => PricingRules.Clear();
}

Program.cs:

using HotDemo;

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/price", (decimal? amount) => Results.Ok(new { total = PricingRules.Calculate(amount ?? 100m) }));

app.Run();