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

src/Aspire.Cli/Commands/DoCommand.cs

@@ -35,9 +35,29 @@ public DoCommand(IDotNetCliRunner runner, IInteractionService interactionService
         {
             var step = result.GetValue(_stepArgument);
             var listSteps = result.GetValue(s_listStepsOption);
-            if (string.IsNullOrEmpty(step) && !listSteps && !ExtensionHelper.IsExtensionHost(interactionService, out _, out _))
+            if (!string.IsNullOrEmpty(step))
             {
-                result.AddError("The 'step' argument is required when not using --list-steps.");
+                return;
+            }
+
+            if (listSteps)
+            {
+                // `aspire do --list-steps` with no step has no meaningful scope: the listing for
+                // `do` is always relative to a target step. Surface a friendly error pointing at
+                // common starting steps and the docs rather than launching the AppHost and
+                // crashing mid-pipeline (see https://github.com/microsoft/aspire/issues/17526).
+                // This applies in the extension host too because `--list-steps` does not flow
+                // through the interactive step prompt in GetRunArgumentsAsync, so without this
+                // error the extension would still hit the original crash path.
+                result.AddError(DoCommandStrings.ListStepsRequiresStep);
+                return;
+            }
+
+            // For a plain `aspire do` invocation, the extension host prompts the user for a step
+            // later in GetRunArgumentsAsync, so don't add a validation error there.
+            if (!ExtensionHelper.IsExtensionHost(interactionService, out _, out _))
+            {
+                result.AddError(DoCommandStrings.StepArgumentRequired);
             }
         });
     }

src/Aspire.Cli/Resources/DoCommandStrings.resx

@@ -138,4 +138,10 @@
   <data name="StepArgumentDescription" xml:space="preserve">
     <value>The name of the step to execute</value>
   </data>
+  <data name="StepArgumentRequired" xml:space="preserve">
+    <value>The 'step' argument is required.</value>
+  </data>
+  <data name="ListStepsRequiresStep" xml:space="preserve">
+    <value>The 'step' argument is required when using --list-steps. Example: 'aspire do deploy --list-steps'. Common starting steps are 'build', 'publish' and 'deploy'. See https://aspire.dev/reference/cli/commands/aspire-do/ for the full list of pipeline steps.</value>
+  </data>
 </root>