Add resource command arguments and visibility by davidfowl · Pull Request #16710 · microsoft/aspire

davidfowl · 2026-05-03T16:41:45Z

Description

Adds resource command argument metadata and command visibility support across hosting, dashboard, CLI, MCP, and polyglot code generation.

This change:

flows command InteractionInput metadata through resource snapshots, dashboard service contracts, JSON resource output, and the auxiliary backchannel
exposes submitted command arguments to handlers as a non-null InteractionInputCollection, matching the interaction service result model
keeps JSON/protobuf handling in the CLI, dashboard, MCP, and auxiliary backchannel transport layers instead of exposing raw JSON on the command API
adds typed C# convenience accessors on InteractionInputCollection for common command argument reads (GetString, GetBoolean, GetInt32, GetDouble) and a TypeScript intrinsic with idiomatic helpers (toArray, get, required, value, requiredValue)
adds CLI forwarding for ordered loose command arguments; the AppHost maps those values onto declared CommandOptions.Arguments by order and performs validation centrally
adds built-in and custom command argument validation that flows field errors back to Dashboard interactions, CLI, MCP, and auxiliary backchannel callers without invoking the command callback
adds command visibility metadata so commands can be exposed to dashboard clients, API clients, or both
updates polyglot SDK snapshots and RemoteHost scanner coverage for the new command option surface
preserves the previously shipped ResourceCommandAnnotation constructor for compatibility
adds Stress playground command samples that exercise common and less common API usage end-to-end

API sample from the Stress playground common command:

serviceBuilder.WithCommand(
    name: "echo-arguments",
    displayName: "Echo arguments",
    executeCommand: context =>
    {
        var arguments = ReadEchoCommandArguments(context.Arguments);
        var message = arguments.Shout ? arguments.Message!.ToUpperInvariant() : arguments.Message!;
        var payload = new
        {
            arguments.Message,
            arguments.Repeat,
            arguments.Shout,
            arguments.Flavor,
            SecretLength = arguments.Secret?.Length ?? 0,
            Echoed = Enumerable.Repeat(message, arguments.Repeat).ToArray()
        };

        return Task.FromResult(CommandResults.Success(
            "Echoed command arguments.",
            new CommandResultData
            {
                Value = JsonSerializer.Serialize(payload),
                Format = CommandResultFormat.Json,
                DisplayImmediately = true
            }));
    },
    commandOptions: new CommandOptions
    {
        Description = "Common dashboard/API command with text, number, boolean, choice, and secret argument inputs.",
        IconName = "Code",
        Arguments =
        [
            new InteractionInput { Name = "message", Label = "Message", InputType = InputType.Text, Required = true, MaxLength = 80 },
            new InteractionInput { Name = "repeat", Label = "Repeat", InputType = InputType.Number, Value = "1" },
            new InteractionInput { Name = "shout", Label = "Shout", InputType = InputType.Boolean, Value = "false" },
            new InteractionInput
            {
                Name = "flavor",
                Label = "Flavor",
                InputType = InputType.Choice,
                Value = "vanilla",
                Options =
                [
                    KeyValuePair.Create("vanilla", "Vanilla"),
                    KeyValuePair.Create("chocolate", "Chocolate"),
                    KeyValuePair.Create("strawberry", "Strawberry")
                ]
            },
            new InteractionInput { Name = "secret", Label = "Secret", InputType = InputType.SecretText }
        ]
    });

static EchoCommandArguments ReadEchoCommandArguments(InteractionInputCollection arguments)
{
    return new EchoCommandArguments
    {
        Message = arguments.GetString("message"),
        Repeat = arguments.GetInt32("repeat"),
        Shout = arguments.GetBoolean("shout"),
        Flavor = arguments.GetString("flavor") ?? "vanilla",
        Secret = arguments.GetString("secret")
    };
}

Custom command argument validation uses the same pattern as interaction input validation. Built-in validation runs first (required, max length, choice membership, boolean, and number parsing). Interactive Dashboard execution prompts through the AppHost interaction service, so validation keeps the input dialog open with field errors. CLI/MCP execute non-interactively and receive structured argument errors:

commandOptions: new CommandOptions
{
    Arguments =
    [
        new InteractionInput { Name = "target", Label = "Target", InputType = InputType.Text, Required = true }
    ],
    ValidateArguments = context =>
    {
        var target = context.Inputs.GetString("target");
        if (string.Equals(target, "prod", StringComparison.OrdinalIgnoreCase))
        {
            context.AddValidationError("target", "Target must not be prod.");
        }

        return Task.CompletedTask;
    }
}

