maui-hot-reload-diagnostics

.NET MAUI ホットリロードの診断

.NET MAUI アプリのホットリロードの問題を体系的に診断します。

すばやく確認するチェックリスト

1. 何が動作していないか特定する：XAML ホットリロード（.xaml の変更）か、C# ホットリロード（.cs の変更）か
2. 実行構成を確認する：Debug 構成で、F5 を押してデバッガーをアタッチした状態で起動する必要があります
3. ファイルを保存し、コードパスを再実行する：C# の変更は、コードを再度実行する必要があります
4. ホットリロードの出力を確認する：［表示］>［出力］>「Hot Reload」（VS）または「C# Hot Reload」（VS Code）

⚠️ ファイルのエンコード要件

重要：すべての .cs ファイルは BOM 付き UTF-8 エンコードである必要があります。

# 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

よくある問題と解決策

「保存しても何も起こらない」

1. Debug 構成であることを確認します（Release ではありません）
2. ホットリロードの出力でエラーを確認します
3. ファイルが保存されていることを確認します（変更しただけでは不十分です）
4. コードパスを再実行します（再度移動する、ボタンをもう一度タップする）

「サポートされていない編集」／「不適切な編集」

次の変更では、必ずアプリを再起動する必要があります。

• メソッド、フィールド、プロパティの追加や削除
• メソッドシグネチャの変更
• 静的コンストラクターの変更
• ジェネリックに関する変更

XAML の変更が反映されない（iOS）

• ⚠️ iOS のビルド設定でリンカーを Don't Link に設定します
• 構成名は正確に Debug にする必要があります
• XamlCompilationOptions.Skip は使用しないでください

変更は反映されるが UI が更新されない

• C# の場合：コードを再度実行する必要があります（再度移動する、もう一度タップする）
• バインド値や状態がキャッシュされていないか確認します
• 正しいターゲットフレームワークのファイルを編集していることを確認します

フレームワーク固有の注意点

MauiReactor v3+

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

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

⚠️ MauiReactor v2 から移行する場合は、MauiProgram.cs から EnableMauiReactorHotReload() の呼び出しを削除してください。

C# マークアップ（CommunityToolkit.Maui.Markup）

重要なポイント — どれか1つでも欠けると、ホットリロードが動作しません。

• ⚠️ UI の構築処理を別の Build() メソッドに切り出します
• ⚠️ 更新が必要なページ／ビューに ICommunityToolkitHotReloadHandler を実装します
• C# ホットリロード後に OnHotReload() メソッドが自動的に呼び出されます
• MauiProgram.cs で .UseMauiCommunityToolkitMarkup() を呼び出す必要があります

Blazor Hybrid の制限事項

次の変更では、必ず再起動する必要があります。

• 新しいコンポーネントの追加
• @inject サービスの変更
• 静的アセットの変更（画像、フォント）
• Program.cs または MauiProgram.cs の変更

次の変更は通常、再起動せずに反映されます。

• Razor マークアップと C# コードブロックの変更
• CSS の変更（キャッシュされている場合はハードリフレッシュが必要なことがあります）
• コンポーネントパラメーターの変更

⚠️ CSS の分離：.razor.css の変更が反映されない場合は、分離された CSS ファイルが正しくリンクされていることを確認してください。

判断の指針 — どのホットリロード方式を使うか？

UI の方式	リロードされるもの	注意点
XAML	.xaml ファイル（即時）	iOS ではリンカーをオフにする必要があります。構成名は「Debug」にする必要があります
C# コードビハインド	メソッド本体のみ	コードパスを再実行する必要があります。不適切な編集では再起動が必要です
MauiReactor v3+	コンポーネントの再レンダリング	コードで呼び出すのではなく、RuntimeHostConfigurationOption が必要です
C# マークアップ	Build() メソッド本体	ICommunityToolkitHotReloadHandler を実装する必要があります
Blazor Hybrid	.razor + .css	新しいコンポーネント／サービスには再起動が必要です

デバッグのヒント

• ⚠️ まずホットリロードの出力ウィンドウを必ず確認してください — 変更が適用されなかった理由が正確に表示されます。
• IDE の起動前に環境変数で詳細ログを有効にします（references/hot-reload-setup.md を参照）。
• バイナリログ（dotnet build -bl:build.binlog）は、ビルドに関連するホットリロードの問題の診断に役立ちます。
• バグを報告する際は、dotnet --info、ワークロード一覧、バイナリログ、ホットリロードの出力を含めてください。

すばやく確認するチェックリスト

• Debug 構成が選択されている（Release ではない）
• デバッガーがアタッチされている（Ctrl+F5 ではなく F5）
• すべての .cs ファイルが BOM 付き UTF-8 である
• ホットリロードの出力ウィンドウでエラーを確認した
• C# の変更後にコードパスを再実行した
• MauiReactor：.csproj に RuntimeHostConfigurationOption がある（コードでの呼び出しではない）
• C# マークアップ：ICommunityToolkitHotReloadHandler を実装した
• Blazor Hybrid：サービス／起動コードを変更していない