MAUI AI Debugging

Build, deploy, inspect, and debug .NET MAUI apps from the terminal. This skill enables a complete feedback loop: build → deploy → inspect → fix → rebuild.

Prerequisites

Install the CLI tool: dotnet tool install --global Redth.MauiDevFlow.CLI

For platform-specific tools: dotnet tool install --global androidsdk.tool (Android) and dotnet tool install --global appledev.tools (iOS/Mac).

Integrating MauiDevFlow into a MAUI App

For complete setup instructions including NuGet packages, MauiProgram.cs registration, Blazor script tag, Mac Catalyst entitlements, and Android port forwarding, see references/setup.md.

Quick summary:

1. •Add NuGet packages (Redth.MauiDevFlow.Agent, and Redth.MauiDevFlow.Blazor for Blazor Hybrid)
2. •Register in MauiProgram.cs inside #if DEBUG
3. •For Blazor Hybrid: add <script src="chobitsu.js"></script> to wwwroot/index.html
4. •For Mac Catalyst: ensure network.server entitlement
5. •For Android: run adb reverse for port forwarding

Core Workflow

1. Ensure a Device/Simulator/Emulator is Running

iOS Simulator:

xcrun simctl list devices booted                              # check booted sims
xcrun simctl boot <UDID>                                      # boot if needed
apple simulator list --booted                                 # alternative
apple simulator boot <UDID>                                   # alternative

Android Emulator:

android avd list                                              # list AVDs
android avd start --name <avd-name>                           # start emulator
adb devices                                                   # verify connected

Mac Catalyst: No device setup needed — runs as desktop app.

2. Build and Deploy

# iOS Simulator
dotnet build -f net10.0-ios -t:Run -p:_DeviceName=:v2:udid=<UDID>

# Android Emulator
dotnet build -f net10.0-android -t:Run

# Mac Catalyst
dotnet build -f net10.0-maccatalyst -t:Run

Adjust TFM version (net9.0, net10.0) to match project. Check the .csproj <TargetFrameworks>. Build + Run can take 30-120+ seconds. Use initial_wait: 120 or higher for async monitoring. The -t:Run flag keeps the process alive (--wait-for-exit). Run in background or a separate shell.

For Android emulators, set up port forwarding after deploy:

adb reverse tcp:9223 tcp:9223    # Agent
adb reverse tcp:9222 tcp:9222    # CDP (Blazor)

3. Verify Connectivity

maui-devflow MAUI status          # Agent connection (native)
maui-devflow cdp status           # CDP connection (Blazor WebView)

4. Inspect and Interact

See Command Reference below for the full command set.

Typical inspection flow:

1. •maui-devflow MAUI tree — see the full visual tree with element IDs, types, text, bounds
2. •maui-devflow MAUI query --automationId "MyButton" — find specific elements
3. •maui-devflow MAUI element <id> — get full details (type, bounds, visibility, children)
4. •maui-devflow MAUI property <id> Text — read any property by name
5. •maui-devflow MAUI screenshot --output screen.png — visual verification

Debugging styling/layout with property inspection: Use property to verify runtime values without relying solely on screenshots:

maui-devflow MAUI property <id> BackgroundColor    # verify dark mode colors
maui-devflow MAUI property <id> TextColor          # check text visibility
maui-devflow MAUI property <id> IsVisible          # check element visibility
maui-devflow MAUI property <id> Width              # verify layout sizing
maui-devflow MAUI property <id> Opacity            # check transparency

Combine tree + property for systematic debugging: get element IDs from tree, then inspect specific properties. This is more reliable than screenshots for verifying exact color values, font sizes, and layout metrics.

Typical interaction flow:

1. •maui-devflow MAUI fill <entryId> "text" — type into Entry/Editor fields
2. •maui-devflow MAUI tap <buttonId> — tap buttons, checkboxes, list items
3. •maui-devflow MAUI clear <entryId> — clear text fields
4. •Take screenshot to verify result

Blazor WebView (if applicable):

1. •maui-devflow cdp snapshot — DOM tree as accessible text (best for AI)
2. •maui-devflow cdp Input fill "css-selector" "text" — fill inputs
3. •maui-devflow cdp Input dispatchClickEvent "css-selector" — click elements
4. •maui-devflow cdp Runtime evaluate "js-expression" — run JS

