Start debugging a .NET program. RECOMMENDED for most debugging scenarios.

This is the preferred method for debugging .NET applications. It launches a new process under the debugger with full feature support including:

• Complete call stack visibility

• Full variable inspection

• All breakpoint features

SMART RESOLUTION: For .NET 6+ apps (WPF/WinForms), automatically resolves .exe to .dll to avoid "deps.json conflict" errors. You can pass either App.exe or App.dll - the correct target will be selected automatically.

PRE-BUILD: By default, builds the project before launching to ensure you're debugging the latest code. Provide build_project path to .csproj file. Set pre_build=False to skip building (e.g., for pre-built binaries).

BUILD WARNINGS: Hidden by default to reduce noise. If the build succeeds but the app behaves unexpectedly, call get_build_diagnostics() to see all warnings — they may reveal the issue.

Use attach_debug only for already-running processes (e.g., ASP.NET services).

Escape hatch: see the dap-escape-hatch prompt for unwrapped DAP requests.

Args: program: Path to the .NET executable or DLL to debug (auto-resolved) cwd: Working directory for the program args: Command line arguments env: Environment variables launch_profile: Optional project launch profile name stop_at_entry: Stop at entry point pre_build: Build project before launching (default: True). Requires build_project. build_project: Path to .csproj file (required when pre_build=True) build_configuration: Build configuration (Debug/Release) stealth_mode: Avoid foreground-stealing UI actions for GUI debugging

AVOID - Use start_debug instead. Attach to already-running process (LIMITED).

LIMITATION: netcoredbg does NOT support justMyCode in attach mode (only in launch). This is an UPSTREAM limitation that CANNOT be fixed by this MCP server. Result: stack traces will be incomplete/empty, debugging will be unreliable.

ONLY use this if you MUST debug an already-running process that you cannot restart (e.g., production service, container you cannot control).

For normal debugging, ALWAYS use start_debug which has full functionality. If start_debug fails with build errors, fix the build - don't switch to attach.

Escape hatch: see the dap-escape-hatch prompt for unwrapped DAP requests.

Args: process_id: PID of an already-running .NET process (NOT for normal debugging)

Stop the current debug session.

Escape hatch: see the dap-escape-hatch prompt for unwrapped DAP requests.

Restart the current debug session with the same configuration.

Stops the current session, optionally rebuilds, and relaunches. Use this after code changes to debug the updated version.

Escape hatch: see the dap-escape-hatch prompt for unwrapped DAP requests.

Args: rebuild: Whether to rebuild before restarting (default: True)

Continue program execution. Blocks until the program stops again or timeout.

State: STOPPED required. Blocks until next stop or timeout.

This tool uses the long-poll pattern: it waits for the debugger to report a stopped event (breakpoint hit, exception, step complete) before returning.

The response includes the new state, stop reason, and next_actions so you know exactly what happened and what to do next.

IMPORTANT: While waiting, the program is RUNNING — do not call get_variables or get_call_stack until this tool returns with state=stopped.

Escape hatch: see the dap-escape-hatch prompt for unwrapped DAP requests.

Pause program execution.

State: RUNNING required. Returns immediately (does not block like step tools). Use get_call_stack() after pause to inspect the stopped state.

Unlike continue/step tools, this returns immediately after sending the pause command — it does not wait for a stopped event.

Escape hatch: see the dap-escape-hatch prompt for unwrapped DAP requests.

Step over to the next line. Blocks until the step completes.

State: STOPPED required.

Executes the current line without entering function calls. Returns the new stopped location with source context.

IMPORTANT: After this returns with state=stopped, inspect variables at the new location before deciding the next action.

Escape hatch: see the dap-escape-hatch prompt for unwrapped DAP requests.

Get available step-in targets for the current stack frame.

State: STOPPED required. Call before step_into(target_id=N) to choose target.

When multiple function calls exist on one line, this returns each one so you can choose which to enter via step_into(target_id=...).

Args: frame_id: Stack frame ID (uses current frame if omitted)

Escape hatch: see the dap-escape-hatch prompt for unwrapped DAP requests.

Step into the next function call. Blocks until the step completes.

State: STOPPED required.

Enters the function being called on the current line. Use this when you need to investigate what happens inside a called function.

