Added overload of AddConnectionString using the builder pattern to make it more approachable (#8251)

* Enhance connection string resource handling with a builder pattern and improve documentation

* Update src/Aspire.Hosting/ConnectionStringBuilderExtensions.cs

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

* Add overload for AppendFormatted method to support IResourceBuilder and update tests for consistency

* Update src/Aspire.Hosting/ConnectionStringBuilderExtensions.cs

---------

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

Author: davidfowl

src/Aspire.Hosting/ApplicationModel/ReferenceExpression.cs

@@ -251,5 +251,16 @@ public void AppendFormatted<T>(T valueProvider) where T : IValueProvider, IManif
         {
             builder.AppendFormatted(valueProvider);
         }
+
+        /// <summary>
+        /// Appends a formatted value to the expression. The value must implement <see cref="IValueProvider"/> and <see cref="IManifestExpressionProvider"/>.
+        /// </summary>
+        /// <param name="valueProvider">An instance of an object which implements <see cref="IValueProvider"/> and <see cref="IManifestExpressionProvider"/>.</param>
+        /// <exception cref="InvalidOperationException"></exception>
+        public void AppendFormatted<T>(IResourceBuilder<T> valueProvider)
+            where T : IResource, IValueProvider, IManifestExpressionProvider
+        {
+            builder.AppendFormatted(valueProvider.Resource);
+        }
     }
 }

src/Aspire.Hosting/ConnectionStringBuilderExtensions.cs

@@ -23,16 +23,13 @@ public static class ConnectionStringBuilderExtensions
     /// <code language="csharp">
     /// var builder = DistributedApplication.CreateBuilder(args);
     ///
-    /// var postgres = builder
-    ///     .AddPostgres("postgres")
+    /// var apiKey = builder.AddParameter("apiKey", secret: true);
     ///
-    /// var database = postgres.AddDatabase("database");
-    ///
-    /// var cs = builder.AddConnectionString("cs", $"{database};Include Error Details=true");
+    /// var cs = builder.AddConnectionString("cs", ReferenceExpression.Create($"Endpoint=http://something;Key={apiKey}"));
     ///
     /// var backend = builder
     ///     .AddProject&lt;Projects.Backend&gt;("backend")
-    ///     .WithReference(cs) // cs is the connection string name, not database
+    ///     .WithReference(cs)
     ///     .WaitFor(database);
     ///
     /// builder.Build().Run();
@@ -50,4 +47,37 @@ public static IResourceBuilder<ConnectionStringResource> AddConnectionString(thi
                           Properties = []
                       });
     }
+
+    /// <summary>
+    /// Adds a connection string resource to the distributed application with the specified expression.
+    /// </summary>
+    /// <remarks>
+    /// This method also enables appending custom data to the connection string based on other resources that expose connection strings.
+    /// </remarks>
+    /// <param name="builder">Distributed application builder</param>
+    /// <param name="name">The name of the resource.</param>
+    /// <param name="connectionStringBuilder">The callback to configure the connection string expression.</param>
+    /// <returns>An <see cref="IResourceBuilder{ConnectionStringResource}"/> instance.</returns>
+    /// <example>
+    /// <code language="csharp">
+    /// var builder = DistributedApplication.CreateBuilder(args);
+    ///
+    /// var apiKey = builder.AddParameter("apiKey", secret: true);
+    ///
+    /// var cs = builder.AddConnectionString("cs", b => b.Append($"Endpoint=http://something;Key={apiKey}"));
+    ///
+    /// var backend = builder
+    ///     .AddProject&lt;Projects.Backend&gt;("backend")
+    ///     .WithReference(cs)
+    ///     .WaitFor(database);
+    ///
+    /// builder.Build().Run();
+    /// </code>
+    /// </example>
+    public static IResourceBuilder<ConnectionStringResource> AddConnectionString(this IDistributedApplicationBuilder builder, [ResourceName] string name, Action<ReferenceExpressionBuilder> connectionStringBuilder)
+    {
+        var rb = new ReferenceExpressionBuilder();
+        connectionStringBuilder(rb);
+        return builder.AddConnectionString(name, rb.Build());
+    }
 }

tests/Aspire.Hosting.Tests/WithReferenceTests.cs

@@ -247,15 +247,15 @@ public async Task ConnectionStringResourceWithConnectionString()
     }
 
     [Fact]
-    public async Task ConnectionStringResourceWithExpressiononnectionString()
+    public async Task ConnectionStringResourceWithExpressionConnectionString()
     {
         using var builder = TestDistributedApplicationBuilder.Create();
 
         var endpoint = builder.AddParameter("endpoint", "http://localhost:3452");
         var key = builder.AddParameter("key", "secretKey", secret: true);
 
         var cs = ReferenceExpression.Create($"Endpoint={endpoint};Key={key}");
-        
+
         // Get the service provider.
         var resource = builder.AddConnectionString("cs", cs);
 
@@ -270,6 +270,31 @@ public async Task ConnectionStringResourceWithExpressiononnectionString()
         Assert.Equal("Endpoint=http://localhost:3452;Key=secretKey", config["ConnectionStrings__cs"]);
     }
 
+    [Fact]
+    public async Task ConnectionStringResourceWithExpressionConnectionStringBuilder()
+    {
+        using var builder = TestDistributedApplicationBuilder.Create();
+
+        var endpoint = builder.AddParameter("endpoint", "http://localhost:3452");
+        var key = builder.AddParameter("key", "secretKey", secret: true);
+
+        // Get the service provider.
+        var resource = builder.AddConnectionString("cs", b =>
+        {
+            b.Append($"Endpoint={endpoint};Key={key}");
+        });
+
+        var projectB = builder.AddProject<ProjectB>("projectb")
+                              .WithReference(resource);
+
+        // Call environment variable callbacks.
+        var config = await EnvironmentVariableEvaluator.GetEnvironmentVariablesAsync(projectB.Resource, DistributedApplicationOperation.Run, TestServiceProvider.Instance).DefaultTimeout();
+
+        var servicesKeysCount = config.Keys.Count(k => k.StartsWith("ConnectionStrings__"));
+        Assert.Equal(1, servicesKeysCount);
+        Assert.Equal("Endpoint=http://localhost:3452;Key=secretKey", config["ConnectionStrings__cs"]);
+    }
+
     [Fact]
     public async Task ConnectionStringResourceWithConnectionStringOverwriteName()
     {