Add Description property to all pipeline steps and show in diagnostics output #13310

Copilot · 2025-12-03T12:42:37Z

Description

Pipeline steps now support optional descriptions to help users and LLMs understand step purpose. Descriptions appear in diagnostics output for better troubleshooting and automated analysis. All pipeline steps across the codebase now include descriptive text.

Changes:

Added Description property to PipelineStep class (nullable string with XML docs)
Used "Aggregation step" terminology for steps that aggregate related operations
Added descriptions to all well-known pipeline steps (deploy, build, publish, diagnostics, etc.)
Added descriptions to all Azure infrastructure steps (environment validation, provisioning, Bicep resources)
Added descriptions to all Azure deployment steps (App Service, Container Apps, ACR login, push, deploy)
Added descriptions to Docker Compose and Kubernetes environment steps
Added descriptions to container and project build steps
Added descriptions to manifest publishing steps
Updated diagnostics output to display descriptions between step name and dependencies
Updated test snapshots to reflect new diagnostics output format with descriptions

Example:

var step = new PipelineStep
{
    Name = "my-step",
    Description = "Validates deployment configuration before provisioning resources.",
    Action = async context => { /* ... */ }
};

Diagnostics output now shows:

Step: build
    Description: Aggregation step for all build operations. All build steps should be required by this step.
    Dependencies: ✓ build-prereq
    Tags: none

Step: build-myproject
    Description: Builds the container image for the myproject project.
    Dependencies: ✓ build-prereq
    Tags: BuildCompute

Step: validate-azure-login
    Description: Validates Azure CLI authentication before deployment.
    Dependencies: ✓ deploy-prereq

Files Modified (17):

Core pipeline infrastructure (PipelineStep, DistributedApplicationPipeline, WellKnownPipelineSteps)
Project and container build infrastructure (ProjectResource, ContainerResourceBuilderExtensions)
Manifest publishing (ManifestPublishingExtensions)
Azure hosting (AzureEnvironmentResource, AzureBicepResource)
Azure App Service (AzureAppServiceEnvironmentResource, AzureAppServiceWebSiteResource)
Azure Container Apps (AzureContainerAppEnvironmentResource, AzureContainerAppResource)
Docker and Kubernetes hosting (DockerComposeEnvironmentResource, KubernetesEnvironmentResource)
Test snapshots (3 files in Aspire.Hosting.Azure.Tests/Snapshots)

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 (nullable property addition, non-breaking)
  - 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-docs issue (consider using one of the following templates):
- No

Original prompt

Add descriptions to pipeline steps. This helps both users and machines (well LLMs) understand what steps are for . Also show the descriptions in the diagnostics step if available

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

Co-authored-by: davidfowl <[email protected]>

eerhardt · 2025-12-03T18:13:56Z