When multiple calls exist on one line, call get_step_in_targets first and pass the desired target's id via target_id.

IMPORTANT: After this returns with state=stopped, you are inside the called function. Use step_out to return to the caller.

Args: thread_id: Thread to step (uses current thread if omitted) target_id: Specific step-in target ID from get_step_in_targets

Escape hatch: see the dap-escape-hatch prompt for unwrapped DAP requests.

Step out of the current function. Blocks until the step completes.

State: STOPPED required.

Continues execution until the current function returns, then stops at the caller. Use this to exit a function you stepped into.

Escape hatch: see the dap-escape-hatch prompt for unwrapped DAP requests.

Get the current debug session state.

Returns state, threads, current position, and exception info. The user cannot see this directly - summarize important info for them.

IMPORTANT: Always check state before asking user to interact with the app GUI! If the app is paused at a breakpoint, the user cannot interact with UI. Call continue_execution first if state shows stopped/paused.

Escape hatch: see the dap-escape-hatch prompt for unwrapped DAP requests.

Gracefully terminate the debugged program.

Sends DAP terminate request for clean shutdown. Falls back to forced disconnect if adapter doesn't support terminate.

Use this instead of stop_debug when you want a graceful exit.

Escape hatch: see the dap-escape-hatch prompt for unwrapped DAP requests.

Add a breakpoint at a specific line.

IMPORTANT TIMING:

• Breakpoints set BEFORE start_debug only work for debugging app startup.

• For UI apps (WPF/WinForms): remove breakpoints before launch, then add them AFTER the UI is fully loaded. Otherwise the app may hang during initialization.

• When debugging UI issues: wait for app to be fully interactive before setting breakpoints in event handlers.

Escape hatch: see the dap-escape-hatch prompt for unwrapped DAP requests.

Args: file: Absolute path to source file line: Line number (1-based) condition: Optional condition expression hit_condition: Optional hit count condition

Remove a breakpoint from a specific line.

Escape hatch: see the dap-escape-hatch prompt for unwrapped DAP requests.

List all breakpoints or breakpoints in a specific file.

Escape hatch: see the dap-escape-hatch prompt for unwrapped DAP requests.

Clear breakpoints from a file or all files.

Escape hatch: see the dap-escape-hatch prompt for unwrapped DAP requests.

Set a breakpoint on a function by name.

Breaks when the named function is entered. This is useful when you know the method name but not the exact line number.

Escape hatch: see the dap-escape-hatch prompt for unwrapped DAP requests.

Args: function_name: Full or partial function name to break on condition: Optional condition expression hit_condition: Optional hit count condition

Configure which exceptions should pause the debugger.