TypeScript AppHosts get the same command argument API with idiomatic JavaScript conversion instead of C#-style GetInt32 helpers. ExecuteCommandContext.arguments and InputsDialogValidationContext.inputs are generated as async getter methods, so await context.arguments() returns command arguments and await context.inputs() returns validation inputs:

import {
    InputsDialogValidationContext,
    ExecuteCommandContext,
    InputType
} from './.modules/aspire.js';

const cache = await builder.addRedis("cache");

await cache.withCommand(
    "set-prefix",
    "Set prefix",
    async (context: ExecuteCommandContext) => {
        const args = await context.arguments();
        const prefix = await args.requiredValue("prefix");
        const count = Number(await args.requiredValue("count"));

        return {
            success: true,
            message: `Validated prefix '${prefix}' with count ${count}.`
        };
    },
    {
        commandOptions: {
            description: "Validates ordered command arguments from the CLI and Dashboard.",
            arguments: [
                {
                    name: "prefix",
                    label: "Prefix",
                    inputType: InputType.Text,
                    required: true,
                    maxLength: 20
                },
                {
                    name: "count",
                    label: "Count",
                    inputType: InputType.Number,
                    required: true
                }
            ],
            validateArguments: async (context: InputsDialogValidationContext) => {
                const args = await context.inputs();
                const prefix = await args.requiredValue("prefix");
                const count = Number(await args.requiredValue("count"));

                if (prefix.toLowerCase() === "bad") {
                    await context.addValidationError("prefix", "Prefix cannot be 'bad'.");
                }

                if (!Number.isFinite(count) || count < 1) {
                    await context.addValidationError("count", "Count must be greater than or equal to 1.");
                }
            }
        }
    });

The TypeScript InteractionInputCollection wrapper caches the backing input array and exposes:

const args = await context.arguments();
const allInputs = await args.toArray();
const maybePrefix = await args.value("prefix");
const prefixInput = await args.required("prefix");
const prefix = await args.requiredValue("prefix");

Getter-only fluent APIs can now be chained naturally in TypeScript. The generated promise wrapper remains awaitable, so both styles work:

await ctx.environment().set("API_ENDPOINT", refExpr`${endpoint}`);

const environment = await ctx.environment();
await environment.set("API_ENDPOINT", refExpr`${endpoint}`);

CLI resource command arguments are passed as ordered values, not matched by input name. For example, the echo-arguments sample can be invoked as:

aspire resource stress-apiservice echo-arguments "Hello E2E" 2 true chocolate sauce --apphost playground/Stress/Stress.AppHost/Stress.AppHost.csproj

The CLI captures loose/overflow tokens in order and sends them as a JSON array over the auxiliary backchannel. CLI/MCP execute non-interactively so missing or invalid arguments fail fast with structured errors. Dashboard command execution leaves argument prompting to the AppHost interaction service, which renders the standard inputs dialog in the Dashboard and supports server-side validation/dynamic updates.

The Stress playground also includes:

echo-command-arguments: small API-only primitive argument command using ResourceCommandVisibility.Api
validate-arguments: validation/failure command using required inputs, defaults, choices, custom argument validation, and structured JSON failures
argument-stress-test: minor dashboard/API stress command with 23 argument inputs to exercise metadata, rendering, submission, and payload handling

Fixes # (issue)

Checklist

Is this feature complete?
- Yes. Ready to ship.
- No. Follow-up changes expected.
Are you including unit tests for the changes and scenario tests if relevant?
- Yes
- No
Did you add public API?
- Yes
  - If yes, did you have an API Review for it?
    - Yes
    - No
  - Did you add <remarks /> and <code /> elements on your triple slash comments?
    - Yes
    - No
- No
Does the change make any security assumptions or guarantees?
- Yes
  - If yes, have you done a threat model and had a security review?
    - Yes
    - No
- No
Does the change require an update in our Aspire docs?
- Yes
  - Link to aspire.dev issue:
    - New issue
- No

github-actions · 2026-05-03T16:42:05Z

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 16710

Or

Run remotely in PowerShell:

iex "& { $(irm https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 16710"

github-actions · 2026-05-03T18:10:41Z