src/Aspire.Hosting/Pipelines/DistributedApplicationPipeline.cs

        _steps.Add(new PipelineStep
        {
            Name = WellKnownPipelineSteps.Deploy,
+            Description = "Meta-step that coordinates all deploy operations. All deploy steps should be required by this step.",


@copilot Is there a better term than "Meta-step"? Can you list some options?

Here are some alternative terms that might be clearer than "Meta-step":

Coordination step - Emphasizes coordinating other steps

Orchestration step - Aligns with Aspire's orchestration theme

Synchronization step - Highlights the synchronization aspect

Anchor step - Describes its role as a dependency anchor point

Milestone step - Represents completion of all related operations

Aggregation step - Shows it aggregates related steps

My recommendation would be "Coordination step" or "Orchestration step" as they're clear and accurately describe the purpose. Which would you prefer?

@copilot what about marker/placehoder/target step?

Those are simpler and clearer! I'll go with "Coordination point" which combines the coordination aspect with the "point" concept (similar to marker/target). It clearly describes that it's a point where all related operations coordinate/converge.

Will update in commit shortly.

@copilot lets use Aggregation step

Updated to use "Aggregation step" throughout the codebase in commit e4bfc24.

… all pipeline steps Co-authored-by: davidfowl <[email protected]>

github-actions · 2025-12-04T09:06:09Z

🚀 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/dotnet/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 13310

Or

Run remotely in PowerShell:

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

Co-authored-by: davidfowl <[email protected]>

Copilot

Pull request overview

This PR adds an optional Description property to the PipelineStep class to improve troubleshooting and provide better context for both users and automated tools (LLMs). The PR includes comprehensive descriptions for all pipeline steps across the codebase and updates diagnostics output to display these descriptions.

Key Changes:

Added nullable Description property to PipelineStep with appropriate XML documentation
Updated terminology from "meta-step" to "coordination point" for better clarity
Added descriptions to 30+ pipeline steps across Azure, Docker, Kubernetes, container builds, and manifest publishing

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/Aspire.Hosting/Pipelines/PipelineStep.cs	Added nullable `Description` property with XML documentation explaining its purpose
src/Aspire.Hosting/Pipelines/DistributedApplicationPipeline.cs	Added descriptions to all well-known pipeline steps and updated diagnostics output to display descriptions
src/Aspire.Hosting/Pipelines/WellKnownPipelineSteps.cs	Updated XML documentation terminology from "meta-step" to "coordination point"
src/Aspire.Hosting/Publishing/ManifestPublishingExtensions.cs	Added description to manifest publishing step
src/Aspire.Hosting/ContainerResourceBuilderExtensions.cs	Added dynamic description for container build steps
src/Aspire.Hosting/ApplicationModel/ProjectResource.cs	Added dynamic description for project build steps
src/Aspire.Hosting.Kubernetes/KubernetesEnvironmentResource.cs	Added description for Kubernetes environment publishing step
src/Aspire.Hosting.Docker/DockerComposeEnvironmentResource.cs	Added descriptions for Docker Compose publish and prepare steps
src/Aspire.Hosting.Azure/AzureEnvironmentResource.cs	Added descriptions for Azure environment steps (publish, validate, context creation, provisioning)
src/Aspire.Hosting.Azure/AzureBicepResource.cs	Added description for Bicep resource provisioning step
src/Aspire.Hosting.Azure.AppService/AzureAppServiceWebSiteResource.cs	Added descriptions for App Service push, summary, and deploy steps
src/Aspire.Hosting.Azure.AppService/AzureAppServiceEnvironmentResource.cs	Added descriptions for ACR login and dashboard URL printing steps
src/Aspire.Hosting.Azure.AppContainers/AzureContainerAppResource.cs	Added descriptions for Container Apps push, summary, and deploy steps
src/Aspire.Hosting.Azure.AppContainers/AzureContainerAppEnvironmentResource.cs	Added descriptions for Container Apps ACR login and dashboard URL printing steps
tests/Aspire.Hosting.Tests/Pipelines/DistributedApplicationPipelineTests.cs	Added two new tests to verify description functionality and well-known step descriptions

Copilot · 2025-12-04T09:16:02Z

tests/Aspire.Hosting.Tests/Pipelines/DistributedApplicationPipelineTests.cs

+        var context = CreateDeployingContext(builder.Build());
+
+        // Execute to trigger configuration callbacks
+        var _ = pipeline.ExecuteAsync(context).DefaultTimeout();


The test executes the pipeline asynchronously with pipeline.ExecuteAsync(context).DefaultTimeout() on line 2170, but the result is assigned to a discard variable _. This task should be awaited to ensure the pipeline completes before assertions.

Suggested change:

// Execute to trigger configuration callbacks await pipeline.ExecuteAsync(context).DefaultTimeout();

Without awaiting, the test may complete before the pipeline finishes executing, potentially causing race conditions where the assertions run before the configuration callback has been invoked.

tests/Aspire.Hosting.Tests/Pipelines/DistributedApplicationPipelineTests.cs

Co-authored-by: davidfowl <[email protected]>

davidfowl · 2025-12-04T21:29:28Z

@copilot Update the snapshots:

🔴 Aspire.Hosting.Azure.Tests.AzureDeployerTests.DeployAsync_WithRedisAccessKeyAuthentication_CreatesCorrectDependencies
🔴 Aspire.Hosting.Azure.Tests.AzureDeployerTests.DeployAsync_WithMultipleComputeEnvironments_Works(step: "diagnostics")
🔴 Aspire.Hosting.Azure.Tests.AzureDeployerTests.DeployAsync_WithAzureResourceDependencies_DoesNotHang(step: "diagnostics")

Co-authored-by: davidfowl <[email protected]>

Copilot · 2025-12-04T21:53:08Z

@copilot Update the snapshots:

🔴 Aspire.Hosting.Azure.Tests.AzureDeployerTests.DeployAsync_WithRedisAccessKeyAuthentication_CreatesCorrectDependencies...

Updated the snapshots in commit 379fa8e. The diagnostics output now includes descriptions for all pipeline steps.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

aka.ms
- Triggering command: /usr/local/bin/bicep /usr/local/bin/bicep build /tmp/aspiremLvN77/teststorage.module.bicep --stdout (dns block)
- Triggering command: /usr/local/bin/bicep /usr/local/bin/bicep build /tmp/aspire5iKubc/env.module.bicep --stdout (dns block)
- Triggering command: /usr/local/bin/bicep /usr/local/bin/bicep build /tmp/aspireLWZsWh/env.module.bicep --stdout (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

Configure Actions setup steps to set up my environment, which run before the firewall is enabled
Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Initial plan

a2ba0f0

Copilot AI assigned Copilot and davidfowl Dec 3, 2025

Copilot started work on behalf of davidfowl December 3, 2025 12:43 View session

Add Description property to pipeline steps and update diagnostics output

ac89e4d

Co-authored-by: davidfowl <[email protected]>

Copilot AI changed the title ~~[WIP] Add descriptions to pipeline steps for clarity~~ Add Description property to pipeline steps and show in diagnostics output Dec 3, 2025

Copilot AI requested a review from davidfowl December 3, 2025 13:14

Copilot finished work on behalf of davidfowl December 3, 2025 13:14

eerhardt reviewed Dec 3, 2025

View reviewed changes

Copilot started work on behalf of eerhardt December 3, 2025 18:14 View session

Copilot AI requested a review from eerhardt December 3, 2025 18:19

Copilot finished work on behalf of eerhardt December 3, 2025 18:19

Copilot started work on behalf of davidfowl December 4, 2025 08:48 View session

Replace "Meta-step" with "Coordination point" and add descriptions to…

5747de8

… all pipeline steps Co-authored-by: davidfowl <[email protected]>

Copilot AI changed the title ~~Add Description property to pipeline steps and show in diagnostics output~~ Add Description property to all pipeline steps and show in diagnostics output Dec 4, 2025

Copilot finished work on behalf of davidfowl December 4, 2025 09:04

davidfowl marked this pull request as ready for review December 4, 2025 09:06

davidfowl requested review from captainsafia and mitchdenny as code owners December 4, 2025 09:06

Copilot AI review requested due to automatic review settings December 4, 2025 09:06

Copilot started reviewing on behalf of davidfowl December 4, 2025 09:06 View session

Copilot started work on behalf of davidfowl December 4, 2025 09:06 View session

Copilot finished reviewing on behalf of davidfowl December 4, 2025 09:08

Change "Coordination point" to "Aggregation step" per feedback

e4bfc24

Co-authored-by: davidfowl <[email protected]>

Copilot finished work on behalf of davidfowl December 4, 2025 09:15

Copilot AI reviewed Dec 4, 2025

View reviewed changes

eerhardt approved these changes Dec 4, 2025

View reviewed changes

davidfowl reviewed Dec 4, 2025

View reviewed changes

tests/Aspire.Hosting.Tests/Pipelines/DistributedApplicationPipelineTests.cs Outdated Show resolved Hide resolved

Copilot started work on behalf of davidfowl December 4, 2025 15:47 View session

Remove unit tests for descriptions per feedback

863e2bc

Co-authored-by: davidfowl <[email protected]>

Copilot finished work on behalf of davidfowl December 4, 2025 15:56

Copilot AI requested a review from davidfowl December 4, 2025 15:56

captainsafia approved these changes Dec 4, 2025

View reviewed changes

Copilot started work on behalf of davidfowl December 4, 2025 21:30 View session

Update test snapshots with pipeline step descriptions

379fa8e

Co-authored-by: davidfowl <[email protected]>

Copilot finished work on behalf of davidfowl December 4, 2025 21:55

davidfowl merged commit 0eb70c4 into main Dec 5, 2025
569 of 571 checks passed

davidfowl deleted the copilot/add-descriptions-to-pipeline-steps branch December 5, 2025 06:21

dotnet-policy-service bot added this to the 13.1 milestone Dec 5, 2025

Add Description property to all pipeline steps and show in diagnostics output #13310

Add Description property to all pipeline steps and show in diagnostics output #13310

Conversation

Copilot AI commented Dec 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Uh oh!

eerhardt Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

davidfowl Dec 4, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 4, 2025

Choose a reason for hiding this comment

Uh oh!

davidfowl Dec 4, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 4, 2025

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Dec 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Dec 4, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

davidfowl commented Dec 4, 2025

Uh oh!

Copilot AI commented Dec 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

I tried to connect to the following addresses, but was blocked by firewall rules:

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Copilot AI commented Dec 3, 2025 •

edited

Loading

github-actions bot commented Dec 4, 2025 •

edited

Loading

Copilot AI commented Dec 4, 2025 •

edited

Loading