Implement Connection Properties and supporting expressions

docs/specs/connection-properties.md

@@ -0,0 +1,75 @@
+# Connection Properties
+> Audience - Aspire contributors and integration authors implementing or consuming `IResourceWithConnectionString` resources.
+
+## Overview
+- `IResourceWithConnectionString.GetConnectionProperties()` returns a stable set of well known keys mapped to `ReferenceExpression` values that are then injected as environment variables in select resources.
+- Keys describe connection metadata beyond the raw connection string so dependent resources can access specific pieces (via `GetConnectionProperty` or environment splatting).
+- Keys are emitted in PascalCase; lookups are case insensitive and duplicates should be avoided.
+- `WithReference(..., ReferenceEnvironmentInjectionFlags.ConnectionProperties)` splats every key as an environment variable using the reference name prefix and an uppercased key (for example `POSTGRES_HOST`).
+
+## Common Behavior
+- Prefer short, technology neutral names when one value is broadly useful (`Host`, `Port`, `Uri`).
+- Use explicit prefixes only when a resource exposes multiple endpoints (`GrpcHost`, `HttpHost`).
+- Child resources (`*DatabaseResource`, `OpenAIModelResource`) typically return the parent set plus a small overlay using `Union` so downstream callers see both shared and resource specific keys.
+- When adding a new resource, surface the minimal property set needed for common configurations.
+
+## Property Catalog
+
+### Network Identity
+
+| Key | Description | Provided By | Notes |
+| --- | --- | --- | --- |
+| Host | Primary hostname or address for the resource. | PostgreSQL, MySQL, SQL Server, Oracle, Redis, Garnet, Valkey, RabbitMQ, NATS, Kafka, MongoDB, Milvus. | Derived from `EndpointProperty.Host` of the primary endpoint. |
+| Port | Primary TCP port number. | Same set as `Host`. | Derived from `EndpointProperty.Port`. |
+
+### URIs and URLs
+
+| Key | Description | Provided By | Notes |
+| --- | --- | --- | --- |
+| Uri | Service specific URI built from host, port, credentials, and scheme. | PostgreSQL, PostgresDatabase, MySQL, MySqlDatabase, Redis, Garnet, Valkey, RabbitMQ, NATS, Seq, MongoDBDatabase, Milvus, Qdrant (gRPC), GitHubModel, OpenAI. | Formatting rules per resource are listed in [URI Construction](#uri-construction). |
+
+### Credentials and Secrets
+
+| Key | Description | Provided By | Notes |
+| --- | --- | --- | --- |
+| Username | Login user for the primary endpoint. | PostgreSQL, MySQL, SQL Server, Oracle, RabbitMQ, NATS, MongoDB. | Defaults align with respective containers (`postgres`, `root`, `sa`, etc.). |
+| Password | Login password. | PostgreSQL, MySQL, SQL Server, Oracle, Redis (when configured), Garnet (when configured), Valkey (when configured), RabbitMQ, NATS (when configured). | Omitted when the resource does not manage credentials. |
+| Key | API key or token parameter. | OpenAI, GitHubModel, Qdrant. | For GitHub Models the key is a PAT or minted token. |
+
+### Database Specific Metadata
+
+| Key | Description | Provided By | Notes |
+| --- | --- | --- | --- |
+| Database | Logical database name associated with the resource. | PostgresDatabase, MySqlDatabase, SqlServerDatabase, OracleDatabase, MongoDBDatabase, MilvusDatabase. | Added on top of the parent server keys. |
+| JdbcConnectionString | JDBC compatible connection string. | PostgreSQL, PostgresDatabase, MySQL, MySqlDatabase, SQL Server, SqlServerDatabase, Oracle, OracleDatabase. | Formats vary per vendor; see [JDBC Formats](#jdbc-formats). |
+
+## URI Construction
+
+URIs as convey connection information in a generic format that is commonly used by client SDKs. It follows the following pattern: `{SCHEME}://[[USERNAME]:[PASSWORD]@]{HOST}:{PORT}[/{RESOURCE}]`
+
+URI components should be url-encoded to prevent parsing issues. This is important as components like the password may contain conflicting characters.
+
+- PostgreSQL server: `postgresql://{Username}:{Password}@{Host}:{Port}` (database resources append `/{Database}`).
+- MySQL server: `mysql://{Username}:{Password}@{Host}:{Port}` (database resources append `/{Database}`).
+- Redis, Garnet, Valkey: `{scheme}://[:{Password}@]{Host}:{Port}` where the scheme matches the resource (`redis`, `valkey`).
+- RabbitMQ: `amqp://{Username}:{Password}@{Host}:{Port}`; `ManagementUri` uses HTTP(S) per endpoint configuration.
+- NATS: `nats://[Username:Password@]{Host}:{Port}` with credentials omitted when absent.
+- MongoDB database: `mongodb://[Username:Password@]{Host}:{Port}/{Database}` with optional `?authSource` and `authMechanism` query string when credentials are present.
+- Milvus: `http(s)://{Host}:{Port}` produced from the primary endpoint; credentials are exposed via the `Token` property.
+
+All URIs are composed with `:uri` formatting to ensure values are escaped correctly when rendered at deploy time.
+
+## JDBC Formats
+
+- PostgreSQL: `jdbc:postgresql://{Host}:{Port}[/{Database}]` (database resources append the database segment).
+- MySQL: `jdbc:mysql://{Host}:{Port}[/{Database}]?user={Username}&password={Password}`.
+- SQL Server: `jdbc:sqlserver://{Host}:{Port};user={Username};password={Password};trustServerCertificate=true[;databaseName={Database}]`.
+- Oracle: `jdbc:oracle:thin:{Username}/{Password}@//{Host}:{Port}[/{Database}]`.
+
+## Implementation Guidance
+
+- Reuse existing key names whenever possible; introduce new keys only for data that is unique or disambiguates multiple endpoints.
+- When a resource inherits another resource's connection properties, merge the parent set first to preserve overrides and annotations.
+- Prefer emitting a single URI per endpoint type; if multiple endpoints exist, use a suffix that clarifies the transport (`HttpUri`, `GrpcUri`).
+- Avoid recomputing expensive values in `GetConnectionProperties`; build reusable `ReferenceExpression` instances or helper methods instead.
+- Expose the values as reusable properties on the resource such that users can create their own expressions when necessary.

playground/AspireWithNode/AspireWithNode.AppHost/AppHost.cs

@@ -1,8 +1,12 @@
-using Microsoft.Extensions.Hosting;
+using Microsoft.Extensions.Hosting;
 
 var builder = DistributedApplication.CreateBuilder(args);
 
-var cache = builder.AddRedis("cache");
+var pass = builder.AddParameter("pass", "p@ssw0rd1");
+
+var cache = builder
+    .AddRedis("cache")
+    .WithPassword(pass);
 
 var weatherapi = builder.AddProject<Projects.AspireWithNode_AspNetCoreApi>("weatherapi");
 

playground/AspireWithNode/NodeFrontend/app.js

@@ -14,7 +14,7 @@ const config = {
     httpsRedirectPort: process.env['HTTPS_REDIRECT_PORT'] ?? (process.env['HTTPS_PORT'] ?? 8443),
     certFile: process.env['HTTPS_CERT_FILE'] ?? '',
     certKeyFile: process.env['HTTPS_CERT_KEY_FILE'] ?? '',
-    cacheAddress: process.env['ConnectionStrings__cache'] ?? '',
+    cacheUrl: process.env['CACHE_URI'] ?? '',
     apiServer: process.env['services__weatherapi__https__0'] ?? process.env['services__weatherapi__http__0']
 };
 console.log(`config: ${JSON.stringify(config)}`);
@@ -28,21 +28,7 @@ const httpsOptions = fs.existsSync(config.certFile) && fs.existsSync(config.cert
     }
     : { enabled: false };
 
-// Setup connection to Redis cache
-const passwordPrefix = ',password=';
-let cacheConfig = {
-    url: `redis://${config.cacheAddress}`
-};
-
-const cachePasswordIndex = config.cacheAddress.indexOf(passwordPrefix);
-if (cachePasswordIndex > 0) {
-    cacheConfig = {
-        url: `redis://${config.cacheAddress.substring(0, cachePasswordIndex)}`,
-        password: config.cacheAddress.substring(cachePasswordIndex + passwordPrefix.length)
-    }
-}
-
-const cache = createClient(cacheConfig);
+const cache = createClient({ url: config.cacheUrl });
 cache.on('error', err => console.error('Redis Client Error', err));
 await cache.connect();
 

playground/milvus/MilvusPlayground.AppHost/Program.cs

@@ -5,6 +5,6 @@
     .WithAttu();
 
 builder.AddProject<Projects.MilvusPlayground_ApiService>("apiservice")
-    .WithReference(milvusdb);
+    .WithReference(milvusdb).WaitFor(milvusdb);
 
 builder.Build().Run();

src/Aspire.Hosting.Azure.AppContainers/BaseContainerAppContext.cs

@@ -253,6 +253,21 @@ BicepValue<string> GetHostValue(string? prefix = null, string? suffix = null)
             return (AllocateParameter(output, secretType: secretType), secretType);
         }
 
+        if (value is IUrlEncoderProvider encoder && encoder.ValueProvider is { } valueProvider)
+        {
+            // Evaluate the inner value to get the bicep expression
+            var (innerValue, secret) = ProcessValue(valueProvider, secretType: secretType, parent: parent);
+
+            var innerExpression = innerValue switch
+            {
+                ProvisioningParameter p => p.Value.Compile(),
+                IBicepValue b => b.Compile(),
+                _ => throw new ArgumentException($"Invalid expression type for url-encoding: {innerValue.GetType()}")
+            };
+
+            return (new FunctionCallExpression(new IdentifierExpression("uriComponent"), innerExpression), secret);
+        }
+
 #pragma warning disable CS0618 // Type or member is obsolete
         if (value is BicepSecretOutputReference)
         {

src/Aspire.Hosting.Azure.AppService/AzureAppServiceWebsiteContext.cs

@@ -141,6 +141,21 @@ private void ProcessEndpoints()
             return (AllocateParameter(output, secretType: secretType), secretType);
         }
 
+        if (value is IUrlEncoderProvider encoder && encoder.ValueProvider is { } valueProvider)
+        {
+            // Evaluate the inner value to get the bicep expression
+            var (innerValue, secret) = ProcessValue(valueProvider, secretType: secretType, parent: parent);
+
+            var innerExpression = innerValue switch
+            {
+                ProvisioningParameter p => p.Value.Compile(),
+                IBicepValue b => b.Compile(),
+                _ => throw new ArgumentException($"Invalid expression type for url-encoding: {innerValue.GetType()}")
+            };
+
+            return (new FunctionCallExpression(new IdentifierExpression("uriComponent"), innerExpression), secret);
+        }
+
         if (value is IAzureKeyVaultSecretReference vaultSecretReference)
         {
             if (parent is null)

src/Aspire.Hosting.Garnet/GarnetResource.cs

@@ -28,6 +28,16 @@ public GarnetResource(string name, ParameterResource password) : this(name)
     /// </summary>
     public EndpointReference PrimaryEndpoint => _primaryEndpoint ??= new(this, PrimaryEndpointName);
 
+    /// <summary>
+    /// Gets the host endpoint reference for this resource.
+    /// </summary>
+    public EndpointReferenceExpression Host => PrimaryEndpoint.Property(EndpointProperty.Host);
+
+    /// <summary>
+    /// Gets the port endpoint reference for this resource.
+    /// </summary>
+    public EndpointReferenceExpression Port => PrimaryEndpoint.Property(EndpointProperty.Port);
+
     /// <summary>
     /// Gets the parameter that contains the Garnet server password.
     /// </summary>
@@ -61,4 +71,43 @@ private ReferenceExpression BuildConnectionString()
 
         return builder.Build();
     }
+
+    /// <summary>
+    /// Gets the connection URI expression for the Garnet server.
+    /// </summary>
+    /// <remarks>
+    /// Format: <c>redis://[:{password}@]{host}:{port}</c>. The password segment is omitted when no password is configured.
+    /// </remarks>
+    public ReferenceExpression UriExpression
+    {
+        get
+        {
+            var builder = new ReferenceExpressionBuilder();
+            builder.AppendLiteral("redis://");
+
+            if (PasswordParameter is not null)
+            {
+                builder.Append($":{PasswordParameter:uri}@");
+            }
+
+            builder.Append($"{Host}");
+            builder.AppendLiteral(":");
+            builder.Append($"{Port}");
+
+            return builder.Build();
+        }
+    }
+
+    IEnumerable<KeyValuePair<string, ReferenceExpression>> IResourceWithConnectionString.GetConnectionProperties()
+    {
+        yield return new("Host", ReferenceExpression.Create($"{Host}"));
+        yield return new("Port", ReferenceExpression.Create($"{Port}"));
+
+        if (PasswordParameter is not null)
+        {
+            yield return new("Password", ReferenceExpression.Create($"{PasswordParameter}"));
+        }
+
+        yield return new("Uri", UriExpression);
+    }
 }

