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 inithas 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, usemaui-devflow-debug. - If an agent is reachable and the user wants to inspect, tap, screenshot, or debug UI, use
maui-devflow-debug.
Workflow
-
Optionally run
maui devflow skills checkand update bundled skills before editing if it reportsupdate-available-from-current-cli. -
Find MAUI app projects in the workspace. Prefer app projects with
UseMaui, platform TFMs such asnet*-android/net*-ios/net*-maccatalyst/net*-windows, or GTK MAUI package references. -
Determine whether each target project is standard MAUI, MAUI + Blazor WebView, GTK, or GTK + Blazor.
-
Add the correct DevFlow package references. Respect Central Package Management if
Directory.Packages.propsis present. -
Register DevFlow in
MauiProgram.csinside#if DEBUG. -
Build and run the app.
-
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
PackageReferenceitems whenDirectory.Packages.propsis managing package versions. - Do not add Blazor DevFlow packages unless the app uses Blazor WebView.
- Do not register DevFlow outside
#if DEBUGunless the user explicitly asks. - Do not use the old
builder.Services.AddMauiDevFlowAgent()pattern; usebuilder.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.csregisters 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 buildsucceeds.- A running app appears in
maui devflow list. maui devflow ui tree --depth 1returns a visual tree.
References
- See
references/package-selection.mdfor package/flavor details. - See
references/mauiprogram-registration.mdfor registration patterns.