Debugging Blazor styling via CDP: Use Runtime evaluate to inspect computed styles and verify CSS:

maui-devflow cdp Runtime evaluate "getComputedStyle(document.querySelector('.my-class')).backgroundColor"
maui-devflow cdp Runtime evaluate "window.matchMedia('(prefers-color-scheme: dark)').matches"
maui-devflow cdp Runtime evaluate "document.styleSheets.length"

This enables verifying Blazor dark mode, layout, and styling without relying solely on screenshots.

5. Reading Application Logs

MauiDevFlow automatically captures all Microsoft.Extensions.Logging (ILogger) output to rotating log files on the device. This means any ILogger<T> calls in the app's code (or in libraries) are available for remote retrieval — invaluable for debugging.

maui-devflow MAUI logs                   # fetch 100 most recent log entries
maui-devflow MAUI logs --limit 50        # fetch 50 entries
maui-devflow MAUI logs --skip 100        # skip newest 100, get next batch

Output is color-coded by level (red=Critical/Error, yellow=Warning, green=Info, gray=Debug/Trace). Each entry includes timestamp, log level, category (logger name), and message.

Debugging workflow with logs:

1. •Reproduce the issue (tap a button, navigate, etc.)
2. •maui-devflow MAUI logs --limit 20 — check recent log entries for errors or warnings
3. •If needed, add temporary ILogger calls to the app code for more detail:
   csharp

   _logger.LogInformation("Button tapped, item count: {Count}", items.Count);
   _logger.LogWarning("Unexpected state: {State}", currentState);
   

4. •Rebuild, redeploy, reproduce, and fetch logs again

Log configuration (in AddMauiDevFlowAgent options):

• •EnableFileLogging (default: true) — toggle file logging
• •MaxLogFileSize (default: 1 MB) — max size per log file before rotation
• •MaxLogFiles (default: 5) — number of rotated files to keep

The agent also exposes logs via REST: GET /api/logs?limit=N&skip=N returns a JSON array.

6. Fix and Rebuild

After identifying issues, edit source, rebuild (dotnet build), and redeploy. The full cycle: edit code → dotnet build -t:Run ... → maui-devflow MAUI status → inspect.

Command Reference

maui-devflow MAUI (Native Agent)

Global options: --agent-host (default localhost), --agent-port (default 9223), --platform.

Element IDs come from MAUI tree or MAUI query. AutomationId-based elements use their AutomationId directly. Others use generated hex IDs. When multiple elements share the same AutomationId, suffixes are appended: TodoCheckBox, TodoCheckBox_1, TodoCheckBox_2, etc.

maui-devflow cdp (Blazor WebView CDP)

Global option: --endpoint (default ws://localhost:9222/devtools/browser).

Agent REST API (Direct HTTP)

The agent exposes JSON endpoints on port 9223 (configurable):

Platform Details

For detailed platform-specific setup, simulator/emulator management, and troubleshooting:

• •Setup & Installation: See references/setup.md
• •iOS / Mac Catalyst: See references/ios-and-mac.md
• •Android: See references/android.md

Tips

• •Use AutomationId on important MAUI controls for stable element references.
• •The visual tree only reflects what's currently rendered. Off-screen items in CollectionView may not appear until scrolled into view.
• •Shell navigation: Use maui-devflow MAUI navigate "//route" for Shell-based apps. Routes are defined in AppShell.xaml via Route property on ShellContent elements.
• •For Blazor Hybrid, cdp snapshot is the most AI-friendly way to read page state.
• •Build times: Mac Catalyst ~5-10s, iOS ~30-60s, Android ~30-90s. Set appropriate timeouts.
• •After Android deploy, always run adb reverse for port forwarding.
• •Property inspection is more reliable than screenshots for verifying exact runtime values (colors, sizes, visibility). Use tree → property workflow for systematic debugging.
• •Application logs are captured automatically from ILogger. Use MAUI logs to fetch them remotely. Add temporary ILogger calls for extra debug output, then fetch logs after reproducing issues. This is often faster than attaching a debugger.