src/Aspire.Hosting.GitHub.Models/GitHubModelResource.cs

@@ -47,11 +47,50 @@ public GitHubModelResource(string name, string model, ParameterResource? organiz
     /// </remarks>
     public ParameterResource Key { get; internal set; }
 
+    /// <summary>
+    /// Gets the connection string expression for the GitHub Models resource.
+    /// </summary>
+    private ReferenceExpression EndpointExpression
+    {
+        get
+        {
+            if (Organization is not null)
+            {
+                var builder = new ReferenceExpressionBuilder();
+                builder.AppendLiteral("https://models.github.ai/orgs/");
+                builder.Append($"{Organization:uri}");
+                builder.AppendLiteral("/inference");
+
+                return builder.Build();
+            }
+
+            return ReferenceExpression.Create($"https://models.github.ai/inference");
+        }
+    }
+
     /// <summary>
     /// Gets the connection string expression for the GitHub Models resource.
     /// </summary>
     public ReferenceExpression ConnectionStringExpression =>
-        Organization is not null
-            ? ReferenceExpression.Create($"Endpoint=https://models.github.ai/orgs/{Organization}/inference;Key={Key};Model={Model}")
-            : ReferenceExpression.Create($"Endpoint=https://models.github.ai/inference;Key={Key};Model={Model}");
+        ReferenceExpression.Create($"Endpoint={EndpointExpression};Key={Key};Model={Model}");
+
+    /// <summary>
+    /// Gets the endpoint URI expression for the GitHub Models resource.
+    /// </summary>
+    /// <remarks>
+    /// Format matches the configured endpoint, for example <c>https://models.github.ai/inference</c> or <c>https://models.github.ai/orgs/{organization}/inference</c> when an organization is specified.
+    /// </remarks>
+    public ReferenceExpression UriExpression => EndpointExpression;
+
+    IEnumerable<KeyValuePair<string, ReferenceExpression>> IResourceWithConnectionString.GetConnectionProperties()
+    {
+        yield return new("Uri", UriExpression);
+        yield return new("Key", ReferenceExpression.Create($"{Key}"));
+        yield return new("Model", ReferenceExpression.Create($"{Model}"));
+
+        if (Organization is not null)
+        {
+            yield return new("Organization", ReferenceExpression.Create($"{Organization}"));
+        }
+    }
 }

