maui-hot-reload-diagnostics
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 ...
Full skill instructions
Systematically diagnose Hot Reload failures for .NET MAUI apps.
.xaml changes) vs C# Hot Reload (.cs changes)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
Some changes always require app restart:
XamlCompilationOptions.Skip<!-- ✅ 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.
Key points — missing any of these breaks hot reload:
Build() methodICommunityToolkitHotReloadHandler on any page/view needing refreshOnHotReload() method is called automatically after C# hot reload.UseMauiCommunityToolkitMarkup() in MauiProgram.csThese changes always require restart:
@inject servicesProgram.cs or MauiProgram.csThese usually work without restart:
⚠️ CSS isolation: If .razor.css changes don't apply, verify the isolated CSS file is properly linked.
| 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 |
references/hot-reload-setup.md).dotnet build -bl:build.binlog) help diagnose build-related hot reload failures.dotnet --info, workload list, binary log, and Hot Reload output..cs files are UTF-8 with BOMRuntimeHostConfigurationOption in .csproj (not code call)ICommunityToolkitHotReloadHandler implemented
Guide for .NET MAUI apps consuming .NET Aspire-hosted backend services. Covers AppHost configuration, service discovery for mobile clients, HttpClient DI setup, Entra ID authentication with MSAL.NET for calling protected APIs, development workflow (Aspire dashboard + MAUI debugging), Blazor Hybri...
Guidance for adding map controls, pins, polygons, polylines, geocoding, Google Maps API key configuration, and platform setup in .NET MAUI apps using Microsoft.Maui.Controls.Maps. USE FOR: "add map", "map control", "map pins", "polygons on map", "polylines", "geocoding", "Google Maps API key", "M...
Guidance for embedding web content in .NET MAUI apps using HybridWebView, including JavaScript–C# interop, bidirectional communication, raw messaging, and trimming/NativeAOT considerations. USE FOR: "HybridWebView", "JavaScript interop", "embed web content", "JS to C# interop", "C# to JavaScript"...
.NET MAUI safe area and edge-to-edge layout guidance for .NET 10+. Covers SafeAreaEdges property, SafeAreaRegions enum, per-edge control, keyboard avoidance, Blazor Hybrid CSS safe areas, migration from legacy APIs, and platform-specific behavior for Android, iOS, and Mac Catalyst. USE FOR: "safe...
.NET MAUI app lifecycle guidance covering the four app states (not running, running, deactivated, stopped), cross-platform Window lifecycle events, backgrounding and resume behaviour, platform-specific lifecycle mapping for Android and iOS/Mac Catalyst, and state-preservation patterns. USE FOR: "...
Guidance for implementing CollectionView in .NET MAUI apps — data display, layouts (list & grid), selection, grouping, scrolling, empty views, templates, incremental loading, swipe actions, and pull-to-refresh. USE FOR: "CollectionView", "list view", "grid layout", "data template", "item template...
Add SQLite local database storage to .NET MAUI apps using sqlite-net-pcl. Covers data models with ORM attributes, async database service with lazy init, DI registration, WAL mode, and file management. Works with any UI pattern (XAML/MVVM, C# Markup, MauiReactor). USE FOR: "SQLite database", "loca...
Guidance for dependency injection in .NET MAUI apps — service registration, lifetime selection (Singleton/Transient/Scoped), constructor injection, automatic resolution via Shell navigation, explicit resolution patterns, platform-specific registrations, and testability best practices. USE FOR: "d...
Guide for creating custom .NET MAUI handlers, customizing existing handlers with property mappers, and implementing platform-specific native views. Covers PrependToMapping/ModifyMapping/AppendToMapping, PropertyMapper, CommandMapper, partial handler classes, and handler registration. USE FOR: "cu...
Performance optimization guidance for .NET MAUI apps covering profiling, compiled bindings, layout efficiency, image optimization, resource dictionaries, startup time, trimming, and NativeAOT configuration. USE FOR: "performance optimization", "slow startup", "app performance", "compiled bindings...
Guide for theming .NET MAUI apps—light/dark mode support, AppThemeBinding, dynamic resources, ResourceDictionary theme switching, and system theme detection. USE FOR: "dark mode", "light mode", "theming", "AppThemeBinding", "theme switching", "ResourceDictionary theme", "dynamic resources", "syst...
Guide for making .NET MAUI apps accessible — screen reader support via SemanticProperties, heading levels, AutomationProperties visibility control, programmatic focus and announcements, and platform-specific gotchas for TalkBack, VoiceOver, and Narrator. USE FOR: "add accessibility", "screen read...
Generate, edit, and beat-sync AI video with leading models in one workspace.
The world's fastest calendar for remote work
Transform Your Design with AI Designer by ImgCreator.ai
Revolutionizing Video Production with AI-Powered Creativity
Extend an image past the frame and let AI fill the new aspect ratio.
Discover your celebrity doppelgänger with StarByFace!
ChainClarity explains 700+ crypto whitepapers in plain English, with layered summaries, comparisons, research tools, alerts, and a $4.99 Pro plan.
Opus.ai: Revolutionize Your Web Experience