designer_action Reference

10.1.5 additions to designer_action and related DesignerMCP tools — new build action parameters, compile feedback on write/read responses, and a context_menu action for grid right-click verification.

AI Integration → designer_action Reference

designer_action('build', …) — new parameters

The build action invokes the same pipeline as the Designer "Build and Publish" dialog. In 10.1.5 it accepts a rebuild_all parameter mirroring the dialog's Rebuild All checkbox, and a comment parameter that annotates the build-history entry.

designer_action(
  action:        "build",            // the verb (required)
  options:       str  = null,        // the verb's argument; unused by 'build'
  rebuild_all:   bool = false,       // false = incremental, true = full rebuild
  comment:       str  = null,        // free-text note recorded in build history
  solution_id:   str  = null,        // REQUIRED routing key (see below)
  solution_name: str  = null         // fallback address by solution name
) -> { build: <block> }
      

These are the parameters of the designer_action tool as a whole; rebuild_all and comment apply only to the build action and are ignored by every other verb.

There is no validate_displays parameter. Display validation renders every XAML display during the build, which takes minutes, so it remains a user-only operation in the Build and Publish dialog and is not exposed on the MCP surface. A build issued through designer_action always compiles the Scripts tables and DisplaysList code-behind on the standard pipeline.

The response is the shared build block. See MCP SDK Reference for the full shape.

# Fast path during iterative development
designer_action('build', solution_id=SID)
# == designer_action('build', rebuild_all=false, solution_id=SID)

# Pre-deploy check - recompile everything
designer_action('build', rebuild_all=true, solution_id=SID)

# Annotate the build history entry
designer_action('build', rebuild_all=true, comment='pre-release smoke', solution_id=SID)

# SID is the solution_id returned by open_solution / create_solution.
# Where that id has been invalidated, address the session by name instead:
designer_action('build', solution_name='MyPlantSolution')
      

write_objects — per-row compile field

When a write_objects call touches a row in one of the four affected tables (ScriptsTasks, ScriptsClasses, ScriptsExpressions, DisplaysList), the response entry for that row carries a compile field populated from the save-time incremental compile.

{
  "results": [
    {
      "table": "ScriptsTasks",
      "name":  "Line1_Cycle",
      "status": "written",
      "compile": {
        "status": "error",
        "diagnostics": [
          { "line": 12, "msg": "The name 'tagx' does not exist in the current context" }
        ]
      }
    },
    {
      "table": "ScriptsClasses",
      "name":  "TankUtils",
      "status": "written",
      "compile": { "status": "ok", "diagnostics": [] }
    }
  ]
}
      

Writes to rows outside the four affected tables carry no compile field — those objects do not participate in the .NET compile pipeline.

The row-level compile reports only what the incremental pipeline saw for that single object. Cross-object breakage — for example, an edit to a ScriptsClasses row that breaks a ScriptsTasks row referencing it — is surfaced by a subsequent designer_action('build') call, not by the write response alone.

get_objects(detail='full') — lastCompile field

When get_objects is called with detail='full' against one of the four affected tables, each returned row carries a lastCompile field holding the most recent compile result for that object.

{
  "table": "ScriptsTasks",
  "name":  "Line1_Cycle",
  "code":  "...",
  "lastCompile": {
    "status": "ok",
    "at":     "2026-04-21T16:02:11Z",
    "diagnostics": []
  }
}
      

Calls with detail='summary' or the default detail level do not include lastCompile — it is only emitted on the full-detail path to keep the summary response compact.

SolutionContext / RefreshContext — build_state section

The context packages returned to the agent on connect and on refresh now include a compact build_state section. This gives the agent a one-shot view of compile health without needing to call designer_action('build') at session start.

{
  "build_state": {
    "built":     42,
    "failed":    1,
    "skipped":   0,
    "timestamp": "2026-04-21T16:02:11Z"
  }
}
      

The fields match the summary portion of the shared build block. Per-object diagnostics are not included here — callers that need them issue designer_action('build') or get_objects(detail='full') on the affected table.

designer_action('context_menu', …) — grid right-click verification

The context_menu action drives a row's right-click context menu through the same UI surface a Designer operator would use. It serves automated verification workflows that previously had to flag MANUAL-QA-BENCH-REQUIRED for any menu-driven step (Tag editor rows, Security Secrets, Devices / Datasets grids, and every other table whose row carries actions accessible only via right-click).

Two modes, discriminated by the presence of a | separator in the options string:

# Inspect: list the items the context menu would show for this row.
designer_action('context_menu', '<TableType>.<RowName>', solution_id=SID)
# Invoke: fire the named menu item on this row.
designer_action('context_menu', '<TableType>.<RowName>|<MenuAction>', solution_id=SID)
      

Inspect form

Returns the snapshot of the menu items after the page's ContextMenu.Opened gates fire against the selected row. Items reflect the post-gate state, so visibility and enablement match what a user would see on right-click.

