Maui Hot Reload Diagnostics

Name: Maui Hot Reload Diagnostics
Author: davidortinau

davidortinau/maui-skills

30 installs
163 repo stars
Updated July 6, 2026
davidortinau/maui-skills

Diagnoses and troubleshoots .NET MAUI Hot Reload issues across C# Hot Reload, XAML Hot Reload, and Blazor Hybrid.

About

Helps diagnose and troubleshoot .NET MAUI Hot Reload issues across C# Hot Reload, XAML Hot Reload and Blazor Hybrid for all UI approaches. A developer uses it when Hot Reload stops working during MAUI development.

Covers C# Hot Reload, XAML Hot Reload, and Blazor Hybrid
Spans XAML, MauiReactor, C# Markup, and Blazor Hybrid UI approaches

Maui Hot Reload Diagnostics by the numbers

30 all-time installs (skills.sh)
Ranked #359 of 596 Debugging skills by installs in the Skillselion catalog
Data as of Aug 3, 2026 (Skillselion catalog sync)

npx skills add https://github.com/davidortinau/maui-skills --skill maui-hot-reload-diagnostics

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

[![Listed on Skillselion](https://skillselion.com/badge/skills/davidortinau/maui-skills/maui-hot-reload-diagnostics.svg)](https://skillselion.com/skills/davidortinau/maui-skills/maui-hot-reload-diagnostics)

Installs	30
repo stars	★ 163
Last updated	July 6, 2026
Repository	davidortinau/maui-skills ↗

What it does

Diagnoses and troubleshoots .NET MAUI Hot Reload issues across C# Hot Reload, XAML Hot Reload, and Blazor Hybrid.

Files

SKILL.mdMarkdownGitHub ↗

.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

Hot Reload Setup & Configuration Reference

Environment Variables for Diagnostics

Enable detailed logging

# Mac/Linux - Edit and Continue logs
export Microsoft_CodeAnalysis_EditAndContinue_LogDir=/tmp/HotReloadLog

# Windows
set Microsoft_CodeAnalysis_EditAndContinue_LogDir=%temp%\HotReloadLog

# XAML Hot Reload logging
export HOTRELOAD_XAML_LOG_MESSAGES=1

# Xamarin-style debug logging (legacy, may help)
export XAMARIN_HOT_RELOAD_SHOW_DEBUG_LOGGING=1

Check if variables are set

# Mac/Linux
env | grep -i hotreload
env | grep -i EditAndContinue

# Windows PowerShell
Get-ChildItem Env: | Where-Object { $_.Name -match "hotreload|EditAndContinue" }

VS Code Settings

Enable in VS Code settings (search "Hot Reload"):

{
  "csharp.experimental.debug.hotReload": true,
  "csharp.debug.hotReloadOnSave": true,
  "csharp.debug.hotReloadVerbosity": "detailed"
}

Visual Studio Settings

1. Tools > Options > Debugging > .NET/C++ Hot Reload 2. Enable: Enable Hot Reload, Apply on file save 3. Set Logging verbosity to Detailed or Diagnostic

MetadataUpdateHandler

For custom hot reload handling (e.g., MauiReactor), implement MetadataUpdateHandler:

[assembly: System.Reflection.Metadata.MetadataUpdateHandler(typeof(HotReloadService))]

internal static class HotReloadService
{
    public static void ClearCache(Type[]? updatedTypes) { }

    public static void UpdateApplication(Type[]? updatedTypes)
    {
        MainThread.BeginInvokeOnMainThread(() =>
        {
            // Refresh your UI framework
        });
    }
}

Verify MetadataUpdateHandler is registered

grep -rn "MetadataUpdateHandler" --include="*.cs"
grep -rn "assembly:.*MetadataUpdateHandler" --include="*.cs"

MauiReactor-Specific Hot Reload Setup

MauiReactor v3+ uses .NET's feature switch pattern for hot reload (no code call needed).

Add to your .csproj file:

<ItemGroup Condition="'$(Configuration)'=='Debug'">
  <RuntimeHostConfigurationOption Include="MauiReactor.HotReload" Value="true" Trim="false" />
</ItemGroup>

<!-- For Release builds (AOT compatibility) -->
<ItemGroup Condition="'$(Configuration)'=='Release'">
  <RuntimeHostConfigurationOption Include="MauiReactor.HotReload" Value="false" Trim="true" />
</ItemGroup>

Check MauiReactor hot reload setup

grep -A2 "MauiReactor.HotReload" *.csproj
grep -rn "EnableMauiReactorHotReload" --include="*.cs" && echo "WARNING: Remove this call for v3+"

MauiReactor hot reload requirements

1. RuntimeHostConfigurationOption set in .csproj (not a code call) 2. Debug configuration 3. Debugger attached (F5) 4. Works on all platforms (iOS, Android, Mac Catalyst, Windows) 5. Works in VS Code and Visual Studio

C# Markup (CommunityToolkit.Maui.Markup) Hot Reload Setup

1. Add the NuGet package: CommunityToolkit.Maui.Markup

2. Enable in MauiProgram.cs:

var builder = MauiApp.CreateBuilder();
builder
    .UseMauiApp<App>()
    .UseMauiCommunityToolkitMarkup(); // Enables hot reload support

3. Implement the handler interface on pages/views that need refresh:

public partial class MainPage : ContentPage, ICommunityToolkitHotReloadHandler
{
    public MainPage()
    {
        Build();
    }

    void Build() => Content = new VerticalStackLayout
    {
        Children =
        {
            new Label().Text("Hello, World!"),
            new Button().Text("Click Me")
        }
    };

    void ICommunityToolkitHotReloadHandler.OnHotReload() => Build();
}

Check C# Markup hot reload setup

grep -i "CommunityToolkit.Maui.Markup" *.csproj
grep -n "UseMauiCommunityToolkitMarkup" MauiProgram.cs
grep -rn "ICommunityToolkitHotReloadHandler" --include="*.cs"

Blazor Hybrid Hot Reload

How Blazor Hybrid hot reload works

Razor components (`.razor`): Changes to markup and C# code blocks reload automatically
CSS files (`.css`): Style changes apply immediately
C# code-behind (`.razor.cs`): Uses standard C# Hot Reload rules
Shared C# code: Standard C# Hot Reload applies

Setup requirements

1. Debug configuration (not Release) 2. Debugger attached (F5, not Ctrl+F5) 3. For Visual Studio: Ensure "Hot Reload on File Save" is enabled

Check Blazor Hybrid setup

grep -rn "BlazorWebView" --include="*.xaml" --include="*.cs"
find . -name "_Imports.razor"
ls -la */wwwroot/ 2>/dev/null || ls -la wwwroot/ 2>/dev/null

Environment variable for Blazor debugging

export ASPNETCORE_ENVIRONMENT=Development

Diagnostic Commands

Collect full diagnostic bundle

# 1. Environment info
dotnet --info > dotnet-info.txt
dotnet workload list > workloads.txt

# 2. Build with binary log
dotnet build -bl:build.binlog -c Debug

# 3. Check for encoding issues
find . -name "*.cs" -path "*/src/*" | head -20 | xargs file

# 4. Check hot reload env vars
env | grep -iE "(hotreload|editandcontinue|xamarin.*debug)" || echo "No hot reload env vars set"

Enable all diagnostic logging then reproduce

export Microsoft_CodeAnalysis_EditAndContinue_LogDir=/tmp/HotReloadLog
export HOTRELOAD_XAML_LOG_MESSAGES=1
# Launch IDE from this terminal, reproduce issue, then check /tmp/HotReloadLog/

References

#!/bin/bash
# Hot Reload Diagnostics Script for .NET MAUI
# Run this to collect diagnostic information for hot reload issues

set -e

OUTPUT_DIR="${1:-hot-reload-diagnostics}"
mkdir -p "$OUTPUT_DIR"

echo "🔍 Collecting Hot Reload Diagnostics..."
echo "   Output directory: $OUTPUT_DIR"
echo ""

# 1. Environment info
echo "📋 Collecting .NET info..."
dotnet --info > "$OUTPUT_DIR/dotnet-info.txt" 2>&1 || echo "Failed to get dotnet info"

echo "📋 Collecting workload list..."
dotnet workload list > "$OUTPUT_DIR/workloads.txt" 2>&1 || echo "Failed to get workloads"

# 2. Check hot reload environment variables
echo "🔧 Checking environment variables..."
{
    echo "=== Hot Reload Environment Variables ==="
    echo ""
    echo "Microsoft_CodeAnalysis_EditAndContinue_LogDir: ${Microsoft_CodeAnalysis_EditAndContinue_LogDir:-NOT SET}"
    echo "HOTRELOAD_XAML_LOG_MESSAGES: ${HOTRELOAD_XAML_LOG_MESSAGES:-NOT SET}"
    echo "XAMARIN_HOT_RELOAD_SHOW_DEBUG_LOGGING: ${XAMARIN_HOT_RELOAD_SHOW_DEBUG_LOGGING:-NOT SET}"
    echo ""
    echo "=== All Related Env Vars ==="
    env | grep -iE "(hotreload|editandcontinue|xamarin.*debug)" || echo "No matching environment variables found"
} > "$OUTPUT_DIR/env-vars.txt"

# 3. Check file encoding (UTF-8 with BOM)
echo "📝 Checking .cs file encoding..."
{
    echo "=== File Encoding Check ==="
    echo "Files should be UTF-8 with BOM (first 3 bytes: ef bb bf)"
    echo ""
    
    if [ -d "src" ]; then
        SEARCH_DIR="src"
    else
        SEARCH_DIR="."
    fi
    
    echo "Checking files in: $SEARCH_DIR"
    echo ""
    
    # Find .cs files and check for BOM
    find "$SEARCH_DIR" -name "*.cs" -type f 2>/dev/null | head -50 | while read -r file; do
        if [ -f "$file" ]; then
            HEX=$(head -c 3 "$file" | od -An -tx1 2>/dev/null | tr -d ' \n')
            if [ "$HEX" = "efbbbf" ]; then
                echo "✅ $file (UTF-8 with BOM)"
            else
                echo "❌ $file (NO BOM - hex: $HEX)"
            fi
        fi
    done
} > "$OUTPUT_DIR/encoding-check.txt"

# 4. Check for MetadataUpdateHandler
echo "🔄 Checking MetadataUpdateHandler..."
{
    echo "=== MetadataUpdateHandler Search ==="
    echo ""
    grep -rn "MetadataUpdateHandler" --include="*.cs" . 2>/dev/null || echo "No MetadataUpdateHandler found"
    echo ""
    echo "=== Assembly Attributes ==="
    grep -rn "assembly:.*MetadataUpdateHandler" --include="*.cs" . 2>/dev/null || echo "No assembly-level MetadataUpdateHandler attribute found"
} > "$OUTPUT_DIR/metadata-handler.txt"

# 5. Check MauiReactor setup
echo "🔧 Checking MauiReactor hot reload setup..."
{
    echo "=== MauiReactor Hot Reload Setup ==="
    echo ""
    echo "--- Package References ---"
    grep -rn "MauiReactor.HotReload\|Reactor.Maui" --include="*.csproj" . 2>/dev/null || echo "No MauiReactor references found"
    echo ""
    echo "--- MauiProgram.cs Hot Reload Setup ---"
    find . -name "MauiProgram.cs" -exec grep -Hn "EnableMauiReactorHotReload\|HotReload" {} \; 2>/dev/null || echo "No hot reload setup found in MauiProgram.cs"
} > "$OUTPUT_DIR/mauireactor-setup.txt"

# 6. Check project configuration
echo "📦 Checking project configuration..."
{
    echo "=== Project Files ==="
    find . -name "*.csproj" -type f 2>/dev/null | head -10
    echo ""
    echo "=== Build Configurations ==="
    grep -rn "<Configuration>" --include="*.csproj" . 2>/dev/null | head -20 || echo "No explicit configurations found"
} > "$OUTPUT_DIR/project-config.txt"

# 7. Check VS Code settings if present
echo "⚙️  Checking VS Code settings..."
{
    echo "=== VS Code Hot Reload Settings ==="
    if [ -f ".vscode/settings.json" ]; then
        echo "Found .vscode/settings.json:"
        grep -E "(hotReload|csharp.experimental|csharp.debug)" .vscode/settings.json 2>/dev/null || echo "No hot reload settings found"
    else
        echo "No .vscode/settings.json found"
    fi
} > "$OUTPUT_DIR/vscode-settings.txt"

# Summary
echo ""
echo "✅ Diagnostics collected in: $OUTPUT_DIR/"
echo ""
echo "Files created:"
ls -la "$OUTPUT_DIR/"
echo ""
echo "📌 Next steps:"
echo "   1. Review encoding-check.txt for files without BOM"
echo "   2. Check env-vars.txt to ensure logging is enabled"
echo "   3. Verify metadata-handler.txt shows your hot reload handler"
echo "   4. If issues persist, run: dotnet build -bl:$OUTPUT_DIR/build.binlog -c Debug"
echo ""
echo "To enable full diagnostic logging, run:"
echo "   export Microsoft_CodeAnalysis_EditAndContinue_LogDir=/tmp/HotReloadLog"
echo "   export HOTRELOAD_XAML_LOG_MESSAGES=1"
echo "Then launch your IDE from this terminal."