mcpField
M
maui-hot-reload-diagnostics

maui-hot-reload-diagnostics

github.com/davidortinau开发17646 次安装16 周前更新
代码仓库

关于 maui-hot-reload-diagnostics

用于排查 .NET MAUI 应用 Hot Reload 故障的诊断技能。它区分 XAML 与 C# 问题，并提供配置、编码、框架特定行为及重启要求的检查方法。

主要功能

  1. 01XAML 与 C# 故障分类
  2. 02Debug 配置检查
  3. 03UTF-8 with BOM 编码验证
  4. 04框架特定指导
  5. 05需重启的编辑参考
  6. 06Hot Reload 日志诊断

适用场景

  1. 01诊断保存后更改未生效
  2. 02排查不支持的编辑或 rude edit
  3. 03解决 iOS XAML 热重载问题
  4. 04检查 Blazor Hybrid 的重启要求

安装

复制下面的命令，在终端中运行。

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

安装后在 Claude Code 中输入/maui-hot-reload-diagnostics确认已加载。

附带文件references/hot-reload-setup.mdscripts/diagnose-hot-reload.sh

详细介绍

.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 构建设置中将 Linker 设为 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# Markup（CommunityToolkit.Maui.Markup）

要点——缺少以下任意一项都会导致热重载失效：

  • ⚠️ 将 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 上必须关闭 Linker；配置必须为“Debug”
C# 代码隐藏仅方法体必须重新触发代码路径；不兼容的编辑需要重启
MauiReactor v3+组件重新渲染需要 RuntimeHostConfigurationOption，而不是代码调用
C# MarkupBuild() 方法体必须实现 ICommunityToolkitHotReloadHandler
Blazor Hybrid.razor + .css添加新组件/服务需要重启

调试技巧

  • ⚠️ 始终先检查热重载输出窗口——其中会明确说明修改被拒绝的原因。
  • 在启动 IDE 前，使用环境变量启用详细日志（参见 references/hot-reload-setup.md）。
  • 二进制日志（dotnet build -bl:build.binlog）有助于诊断与构建相关的热重载故障。
  • 报告 Bug 时，请附上：dotnet --info、工作负载列表、二进制日志和热重载输出。

快速检查清单

  • 已选择 Debug 配置（而非 Release）
  • 已附加调试器（F5，而非 Ctrl+F5）
  • 所有 .cs 文件均为带 BOM 的 UTF-8 编码
  • 已检查热重载输出窗口中的错误
  • C# 修改后已重新触发代码路径
  • MauiReactor：.csproj 中包含 RuntimeHostConfigurationOption（而非代码调用）
  • C# Markup：已实现 ICommunityToolkitHotReloadHandler
  • Blazor Hybrid：未修改服务/启动代码

评论

支持 Markdown