MAUI

Install

For a MAUI app that wants the standard setup, install the all-in-one MAUI package:

dotnet add package Ansight.Maui --prerelease

Install the tool package directly only when you are using Ansight.Core and registering tool suites yourself:

dotnet add package Ansight.Tools.Maui --prerelease

Register the Suite

using Ansight;
using Ansight.Tools.Maui;

var options = Options.CreateBuilder()
    .WithMauiTools()
    .WithReadWriteToolAccess()
    .Build();

Use WithReadOnlyToolAccess() for page, tree, element, binding, resource, navigation, layout, handler, and binding-context inspection. Use WithReadWriteToolAccess() only when a workflow needs mutation, XAML experiments, app theme changes, or app-code invocation.

Registration API

• WithMauiTools(): registers the full .NET MAUI tool suite. No suite-specific configuration is currently required.

Specific Concerns

• The suite runs on the MAUI main thread and inspects the active MAUI Application window.
• maui.get_visual_tree and maui.find_elements return MAUI element ids that can be passed to focused element, property, binding, layout, handler, action, wait, XAML experiment, and binding-context tools.
• Element ids are runtime ids. Prefer AutomationId when you need stable lookup across sessions.
• maui.get_bindable_property, maui.get_bindings, and maui.get_binding_context can reveal user-entered text and app state.
• maui.get_resource_state can reveal resource keys and, when requested, shallow resource values.
• maui.invoke_element_action and maui.invoke_binding_context_command can execute app code.
• maui.inflate_xaml creates detached MAUI elements from arbitrary XAML. Use maui.add_element and maui.remove_element to attach or detach those elements.
• maui.set_app_theme changes Application.Current.UserAppTheme at runtime.
• maui.set_bindable_property, maui.clear_bindable_property, maui.add_element, maui.remove_element, maui.set_app_theme, and maui.set_binding_context_property mutate live UI, theme, or view-model state.
• The suite is supported on Android, iOS, and Mac Catalyst MAUI targets.

Tool Matrix

Core Inspection

Get Current MAUI Page

Arguments: none.

Returns platform, capturedAtUtc, windowCount, window, rootPage, currentPage, and navigation.

{
  "toolId": "maui.get_current_page",
  "arguments": {}
}

Get MAUI Visual Tree

Arguments:

• root: currentPage, rootPage, or window; default currentPage
• rootNodeId: optional node id or AutomationId to use as the subtree root
• includeBounds: include MAUI layout bounds; default true
• includeProperties: include common element properties; default false
• includeBindableProperties: include bindable-property metadata; default false
• includeBindingContexts: include binding-context type metadata; default false
• maxDepth: child depth limit; default 8
• maxNodes: maximum nodes before truncation; default 500

{
  "toolId": "maui.get_visual_tree",
  "arguments": {
    "root": "currentPage",
    "includeBounds": true,
    "includeBindingContexts": true,
    "maxDepth": 6
  }
}

Find MAUI Elements

Searches without returning the whole tree.

Common filters:

• nodeId, automationId, styleId, classId
• typeName, kind, labelContains, bindingContextTypeName
• visible, enabled
• propertyName and optional propertyValueJson
• root, rootNodeId, maxDepth, maxResults

{
  "toolId": "maui.find_elements",
  "arguments": {
    "automationId": "LoginEmailEntry",
    "includeBounds": true
  }
}

Get MAUI Element

Arguments:

• nodeId: required node id or AutomationId
• includeBounds, includeProperties, includeBindableProperties, includeBindingContext, includeChildren

{
  "toolId": "maui.get_element",
  "arguments": {
    "nodeId": "LoginEmailEntry",
    "includeBindableProperties": true
  }
}

Bindable Properties

Get Bindable Property

Arguments:

• nodeId: required node id or AutomationId
• propertyName: required bindable property name, such as Text or TextProperty
• declaringTypeName: optional declaring type name

{
  "toolId": "maui.get_bindable_property",
  "arguments": {
    "nodeId": "LoginEmailEntry",
    "propertyName": "Text"
  }
}

Set Bindable Property

Arguments:

• nodeId: required node id or AutomationId
• propertyName: required bindable property name
• declaringTypeName: optional declaring type name
• valueJson: required new value encoded as JSON

{
  "toolId": "maui.set_bindable_property",
  "arguments": {
    "nodeId": "LoginEmailEntry",
    "propertyName": "Text",
    "valueJson": "\"person@example.com\""
  }
}

Clear Bindable Property

Arguments:

• nodeId: required node id or AutomationId
• propertyName: required bindable property name
• declaringTypeName: optional declaring type name
• mode: value, binding, or both; default both

{
  "toolId": "maui.clear_bindable_property",
  "arguments": {
    "nodeId": "StatusLabel",
    "propertyName": "Text",
    "mode": "both"
  }
}

Runtime UI Mutation

Inflate XAML

Arguments:

• xaml: required MAUI XAML markup to inflate with LoadFromXaml
• rootTypeName: optional CLR type name to instantiate before loading XAML

Returns a retained detached element id that can be passed to maui.add_element.

{
  "toolId": "maui.inflate_xaml",
  "arguments": {
    "xaml": "<Label xmlns=\"http://schemas.microsoft.com/dotnet/2021/maui\" Text=\"Experiment\" />"
  }
}

Add Element

Arguments:

