Add ReferenceExpression to the External Parameters article

docs/fundamentals/external-parameters.md

@@ -134,11 +134,15 @@ var builder = DistributedApplication.CreateBuilder(args);
 var redis = builder.AddConnectionString("redis");
 
 builder.AddProject<Projects.WebApplication>("api")
-       .WithReference(redis);
+       .WithReference(redis)
+       .WaitFor(redis);
 
 builder.Build().Run();
 ```
 
+> [!NOTE]
+> Using <xref:Aspire.Hosting.ResourceBuilderExtensions.WaitFor*> with a connection string will implicitly wait for the resource that the connection string connects to.
+
 Now consider the following app host configuration file _:::no-loc text="appsettings.json":::_:
 
 ```json
@@ -151,6 +155,18 @@ Now consider the following app host configuration file _:::no-loc text="appsetti
 
 For more information pertaining to connection strings and their representation in the deployment manifest, see [Connection string and binding references](../deployment/manifest-format.md#connection-string-and-binding-references).
 
+### Build connection strings with reference expressions
+
+If you want to construct a connection string from parameters and ensure that it's handled correctly in both development and production, use <xref:Aspire.Hosting.ConnectionStringBuilderExtensions.AddConnectionString*> with a <xref:Aspire.Hosting.ApplicationModel.ReferenceExpression>.
+
+For example, if you have a secret parameter that stores a small part of a connection string, use this code to insert it:
+
+:::code language="csharp" source="snippets/referenceexpressions/AspireReferenceExpressions.AppHost/Program.cs" id="secretkey":::
+
+You can also use reference expressions to append text to connection strings created by .NET Aspire resources. For example, when you add a PostgreSQL resource to your .NET Aspire solution, the database server runs in a container and a connection string is formulated for it. In the following code, the extra property `Include Error Details` is appended to that connection string before it's passed to consuming projects:
+
+:::code language="csharp" source="snippets/referenceexpressions/AspireReferenceExpressions.AppHost/Program.cs" id="postgresappend":::
+
 ## Parameter example
 
 To express a parameter, consider the following example code:

docs/fundamentals/snippets/referenceexpressions/AspireReferenceExpressions.AppHost/AspireReferenceExpressions.AppHost.csproj

@@ -0,0 +1,23 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <Sdk Name="Aspire.AppHost.Sdk" Version="9.2.0" />
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net9.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <UserSecretsId>6329c834-f9f4-422d-b8e3-d9583b2574c3</UserSecretsId>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Aspire.Hosting.AppHost" Version="9.2.0" />
+    <PackageReference Include="Aspire.Hosting.PostgreSQL" Version="9.2.1" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\AspireReferenceExpressions.CatalogAPI\AspireReferenceExpressions.CatalogAPI.csproj" />
+    <ProjectReference Include="..\AspireReferenceExpressions.CustomerAPI\AspireReferenceExpressions.CustomerAPI.csproj" />
+  </ItemGroup>
+
+</Project>

docs/fundamentals/snippets/referenceexpressions/AspireReferenceExpressions.AppHost/Program.cs

@@ -0,0 +1,28 @@
+var builder = DistributedApplication.CreateBuilder(args);
+
+// <secretkey>
+var secretKey = builder.AddParameter("secretkey", secret: true);
+
+var connectionString = builder.AddConnectionString(
+    "composedconnectionstring",
+    ReferenceExpression.Create($"Endpoint=https://api.contoso.com/v1;Key={secretKey}"));
+
+builder.AddProject<Projects.AspireReferenceExpressions_CatalogAPI>("catalogapi")
+       .WithReference(connectionString)
+       .WaitFor(connectionString);
+// </secretkey>
+
+// <postgresappend>
+var postgres = builder.AddPostgres("postgres");
+var database = postgres.AddDatabase("db");
+
+var pgConnectionString = builder.AddConnectionString(
+    "pgdatabase",
+    ReferenceExpression.Create($"{database};Include Error Details=true"));
+
+builder.AddProject<Projects.AspireReferenceExpressions_CustomerAPI>("customerapi")
+       .WithReference(pgConnectionString)
+       .WaitFor(pgConnectionString);
+// </postgresappend>
+
+builder.Build().Run();

docs/fundamentals/snippets/referenceexpressions/AspireReferenceExpressions.AppHost/Properties/launchSettings.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json.schemastore.org/launchsettings.json",
+  "profiles": {
+    "https": {
+      "commandName": "Project",
+      "dotnetRunMessages": true,
+      "launchBrowser": true,
+      "applicationUrl": "https://localhost:17120;http://localhost:15249",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development",
+        "DOTNET_ENVIRONMENT": "Development",
+        "ASPIRE_DASHBOARD_OTLP_ENDPOINT_URL": "https://localhost:21231",
+        "ASPIRE_RESOURCE_SERVICE_ENDPOINT_URL": "https://localhost:22183"
+      }
+    },
+    "http": {
+      "commandName": "Project",
+      "dotnetRunMessages": true,
+      "launchBrowser": true,
+      "applicationUrl": "http://localhost:15249",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development",
+        "DOTNET_ENVIRONMENT": "Development",
+        "ASPIRE_DASHBOARD_OTLP_ENDPOINT_URL": "http://localhost:19230",
+        "ASPIRE_RESOURCE_SERVICE_ENDPOINT_URL": "http://localhost:20092"
+      }
+    }
+  }
+}