Re-running the failed jobs in the CI workflow for this pull request because 1 job was identified as retry-safe transient failures in the CI run attempt.
GitHub was asked to rerun all failed jobs for that attempt, and the rerun is being tracked in the rerun attempt.
The job links below point to the failed attempt jobs that matched the retry-safe transient failure rules.

Tests / Hosting-1 / Hosting-1 (windows-latest) - Job-level runner or infrastructure failure matched the transient allowlist.

github-actions · 2026-05-04T02:58:42Z

Re-running the failed jobs in the CI workflow for this pull request because 1 job was identified as retry-safe transient failures in the CI run attempt.
GitHub was asked to rerun all failed jobs for that attempt, and the rerun is being tracked in the rerun attempt.
The job links below point to the failed attempt jobs that matched the retry-safe transient failure rules.

Tests / Hosting-1 / Hosting-1 (windows-latest) - Job-level runner or infrastructure failure matched the transient allowlist.

github-actions · 2026-05-04T07:39:09Z

Re-running the failed jobs in the CI workflow for this pull request because 1 job was identified as retry-safe transient failures in the CI run attempt.
GitHub was asked to rerun all failed jobs for that attempt, and the rerun is being tracked in the rerun attempt.
The job links below point to the failed attempt jobs that matched the retry-safe transient failure rules.

Tests / Hosting-5 / Hosting-5 (windows-latest) - Job-level runner or infrastructure failure matched the transient allowlist.

Copilot

Pull request overview

Adds end-to-end support for resource command argument metadata and command visibility across Aspire Hosting, Dashboard, CLI, auxiliary backchannel, and polyglot SDK generation, including validation flows that return structured field errors without executing the command.

Changes:

Flow command argument definitions (InteractionInput) through snapshots/service contracts/JSON and add InteractionInputCollection accessors for typed reads.
Add command visibility metadata and enforce it in Dashboard (Dashboard-only) and CLI/API discovery (API-visible).
Extend Dashboard/CLI/MCP/backchannel execution paths to submit arguments and receive structured validation errors; update polyglot codegen accordingly.

Show a summary per file