src/Aspire.Hosting.Kafka/KafkaServerResource.cs

@@ -25,6 +25,16 @@ public class KafkaServerResource(string name) : ContainerResource(name), IResour
     /// </summary>
     public EndpointReference PrimaryEndpoint => _primaryEndpoint ??= new(this, PrimaryEndpointName);
 
+    /// <summary>
+    /// Gets the host endpoint reference for the primary endpoint.
+    /// </summary>
+    public EndpointReferenceExpression Host => PrimaryEndpoint.Property(EndpointProperty.Host);
+
+    /// <summary>
+    /// Gets the port endpoint reference for the primary endpoint.
+    /// </summary>
+    public EndpointReferenceExpression Port => PrimaryEndpoint.Property(EndpointProperty.Port);
+
     /// <summary>
     /// Gets the internal endpoint for the Kafka broker. This endpoint is used for container to broker communication.
     /// To connect to the Kafka broker from a host process, use <see cref="PrimaryEndpoint"/>.
@@ -36,4 +46,10 @@ public class KafkaServerResource(string name) : ContainerResource(name), IResour
     /// </summary>
     public ReferenceExpression ConnectionStringExpression =>
        ReferenceExpression.Create($"{PrimaryEndpoint.Property(EndpointProperty.HostAndPort)}");
