Skip to content

[release/13.4] Friendly error for 'aspire do --list-steps' without a step - #17543

Merged
David Fowler (davidfowl) merged 4 commits into
release/13.4from
backport/pr-17535-to-release/13.4
May 27, 2026
Merged

David Fowler (davidfowl) merged 4 commits into
release/13.4from
backport/pr-17535-to-release/13.4

Conversation

@aspire-repo-bot

Copy link
Copy Markdown
Contributor

Backport of #17535 to release/13.4

/cc Mitch Denny (@mitchdenny)

Customer Impact

Testing

Risk

Regression?

Mitch Denny (mitchdenny) and others added 4 commits May 27, 2026 14:25
'aspire do' is always step-targeted, so '--list-steps' with no step has no
meaningful scope. The validator previously allowed it, which caused the CLI
to launch the AppHost and race ahead executing the full pipeline before
the CLI could fetch steps and stop. That race surfaced as
'InvalidOperationException: Sequence contains more than one matching
element' from AzurePublishingContext (#17526).

Tighten the DoCommand validator to always require the step argument
(outside the extension host, which prompts interactively). When the user
specifies '--list-steps' without a step, emit a friendly, localized error
pointing at concrete examples: 'aspire do deploy --list-steps' or
'aspire do publish --list-steps'.

Adds StepArgumentRequired and ListStepsRequiresStep entries to
DoCommandStrings.resx + Designer.cs and refreshes all xlf translations
via UpdateXlf.

Tests:
 - DoCommandTests: new DoCommandWithListStepsAndNoStepArgumentShowsFriendlyError
   regression case; existing list-steps tests updated to pass a step.
 - ListStepsTests (E2E): single Docker-backed test now exercises
   'aspire do --list-steps' (asserts friendly error and the absence of
   the 'Sequence contains more than one matching element' crash) plus
   'aspire do deploy --list-steps', 'aspire publish --list-steps' and
   'aspire deploy --list-steps' against a freshly created starter app.

Fixes: #17526

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Expand the 'aspire do --list-steps' validation error to enumerate every
well-known pipeline step instead of just naming 'deploy' and 'publish'.
The step names are hand-maintained in DoCommand alongside a comment
pointing at src/Aspire.Hosting/Pipelines/WellKnownPipelineSteps.cs (the
CLI does not reference Aspire.Hosting). Updated unit and E2E assertions
to match the new message shape.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Replace the long enumeration of well-known step names with a short,
opinionated suggestion (build, publish, deploy) and a link to the
official 'aspire do' reference page on aspire.dev for the full list.
This removes the hand-maintained mirror of WellKnownPipelineSteps in
DoCommand and simplifies localization since the message no longer takes
a format parameter.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- DoCommand validator: fire the ListStepsRequiresStep friendly error
  for `aspire do --list-steps` even when running in the extension host,
  because --list-steps does not flow through GetRunArgumentsAsync's
  interactive step prompt and would otherwise still hit the original
  pipeline crash from #17526.
- ListStepsTests (E2E): replace long, wrap-sensitive substrings with
  short fragments ("required when using --list-steps", "aspire.dev/")
  so the assertion does not fail when the friendly error wraps in a
  narrow Docker terminal.
- DoCommandTests: add DoCommandWithListStepsAndNoStepArgumentInExtensionHostShowsFriendlyError
  to regression-test the extension-host path.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

@github-actions

Copy link
Copy Markdown
Contributor

🚀 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 -- 17543

Or

  • Run remotely in PowerShell:
iex "& { $(irm https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 17543"

@github-actions

Copy link
Copy Markdown
Contributor

❓ CLI E2E Tests unknown — 107 passed, 0 failed, 2 unknown (commit bcd89e9)

