maui-hot-reload-diagnostics

name

maui-hot-reload-diagnostics

description

Diagnose and troubleshoot .NET MAUI Hot Reload issues (C# Hot Reload, XAML Hot Reload, Blazor Hybrid). Covers all UI approaches (XAML, MauiReactor, C# Markup, Blazor Hybrid), Visual Studio, VS Code, environment variables, encoding requirements, and MetadataUpdateHandler. USE FOR: "hot reload not working", "XAML hot reload", "C# hot reload", "UI not updating", "hot reload troubleshooting", "MetadataUpdateHandler", "hot reload Blazor Hybrid", "hot reload VS Code", "DOTNET_WATCH". DO NOT USE FOR: general build errors (not hot reload related), app lifecycle events (use maui-app-lifecycle), or performance profiling (use maui-performance).

.NET MAUI Hot Reload Diagnostics

Systematically diagnose Hot Reload failures for .NET MAUI apps.

Quick diagnosis checklist

1. Identify what's failing: XAML Hot Reload (.xaml changes) vs C# Hot Reload (.cs changes)
2. Check run configuration: Must be Debug config, started with F5/debugger attached
3. Save file and re-execute code path: C# changes require re-triggering the code
4. Check Hot Reload output: View > Output > "Hot Reload" (VS) or "C# Hot Reload" (VS Code)

⚠️ File encoding requirement

CRITICAL: All .cs files must be UTF-8 with BOM encoding.

# Check if file has BOM (should show "UTF-8 Unicode (with BOM)")
file -I *.cs

# Find files without BOM
find . -name "*.cs" -exec sh -c 'head -c 3 "$1" | od -An -tx1 | grep -q "ef bb bf" || echo "$1"' _ {} \;

# Fix: convert to UTF-8 with BOM
sed -i '1s/^\(\xef\xbb\xbf\)\?/\xef\xbb\xbf/' file.cs
# Or in VS Code: Open file > Save with Encoding > UTF-8 with BOM

Common issues and fixes

"Nothing happens when I save"

1. Verify Debug configuration (not Release)
2. Check Hot Reload output for errors
3. Ensure file is saved (not just modified)
4. Re-execute the code path (navigate again, tap button again)

"Unsupported edit" / "Rude edit"

Some changes always require app restart:

• Adding/removing methods, fields, properties
• Changing method signatures
• Modifying static constructors
• Changes to generics

XAML changes don't apply (iOS)

• ⚠️ Set Linker to Don't Link in iOS build settings
• Config must be named exactly Debug
• Don't use XamlCompilationOptions.Skip

Changes apply but UI doesn't update

• For C#: Must re-trigger the code (re-navigate, re-tap)
• Check for cached binding values or state
• Verify you're editing the correct target framework file

Framework-specific pitfalls

MauiReactor v3+

<!-- ✅ Correct — feature switch in .csproj -->
<ItemGroup Condition="'$(Configuration)'=='Debug'">
  <RuntimeHostConfigurationOption Include="MauiReactor.HotReload" Value="true" Trim="false" />
</ItemGroup>

// ❌ Wrong — v2 API, remove for v3+
.EnableMauiReactorHotReload()

⚠️ If migrating from MauiReactor v2, remove the EnableMauiReactorHotReload() call from MauiProgram.cs.

C# Markup (CommunityToolkit.Maui.Markup)

Key points — missing any of these breaks hot reload:

• ⚠️ Extract UI building into a separate Build() method
• ⚠️ Implement ICommunityToolkitHotReloadHandler on any page/view needing refresh
• The OnHotReload() method is called automatically after C# hot reload
• Must call .UseMauiCommunityToolkitMarkup() in MauiProgram.cs

Blazor Hybrid limitations

These changes always require restart:

• Adding new components
• Modifying @inject services
• Static asset changes (images, fonts)
• Changes to Program.cs or MauiProgram.cs

These usually work without restart:

• Razor markup and C# code block changes
• CSS changes (may need hard refresh if cached)
• Changing component parameters

⚠️ CSS isolation: If .razor.css changes don't apply, verify the isolated CSS file is properly linked.

Decision framework — which hot reload type?

UI approach	What reloads	Watch out for
XAML	.xaml files (instant)	Linker must be off on iOS; config must be "Debug"
C# code-behind	Method bodies only	Must re-trigger code path; rude edits require restart
MauiReactor v3+	Component re-render	Need RuntimeHostConfigurationOption, not code call
C# Markup	Build() method body	Must implement ICommunityToolkitHotReloadHandler
Blazor Hybrid	.razor + .css	New components/services need restart

Debugging tips

• ⚠️ Always check the Hot Reload output window first — it tells you exactly why a change was rejected.
• Enable detailed logging with env vars before launching IDE (see references/hot-reload-setup.md).
• Binary logs (dotnet build -bl:build.binlog) help diagnose build-related hot reload failures.
• When reporting bugs, include: dotnet --info, workload list, binary log, and Hot Reload output.

Quick checklist

• Debug configuration selected (not Release)
• Debugger attached (F5, not Ctrl+F5)
• All .cs files are UTF-8 with BOM
• Hot Reload output window checked for errors
• Code path re-triggered after C# changes
• MauiReactor: RuntimeHostConfigurationOption in .csproj (not code call)
• C# Markup: ICommunityToolkitHotReloadHandler implemented
• Blazor Hybrid: not changing services/startup code