{
  "mode": "inspect",
  "table": "SecuritySecrets",
  "row":   "AdminPass",
  "items": [
    { "header": "Copy SecretValue to clipboard",
      "tag":    "TDEV1412_CopySecretValue",
      "isEnabled": true,
      "isVisible": true }
  ]
}
      

Invoke form

Matches MenuAction against MenuItem.Tag first (case-sensitive — Tags are programmer-set stable identifiers), then against Header text (case-insensitive). Fires RaiseEvent(MenuItem.ClickEvent) on the matched item; the response carries any error the Click handler raised.

{
  "mode": "invoke",
  "table": "SecuritySecrets",
  "row":   "AdminPass",
  "match": { "matchedBy": "tag", "tag": "TDEV1412_CopySecretValue" },
  "status": "ok"
}
      

Prefer Tag matching for stable AI scripts — Header text often carries localization or accelerator markers that drift release to release. Tags are author-set in code-behind and stay stable across cosmetic UI changes.

Page coverage (v1)

v1 wires only pages that expose the canonical GridControlObj element name — every W3ContentsControl-derived grid (Tags, Devices, Alarms, Datasets, Security, Reports, etc.). Display editors and the project tree return PAGE_NOT_SUPPORTED; future releases extend the verb's surface area.

Error Codes

list_wizard_options and pick_wizard_variant — wizard symbols

These two paired tools drive the five wizard symbols — BLOWER, MOTOR, PUMP, TANK, VALVE. Each is a parameterized graphical symbol whose appearance is assembled from named segments (appearance, orientation, feet, output, and others depending on the symbol). They have nothing to do with solution templates: list_wizard_options reports the legal option values for one symbol type, and pick_wizard_variant resolves a set of chosen options to a concrete variant and applies it to the open solution.

Flow

1. Call list_wizard_options with the symbol type. It returns segments[] (each with name, label, and legal options[]), constraints[] (cross-segment guards), defaultVariant, and labelContract. This is pure data — no Designer session is required.
2. Call pick_wizard_variant with the same symbol type and a JSON option map. The platform applies the cross-segment constraints, resolves the canonical variant name, verifies it exists in the library, and writes the symbol into DisplaysSymbols.
3. Omitting target_symbol_name creates a new symbol instance, auto-named PUMP1, PUMP2, and so on. Supplying it replaces the variant of that existing symbol in place.

# 1. Discover the segment/option taxonomy for one symbol type
list_wizard_options(wizard_type='PUMP')
# -> { segments: [ { name: "appearance", label: "Appearance",
#                    options: [...] }, ... ],
#      constraints: [...], defaultVariant: "...", labelContract: {...} }

# 2. Create a new PUMP symbol with the chosen options
pick_wizard_variant(
  wizard_type='PUMP',
  options='{"appearance":"Detailed","orientation":"Right","feet":"None","output":"Top"}',
  solution_id=SID)
# -> a new symbol (PUMP1, PUMP2, ...) in DisplaysSymbols

# 3. Or replace the variant of a symbol that already exists
pick_wizard_variant(
  wizard_type='PUMP',
  options='{"appearance":"Simple","orientation":"Left"}',
  target_symbol_name='PUMP1',
  solution_id=SID)
      

Option values accept either the human label (Detailed) or the canonical token (DET), and any segment left out of the map falls back to that wizard's default. The options argument is a JSON object passed as a string; any other JSON shape is rejected with INVALID_OPTIONS_SHAPE, and an unrecognized symbol type with INVALID_WIZARD_TYPE plus the list of valid ones.

pick_wizard_variant writes to the solution — it is not read-only. The symbol lands in DisplaysSymbols; placing it on a Display is a separate DisplaysList write. list_wizard_options writes nothing and can be called safely at any time. Note that pick_wizard_variant is DesignerMCP-only in this release; the ConsoleMCP surface returns DESIGNER_MCP_ONLY.

set_object_value — live Object Model write

set_object_value writes a single row in the live Object Model — a tag value, an attribute, or any other runtime-writable object exposed under the 12 Object Model roots. It is distinct from write_objects: write_objects targets the solution's configuration tables (Tags, Devices, ScriptsTasks, etc., as authored in Designer), while set_object_value targets live runtime state on the connected solution.

Use set_object_value when an AI workflow needs to drive a control loop, exercise a tag-bound dynamic, or seed runtime state for a smoke test against a running solution. Use write_objects when the change should land in the saved solution and survive a restart.

# Drive a live tag value in the running runtime.
# The path is 'path', and the value is always passed as a string -
# the kernel coerces it to the target object's actual type.
set_object_value(path="Tag.Plant1/Line1/Setpoint", value="72.5", solution_id=SID)

# Booleans use the string forms 'true' / 'false'
set_object_value(path="Tag.Pump1.Running", value="true", solution_id=SID)
      

The runtime equivalent on the RuntimeMCP surface carries the same tool name — see Runtime MCP Reference. On the DesignerMCP surface, set_object_value requires a runtime to be bound to the active Designer session; calls against a solution that has no running runtime return an error.

Error Codes

In this section...