Controls exception breakpoints — when the debugger should stop on exceptions. By default, no exception filters are set (exceptions don't pause unless uncaught).

Common filters supported by netcoredbg:

• "all": Break on all exceptions (caught and uncaught)

• "user-unhandled": Break on exceptions not handled in user code

Pass an empty list to disable all exception breakpoints.

Escape hatch: see the dap-escape-hatch prompt for unwrapped DAP requests.

Args: filters: List of exception filter names. Pass [] to disable.

Get all threads in the debugged process.

Escape hatch: see the dap-escape-hatch prompt for unwrapped DAP requests.

Get the call stack for a thread.

State: STOPPED required. Returns frame_id values needed for get_scopes().

Diagnostic: Set NETCOREDBG_STACKTRACE_DELAY_MS env var to add delay before stackTrace request. This helps diagnose timing issues with ICorDebugThread3. Example: NETCOREDBG_STACKTRACE_DELAY_MS=300

Escape hatch: see the dap-escape-hatch prompt for unwrapped DAP requests.

Get variable scopes for a stack frame.

State: STOPPED required. Call get_call_stack() first to get frame_id. Returns variables_reference for get_variables().

Escape hatch: see the dap-escape-hatch prompt for unwrapped DAP requests.

Get variables for a scope or structured variable.

State: STOPPED required. Call get_scopes() first to get variables_reference.

Supports paging for large collections (e.g. arrays, lists).

Args: variables_reference: Reference from get_scopes or a nested variable filter: Filter to "indexed" (array elements) or "named" (properties only) start: Index of first variable to fetch (for paging) count: Maximum number of variables to return (for paging)

Escape hatch: see the dap-escape-hatch prompt for unwrapped DAP requests.

Evaluate an expression in the current debug context.

State: STOPPED required.

Escape hatch: see the dap-escape-hatch prompt for unwrapped DAP requests.

Set a variable's value during debugging.

State: STOPPED required.

Modifies a variable in the current scope. The program must be stopped. Use get_variables first to find the variables_reference for the scope.

Args: variables_reference: Reference from get_scopes or get_variables name: Variable name to modify value: New value as a string expression

Escape hatch: see the dap-escape-hatch prompt for unwrapped DAP requests.

Get information about the current exception.

State: STOPPED required (stopped on exception).

Escape hatch: see the dap-escape-hatch prompt for unwrapped DAP requests.

List loaded assemblies/modules in the debug session.

Returns module name, path, version, optimization status, and symbol loading state. Useful for diagnosing assembly loading failures and version conflicts.

Note: Data comes from module load/unload events tracked during the session.

Escape hatch: see the dap-escape-hatch prompt for unwrapped DAP requests.

List active debugger progress operations.

Poll this during long adapter operations to see current progressId, title, message, percentage, cancellability, and start timestamp.

Escape hatch: see the dap-escape-hatch prompt for unwrapped DAP requests.

List sources currently loaded by the debug adapter.

Capability-gated on supportsLoadedSourcesRequest. Also refreshes the session's live loadedSource event view on success.

Escape hatch: see the dap-escape-hatch prompt for unwrapped DAP requests.

Disassemble machine instructions around a memoryReference.

Capability-gated on supportsDisassembleRequest. Use a stack frame's instructionPointerReference or an executable memoryReference from a variable.

Escape hatch: see the dap-escape-hatch prompt for unwrapped DAP requests.

Resolve a DAP locationReference into source coordinates.

Capability-gated on supportsLocationsRequest. A locationReference can be returned by variables or stack frames in adapters that implement DAP 1.68+.

Escape hatch: see the dap-escape-hatch prompt for unwrapped DAP requests.

Evaluate an expression while the program is running (atomic pause-eval-resume).

Pauses execution for ~5ms, evaluates the expression, then resumes. Use this instead of manually pausing, evaluating, and continuing.

IMPORTANT: Only works when program is RUNNING. If stopped, use evaluate_expression instead.

Args: expression: Expression to evaluate (e.g., "myVariable", "list.Count") frame_id: Optional stack frame ID for evaluation context

Escape hatch: see the dap-escape-hatch prompt for unwrapped DAP requests.

Get full exception context in one call (exception autopsy).

State: STOPPED required (stopped on exception).

Returns exception type/message, inner exception chain, stack frames with source locations, and local variables for the top N frames — all in a single response. Use this FIRST when the debugger stops on an exception.

This replaces the manual sequence of: get_exception_info → get_call_stack → get_scopes → get_variables

Args: max_frames: Maximum stack frames to return (default 10) include_variables_for_frames: Include locals for top N frames (default 1) max_inner_exceptions: Max inner exception chain depth (default 5)

Escape hatch: see the dap-escape-hatch prompt for unwrapped DAP requests.

Get rich context when stopped at any breakpoint — one call replaces many.

Returns stop reason, stack trace with source, locals in the top frame, hit count for the current breakpoint, and recent output lines.

Call this FIRST when execution stops. It gives you everything you need to understand the stop without multiple sequential tool calls.

Args: include_variables: Include local variables for top frame (default True) include_output_tail: Include last N output lines (default 10, 0 to skip)

Escape hatch: see the dap-escape-hatch prompt for unwrapped DAP requests.

Set a non-stopping tracepoint that logs expression values.

State: Works in any state. The tracepoint fires automatically on each hit.

The tracepoint evaluates the expression each time the line is hit, without visibly pausing the program. Results are stored in a trace buffer accessible via get_trace_log.

Async state machines: when the target line is inside an async method, the C# compiler moves the first executable instruction to the line after the await. netcoredbg reports the adjusted line via DAP, and netcoredbg-mcp tracks both the user-requested and adjusted lines — tracepoint matching works for both. No user action required; get_trace_log will contain entries and the program will NOT pause.

Args: file: Source file path line: Line number (1-based) expression: Expression to evaluate on each hit

Remove a tracepoint by ID.

Args: tracepoint_id: Tracepoint ID (e.g., "tp-1")

Get tracepoint evaluation log.

State: Works in any state.

Args: since: Only return entries after this timestamp (monotonic) tracepoint_id: Filter to specific tracepoint

Clear the tracepoint evaluation log.

Capture all local variables at the current frame as a named snapshot.

State: STOPPED required.

Must be called when the program is stopped at a breakpoint. Max 20 snapshots per session (oldest evicted when full).

Args: name: Unique name for this snapshot

Compare two snapshots and show variable differences.

Args: name1: First snapshot name (before state) name2: Second snapshot name (after state)

List all captured snapshots with metadata.

Analyze a collection variable in one call.

State: STOPPED required. Get variables_reference from get_variables() response.

Returns count, element type, null count, first/last N items, and numeric stats (min/max/sum/average) for numeric collections.

Args: variables_reference: Variable reference from get_variables response sample_size: Number of first/last items to include (default 5)

Produce a flattened summary of a complex object.

State: STOPPED required. Get variables_reference from get_variables() response.

Returns property paths (dot notation), values, and types up to the configured depth. Detects circular references.

Args: variables_reference: Variable reference from get_variables response max_depth: Maximum nesting depth (default 2, max 5) max_properties: Maximum total properties to return (default 50)

Read raw memory bytes from a debugger memoryReference.

Capability-gated: current netcoredbg builds usually return an unsupported error unless they advertise supportsReadMemoryRequest.

Escape hatch: see the dap-escape-hatch prompt for unwrapped DAP requests.

Args: memory_reference: DAP memoryReference from a variable or stack frame offset: Byte offset from the memory reference count: Number of bytes to read; count=0 returns empty data locally

Write base64-encoded bytes to a debugger memoryReference.

DESTRUCTIVE: this mutates debuggee memory and can corrupt process state. Capability-gated: current netcoredbg builds usually return an unsupported error unless they advertise supportsWriteMemoryRequest.

Escape hatch: see the dap-escape-hatch prompt for unwrapped DAP requests.

Args: memory_reference: DAP memoryReference from a variable or stack frame data: Base64-encoded bytes to write offset: Byte offset from the memory reference allow_partial: Let the adapter perform a partial write if needed

Get stdout/stderr output from the debugged program.

IMPORTANT: The user cannot see this output directly. YOU must read it and summarize relevant information for the user. Never tell the user to "check the console" or "look at output".

Call periodically during debugging to catch log messages and errors.

Args: clear: Clear the output buffer after reading (default False) category: Filter by category: "stdout", "stderr", or "console" (default: all)

Search program output for a pattern (regex supported).

Use this instead of get_output when looking for specific messages, errors, or log entries in large output. Returns matching lines with context.

Args: pattern: Regex pattern to search for (case-insensitive) context_lines: Number of lines before/after each match (default 2) category: Filter by category: "stdout", "stderr", or "console" (default: all)

Returns: List of matches with line numbers and context

Get the last N lines of program output.

Useful for checking recent output without loading everything. The user cannot see this - summarize relevant info for them.

Args: lines: Number of lines to return (default 50) category: Filter by category: "stdout", "stderr", or "console" (default: all)

Get full build diagnostics including all warnings.

Build warnings are hidden by default in start_debug/restart_debug responses to reduce context noise. Call this tool when:

• Build succeeds but the app crashes or behaves unexpectedly

• Investigating assembly loading or compatibility issues

• Checking nullable reference, deprecation, or platform warnings

• Debugging "it compiles but doesn't work" situations

Args: include_warnings: Include warning details (default True, the point of this tool)

Clear stale debugger state and report a compact hygiene result.

Create a named breakpoint/tracepoint group for smoke evidence.

Inspect grouped breakpoint hits and trace logs.

Remove a named instrumentation group with leak detection.

Mark the current output buffer position for later assertions.

Assert required and forbidden output patterns since a checkpoint.

Verify that the debug session matches expected runtime evidence.

Run a bounded runtime smoke scenario plan with cleanup evidence.

Get the visual tree of the debugged application — ALL top-level windows.

Covers the main app window and any sibling windows (modal dialogs, popups, file pickers) owned by the same process. Modal dialogs created via WPF Window.ShowDialog() are sibling top-level windows, not descendants of the main window — they appear in the "windows" array alongside the main window.

Call after start_debug and wait for the application window to appear.

Args: max_depth: Maximum depth to traverse within each window (default 3) max_children: Maximum children per element (default 50)

Returns: FlaUI backend: {"windows": [tree, ...], "count": N, "primary": "Main App"} Each tree entry carries automationId, controlType, name, rect, children, etc. Use ui_switch_window to retarget subsequent calls at a specific window (e.g. a modal dialog).

pywinauto fallback backend: a single-window tree dict with
automationId/name/rect/children at the root (no windows array,
no count, no primary). Callers that need to support both
backends should probe for the "windows" key and fall back to
treating the response itself as a single-window tree.

Bring the debuggee window to the foreground and exit stealth mode.

Retarget the UI backend at a different top-level window of the same process.

Use this to enter modal dialogs, file pickers, or popups that appear as sibling windows of the app's main window. After switching, all subsequent ui_* calls (find_element, click, send_keys, etc.) operate inside the new window's subtree.

Typical flow:

1. ui_get_window_tree() → inspect "windows" array

2. ui_switch_window(name="Create collection") → enter dialog

3. ui_find_element(control_type="Edit") → locate dialog TextBox

4. ui_send_keys_batch(keys=["Characters", "{ENTER}"]) → type + submit

5. After dialog closes, ui_switch_window(name="Main App Title") to return to the original window

Requires the FlaUI bridge backend; the pywinauto fallback raises NotImplementedError. At least one of name or automation_id must be provided; automation_id is matched first.

Args: name: Window title (e.g., the dialog's Title/Name property) automation_id: Window's AutomationId property (if any)

Returns: {"switched": True, "title": "...", "automationId": "..."} on success

Find a UI element by AutomationId, name, control type, or XPath.

At least one search criterion must be provided. Use ui_get_window_tree first to discover available elements.

Args: automation_id: AutomationId property (most reliable for WPF) name: Element's Name/Title property control_type: Type like "Button", "TextBox", "MenuItem" root_id: Optional AutomationId to scope search to a subtree xpath: Optional XPath expression (FlaUI backend only)

Returns: Element info if found

Set keyboard focus to a UI element.

Uses UIA-based Focus() for FlaUI backend (monitor/DPI-agnostic), or element search + set_focus for pywinauto backend.

Call this before ui_send_keys to ensure keys go to the right element.

Args: automation_id: AutomationId property (FlaUI + pywinauto) name: Element's Name/Title property (FlaUI + pywinauto) control_type: Control type (pywinauto only) root_id: Optional AutomationId to scope search (pywinauto only) xpath: Optional XPath expression (pywinauto only)

Send keyboard input to a UI element.

Note: If app is STOPPED at breakpoint, resume with continue_execution() first.

Tries cached coordinates first (click to focus, then send keys), then falls back to pywinauto element search.

Key syntax (modifiers are PREFIX characters, special keys in braces):

• Regular text: "hello world"

• Modifiers: ^ = Ctrl, % = Alt, + = Shift

• Alt+Z: "%z" Alt+F4: "%{F4}"

• Ctrl+C: "^c" Ctrl+Shift+S: "^+s"

• Shift+Tab: "+{TAB}"

• Special keys: {ENTER} {TAB} {ESC} {DELETE} {BACKSPACE}

• Arrow keys: {LEFT} {RIGHT} {UP} {DOWN}

• Navigation: {HOME} {END} {PGUP} {PGDN}

• Function keys: {F1} {F2} ... {F12}

• Combined: Ctrl+End = "^{END}", Alt+Z = "%z"

IMPORTANT: Modifier prefixes (^%+) apply to the NEXT character or {KEY}. For Alt+Z send "%z" (NOT "{ALT}z" or "Alt+Z").

Args: keys: Keys to send (see syntax above) automation_id: Target element's AutomationId name: Target element's Name control_type: Target element's control type

Send keyboard input to the currently focused element.

Use this AFTER ui_set_focus to avoid re-searching for complex elements like DataGrid that may timeout on repeated searches.

Workflow:

1. ui_set_focus(automation_id="MyElement") # Focus the element

2. ui_send_keys_focused(keys="^{END}") # Send keys without re-search

Key syntax (modifiers are PREFIX characters, special keys in braces):

• ^ = Ctrl, % = Alt, + = Shift

• Alt+Z: "%z" Ctrl+C: "^c" Shift+Tab: "+{TAB}"

• Special: {ENTER} {TAB} {ESC} {DELETE} {BACKSPACE}

• Arrows: {LEFT} {RIGHT} {UP} {DOWN}

• Navigation: {HOME} {END} {PGUP} {PGDN}

• Combined: Ctrl+End = "^{END}", Ctrl+Home = "^{HOME}"

IMPORTANT: For Alt+Z send "%z" (NOT "{ALT}z").

Args: keys: Keys to send (see syntax above)

Send a batch of key sequences in a single call, holding focus throughout.

Solves the race condition where the terminal steals focus between individual send_keys calls. The bridge holds foreground + element focus for the entire batch, sending keys with configurable delay.

Use this for: arrow navigation (20x DOWN), typing sequences, keyboard shortcuts.

Args: keys: List of key strings, each sent separately with delay. Example: ["{DOWN}", "{DOWN}", "{DOWN}"] for 3 arrow presses. automation_id: Target element to focus before sending. delay_ms: Milliseconds between each key (default 50ms).

Click on a UI element.

Note: If app is STOPPED at breakpoint, resume with continue_execution() first.

Tries cached coordinates first (from last ui_get_window_tree call), then falls back to pywinauto element search.

Args: automation_id: AutomationId property name: Element's Name/Title property control_type: Control type

Invoke a UI element using UIA InvokePattern (no mouse movement).

Note: If app is STOPPED at breakpoint, resume with continue_execution() first.

Preferred over ui_click for buttons, menu items, and hyperlinks because it works reliably even when the element is off-screen or partially obscured. Falls back to Click() if InvokePattern is not supported.

Args: automation_id: AutomationId property name: Element's Name/Title property control_type: Control type (Button, MenuItem, Hyperlink, etc.) root_id: Optional AutomationId to scope search to a subtree xpath: Optional XPath expression (FlaUI backend only)

Toggle a CheckBox or ToggleButton using UIA TogglePattern.

Returns the new toggle state after the operation: "On", "Off", or "Indeterminate". Use this instead of ui_click for checkboxes to get reliable state feedback.

Note: If app is STOPPED at breakpoint, resume with continue_execution() first.

Args: automation_id: AutomationId property name: Element's Name/Title property control_type: Control type (CheckBox, ToggleButton, etc.) root_id: Optional AutomationId to scope search to a subtree xpath: Optional XPath expression (FlaUI backend only)

Complete a standard Windows Open/Save file dialog in a single call.

Enters the file path and clicks the accept button. Handles the standard Win32 dialog layout (File name ComboBox + Open/Save button) with multi-strategy fallback for different dialog variants.

Args: path: Full file path to enter (e.g. "C:/data/test.txt") accept_button: Name of accept button (default "Open", use "Save" for save dialogs)

Click at absolute screen coordinates.

Use with ui_get_window_tree rectangle data when element search fails. Get coordinates from the 'rectangle' field in tree output. Click goes to the center: x = (left + right) / 2, y = (top + bottom) / 2

Args: x: Screen X coordinate y: Screen Y coordinate

Take a screenshot of the debugged application's window.

Returns inline ImageContent (WebP at max_width resolution) directly to your vision pipeline, plus TextContent with metadata and HD file path.

Use this to see the actual UI state — what the user would see.

Useful for:

• Verifying UI rendered correctly after a debug step

• Finding elements that don't appear in the automation tree

• Understanding visual layout and spacing

• Debugging rendering issues

Note: If app is STOPPED at breakpoint, resume with continue_execution() first.

Args: max_width: Maximum image width. Default 1280; max useful is 1568. format: Image format: "webp" (smallest), "jpeg", "png"

Take a screenshot with numbered UI elements overlaid (Set-of-Mark pattern).

Returns annotated WebP image + compact element index. Each interactive element gets a numbered label on the screenshot.

Use ui_click_annotated(element_id) to interact with elements by number.

Args: max_depth: How deep to traverse the UI tree (default 3) interactive_only: Only interactive elements (default True) max_width: Max image width (default 1024) format: Image format: "webp" (smallest), "jpeg", "png" compact: Compact element index — id+name only (default True, saves ~60KB)

Click an element by its ID from ui_take_annotated_screenshot.

Uses the numbered element from the last annotated screenshot. Call ui_take_annotated_screenshot first to get element IDs.

Args: element_id: Element ID number from the annotated screenshot generation: Generation counter from the screenshot response (optional, warns if stale)

Select items by index in a list/grid control (DataGrid, ListView, ListBox).

With FlaUI backend: uses SelectionItemPattern (reliable for virtualized lists). With pywinauto backend: two strategies (tries both):

1. UIA SelectionItemPattern — works for non-virtualized lists

2. Coordinate click fallback — clicks items using cached rectangles (Ctrl+click for multi-select, plain click for first item)

For WPF virtualized lists (VirtualizingStackPanel), strategy 1 may fail because off-screen items don't have UI containers. Strategy 2 uses visible item coordinates from the cache. FlaUI backend handles this natively.

Args: automation_id: AutomationId of the list/grid control indices: List of 0-based item indices to select mode: "replace" (clear existing, select these) or "add" (add to existing selection)

Right-click on a UI element to open context menu.

Tries cached coordinates first, then falls back to pywinauto element search.

Note: If app is STOPPED at breakpoint, resume with continue_execution() first.

Args: automation_id: AutomationId property name: Element's Name/Title property control_type: Control type

Double-click on a UI element.

Tries cached coordinates first, then falls back to pywinauto element search.

Note: If app is STOPPED at breakpoint, resume with continue_execution() first.

Args: automation_id: AutomationId property name: Element's Name/Title property control_type: Control type

Scroll a UI control.

Note: If app is STOPPED at breakpoint, resume with continue_execution() first.

Args: automation_id: AutomationId of the scrollable control direction: "up", "down", "left", "right" amount: Number of scroll units (default 3)

Drag from one position to another.

Two modes:

1. By AutomationId: from_automation_id + to_automation_id (uses cached rectangles)

2. By coordinates: from_x, from_y, to_x, to_y (absolute screen coords)

For mode 1, call ui_get_window_tree first to populate cache.

Args: from_automation_id: Source element AutomationId to_automation_id: Target element AutomationId from_x: Source X coordinate (screen absolute) from_y: Source Y coordinate to_x: Target X coordinate to_y: Target Y coordinate speed_ms: Total drag duration in milliseconds. Minimum 20 ms so the gesture always emits enough waypoints to cross common WPF drag thresholds reliably. hold_modifiers: Optional modifier names to hold for the full drag. Accepted values: ctrl, shift, alt, win.

Notes: - Identical from/to coordinates are rejected. - Short drags that stay below the system drag threshold should use ui_click instead of ui_drag.

Send a supported system event through the active UI backend.

Hold modifiers across subsequent UI input calls.

Release held modifiers or all held modifiers.

Inspect currently held modifiers.

Get the currently selected item in a list/grid control.

Returns the selected item's name, index, and properties. Useful for verifying selection state after clicks or keyboard navigation.

Note: FlaUI backend returns selection for the first item only. Use ui_find_element to inspect individual items for full multi-selection state.

Args: automation_id: AutomationId of the list/grid/combobox control root_id: Optional AutomationId to scope search to a subtree xpath: Optional XPath expression (FlaUI backend only)

Read text content from a UI element using multi-strategy extraction.

Tries 5 strategies in order: ValuePattern → TextPattern → Name → LegacyIAccessible → visible text descendants. The response includes which strategy provided the text (source field).

When the primary text looks like a CLR type name (e.g., "Namespace.Class"), automatically falls back to visible descendant text.

Args: automation_id: AutomationId property name: Element's Name/Title property root_id: Optional AutomationId to scope search to a subtree xpath: Optional XPath expression (FlaUI backend only)

Get information about the currently focused UI element.

Returns the focused element's automationId, name, controlType, and value. Useful for verifying focus state after ui_set_focus or tab navigation.

Note: Returns focus within the app window, not always OS-level dialogs.

Wait for a UI element to appear within timeout.

Polls every 500ms until the element is found or timeout expires. Useful for waiting for dialogs, popups, or dynamically created elements.

Args: automation_id: AutomationId to wait for name: Element name to wait for control_type: Control type to wait for timeout: Maximum wait time in seconds (default 5) root_id: Optional AutomationId to scope search to a subtree xpath: Optional XPath expression (FlaUI backend only)

Close a top-level window via WindowPattern.

After closing, subsequent ui_* calls return an error if the closed window was the active session window. Use window_title to target a specific window (e.g. a modal dialog); omit to close the main application window.

Args: window_title: Optional partial title match to target a specific window. Omit to target the main connected window.

Maximize a top-level window via WindowPattern.

Args: window_title: Optional partial title match. Omit to target main window.

Minimize a top-level window via WindowPattern.

Args: window_title: Optional partial title match. Omit to target main window.

Restore a minimized or maximized window to normal state via WindowPattern.

Args: window_title: Optional partial title match. Omit to target main window.

Move a window to screen coordinates (x, y) via TransformPattern.

Returns {moved: false, reason: "..."} if the window cannot be moved (CanMove = false). Does NOT raise an exception in that case.

Args: x: Target screen X coordinate for the window's top-left corner. y: Target screen Y coordinate for the window's top-left corner. window_title: Optional partial title match. Omit to target main window.

Resize a window to the given dimensions via TransformPattern.

Returns {resized: false, reason: "..."} if the window cannot be resized (CanResize = false). Does NOT raise an exception in that case.

Args: width: Target window width in pixels. height: Target window height in pixels. window_title: Optional partial title match. Omit to target main window.

Expand a TreeView node, ComboBox dropdown, or other collapsible element.

Uses ExpandCollapsePattern. Expanding an already-expanded element is safe and returns {expanded: true, was_already: true}.

Args: automation_id: AutomationId of the element to expand.

Collapse a TreeView node, ComboBox dropdown, or other collapsible element.

Uses ExpandCollapsePattern. Collapsing an already-collapsed element is safe and returns {collapsed: true, was_already: true}.

Args: automation_id: AutomationId of the element to collapse.

Set a numeric value on a slider, spinner, or progress bar via RangeValuePattern.

Returns {set: false, reason: "value X out of range [min..max]"} if the value is outside the element's Min/Max bounds — does NOT raise an exception.

Args: automation_id: AutomationId of the RangeValue element (slider, spinner, etc.) value: The numeric value to set. Must be within element's [Minimum, Maximum].

Read text content from the system clipboard.

Executes on an STA thread inside the FlaUI bridge (required by System.Windows.Clipboard). Returns {text: "...", has_text: bool}.

Write text to the system clipboard.

Executes on an STA thread inside the FlaUI bridge (required by System.Windows.Clipboard). Supports full Unicode including emoji and CJK.

Args: text: The text to write to the clipboard.

Realize a virtualized list or grid item so it enters the visual tree.

Virtualized lists (VirtualizingStackPanel with VirtualizationMode=Recycling) only create UI elements for visible rows. Items outside the viewport are "virtualized" — they exist in the data source but have no AutomationElement. This tool forces the item into the visual tree so subsequent ui_click or ui_find_element calls can reach it.

Operation is idempotent: re-realizing an already-realized item is safe and returns {realized: true} without error.

Returns: {realized: true, element_id: "...", bounding_rect: {x, y, width, height}} on success. {realized: false, reason: "item not found"} if the item is not in the data source. {realized: false, reason: "container does not support ItemContainerPattern"} if the container is not a virtualizing list.

Args: container_automation_id: AutomationId of the list/grid container. prop_name: Property to search by. Supported: "AutomationId", "Name", "ClassName". value: Value to match against the chosen property.

Send keys while holding modifiers and report cleanup evidence.

Read, select, or assert WPF DataGrid row evidence.

Read selected UI fields without dumping the full tree.