SuperAPI AI Directory

maui-devflow-onboard

Coding & development

View repository

Updated 10-16 08:15

About this skill

DevFlow Onboard

Use this skill to add MAUI DevFlow to a project after maui devflow init has installed the DevFlow skills.

When to Use

  • The project has no Microsoft.Maui.DevFlow.* package references yet.
  • The user asks how to onboard, initialize, install, integrate, or set up DevFlow.
  • The agent needs to choose between standard, Blazor, GTK, or GTK + Blazor DevFlow packages.
  • The repo uses Central Package Management and package edits need to be split correctly.
  • maui devflow init has installed skills and the user asks for the next project edits.

Route Elsewhere

  • If package references and AddMauiDevFlowAgent() are already present but the CLI cannot connect, use maui-devflow-debug.
  • If an agent is reachable and the user wants to inspect, tap, screenshot, or debug UI, use maui-devflow-debug.

Workflow

  1. Optionally run maui devflow skills check and update bundled skills before editing if it reports update-available-from-current-cli.

  2. Find MAUI app projects in the workspace. Prefer app projects with UseMaui, platform TFMs such as net*-android/net*-ios/net*-maccatalyst/net*-windows, or GTK MAUI package references.

  3. Determine whether each target project is standard MAUI, MAUI + Blazor WebView, GTK, or GTK + Blazor.

  4. Add the correct DevFlow package references. Respect Central Package Management if Directory.Packages.props is present.

  5. Register DevFlow in MauiProgram.cs inside #if DEBUG.

  6. Build and run the app.

  7. Verify with:

    maui devflow diagnose
    maui devflow wait
    maui devflow ui tree --depth 1
    

If verification fails after integration, switch to maui-devflow-debug for connectivity recovery.

Stop Signals

  • Stop before editing if multiple MAUI app projects exist and the user has not indicated which one to onboard.
  • Stop and ask before enabling DevFlow outside Debug builds.
  • Stop after package/registration edits and verify with a build before doing runtime debugging.

Critical Anti-patterns

  • Do not add versions to project PackageReference items when Directory.Packages.props is managing package versions.
  • Do not add Blazor DevFlow packages unless the app uses Blazor WebView.
  • Do not register DevFlow outside #if DEBUG unless the user explicitly asks.
  • Do not use the old builder.Services.AddMauiDevFlowAgent() pattern; use builder.AddMauiDevFlowAgent().

Package Selection

Project flavor Required packages
Standard 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 indicators include a Microsoft.AspNetCore.Components.WebView.Maui package reference or AddMauiBlazorWebView() in MauiProgram.cs.

GTK indicators include Microsoft.Maui.Platforms.Linux.Gtk4 or Microsoft.Maui.Platforms.Linux.Gtk4.BlazorWebView. Migrate superseded Platform.Maui.Linux.Gtk4* references before adding the current GTK DevFlow packages; do not mix the two backends.

Central Package Management

If the repo uses Directory.Packages.props, put versions there and leave project PackageReference entries versionless.

<!-- Directory.Packages.props -->
<PackageVersion Include="Microsoft.Maui.DevFlow.Agent" Version="<current-version>" />
<!-- App.csproj -->
<PackageReference Include="Microsoft.Maui.DevFlow.Agent" />

If the repo does not use Central Package Management, put the version on the PackageReference.

MauiProgram.cs Registration

For standard MAUI:

using Microsoft.Maui.DevFlow.Agent;

// inside CreateMauiApp(), before return builder.Build();
#if DEBUG
builder.AddMauiDevFlowAgent();
#endif

For 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

For GTK, use the .Gtk namespaces and packages. AddMauiDevFlowAgent() starts automatically when GtkMauiApplication creates its first window. An explicit this.StartDevFlowAgent() hook is also available inside a GtkMauiApplication.OnStarted() override; builder registration is still required.

For Mac Catalyst, ensure the Debug entitlements allow the in-app HTTP server:

<key>com.apple.security.network.server</key>
<true/>

Validation Checklist

  • MauiProgram.cs registers DevFlow only in Debug builds.
  • The app project references the package flavor that matches the target platform.
  • Blazor DevFlow tools are added only when the app uses Blazor WebView.
  • GTK apps use the current backend and start the DevFlow agent automatically after the first window is created.
  • Mac Catalyst Debug entitlements include com.apple.security.network.server.
  • dotnet build succeeds.
  • A running app appears in maui devflow list.
  • maui devflow ui tree --depth 1 returns a visual tree.

References

  • See references/package-selection.md for package/flavor details.
  • See references/mauiprogram-registration.md for registration patterns.