Diagnosing Hot Reload
This guide helps you:
- Self-diagnose Hot Reload failures (C#/.NET Hot Reload and XAML Hot Reload).
- Capture high-signal diagnostics you can zip up and share with the team for analysis.
Terminology (quick):
- .NET Hot Reload (C# Hot Reload): Updates managed code while the app runs (powered by the debugger + compiler).
- XAML Hot Reload: Updates XAML UI while the app runs.
- In Visual Studio docs you’ll also see Edit and Continue (older name / related mechanism).
- Editing a
.xamlfile does not update the running UI.
- Editing a
.csfile does not take effect (even after re-triggering the code path), or Visual Studio reports the edit as unsupported.
It’s common for one to work while the other does not—diagnose them separately.
- check for updates and when possible use the latest previews, pre-release, and Insiders versions. This is where fixes first appear.
- Use Debug configuration (not Release, not a custom configuration).
- Start the app with F5 / Start Debugging for the most reliable Hot Reload experience.
Why this matters: Hot Reload is designed for debug builds and can be unavailable in Release/custom configurations.
- Hot Reload typically applies on file save.
- For C# changes, you often must re-execute the code (tap the button again, re-navigate, re-run the timer tick, etc.) to see the updated behavior.
Before changing anything else, look for the reason Hot Reload didn’t apply:
-
Visual Studio:
View > Outputthen select Hot Reload from the dropdown. -
VS Code:
View > Outputthen select C# Hot Reload (or C#) from the dropdown.
In VS Code you can also control the level of detail you see in the Output panel by tapping the settings icon in the Output panel header.
Visual Studio allows Hot Reload to be disabled at the IDE level.
- Open Tools > Options
- Search for Hot Reload
- Verify settings under Debugging > .NET/C++ Hot Reload:
- Enable Hot Reload
- (Optional) Enable when not debugging (Ctrl+F5 scenario)
- (Optional) Apply on file save
- Logging verbosity: set to Detailed or Diagnostic when troubleshooting
If you suspect auto-apply isn’t happening:
- Use the Hot Reload toolbar button, or press Alt+F10 (Apply Code Changes) while debugging.
- Unsupported edit (“rude edit”): Hot Reload will tell you the edit can’t be applied without restart.
- Build errors: if the new code doesn’t compile, Hot Reload can’t apply it.
- Mixed-mode/native debugging: some mixed native/managed debugging scenarios disable Hot Reload.
For MAUI, enable XAML Hot Reload in:
- Debug > Options > XAML Hot Reload
- Make sure the checkbox is enabled for the platform you’re debugging (Windows / Android / iOS, etc.)
For .NET MAUI XAML Hot Reload:
- Your debug configuration must be named
Debug. - On iOS, ensure the Linker is set to Don't Link.
-
XamlCompilationOptions.Skipis not supported. - Don’t add/remove NuGet packages or new source files while debugging—stop debugging, make structural changes, and restart.
If XAML updates still don’t apply: try a “full reload” from the Hot Reload UI (when available), or restart the debug session.
VS Code support depends on the MAUI and C# tooling you have installed and enabled.
- Install the .NET MAUI extension for VS Code.
- Ensure you have the current C# tooling (C# Dev Kit / C# extension, depending on your setup).
C# Hot Reload can be experimental in VS Code and may be disabled by default.
In VS Code Settings, search for “Hot Reload” and enable:
- C# > Experimental > Debug: Hot Reload
- C# Debug: Hot Reload On Save (recommended)
Also set:
-
C# Debug: Hot Reload Verbosity =
detailed(ordiagnostic) while troubleshooting.
- Open View > Output
- Select C# Hot Reload (or C#) in the output dropdown
- Reproduce the issue and copy the log output
This is often not a Hot Reload failure. Common causes:
- You didn’t re-trigger the code path (C#): the old code already ran; invoke it again.
- UI state is masking changes: e.g., cached binding values, navigation stack state, template caching.
- You’re editing the wrong target in a multi-target MAUI project (e.g., you’re debugging Android but changed a Windows-only file).
Quick test:
- Make a very obvious change (e.g., return a different constant string, change a label text) and re-run the relevant action.
When reporting Hot Reload issues, please zip a folder containing as many of these as possible:
-
Visual Studio version:
Help > About Microsoft Visual Studio(copy/paste) -
.NET SDK info:
dotnet --info
-
Installed workloads:
dotnet workload list
-
Visual Studio:
- Set
Tools > Options > Debugging > .NET/C++ Hot Reload > Logging verbosityto Diagnostic -
View > Output→ select Hot Reload - Reproduce the issue
- Copy the output into
hot-reload-output.txt
- Set
-
VS Code:
- Set C# Debug: Hot Reload Verbosity to
detailed/diagnostic -
View > Output→ select C# Hot Reload (or C#) - Reproduce the issue
- Copy the output into
vscode-hot-reload-output.txt
- Set C# Debug: Hot Reload Verbosity to
A binlog captures exactly what MSBuild did and is extremely useful.
From a developer command prompt (or terminal):
dotnet build -bl:build.binlog -c DebugFor a specific target framework (example):
dotnet build -bl:build.binlog -c Debug -f net8.0-androidIf you’re comfortable collecting internal diagnostics, you can set an environment variable to emit more detailed Edit-and-Continue logs.
Set the following environment variable before launching Visual Studio 2022/2026 or Visual Studio Code.
Windows:
set Microsoft_CodeAnalysis_EditAndContinue_LogDir=%temp%\HotReloadLog
Mac:
export Microsoft_CodeAnalysis_EditAndContinue_LogDir=/tmp/HotReloadLog
Then reproduce the problem and include the generated log folder in your zip.
Note: These logs may contain source code snippets/paths. Review before sharing externally.
Include a README.md with:
- Exact steps (what you changed, where, expected vs actual)
- Platform target (Android emulator, iOS simulator/device, Windows)
- Whether it’s XAML or C# Hot Reload failing (or both)
- If possible: a minimal repro project or a GitHub repo/branch
hot-reload-diagnostics/
README.md
vs-about.txt
dotnet--info.txt
dotnet-workload-list.txt
hot-reload-output.txt
vscode-hot-reload-output.txt
build.binlog
enc-logs/ # if collected
Some edits require a restart (e.g., many changes outside method bodies, signature changes, etc.).
- See official “Supported code changes” documentation.
Hot Reload is designed for debug builds; Release/custom configurations often disable it.
Some Hot Reload features (especially XAML Hot Reload) expect F5/Start Debugging.
- XAML Hot Reload requires iOS Linker Don't Link and a Debug config named
Debug. - Restart debugging after structural changes (new packages/files).
Make sure your physical Android or iOS device is on the same network as your development machine.