View all recordings
Status Test Recording
✅ AddPackageInteractiveWhileAppHostRunningDetached ✅ ▶️ View recording
✅ AddPackageWhileAppHostRunningDetached ✅ ▶️ View recording
✅ AgentCommands_AllHelpOutputs_AreCorrect ✅ ▶️ View recording
✅ AgentInitCommand_DefaultSelection_InstallsDefaultSkills ✅ ▶️ View recording
✅ AgentInitCommand_MigratesDeprecatedConfig ✅ ▶️ View recording
✅ AgentMcpListStructuredLogsReturnsLogsFromStarterApp ✅ ▶️ View recording
✅ AgentMcpListStructuredLogsReturnsLogsFromStarterApp_DevLocalhost ✅ ▶️ View recording
✅ AgentMcpListStructuredLogsReturnsLogsFromStarterApp_Isolated ✅ ▶️ View recording
✅ AllPublishMethodsBuildDockerImages ✅ ▶️ View recording
✅ AspireAddAndStartWorkAgainstLegacyAppHostTs ✅ ▶️ View recording
✅ AspireAddPackageVersionToDirectoryPackagesProps ✅ ▶️ View recording
✅ AspireInitSingleFileAppHostRunsViaDotnetRunAppHost ✅ ▶️ View recording
✅ AspireInitWithExistingAppHostDirRecreatesMissingNuGetConfigAndPreservesFiles ✅ ▶️ View recording
❔ AspireInitWithSolutionFileGeneratesAppHostThatBuildsAgainstChannelHive ❔ ▶️ View recording
✅ AspireStartUpdatesStaleTypeScriptAppHostPath ✅ ▶️ View recording
✅ AspireUpdateRemovesAppHostPackageVersionFromDirectoryPackagesProps ✅ ▶️ View recording
✅ AspireUpdateRemovesOrphanAppHostPackageVersionWhenSdkAlreadyCurrent ✅ ▶️ View recording
✅ Banner_DisplayedOnFirstRun ✅ ▶️ View recording
✅ Banner_DisplayedWithExplicitFlag ✅ ▶️ View recording
✅ Banner_NotDisplayedWithNoLogoFlag ✅ ▶️ View recording
✅ CertificatesClean_RemovesCertificates ✅ ▶️ View recording
✅ CertificatesTrust_WithNoCert_CreatesAndTrustsCertificate ✅ ▶️ View recording
✅ CertificatesTrust_WithUntrustedCert_TrustsCertificate ✅ ▶️ View recording
✅ ConfigSetGet_CreatesNestedJsonFormat ✅ ▶️ View recording
✅ CreateAndRunAspireStarterProject ✅ ▶️ View recording
✅ CreateAndRunAspireStarterProjectWithBundle ✅ ▶️ View recording
✅ CreateAndRunEmptyAppHostProject ✅ ▶️ View recording
✅ CreateAndRunJavaEmptyAppHostProject ✅ ▶️ View recording
✅ CreateAndRunJsReactProject ✅ ▶️ View recording
✅ CreateAndRunPythonReactProject ✅ ▶️ View recording
✅ CreateAndRunTypeScriptEmptyAppHostProject ✅ ▶️ View recording
✅ CreateAndRunTypeScriptStarterProject ✅ ▶️ View recording
✅ CreateJavaAppHostWithViteApp ✅ ▶️ View recording
✅ CreateTypeScriptAppHostWithViteApp_AllowsGuestAppPackageManagerToDiffer ✅ ▶️ View recording
✅ CreateTypeScriptAppHostWithViteApp_UsesConfiguredToolchain ✅ ▶️ View recording
✅ DashboardRunWithAgentMcpListTracesReturnsNoTraces ✅ ▶️ View recording
✅ DashboardRunWithAgentMcpListTracesReturnsNoTraces_DevLocalhost ✅ ▶️ View recording
✅ DashboardRunWithOtelTracesReturnsNoTraces ✅ ▶️ View recording
✅ DashboardRunWithOtelTracesReturnsNoTraces_DevLocalhost ✅ ▶️ View recording
✅ DeployK8sBasicApiService ✅ ▶️ View recording
✅ DeployK8sWithExternalHelmChart ✅ ▶️ View recording
✅ DeployK8sWithGarnet ✅ ▶️ View recording
✅ DeployK8sWithMongoDB ✅ ▶️ View recording
✅ DeployK8sWithMySql ✅ ▶️ View recording
✅ DeployK8sWithPostgres ✅ ▶️ View recording
✅ DeployK8sWithRabbitMQ ✅ ▶️ View recording
✅ DeployK8sWithRedis ✅ ▶️ View recording
✅ DeployK8sWithSqlServer ✅ ▶️ View recording
✅ DeployK8sWithValkey ✅ ▶️ View recording
✅ DeployTypeScriptAppToKubernetes ✅ ▶️ View recording
✅ DescribeCommandResolvesReplicaNames ✅ ▶️ View recording
✅ DescribeCommandShowsRunningResources ✅ ▶️ View recording
✅ DetachFormatJsonProducesValidJson ✅ ▶️ View recording
✅ DetachFormatJsonProducesValidJsonWhenRestartingExistingInstance ✅ ▶️ View recording
✅ DoPublishAndDeployListStepsWork ✅ ▶️ View recording
✅ DocsCommand_RendersInteractiveMarkdownFromLocalSource ✅ ▶️ View recording
✅ DoctorCommand_DetectsDeprecatedAgentConfig ✅ ▶️ View recording
✅ DoctorCommand_TypeScriptAppHostReportsMissingConfiguredToolchain ✅ ▶️ View recording
✅ DoctorCommand_WithSslCertDir_ShowsTrusted ✅ ▶️ View recording
✅ DoctorCommand_WithoutSslCertDir_ShowsPartiallyTrusted ✅ ▶️ View recording
✅ GatewayWithoutExternalEndpoint_FailsPublishWithGuidance ✅ ▶️ View recording
✅ GeneratedAspireDevScript_StartsWatchMode_WithConfiguredToolchain ✅ ▶️ View recording
✅ GlobalMigration_HandlesCommentsAndTrailingCommas ✅ ▶️ View recording
✅ GlobalMigration_HandlesMalformedLegacyJson ✅ ▶️ View recording
✅ GlobalMigration_PreservesAllValueTypes ✅ ▶️ View recording
✅ GlobalMigration_SkipsWhenNewConfigExists ✅ ▶️ View recording
✅ GlobalSettings_MigratedFromLegacyFormat ✅ ▶️ View recording
✅ IngressWithoutExternalEndpoint_FailsPublishWithGuidance ✅ ▶️ View recording
✅ InitTypeScriptAppHost_AugmentsExistingViteRepoInWorkspaceSubdirectory ✅ ▶️ View recording
✅ InteractiveCSharpInitCreatesExpectedFiles ✅ ▶️ View recording
✅ InvalidAppHostPathWithComments_IsHealedOnRun ✅ ▶️ View recording
✅ JavaScriptHostingApisRunFromTypeScriptAppHost ✅ ▶️ View recording
✅ LatestCliCanStartStableChannelAppHost ✅ ▶️ View recording
✅ LatestCliCanStartStableChannelTypeScriptAppHost ✅ ▶️ View recording
✅ LegacySettingsMigration_AdjustsRelativeAppHostPath ✅ ▶️ View recording
✅ LogsCommandShowsResourceLogs ✅ ▶️ View recording
✅ OtelLogsReturnsStructuredLogsFromStarterApp ✅ ▶️ View recording
✅ OtelLogsReturnsStructuredLogsFromStarterAppIsolated ✅ ▶️ View recording
✅ PsCommandListsRunningAppHost ✅ ▶️ View recording
✅ PsFormatJsonOutputsOnlyJsonToStdout ✅ ▶️ View recording
✅ PublishJavaScriptPatternsGeneratesExpectedDockerComposeArtifacts ✅ ▶️ View recording
✅ PublishWithConfigureEnvFileUpdatesEnvOutput ✅ ▶️ View recording
✅ PublishWithDockerComposeServiceCallbackSucceeds ✅ ▶️ View recording
✅ PublishWithoutOutputPathUsesAppHostDirectoryDefault ✅ ▶️ View recording
✅ ResourceCommand_FailedExecution_DisplaysAppHostLogPathAndLogContainsEntries ✅ ▶️ View recording
✅ ResourceCommand_SetAndDeleteParameterUpdatesDescribeOutput ✅ ▶️ View recording
✅ RestoreGeneratesSdkFiles ✅ ▶️ View recording
✅ RestoreGeneratesSdkFiles_WithConfiguredToolchain ✅ ▶️ View recording
✅ RestoreRefreshesGeneratedSdkAfterAddingIntegration ✅ ▶️ View recording
✅ RestoreSupportsConfigOnlyHelperPackageAndCrossPackageTypes ✅ ▶️ View recording
✅ RunFromParentDirectory_UsesExistingConfigNearAppHost ✅ ▶️ View recording
✅ RunReportsSyntaxErrorsForDotNetAppHost ✅ ▶️ View recording
✅ RunReportsSyntaxErrorsForTypeScriptAppHost ✅ ▶️ View recording
✅ SecretCrudOnDotNetAppHost ✅ ▶️ View recording
✅ SecretCrudOnTypeScriptAppHost ✅ ▶️ View recording
✅ StagingChannel_ConfigureAndVerifySettings_ThenSwitchChannels ✅ ▶️ View recording
✅ StartAndWaitForTypeScriptSqlServerAppHostWithNativeAssets ✅ ▶️ View recording
✅ StartReportsSyntaxErrorsForDotNetAppHost ✅ ▶️ View recording
✅ StartReportsSyntaxErrorsForTypeScriptAppHost ✅ ▶️ View recording
✅ StopAllAppHostsFromAppHostDirectory ✅ ▶️ View recording
✅ StopJavaPolyglotAppHostUsingApphostDirectory ✅ ▶️ View recording
✅ StopNonInteractiveSingleAppHost ✅ ▶️ View recording
✅ StopTypeScriptPolyglotAppHostUsingApphostDirectory ✅ ▶️ View recording
✅ StopWithNoRunningAppHostExitsSuccessfully ✅ ▶️ View recording
✅ UnAwaitedChainsCompileWithAutoResolvePromises ✅ ▶️ View recording
❔ UpdateProjectChannelToStable_CSharpEmptyAppHost_PreservesAspireConfigChannel ❔ ▶️ View recording
✅ UpdateProjectChannelToStable_CSharpSingleFileInit_PreservesAspireConfigChannel ✅ ▶️ View recording
✅ UpdateProjectChannelToStable_TypeScriptSingleFileInit_PreservesAspireConfigChannel ✅ ▶️ View recording
✅ UpdateProjectChannelToStable_TypeScript_PreviewsStablePackagesAndPreservesChannel ✅ ▶️ View recording

