Skip to content
Tutorials Center
My learning

Topics

Lesson 5 of 41 ยท Getting Started

Debugging and Hot Reload

Learn how to run a Blazor app with dotnet watch, use Hot Reload, set breakpoints, read browser console errors, log with ILogger and spot the mistakes beginners make most often.

Writing a component is only half of the job. The other half is finding out why it does not do what you expect. Blazor gives you three strong tools for that: Hot Reload, which applies code edits to a running app, breakpoints in your editor, and logging to the terminal or the browser console.

This site cannot run a Blazor app, so the commands and .razor code below are read-only. The runnable C# examples are stand-ins: small console programs that demonstrate the ideas behind Hot Reload and logging, not the real tools.

Running with dotnet watch

From the project folder, start the app with the watcher:

Terminal
dotnet watch

dotnet watch builds the project, starts the web server and keeps watching your source files. When you save a file it tries to apply the change to the running process. If it cannot, it asks whether to restart the app (a "rude edit"). With Visual Studio you get the same behaviour from the Hot Reload button; with dotnet run you get none of it.

What Hot Reload can usually apply without a restart:

  • Edits to markup and @code blocks in .razor files.
  • Changes to method bodies and new methods or properties.
  • CSS changes (including scoped .razor.css files).

What usually forces a restart:

  • Changing a base class, an interface list or a constructor signature.
  • Editing Program.cs service registrations (the app has already built its container).
  • Changes to the project file or appsettings.json structure.

Because Hot Reload keeps the process alive, your component state (a counter at 7, for example) often survives an edit. That is great for tweaking styles, and surprising when you change an initial value and nothing seems to happen: the field was already initialised. Refresh the page to start fresh.

A picture of the Hot Reload loop

flowchart LR
  A["Edit and save .razor file"] --> B["dotnet watch compiles a delta"]
  B --> C{"Can the runtime apply it?"}
  C -->|"yes"| D["Running app patched<br/>state is kept"]
  C -->|"no (rude edit)"| E["Prompt: restart app"]
  D --> F["Browser re-renders component"]
  E --> F

The runtime applies small edits in place; structural edits need a restart.

Breakpoints and the debugger

In Visual Studio or VS Code (with the C# Dev Kit) press F5, click the margin next to a line in a .razor file or .cs file, and interact with the page. Execution stops on the line and you can inspect currentCount, step over, step into and see the call stack.

Where the code runs matters:

  • Interactive Server and prerendering: your C# runs on the server, so the IDE debugger attaches to the server process directly.
  • WebAssembly: your C# runs in the browser. Debugging uses the browser's remote debugging protocol (Chrome and Edge are supported); set breakpoints in the IDE or in the browser's Sources tab.

A common surprise: a component renders twice on the server when prerendering is on. The breakpoint in OnInitialized hits twice, once for the prerender and once when the interactive circuit starts. That is expected, and the lifecycle lesson explains why.

Reading errors

Blazor reports problems in three places:

  1. The build output. Razor compile errors such as an unclosed tag or a misspelt parameter name point to the .razor line.
  2. The browser's developer console (F12). JavaScript interop failures and WebAssembly load errors show up here.
  3. The error bar at the bottom of the page: "An unhandled error has occurred. Reload". In Development the details are in the terminal and the console.

For Interactive Server, a thrown exception inside an event handler ends the circuit (the connection between this browser tab and the server). The user must reload. That is why handlers should catch the errors they can recover from.

HTML
@code {
    private string? message;

    private async Task Save()
    {
        try
        {
            await Service.SaveAsync();
            message = "Saved";
        }
        catch (InvalidOperationException ex)
        {
            message = "Could not save: " + ex.Message;
        }
    }
}

Logging with ILogger

Inject ILogger<T> to write structured messages. In a component:

HTML
@inject ILogger<Counter> Logger

<button @onclick="Increment">Click</button>

@code {
    private int count;

    private void Increment()
    {
        count++;
        Logger.LogInformation("Count is now {Count}", count);
    }
}

On the server the message goes to the terminal that runs dotnet watch. In WebAssembly the logger writes to the browser console. Use placeholders like rather than string interpolation so logging systems can index the values. Levels from least to most severe are Trace, Debug, Information, Warning, Error and Critical; the default filter shows Information and above.

Stand-in: the idea of Hot Reload

Hot Reload swaps method bodies while the object and its fields stay alive. We can mimic that with a delegate we replace while the component's state is kept:

C# Stand-in: patching behaviour, keeping state

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

The lesson of the stand-in: after a patch the old state (3) is still there, so adding 10 gives 13. Only a restart resets it.

Stand-in: a tiny logger with levels and a filter

C# Stand-in: ILogger-style levels

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

Common mistakes

  • Expecting Hot Reload to reset state. It keeps it. Reload the page for a clean start.
  • Debugging the wrong process. With WebAssembly the code runs in the browser; a server breakpoint will never hit.
  • Swallowing exceptions. An empty catch hides the real error. Log it.
  • Using Console.WriteLine in WebAssembly and looking at the terminal. It goes to the browser console.
  • Forgetting that prerendering runs lifecycle methods twice. Guard expensive side effects.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which command runs a Blazor app and applies code edits without a full restart where possible?

    dotnet watch starts the app and uses Hot Reload to patch the running process when you save files.
  2. 2. You edit the initial value of a field and Hot Reload does not seem to change what is on screen. Why?

    Hot Reload patches code but keeps live objects. Refresh the page to create the component again with the new initial value.
  3. 3. In Interactive Server mode, what happens when an unhandled exception is thrown in an event handler?

    An unhandled exception terminates the circuit, so catch errors you can recover from.
  4. 4. Where does Logger.LogInformation output appear for a WebAssembly app?

    WebAssembly code runs in the browser, so its logger writes to the browser console.

Summary

  • Use dotnet watch (or the IDE Hot Reload button) for fast feedback.
  • Hot Reload patches code and keeps state; structural changes need a restart.
  • Breakpoints attach to the server process (Interactive Server) or the browser (WebAssembly).
  • Unhandled exceptions end an Interactive Server circuit: catch what you can handle.
  • Inject ILogger<T> and log with placeholders and levels.

Next: Razor Syntax Basics