Add async PipelineStepFactoryContext and WithPipelineStepFactory extension methods (#12165)

* Initial plan

* Implement PipelineStepFactoryContext with PipelineContext and Resource properties

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

* Make PipelineStepAnnotation factory async to support walking resource graph

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

* Add WithPipelineStep extension methods with sync and async overloads

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

* Add sync constructor overloads and update code to use WithPipelineStep

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

* Rename WithPipelineStep to WithPipelineStepFactory

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

* Change DependsOnSteps and RequiredBySteps to init properties

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

---------

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: davidfowl <[email protected]>

Author: Copilot

src/Aspire.Hosting.Azure/AzureEnvironmentResource.cs

@@ -59,7 +59,7 @@ public AzureEnvironmentResource(string name, ParameterResource location, Paramet
     {
         Annotations.Add(new PublishingCallbackAnnotation(PublishAsync));
 
-        Annotations.Add(new PipelineStepAnnotation(() =>
+        Annotations.Add(new PipelineStepAnnotation((factoryContext) =>
         {
             ProvisioningContext? provisioningContext = null;
 

src/Aspire.Hosting/Pipelines/DistributedApplicationPipeline.cs

@@ -104,7 +104,8 @@ public void AddStep(PipelineStep step)
 
     public async Task ExecuteAsync(PipelineContext context)
     {
-        var allSteps = _steps.Concat(CollectStepsFromAnnotations(context)).ToList();
+        var annotationSteps = await CollectStepsFromAnnotationsAsync(context).ConfigureAwait(false);
+        var allSteps = _steps.Concat(annotationSteps).ToList();
 
         if (allSteps.Count == 0)
         {
@@ -119,21 +120,29 @@ public async Task ExecuteAsync(PipelineContext context)
         await ExecuteStepsAsTaskDag(allSteps, stepsByName, context).ConfigureAwait(false);
     }
 
-    private static IEnumerable<PipelineStep> CollectStepsFromAnnotations(PipelineContext context)
+    private static async Task<List<PipelineStep>> CollectStepsFromAnnotationsAsync(PipelineContext context)
     {
+        var steps = new List<PipelineStep>();
+
         foreach (var resource in context.Model.Resources)
         {
             var annotations = resource.Annotations
                 .OfType<PipelineStepAnnotation>();
 
             foreach (var annotation in annotations)
             {
-                foreach (var step in annotation.CreateSteps())
+                var factoryContext = new PipelineStepFactoryContext
                 {
-                    yield return step;
-                }
+                    PipelineContext = context,
+                    Resource = resource
+                };
+
+                var annotationSteps = await annotation.CreateStepsAsync(factoryContext).ConfigureAwait(false);
+                steps.AddRange(annotationSteps);
             }
         }
+
+        return steps;
     }
 
     private static void ValidateSteps(IEnumerable<PipelineStep> steps)

src/Aspire.Hosting/Pipelines/PipelineStep.cs

@@ -24,14 +24,14 @@ public class PipelineStep
     public required Func<PipelineStepContext, Task> Action { get; init; }
 
     /// <summary>
-    /// Gets the list of step names that this step depends on.
+    /// Gets or initializes the list of step names that this step depends on.
     /// </summary>
-    public List<string> DependsOnSteps { get; } = [];
+    public List<string> DependsOnSteps { get; init; } = [];
 
     /// <summary>
-    /// Gets the list of step names that require this step to complete before they can finish.
+    /// Gets or initializes the list of step names that require this step to complete before they can finish.
     /// </summary>
-    public List<string> RequiredBySteps { get; } = [];
+    public List<string> RequiredBySteps { get; init; } = [];
 
     /// <summary>
     /// Adds a dependency on another step.

src/Aspire.Hosting/Pipelines/PipelineStepAnnotation.cs

@@ -14,29 +14,48 @@ namespace Aspire.Hosting.Pipelines;
 [Experimental("ASPIREPIPELINES001", UrlFormat = "https://aka.ms/aspire/diagnostics/{0}")]
 public class PipelineStepAnnotation : IResourceAnnotation
 {
-    private readonly Func<IEnumerable<PipelineStep>> _factory;
+    private readonly Func<PipelineStepFactoryContext, Task<IEnumerable<PipelineStep>>> _factory;
 
     /// <summary>
     /// Initializes a new instance of the <see cref="PipelineStepAnnotation"/> class.
     /// </summary>
     /// <param name="factory">A factory function that creates the pipeline step.</param>
-    public PipelineStepAnnotation(Func<PipelineStep> factory)
+    public PipelineStepAnnotation(Func<PipelineStepFactoryContext, PipelineStep> factory)
     {
-        _factory = () => [factory()];
+        _factory = (context) => Task.FromResult<IEnumerable<PipelineStep>>([factory(context)]);
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="PipelineStepAnnotation"/> class.
+    /// </summary>
+    /// <param name="factory">An async factory function that creates the pipeline step.</param>
+    public PipelineStepAnnotation(Func<PipelineStepFactoryContext, Task<PipelineStep>> factory)
+    {
+        _factory = async (context) => [await factory(context).ConfigureAwait(false)];
     }
 
     /// <summary>
     /// Initializes a new instance of the <see cref="PipelineStepAnnotation"/> class with a factory that creates multiple pipeline steps.
     /// </summary>
     /// <param name="factory">A factory function that creates multiple pipeline steps.</param>
-    public PipelineStepAnnotation(Func<IEnumerable<PipelineStep>> factory)
+    public PipelineStepAnnotation(Func<PipelineStepFactoryContext, IEnumerable<PipelineStep>> factory)
+    {
+        _factory = (context) => Task.FromResult(factory(context));
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="PipelineStepAnnotation"/> class with a factory that creates multiple pipeline steps.
+    /// </summary>
+    /// <param name="factory">An async factory function that creates multiple pipeline steps.</param>
+    public PipelineStepAnnotation(Func<PipelineStepFactoryContext, Task<IEnumerable<PipelineStep>>> factory)
     {
         _factory = factory;
     }
 
     /// <summary>
-    /// Creates pipeline steps.
+    /// Creates pipeline steps asynchronously.
     /// </summary>
-    /// <returns>The created pipeline steps.</returns>
-    public IEnumerable<PipelineStep> CreateSteps() => _factory();
+    /// <param name="context">The factory context containing the pipeline context and resource.</param>
+    /// <returns>A task that represents the asynchronous operation and contains the created pipeline steps.</returns>
+    public Task<IEnumerable<PipelineStep>> CreateStepsAsync(PipelineStepFactoryContext context) => _factory(context);
 }

src/Aspire.Hosting/Pipelines/PipelineStepExtensions.cs

@@ -0,0 +1,84 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+#pragma warning disable ASPIREPUBLISHERS001
+
+using System.Diagnostics.CodeAnalysis;
+using Aspire.Hosting.ApplicationModel;
+
+namespace Aspire.Hosting.Pipelines;
+
+/// <summary>
+/// Provides extension methods for adding pipeline steps to resources.
+/// </summary>
+[Experimental("ASPIREPIPELINES001", UrlFormat = "https://aka.ms/aspire/diagnostics/{0}")]
+public static class PipelineStepExtensions
+{
+    /// <summary>
+    /// Adds a pipeline step to the resource that will be executed during deployment.
+    /// </summary>
+    /// <typeparam name="T">The type of the resource.</typeparam>
+    /// <param name="builder">The resource builder.</param>
+    /// <param name="factory">A factory function that creates the pipeline step.</param>
+    /// <returns>The resource builder for chaining.</returns>
+    public static IResourceBuilder<T> WithPipelineStepFactory<T>(
+        this IResourceBuilder<T> builder,
+        Func<PipelineStepFactoryContext, PipelineStep> factory) where T : IResource
+    {
+        ArgumentNullException.ThrowIfNull(builder);
+        ArgumentNullException.ThrowIfNull(factory);
+
+        return builder.WithAnnotation(new PipelineStepAnnotation(factory));
+    }
+
+    /// <summary>
+    /// Adds a pipeline step to the resource that will be executed during deployment.
+    /// </summary>
+    /// <typeparam name="T">The type of the resource.</typeparam>
+    /// <param name="builder">The resource builder.</param>
+    /// <param name="factory">An async factory function that creates the pipeline step.</param>
+    /// <returns>The resource builder for chaining.</returns>
+    public static IResourceBuilder<T> WithPipelineStepFactory<T>(
+        this IResourceBuilder<T> builder,
+        Func<PipelineStepFactoryContext, Task<PipelineStep>> factory) where T : IResource
+    {
+        ArgumentNullException.ThrowIfNull(builder);
+        ArgumentNullException.ThrowIfNull(factory);
+
+        return builder.WithAnnotation(new PipelineStepAnnotation(factory));
+    }
+
+    /// <summary>
+    /// Adds multiple pipeline steps to the resource that will be executed during deployment.
+    /// </summary>
+    /// <typeparam name="T">The type of the resource.</typeparam>
+    /// <param name="builder">The resource builder.</param>
+    /// <param name="factory">A factory function that creates multiple pipeline steps.</param>
+    /// <returns>The resource builder for chaining.</returns>
+    public static IResourceBuilder<T> WithPipelineStepFactory<T>(
+        this IResourceBuilder<T> builder,
+        Func<PipelineStepFactoryContext, IEnumerable<PipelineStep>> factory) where T : IResource
+    {
+        ArgumentNullException.ThrowIfNull(builder);
+        ArgumentNullException.ThrowIfNull(factory);
+
+        return builder.WithAnnotation(new PipelineStepAnnotation(factory));
+    }
+
+    /// <summary>
+    /// Adds multiple pipeline steps to the resource that will be executed during deployment.
+    /// </summary>
+    /// <typeparam name="T">The type of the resource.</typeparam>
+    /// <param name="builder">The resource builder.</param>
+    /// <param name="factory">An async factory function that creates multiple pipeline steps.</param>
+    /// <returns>The resource builder for chaining.</returns>
+    public static IResourceBuilder<T> WithPipelineStepFactory<T>(
+        this IResourceBuilder<T> builder,
+        Func<PipelineStepFactoryContext, Task<IEnumerable<PipelineStep>>> factory) where T : IResource
+    {
+        ArgumentNullException.ThrowIfNull(builder);
+        ArgumentNullException.ThrowIfNull(factory);
+
+        return builder.WithAnnotation(new PipelineStepAnnotation(factory));
+    }
+}

src/Aspire.Hosting/Pipelines/PipelineStepFactoryContext.cs

@@ -0,0 +1,24 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.Diagnostics.CodeAnalysis;
+using Aspire.Hosting.ApplicationModel;
+
+namespace Aspire.Hosting.Pipelines;
+
+/// <summary>
+/// Provides contextual information for creating pipeline steps from a <see cref="PipelineStepAnnotation"/>.
+/// </summary>
+[Experimental("ASPIREPIPELINES001", UrlFormat = "https://aka.ms/aspire/diagnostics/{0}")]
+public class PipelineStepFactoryContext
+{
+    /// <summary>
+    /// Gets the pipeline context that has the model and other properties.
+    /// </summary>
+    public required PipelineContext PipelineContext { get; init; }
+
+    /// <summary>
+    /// Gets the resource that this factory is associated with.
+    /// </summary>
+    public required IResource Resource { get; init; }
+}