File	Description
tests/Shared/TestDashboardClient.cs	Updates test dashboard client API to include arguments/validate-only parameters.
tests/PolyglotAppHosts/Aspire.Hosting/TypeScript/apphost.ts	Updates TypeScript apphost usage for getter-only promise APIs.
tests/PolyglotAppHosts/Aspire.Hosting.Foundry/TypeScript/apphost.ts	Updates Foundry TypeScript apphost for getter-only promise APIs.
tests/PolyglotAppHosts/Aspire.Hosting.Foundry/Java/AppHost.java	Updates Foundry Java apphost config mutation patterns.
tests/Aspire.Hosting.Tests/ResourceCommandServiceTests.cs	Adds unit tests for argument mapping/validation behavior in Hosting.
tests/Aspire.Hosting.Tests/Dashboard/DashboardServiceTests.cs	Adds dashboard service tests for argument metadata, visibility, and validate-only execution.
tests/Aspire.Hosting.Tests/Backchannel/AuxiliaryBackchannelTests.cs	Updates capability test naming to reflect current capability set.
tests/Aspire.Hosting.Tests/Backchannel/AuxiliaryBackchannelRpcTargetTests.cs	Adds backchannel tests for JSON argument mapping and validate-only validation errors.
tests/Aspire.Hosting.RemoteHost.Tests/AtsCapabilityScannerTests.cs	Updates ATS scanner test expectations for deprecated command option surface.
tests/Aspire.Hosting.EntityFrameworkCore.Tests/EFCoreOperationExecutorTests.cs	Updates EFCore tool command creation for new command constructor parameters.
tests/Aspire.Hosting.CodeGeneration.TypeScript.Tests/Snapshots/transport.verified.ts	Updates TS transport snapshot (including callback marshalling).
tests/Aspire.Hosting.CodeGeneration.TypeScript.Tests/Snapshots/base.verified.ts	Adds TS InteractionInputCollection wrapper and InputType enum snapshot.
tests/Aspire.Hosting.CodeGeneration.TypeScript.Tests/Snapshots/AtsGeneratedAspire.verified.ts	Exports InteractionInputCollection/InputType from generated SDK snapshot.
tests/Aspire.Hosting.CodeGeneration.TypeScript.Tests/AtsTypeScriptCodeGeneratorTests.cs	Adds assertions for generated `arguments()` API surface.
tests/Aspire.Hosting.CodeGeneration.Rust.Tests/Snapshots/TwoPassScanningGeneratedAspire.verified.rs	Updates Rust snapshot for new enums/DTOs and command validation context exposure.
tests/Aspire.Hosting.CodeGeneration.Python.Tests/Snapshots/TwoPassScanningGeneratedAspire.verified.py	Updates Python snapshot for new literals/types and removed init-only setters.
tests/Aspire.Dashboard.Tests/ResourceOutgoingPeerResolverTests.cs	Updates dashboard test mock to new ExecuteResourceCommandAsync signature.
tests/Aspire.Dashboard.Tests/Model/DashboardCommandExecutorTests.cs	Adds tests for dashboard-side argument marshalling behavior.
tests/Aspire.Dashboard.Tests/Integration/Playwright/Infrastructure/MockDashboardClient.cs	Updates Playwright dashboard mock for new command execution signature.
tests/Aspire.Dashboard.Components.Tests/Pages/ConsoleLogsTests.cs	Updates command view model construction to use argument inputs.
tests/Aspire.Dashboard.Components.Tests/Controls/ResourceDetailsTests.cs	Updates command view model construction to use argument inputs.
tests/Aspire.Cli.Tests/TestServices/TestAppHostAuxiliaryBackchannel.cs	Captures backchannel command arguments and call counts for tests.
tests/Aspire.Cli.Tests/Mcp/ExecuteResourceCommandToolTests.cs	Adds MCP tool tests for argument forwarding and validation error formatting.
tests/Aspire.Cli.Tests/Mcp/ApiDocs/ApiDocsIndexServiceTests.cs	Makes test fetcher request tracking thread-safe under concurrency.
tests/Aspire.Cli.Tests/Commands/ResourceCommandTests.cs	Adds CLI tests for forwarding loose/ordered command arguments to backchannel.
tests/Aspire.Cli.Tests/Commands/ResourceCommandHelperTests.cs	Adds CLI helper tests for argument forwarding and validation error display.
tests/Aspire.Cli.Tests/Backchannel/ResourceSnapshotMapperTests.cs	Extends CLI snapshot mapping tests for visibility and argument input metadata.
tests/Aspire.Cli.EndToEnd.Tests/TypeScriptReusablePackageTests.cs	Updates E2E TS snippets for getter-only promise APIs.
src/Shared/Model/Serialization/ResourceJson.cs	Extends shared resource JSON schema with command visibility and argument inputs.
src/Aspire.TypeSystem/AtsCapabilityInfo.cs	Adds callback metadata (signature) to DTO property info.
src/Aspire.Hosting/ResourceBuilderExtensions.cs	Validates command argument metadata and wires new command annotation constructor.
src/Aspire.Hosting/Orchestrator/ParameterProcessor.cs	Updates parameter commands to new command constructor signature.
src/Aspire.Hosting/IInteractionService.cs	Exposes InteractionInput/InteractionInputCollection to ATS and adds typed accessors + ToArray export.
src/Aspire.Hosting/Dashboard/proto/Partials.cs	Filters commands by dashboard visibility and adds argument input DTO mapping.
src/Aspire.Hosting/Dashboard/proto/dashboard_service.proto	Extends gRPC contract with argument inputs/arguments payload and validation-only semantics; deprecates parameter.
src/Aspire.Hosting/Dashboard/DashboardServiceData.cs	Adds argument creation and validate-only execution path with invalid-argument reporting.
src/Aspire.Hosting/Dashboard/DashboardService.cs	Implements argument conversion/validation-only execution and returns structured invalid arguments.
src/Aspire.Hosting/Backchannel/BackchannelDataTypes.cs	Extends auxiliary backchannel request/response and snapshots for args/visibility/validation errors.
src/Aspire.Hosting/Backchannel/AuxiliaryBackchannelRpcTarget.cs	Adds JSON object/array argument mapping, validate-only path, and snapshot argument metadata/visibility.
src/Aspire.Hosting/ApplicationModel/ResourceNotificationService.cs	Flows argument metadata and visibility into resource command snapshots.
src/Aspire.Hosting/ApplicationModel/ResourceCommandService.cs	Adds argument mapping (named+ordered), built-in validation + custom validation callback, and surfaces invalid args.
src/Aspire.Hosting/ApplicationModel/ResourceCommandAnnotation.cs	Adds arguments/visibility/validation callback to command annotation and adds ExecuteCommandContext.Arguments.
src/Aspire.Hosting/ApplicationModel/CustomResourceSnapshot.cs	Extends ResourceCommandSnapshot with arguments and visibility metadata.
src/Aspire.Hosting/ApplicationModel/CommandsConfigurationExtensions.cs	Updates lifecycle commands to new command constructor signature.
src/Aspire.Hosting/ApplicationModel/CommandOptions.cs	Adds command arguments/visibility/validation callback surface; deprecates Parameter.
src/Aspire.Hosting.RemoteHost/AtsCapabilityScanner.cs	Enhances ATS scanning for callbacks and suppresses init-only setters from generated capabilities.
src/Aspire.Hosting.RemoteHost/Ats/AtsMarshaller.cs	Supports DTO deserialization that includes delegate callback properties.
src/Aspire.Hosting.Integration.Analyzers/AspireExportAnalyzer.cs	Avoids generating setters for init-only properties in analyzer.
src/Aspire.Hosting.CodeGeneration.TypeScript/Resources/transport.ts	Marshals functions as callbacks in TS transport layer.
src/Aspire.Hosting.CodeGeneration.TypeScript/Resources/base.ts	Adds TS InputType + InteractionInputCollection wrapper utilities.
src/Aspire.Hosting.CodeGeneration.TypeScript/AtsTypeScriptCodeGenerator.cs	Emits TS callback property types, promise-wrapper chaining for getter-only APIs, and special-cases interaction input types.
src/Aspire.Dashboard/ServiceClient/Partials.cs	Maps gRPC command argument inputs and response invalid inputs into view models.
src/Aspire.Dashboard/ServiceClient/IDashboardClient.cs	Extends dashboard client interface for arguments and validate-only support.
src/Aspire.Dashboard/ServiceClient/DashboardClient.cs	Sends arguments/validate-only flags in ExecuteResourceCommand requests.
src/Aspire.Dashboard/Model/ResourceViewModel.cs	Updates command view model to carry argument input metadata instead of legacy parameter.
src/Aspire.Dashboard/Model/ResourceCommandResponseViewModel.cs	Adds validation-failed kind and carries invalid argument inputs for UI display.
src/Aspire.Dashboard/Model/DashboardCommandExecutor.cs	Adds UI flow to collect arguments, validate-only roundtrip, and execute with submitted args.
src/Aspire.Cli/Mcp/Tools/ListResourcesTool.cs	Extends MCP JSON serialization context for command argument metadata.
src/Aspire.Cli/Mcp/Tools/ExecuteResourceCommandTool.cs	Adds MCP command argument forwarding and formats structured validation errors.
src/Aspire.Cli/JsonSourceGenerationContext.cs	Adds source-gen support for serializing string arrays (ordered args).
src/Aspire.Cli/Commands/ResourceCommandHelper.cs	Adds optional JSON arguments parameter and appends validation errors to error output.
src/Aspire.Cli/Commands/ResourceCommand.cs	Captures unmatched tokens as ordered arguments and forwards them to backchannel execution.
src/Aspire.Cli/Commands/PsCommand.cs	Extends PS command JSON serialization context for argument metadata.
src/Aspire.Cli/Commands/DescribeCommand.cs	Extends describe output JSON serialization context for argument metadata.
src/Aspire.Cli/Backchannel/ResourceSnapshotMapper.cs	Filters commands by API visibility and maps argument inputs/visibility into JSON output.
src/Aspire.Cli/Backchannel/IAppHostAuxiliaryBackchannel.cs	Extends backchannel interface to accept optional command arguments payload.
src/Aspire.Cli/Backchannel/BackchannelJsonSerializerContext.cs	Adds source-gen support for new backchannel types (args + validation errors).
src/Aspire.Cli/Backchannel/AppHostAuxiliaryBackchannel.cs	Sends command arguments over auxiliary backchannel RPC.
playground/TypeScriptAppHost/apphost.ts	Adds sample TS command with arguments + validation callback demonstrating the API.
playground/Stress/Stress.AppHost/AppHost.cs	Adds stress playground commands that exercise argument metadata, visibility, validation, and ordered CLI args.

Copilot's findings

Files reviewed: 73/73 changed files
Comments generated: 2

mitchdenny

5 non-blocking comments on the new resource command arguments / validate-only / visibility surface — all distinct from the existing review threads. Mostly correctness/UX edge cases (validate-only Success masking not-found, Trim() on SecretText, Number input silent-fallback in dashboard, Options ToDictionary on duplicate keys, GetInt32 vs Number-as-double).