docs/fundamentals/snippets/referenceexpressions/AspireReferenceExpressions.AppHost/appsettings.Development.json

@@ -0,0 +1,8 @@
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft.AspNetCore": "Warning"
+    }
+  }
+}

docs/fundamentals/snippets/referenceexpressions/AspireReferenceExpressions.AppHost/appsettings.json

@@ -0,0 +1,9 @@
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft.AspNetCore": "Warning",
+      "Aspire.Hosting.Dcp": "Warning"
+    }
+  }
+}

docs/fundamentals/snippets/referenceexpressions/AspireReferenceExpressions.CatalogAPI/AspireReferenceExpressions.CatalogAPI.csproj

@@ -0,0 +1,17 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+
+  <PropertyGroup>
+    <TargetFramework>net9.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.0.2" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\AspireReferenceExpressions.ServiceDefaults\AspireReferenceExpressions.ServiceDefaults.csproj" />
+  </ItemGroup>
+
+</Project>

docs/fundamentals/snippets/referenceexpressions/AspireReferenceExpressions.CatalogAPI/AspireReferenceExpressions.CatalogAPI.http

@@ -0,0 +1,6 @@
+@AspireReferenceExpressions.CatalogAPI_HostAddress = http://localhost:5058
+
+GET {{AspireReferenceExpressions.CatalogAPI_HostAddress}}/weatherforecast/
+Accept: application/json
+
+###

docs/fundamentals/snippets/referenceexpressions/AspireReferenceExpressions.CatalogAPI/Program.cs

@@ -0,0 +1,45 @@
+var builder = WebApplication.CreateBuilder(args);
+
+builder.AddServiceDefaults();
+
+// Add services to the container.
+// Learn more about configuring OpenAPI at https://aka.ms/aspnet/openapi
+builder.Services.AddOpenApi();
+
+var app = builder.Build();
+
+app.MapDefaultEndpoints();
+
+// Configure the HTTP request pipeline.
+if (app.Environment.IsDevelopment())
+{
+    app.MapOpenApi();
+}
+
+app.UseHttpsRedirection();
+
+var summaries = new[]
+{
+    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
+};
+
+app.MapGet("/weatherforecast", () =>
+{
+    var forecast =  Enumerable.Range(1, 5).Select(index =>
+        new WeatherForecast
+        (
+            DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
+            Random.Shared.Next(-20, 55),
+            summaries[Random.Shared.Next(summaries.Length)]
+        ))
+        .ToArray();
+    return forecast;
+})
+.WithName("GetWeatherForecast");
+
+app.Run();
+
+record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
+{
+    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
+}

docs/fundamentals/snippets/referenceexpressions/AspireReferenceExpressions.CatalogAPI/Properties/launchSettings.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://json.schemastore.org/launchsettings.json",
+  "profiles": {
+    "http": {
+      "commandName": "Project",
+      "dotnetRunMessages": true,
+      "launchBrowser": false,
+      "applicationUrl": "http://localhost:5058",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development"
+      }
+    },
+    "https": {
+      "commandName": "Project",
+      "dotnetRunMessages": true,
+      "launchBrowser": false,
+      "applicationUrl": "https://localhost:7171;http://localhost:5058",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development"
+      }
+    }
+  }
+}

docs/fundamentals/snippets/referenceexpressions/AspireReferenceExpressions.CatalogAPI/appsettings.Development.json