• parentNodeId: required live parent node id or AutomationId
• elementNodeId: required node id returned by maui.inflate_xaml, a live node id, or an AutomationId
• index: optional insertion index for layout children
• replaceContent: replace an existing Content value when adding to a content control; default false
• detachFromCurrentParent: detach the element from its current parent before adding it; default false

{
  "toolId": "maui.add_element",
  "arguments": {
    "parentNodeId": "ExperimentHost",
    "elementNodeId": "82c2f357a0a64d5f9e6f1cb3b47e7b24",
    "detachFromCurrentParent": true
  }
}

Remove Element

Arguments:

• nodeId: required node id returned by the visual tree, maui.inflate_xaml, or an AutomationId
• forget: forget a retained inflated element after detaching it; default false

{
  "toolId": "maui.remove_element",
  "arguments": {
    "nodeId": "82c2f357a0a64d5f9e6f1cb3b47e7b24",
    "forget": true
  }
}

Set App Theme

Arguments:

• theme: required system, light, or dark; system clears the override and follows the device/app default

The tool sets Application.Current.UserAppTheme and returns the previous and current UserAppTheme and effective RequestedTheme values.

{
  "toolId": "maui.set_app_theme",
  "arguments": {
    "theme": "dark"
  }
}

Binding Diagnostics

Get Binding Context

Arguments:

• nodeId: required node id or AutomationId
• includeProperties: include public property snapshots; default false
• maxDepth: object graph depth limit; default 1, maximum 4
• maxProperties: public property limit per object; default 32

{
  "toolId": "maui.get_binding_context",
  "arguments": {
    "nodeId": "LoginPage",
    "includeProperties": true,
    "maxDepth": 1
  }
}

Get MAUI Bindings

Arguments:

• nodeId: required node id or AutomationId
• propertyName: optional bindable property name
• includeUnbound: include properties without active bindings; default false
• includeValues: include current target values; default false
• maxProperties: maximum bindable properties to inspect; default 32

{
  "toolId": "maui.get_bindings",
  "arguments": {
    "nodeId": "LoginEmailEntry",
    "includeValues": true
  }
}

App State Diagnostics

Get MAUI Resource State

Arguments:

• nodeId: optional node id or AutomationId
• scope: effective, application, window, page, or element; default effective
• includeValues: include shallow value snapshots; default false
• includeMergedDictionaries: include merged dictionary summaries; default true
• maxEntries: maximum entries per dictionary; default 16

{
  "toolId": "maui.get_resource_state",
  "arguments": {
    "nodeId": "LoginPage",
    "scope": "effective",
    "includeMergedDictionaries": true
  }
}

Get MAUI Navigation State

Arguments:

• includeWindows: include all application windows; default true
• includeShellItems: include Shell item, section, and content summaries; default true

{
  "toolId": "maui.get_navigation_state",
  "arguments": {
    "includeShellItems": true
  }
}

Get Layout Diagnostics

Arguments:

• nodeId: required node id or AutomationId

{
  "toolId": "maui.get_layout_diagnostics",
  "arguments": {
    "nodeId": "SubmitButton"
  }
}

Get Handler Diagnostics

Arguments:

• nodeId: required node id or AutomationId
• includePlatformViewProperties: include shallow native platform-view public property snapshots; default false
• maxProperties: platform-view property limit; default 32

{
  "toolId": "maui.get_handler_diagnostics",
  "arguments": {
    "nodeId": "SubmitButton",
    "includePlatformViewProperties": false
  }
}

Actions And Waiting

Invoke Element Action

Arguments:

• nodeId: required node id or AutomationId
• action: focus, unfocus, executeCommand, invokeTap, toggle, setText, or selectPickerItem
• commandName: command property name for executeCommand; default Command
• parameterJson: optional command parameter encoded as JSON
• valueJson: required by setText and selectPickerItem
• requireCanExecute: fail when a command returns false from CanExecute; default true

{
  "toolId": "maui.invoke_element_action",
  "arguments": {
    "nodeId": "SubmitButton",
    "action": "executeCommand"
  }
}

Wait For MAUI UI

Arguments:

• condition: elementExists, elementVisible, propertyEquals, currentPage, or bindingContextPropertyEquals
• timeoutMs: default 5000
• pollIntervalMs: default 100
• nodeId, automationId, typeName, labelContains
• propertyName and expectedJson for value conditions
• root and maxDepth for element searches

{
  "toolId": "maui.wait_for_ui",
  "arguments": {
    "condition": "elementVisible",
    "automationId": "SubmitButton",
    "timeoutMs": 5000
  }
}

Binding Context Mutation

Invoke Binding Context Command

Arguments:

• nodeId: required node id or AutomationId
• commandName: public ICommand property name; Command suffix is optional
• parameterJson: optional command parameter encoded as JSON
• requireCanExecute: fail when the command returns false from CanExecute; default true

{
  "toolId": "maui.invoke_binding_context_command",
  "arguments": {
    "nodeId": "LoginPage",
    "commandName": "SubmitCommand"
  }
}

Set Binding Context Property

Arguments:

• nodeId: required node id or AutomationId
• propertyName: writable public binding-context property name
• valueJson: required new value encoded as JSON

{
  "toolId": "maui.set_binding_context_property",
  "arguments": {
    "nodeId": "LoginPage",
    "propertyName": "Email",
    "valueJson": "\"person@example.com\""
  }
}