+
+    IEnumerable<KeyValuePair<string, ReferenceExpression>> IResourceWithConnectionString.GetConnectionProperties()
+    {
+        yield return new("Host", ReferenceExpression.Create($"{Host}"));
+        yield return new("Port", ReferenceExpression.Create($"{Port}"));
+    }
 }

src/Aspire.Hosting.Milvus/MilvusDatabaseResource.cs

@@ -23,6 +23,9 @@ public class MilvusDatabaseResource(string name, string databaseName, MilvusServ
     /// <summary>
     /// Gets the connection string expression for the Milvus database.
     /// </summary>
+    /// <remarks>
+    /// Format: <c>Endpoint={uri};Key={token};Database={DatabaseName}</c>.
+    /// </remarks>
     public ReferenceExpression ConnectionStringExpression =>
        ReferenceExpression.Create($"{Parent};Database={DatabaseName}");
 
@@ -36,4 +39,9 @@ private static string ThrowIfNullOrEmpty([NotNull] string? argument, [CallerArgu
         ArgumentException.ThrowIfNullOrEmpty(argument, paramName);
         return argument;
     }
+
+    IEnumerable<KeyValuePair<string, ReferenceExpression>> IResourceWithConnectionString.GetConnectionProperties() =>
+        Parent.CombineProperties([
+            new("Database", ReferenceExpression.Create($"{DatabaseName}"))
+        ]);
 }

src/Aspire.Hosting.Milvus/MilvusServerResource.cs

@@ -35,12 +35,38 @@ public MilvusServerResource(string name, ParameterResource apiKey) : base(name)
     /// </summary>
     public EndpointReference PrimaryEndpoint => _primaryEndpoint ??= new(this, PrimaryEndpointName);
 
+    /// <summary>
+    /// Gets the host endpoint reference for this resource.
+    /// </summary>
+    public EndpointReferenceExpression Host => PrimaryEndpoint.Property(EndpointProperty.Host);
+
+    /// <summary>
+    /// Gets the port endpoint reference for this resource.
+    /// </summary>
+    public EndpointReferenceExpression Port => PrimaryEndpoint.Property(EndpointProperty.Port);
+
+    /// <summary>
+    /// Gets a valid access token to access the Milvus instance.
+    /// </summary>
+    public ReferenceExpression Token => ReferenceExpression.Create($"root:{ApiKeyParameter}");
+
     /// <summary>
     /// Gets the connection string expression for the Milvus gRPC endpoint.
     /// </summary>
+    /// <remarks>
+    /// Format: <c>Endpoint={uri};Key={token}</c>.
+    /// </remarks>
     public ReferenceExpression ConnectionStringExpression =>
        ReferenceExpression.Create(
-            $"Endpoint={PrimaryEndpoint.Property(EndpointProperty.Url)};Key=root:{ApiKeyParameter}");
+            $"Endpoint={UriExpression};Key={Token}");
+
+    /// <summary>
+    /// Gets URI expression for the Milvus instance.
+    /// </summary>
+    /// <remarks>
+    /// Format: <c>http://{host}:{port}</c>.
+    /// </remarks>
+    public ReferenceExpression UriExpression => ReferenceExpression.Create($"{PrimaryEndpoint.Property(EndpointProperty.Url)}");
 
     private readonly Dictionary<string, string> _databases = new Dictionary<string, string>(StringComparers.ResourceName);
 
@@ -53,4 +79,12 @@ internal void AddDatabase(string name, string databaseName)
     {
         _databases.TryAdd(name, databaseName);
     }
+
+    IEnumerable<KeyValuePair<string, ReferenceExpression>> IResourceWithConnectionString.GetConnectionProperties()
+    {
+        yield return new("Host", ReferenceExpression.Create($"{Host}"));
+        yield return new("Port", ReferenceExpression.Create($"{Port}"));
+        yield return new("Token", ReferenceExpression.Create($"{Token}"));
+        yield return new("Uri", UriExpression);
+    }
 }