@@ -0,0 +1,8 @@
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft.AspNetCore": "Warning"
+    }
+  }
+}

docs/fundamentals/snippets/referenceexpressions/AspireReferenceExpressions.CatalogAPI/appsettings.json

@@ -0,0 +1,9 @@
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft.AspNetCore": "Warning"
+    }
+  },
+  "AllowedHosts": "*"
+}

docs/fundamentals/snippets/referenceexpressions/AspireReferenceExpressions.CustomerAPI/AspireReferenceExpressions.CustomerAPI.csproj

@@ -0,0 +1,17 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+
+  <PropertyGroup>
+    <TargetFramework>net9.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.0.2" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\AspireReferenceExpressions.ServiceDefaults\AspireReferenceExpressions.ServiceDefaults.csproj" />
+  </ItemGroup>
+
+</Project>

docs/fundamentals/snippets/referenceexpressions/AspireReferenceExpressions.CustomerAPI/AspireReferenceExpressions.CustomerAPI.http

@@ -0,0 +1,6 @@
+@AspireReferenceExpressions.CustomerAPI_HostAddress = http://localhost:5022
+
+GET {{AspireReferenceExpressions.CustomerAPI_HostAddress}}/weatherforecast/
+Accept: application/json
+
+###

docs/fundamentals/snippets/referenceexpressions/AspireReferenceExpressions.CustomerAPI/Program.cs

@@ -0,0 +1,43 @@
+var builder = WebApplication.CreateBuilder(args);
+
+builder.AddServiceDefaults();
+
+// Add services to the container.
+// Learn more about configuring OpenAPI at https://aka.ms/aspnet/openapi
+builder.Services.AddOpenApi();
+
+var app = builder.Build();
+
+app.MapDefaultEndpoints();
+
+// Configure the HTTP request pipeline.
+if (app.Environment.IsDevelopment())
+{
+    app.MapOpenApi();
+}
+
+var summaries = new[]
+{
+    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
+};
+
+app.MapGet("/weatherforecast", () =>
+{
+    var forecast =  Enumerable.Range(1, 5).Select(index =>
+        new WeatherForecast
+        (
+            DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
+            Random.Shared.Next(-20, 55),
+            summaries[Random.Shared.Next(summaries.Length)]
+        ))
+        .ToArray();
+    return forecast;
+})
+.WithName("GetWeatherForecast");
+
+app.Run();
+
+record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
+{
+    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
+}

docs/fundamentals/snippets/referenceexpressions/AspireReferenceExpressions.CustomerAPI/Properties/launchSettings.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json.schemastore.org/launchsettings.json",
+  "profiles": {
+    "http": {
+      "commandName": "Project",
+      "dotnetRunMessages": true,
+      "launchBrowser": false,
+      "applicationUrl": "http://localhost:5022",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development"
+      }
+    }
+  }
+}

docs/fundamentals/snippets/referenceexpressions/AspireReferenceExpressions.CustomerAPI/appsettings.Development.json

@@ -0,0 +1,8 @@
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft.AspNetCore": "Warning"
+    }
+  }
+}

docs/fundamentals/snippets/referenceexpressions/AspireReferenceExpressions.CustomerAPI/appsettings.json

@@ -0,0 +1,9 @@
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft.AspNetCore": "Warning"
+    }
+  },
+  "AllowedHosts": "*"
+}

docs/fundamentals/snippets/referenceexpressions/AspireReferenceExpressions.ServiceDefaults/AspireReferenceExpressions.ServiceDefaults.csproj

@@ -0,0 +1,22 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net9.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <IsAspireSharedProject>true</IsAspireSharedProject>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <FrameworkReference Include="Microsoft.AspNetCore.App" />
+
+    <PackageReference Include="Microsoft.Extensions.Http.Resilience" Version="9.4.0" />
+    <PackageReference Include="Microsoft.Extensions.ServiceDiscovery" Version="9.2.0" />
+    <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.11.2" />
+    <PackageReference Include="OpenTelemetry.Extensions.Hosting" Version="1.11.2" />
+    <PackageReference Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.11.1" />
+    <PackageReference Include="OpenTelemetry.Instrumentation.Http" Version="1.11.1" />
+    <PackageReference Include="OpenTelemetry.Instrumentation.Runtime" Version="1.11.1" />
+  </ItemGroup>
+
+</Project>