用途
MAUI DevFlow Onboard 用于在 maui devflow init 已安装 DevFlow 技能之后,把 MAUI DevFlow 接入到 .NET MAUI 项目中。它面向的是项目尚未引用任何 Microsoft.Maui.DevFlow.* 包、用户询问如何接入、初始化、安装、集成或设置 DevFlow 的场景。
何时使用
- 项目还没有
Microsoft.Maui.DevFlow.*包引用。 - 用户询问如何接入、初始化、安装、集成或设置 DevFlow。
- 需要在标准、Blazor、GTK 或 GTK + Blazor DevFlow 包之间做选择。
- 仓库使用中央包管理,包编辑需要正确拆分。
maui devflow init已安装技能,用户询问下一步的项目编辑。
何时转向其他技能
- 如果包引用和
AddMauiDevFlowAgent()已存在,但 CLI 无法连接,使用maui-devflow-debug。 - 如果 agent 可访问,且用户想要检查、点击、截图或调试 UI,使用
maui-devflow-debug。
工作流程
- 可选:在编辑前运行
maui devflow skills check并更新捆绑技能,如果它报告update-available-from-current-cli。 - 在工作区中查找 MAUI 应用项目。优先选择带有
UseMaui、平台 TFM(如net*-android/net*-ios/net*-maccatalyst/net*-windows)或 GTK MAUI 包引用的应用项目。 - 判断每个目标项目是标准 MAUI、MAUI + Blazor WebView、GTK,还是 GTK + Blazor。
- 添加正确的 DevFlow 包引用。如果存在
Directory.Packages.props,需遵守中央包管理。 - 在
MauiProgram.cs的#if DEBUG中注册 DevFlow。 - 构建并运行应用。
- 使用以下命令验证:
maui devflow diagnosemaui devflow waitmaui devflow ui tree --depth 1
- 如果集成后验证失败,切换到
maui-devflow-debug进行连接恢复。
停止信号
- 如果存在多个 MAUI 应用项目且用户未指明要接入哪一个,在编辑前停止。
- 在 Debug 构建之外启用 DevFlow 之前,停止并询问。
- 在包/注册编辑完成后停止,并在进行运行时调试前先通过构建验证。
关键反模式
- 当
Directory.Packages.props管理包版本时,不要给项目PackageReference项添加版本。 - 除非应用使用 Blazor WebView,否则不要添加 Blazor DevFlow 包。
- 除非用户明确要求,否则不要在
#if DEBUG之外注册 DevFlow。 - 不要使用旧的
builder.Services.AddMauiDevFlowAgent()模式;应使用builder.AddMauiDevFlowAgent()。
包选择
| 项目类型 | 所需包 |
|---|---|
| 标准 MAUI | Microsoft.Maui.DevFlow.Agent |
| MAUI + Blazor WebView | Microsoft.Maui.DevFlow.Agent、Microsoft.Maui.DevFlow.Blazor |
| GTK MAUI | Microsoft.Maui.DevFlow.Agent.Gtk |
| GTK MAUI + Blazor WebView | Microsoft.Maui.DevFlow.Agent.Gtk、Microsoft.Maui.DevFlow.Blazor.Gtk |
Blazor WebView 的指示包括 Microsoft.AspNetCore.Components.WebView.Maui 包引用或 MauiProgram.cs 中的 AddMauiBlazorWebView()。
GTK 的指示包括 Microsoft.Maui.Platforms.Linux.Gtk4 或 Microsoft.Maui.Platforms.Linux.Gtk4.BlazorWebView。在添加当前 GTK DevFlow 包之前,先迁移已被取代的 Platform.Maui.Linux.Gtk4* 引用;不要混用两种后端。
中央包管理
如果仓库使用 Directory.Packages.props,把版本放在那里,并让项目 PackageReference 条目不带版本。
<!-- Directory.Packages.props -->
<PackageVersion Include="Microsoft.Maui.DevFlow.Agent" Version="<current-version>" />
<!-- App.csproj -->
<PackageReference Include="Microsoft.Maui.DevFlow.Agent" />
如果仓库不使用中央包管理,把版本放在 PackageReference 上。
MauiProgram.cs 注册
标准 MAUI:
using Microsoft.Maui.DevFlow.Agent;
// inside CreateMauiApp(), before return builder.Build();
#if DEBUG
builder.AddMauiDevFlowAgent();
#endif
MAUI + Blazor WebView:
using Microsoft.Maui.DevFlow.Agent;
using Microsoft.Maui.DevFlow.Blazor;
// inside CreateMauiApp(), before return builder.Build();
#if DEBUG
builder.AddMauiDevFlowAgent();
builder.AddMauiBlazorDevFlowTools();
#endif
GTK:使用 .Gtk 命名空间和包。当 GtkMauiApplication 创建第一个窗口时,AddMauiDevFlowAgent() 会自动启动。在 GtkMauiApplication.OnStarted() 重写中也可以使用显式的 this.StartDevFlowAgent() 钩子;仍然需要 builder 注册。
Mac Catalyst:确保 Debug 权限允许应用内 HTTP 服务器:
<key>com.apple.security.network.server</key>
<true/>
验证清单
MauiProgram.cs仅在 Debug 构建中注册 DevFlow。- 应用项目引用的包类型与目标平台匹配。
- 仅当应用使用 Blazor WebView 时才添加 Blazor DevFlow 工具。
- GTK 应用使用当前后端,并在第一个窗口创建后自动启动 DevFlow agent。
- Mac Catalyst Debug 权限包含
com.apple.security.network.server。 dotnet build成功。- 运行中的应用出现在
maui devflow list中。 maui devflow ui tree --depth 1返回可视化树。
参考
- 包/类型细节见
references/package-selection.md。 - 注册模式见
references/mauiprogram-registration.md。