📹 Recordings uploaded automatically from CI run #26517382590

@davidfowl
David Fowler (davidfowl) merged commit 45a30c8 into release/13.4 May 27, 2026
617 of 620 checks passed
@davidfowl
David Fowler (davidfowl) deleted the backport/pr-17535-to-release/13.4 branch May 27, 2026 16:15
@microsoft-github-policy-service microsoft-github-policy-service Bot added this to the 13.4 milestone May 27, 2026
aspire-repo-bot Bot added a commit to microsoft/aspire.dev that referenced this pull request May 27, 2026
The aspire do command validator was tightened to always require
the step argument when --list-steps is specified. Without a step,
the CLI now emits a friendly error suggesting the correct form,
e.g. 'aspire do deploy --list-steps'.

Update examples and description in aspire-do.mdx to reflect that
--list-steps must be used as 'aspire do <step> --list-steps'.

Documents changes from microsoft/aspire#17543.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@aspire-repo-bot

Copy link
Copy Markdown
Contributor Author

Pull request created: #1096

Generated by PR Documentation Check

@aspire-repo-bot

Copy link
Copy Markdown
Contributor Author

📝 Documentation has been drafted in microsoft/aspire.dev#1096 targeting release/13.4.

Updated src/frontend/src/content/docs/reference/cli/commands/aspire-do.mdx to reflect that aspire do --list-steps now requires a step argument. The "Quick listing with --list-steps" section, the introductory bullet, and the Examples section all now show aspire do deploy --list-steps as the correct form, and note that omitting the step argument returns a friendly error.

Note

This draft PR needs human review before merging.

@github-actions github-actions Bot locked and limited conversation to collaborators Jun 27, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants