diff --git a/.github/agents/connectionproperties.agent.md b/.github/agents/connectionproperties.agent.md new file mode 100644 index 00000000000..54a97719d45 --- /dev/null +++ b/.github/agents/connectionproperties.agent.md @@ -0,0 +1,80 @@ +--- +name: connection-properties-expert +description: Specialized agent for creating and improving Connection Properties in Aspire resource and README files. +tools: ['read', 'search', 'edit'] +--- + +You are a C# developer. Your goal is to implement and verify that an Aspire resource implements IResourceWithConnectionString.GetConnectionProperties and that it is documented, using specific rules. + +## IResourceWithConnectionString.GetConnectionProperties rules + +Common Connection properties are +- Host +- Port +- Password, when available +- UserName, when available +- Uri, representing a service resource url, like [protocol]://[username]:[password]@[host]:[port]/[subresource]?parameter=... +- Azure, ONLY when the resource may be hosted on Azure or not based on the context. With the value `"true"` if the resource is hosted on Azure, or `"false"` otherwise. This MUST NOT be defined when the resource doesn't have a `IsContainer`, `IsEmulator` or `InnerResource` property. +- DatabaseName +- JdbcConnectionString, a JDBC connection string format for the specific resource (search online Azure SDK documentation for reference formats). + +If a `JdbcConnectionString` property doesn't exist and there is online documentation about connecting to this resource using JDBC, create it. + +## Parent resources + +When a resource class implement IResourceWithParent its connection properties should inherit its parent's ones. Then define it own to override the values, like Uri if applicable. + +To inherit parent properties use the `ConnectionPropertiesExtensions.CombineProperties` method like this: + +```c# +IEnumerable> IResourceWithConnectionString.GetConnectionProperties() => + Parent.CombineProperties([ + new("Database", ReferenceExpression.Create($"{DatabaseName}")), + new("Uri", UriExpression), + new("JdbcConnectionString", JdbcConnectionString), + ]); +``` + +Where `Parent` comes from the `IResourceWithParent` interface. + +## Documentation + +Each Azure resource has an associated README.md file in the same folder. Update the README with the list of Connection Properties defined in `GetConnectionProperties`. + +Here is a sample section for Sql Server: + +```md +## Connection Properties + +When you reference a SQL Server resource using `WithReference`, the following connection properties are made available to the consuming project: + +### SQL Server server + +The SQL Server server resource exposes the following connection properties: + +| Property Name | Description | +|---------------|-------------| +| `Host` | The hostname or IP address of the SQL Server | +| `Port` | The port number the SQL Server is listening on | +| `Username` | The username for authentication | +| `Password` | The password for authentication | +| `Uri` | The connection URI in mssql:// format, with the format `mssql://{Username}:{Password}@{Host}:{Port}` | +| `JdbcConnectionString` | JDBC-format connection string, with the format `jdbc:sqlserver://{Host}:{Port};user={Username};password={Password};trustServerCertificate=true` | + +### SQL Server database + +The SQL Server database resource inherits all properties from its parent `SqlServerServerResource` and adds: + +| Property Name | Description | +|---------------|-------------| +| `Uri` | The connection URI in mssql:// format, with the format `mssql://{Username}:{Password}@{Host}:{Port}/{DatabaseName}` | +| `JdbcConnectionString` | JDBC connection string with database name, with the format `jdbc:sqlserver://{Host}:{Port};user={Username};password={Password};trustServerCertificate=true;databaseName={DatabaseName}` | +| `Database` | The name of the database | + +Aspire exposes each property as an environment variable named `[RESOURCE]_[PROPERTY]`. For instance, the `Uri` property of a resource called `db1` becomes `DB1_URI`. +``` + +- The table should be formatted identically to this sample +- Each resource gets its own table +- Uri and JdbcConnectionString must have their format in the description +- The `Connection Properties` should be the last before external links like `Additional documentation` \ No newline at end of file diff --git a/.vscode/mcp.json b/.vscode/mcp.json index 2cc0b6607b3..1bd572d56e2 100644 --- a/.vscode/mcp.json +++ b/.vscode/mcp.json @@ -1,13 +1,4 @@ { "servers": { - "aspire-mcp-tools": { - "type": "stdio", - "command": "dotnet", - "args": [ - "run", - "--project", - "${workspaceFolder}/tools/AspireMcpTools/AspireMcpTools.csproj" - ] - } } -} \ No newline at end of file +} diff --git a/src/Aspire.Hosting.Garnet/README.md b/src/Aspire.Hosting.Garnet/README.md index 4353046e58f..c2fb8f81193 100644 --- a/src/Aspire.Hosting.Garnet/README.md +++ b/src/Aspire.Hosting.Garnet/README.md @@ -1,10 +1,12 @@ # Aspire.Hosting.Garnet library -Provides extension methods and resource definitions for an Aspire AppHost to configure Cache for Garnet. +Provides extension methods and resource definitions for an Aspire AppHost to configure a Garnet cache resource. -## Install the package +## Getting started -In your AppHost project, install the `Aspire.Hosting.Garnet` library with [NuGet](https://www.nuget.org): +### Install the package + +In your AppHost project, install the Aspire Garnet Hosting library with [NuGet](https://www.nuget.org): ```dotnetcli dotnet add package Aspire.Hosting.Garnet @@ -12,10 +14,10 @@ dotnet add package Aspire.Hosting.Garnet ## Usage example -Then, in the _AppHost.cs_ file of `AppHost`, register a Garnet server and consume the connection using the following methods: +Then, in the _AppHost.cs_ file of `AppHost`, add a Garnet resource and consume the connection using the following methods: ```csharp -var garnet = builder.AddGarnet("cache") +var garnet = builder.AddGarnet("cache"); var myService = builder.AddProject() .WithReference(garnet); @@ -27,6 +29,23 @@ The `WithReference` method configures a connection in the `MyService` project na builder.AddRedisClient("cache"); ``` +## Connection Properties + +When you reference a Garnet resource using `WithReference`, the following connection properties are made available to the consuming project: + +### Garnet + +The Garnet resource exposes the following connection properties: + +| Property Name | Description | +|---------------|-------------| +| `Host` | The hostname or IP address of the Garnet server | +| `Port` | The port number the Garnet server is listening on | +| `Password` | The password for authentication (available when a password parameter is configured) | +| `Uri` | The connection URI, with the format `redis://:{Password}@{Host}:{Port}` | + +Aspire exposes each property as an environment variable named `[RESOURCE]_[PROPERTY]`. For instance, the `Uri` property of a resource called `db1` becomes `DB1_URI`. + ## Additional documentation * https://github.com/microsoft/garnet/blob/main/README.md diff --git a/src/Aspire.Hosting.GitHub.Models/README.md b/src/Aspire.Hosting.GitHub.Models/README.md index a79ef4c6b15..d898b00751a 100644 --- a/src/Aspire.Hosting.GitHub.Models/README.md +++ b/src/Aspire.Hosting.GitHub.Models/README.md @@ -78,6 +78,23 @@ Then in user secrets: } ``` +## Connection Properties + +When you reference a GitHub Model resource using `WithReference`, the following connection properties are made available to the consuming project: + +### GitHub Model + +The GitHub Model resource exposes the following connection properties: + +| Property Name | Description | +|---------------|-------------| +| `Uri` | The GitHub Models inference endpoint URI, with the format `https://models.github.ai/inference` | +| `Key` | The API key (PAT or GitHub App token) for authentication | +| `Model` | The model identifier for inference requests, for instance `openai/gpt-4o-mini` | +| `Organization` | The organization attributed to the request (available when configured) | + +Aspire exposes each property as an environment variable named `[RESOURCE]_[PROPERTY]`. For instance, the `Uri` property of a resource called `db1` becomes `DB1_URI`. + ## Available Models GitHub Models supports various AI models. Some popular options include: diff --git a/src/Aspire.Hosting.Kafka/README.md b/src/Aspire.Hosting.Kafka/README.md index 2d1fb7871c7..3615821f2e3 100644 --- a/src/Aspire.Hosting.Kafka/README.md +++ b/src/Aspire.Hosting.Kafka/README.md @@ -23,8 +23,24 @@ var myService = builder.AddProject() .WithReference(kafka); ``` +## Connection Properties + +When you reference a Kafka resource using `WithReference`, the following connection properties are made available to the consuming project: + +### Kafka server + +The Kafka server resource exposes the following connection properties: + +| Property Name | Description | +|---------------|-------------| +| `Host` | The host-facing Kafka listener hostname or IP address | +| `Port` | The host-facing Kafka listener port | + +Aspire exposes each property as an environment variable named `[RESOURCE]_[PROPERTY]`. For instance, the `Uri` property of a resource called `db1` becomes `DB1_URI`. + ## Additional documentation -https://learn.microsoft.com/dotnet/aspire/messaging/kafka-component + +* https://learn.microsoft.com/dotnet/aspire/messaging/kafka-component ## Feedback & contributing diff --git a/src/Aspire.Hosting.Milvus/README.md b/src/Aspire.Hosting.Milvus/README.md index c2adce9e097..66f551e7e24 100644 --- a/src/Aspire.Hosting.Milvus/README.md +++ b/src/Aspire.Hosting.Milvus/README.md @@ -23,7 +23,33 @@ var myService = builder.AddProject() .WithReference(milvus); ``` +## Connection Properties + +When you reference a Milvus resource using `WithReference`, the following connection properties are made available to the consuming project: + +### Milvus server + +The Milvus server resource exposes the following connection properties: + +| Property Name | Description | +|---------------|-------------| +| `Host` | The hostname or IP address of the Milvus server | +| `Port` | The gRPC port exposed by the Milvus server | +| `Token` | The authentication token, with the format `root:{ApiKey}` | +| `Uri` | The gRPC endpoint URI, with the format `http://{Host}:{Port}` | + +### Milvus database + +The Milvus database resource combines the server properties above and adds the following connection property: + +| Property Name | Description | +|---------------|-------------| +| `Database` | The Milvus database name | + +Aspire exposes each property as an environment variable named `[RESOURCE]_[PROPERTY]`. For instance, the `Uri` property of a resource called `db1` becomes `DB1_URI`. + ## Additional documentation + * https://milvus.io/docs ## Feedback & contributing diff --git a/src/Aspire.Hosting.MongoDB/README.md b/src/Aspire.Hosting.MongoDB/README.md index 08247e7d7fd..622d8f89393 100644 --- a/src/Aspire.Hosting.MongoDB/README.md +++ b/src/Aspire.Hosting.MongoDB/README.md @@ -23,8 +23,37 @@ var myService = builder.AddProject() .WithReference(db); ``` +## Connection Properties + +When you reference a MongoDB resource using `WithReference`, the following connection properties are made available to the consuming project: + +### MongoDB server + +The MongoDB server resource exposes the following connection properties: + +| Property Name | Description | +|---------------|-------------| +| `Host` | The hostname or IP address of the MongoDB server | +| `Port` | The port number the MongoDB server is listening on | +| `Username` | The username for authentication | +| `Password` | The password for authentication (available when a password parameter is configured) | +| `AuthenticationDatabase` | The authentication database (available when a password parameter is configured) | +| `AuthenticationMechanism` | The authentication mechanism (available when a password parameter is configured) | +| `Uri` | The connection URI, with the format `mongodb://{Username}:{Password}@{Host}:{Port}/?authSource={AuthenticationDatabase}&authMechanism={AuthenticationMechanism}` | + +### MongoDB database + +The MongoDB database resource combines the server properties above and adds the following connection property: + +| Property Name | Description | +|---------------|-------------| +| `Database` | The MongoDB database name | + +Aspire exposes each property as an environment variable named `[RESOURCE]_[PROPERTY]`. For instance, the `Uri` property of a resource called `db1` becomes `DB1_URI`. + ## Additional documentation -https://learn.microsoft.com/dotnet/aspire/database/mongodb-component + +* https://learn.microsoft.com/dotnet/aspire/database/mongodb-component ## Feedback & contributing diff --git a/src/Aspire.Hosting.MySql/README.md b/src/Aspire.Hosting.MySql/README.md index 55f4a2b3b20..03f28e2537a 100644 --- a/src/Aspire.Hosting.MySql/README.md +++ b/src/Aspire.Hosting.MySql/README.md @@ -23,8 +23,38 @@ var myService = builder.AddProject() .WithReference(db); ``` +## Connection Properties + +When you reference a MySQL resource using `WithReference`, the following connection properties are made available to the consuming project: + +### MySQL server + +The MySQL server resource exposes the following connection properties: + +| Property Name | Description | +|---------------|-------------| +| `Host` | The hostname or IP address of the MySQL server | +| `Port` | The port number the MySQL server is listening on | +| `Username` | The username for authentication | +| `Password` | The password for authentication | +| `Uri` | The connection URI, with the format `mysql://root:{Password}@{Host}:{Port}` | +| `JdbcConnectionString` | The JDBC connection string for MySQL, with the format `jdbc:mysql://{Host}:{Port}/?user={Username}&password={Password}` | + +### MySQL database + +The MySQL database resource combines the server properties above and adds the following connection properties: + +| Property Name | Description | +|---------------|-------------| +| `Database` | The MySQL database name | +| `Uri` | The database-specific URI, with the format `mysql://root:{Password}@{Host}:{Port}/{Database}` | +| `JdbcConnectionString` | The database-specific JDBC connection string, with the format `jdbc:mysql://{Host}:{Port}/{Database}?user={Username}&password={Password}` | + +Aspire exposes each property as an environment variable named `[RESOURCE]_[PROPERTY]`. For instance, the `Uri` property of a resource called `db1` becomes `DB1_URI`. + ## Additional documentation -https://learn.microsoft.com/dotnet/aspire/database/mysql-component + +* https://learn.microsoft.com/dotnet/aspire/database/mysql-component ## Feedback & contributing diff --git a/src/Aspire.Hosting.Nats/README.md b/src/Aspire.Hosting.Nats/README.md index 89f9dbe75ae..2c34309d8e5 100644 --- a/src/Aspire.Hosting.Nats/README.md +++ b/src/Aspire.Hosting.Nats/README.md @@ -23,8 +23,27 @@ var myService = builder.AddProject() .WithReference(nats); ``` +## Connection Properties + +When you reference a NATS resource using `WithReference`, the following connection properties are made available to the consuming project: + +### NATS server + +The NATS server resource exposes the following connection properties: + +| Property Name | Description | +|---------------|-------------| +| `Host` | The hostname or IP address of the NATS server | +| `Port` | The port number the NATS server is listening on | +| `Username` | The username for authentication | +| `Password` | The password for authentication | +| `Uri` | The connection URI with the format `nats://{Username}:{Password}@{Host}:{Port}` | + +Aspire exposes each property as an environment variable named `[RESOURCE]_[PROPERTY]`. For instance, the `Uri` property of a resource called `db1` becomes `DB1_URI`. + ## Additional documentation -https://learn.microsoft.com/dotnet/aspire/messaging/nats-component + +* https://learn.microsoft.com/dotnet/aspire/messaging/nats-component ## Feedback & contributing diff --git a/src/Aspire.Hosting.OpenAI/README.md b/src/Aspire.Hosting.OpenAI/README.md index 102e0d53183..3f70af4143d 100644 --- a/src/Aspire.Hosting.OpenAI/README.md +++ b/src/Aspire.Hosting.OpenAI/README.md @@ -118,6 +118,30 @@ var chat = openai.AddModel("chat", "gpt-4o-mini"); Both the parent and model connection strings will include the custom endpoint. +## Connection Properties + +When you reference an OpenAI resource using `WithReference`, the following connection properties are made available to the consuming project: + +### OpenAIResource + +The OpenAI resource exposes the following connection properties: + +| Property Name | Description | +|---------------|-------------| +| `Endpoint` | The base endpoint URI for the OpenAI API, with the format `https://api.openai.com/v1` | +| `Uri` | The endpoint URI (same as Endpoint), with the format `https://api.openai.com/v1` | +| `Key` | The API key for authentication | + +### OpenAI model + +The OpenAI model resource combines the parent properties above and adds the following connection property: + +| Property Name | Description | +|---------------|-------------| +| `Model` | The model identifier for inference requests, for instance `gpt-4o-mini` | + +Aspire exposes each property as an environment variable named `[RESOURCE]_[PROPERTY]`. For instance, the `Uri` property of a resource called `db1` becomes `DB1_URI`. + ## Additional documentation * https://platform.openai.com/docs/models diff --git a/src/Aspire.Hosting.Oracle/OracleDatabaseResource.cs b/src/Aspire.Hosting.Oracle/OracleDatabaseResource.cs index 9da0cad3322..6ddfcbe31e6 100644 --- a/src/Aspire.Hosting.Oracle/OracleDatabaseResource.cs +++ b/src/Aspire.Hosting.Oracle/OracleDatabaseResource.cs @@ -26,6 +26,15 @@ public class OracleDatabaseResource(string name, string databaseName, OracleData public ReferenceExpression ConnectionStringExpression => ReferenceExpression.Create($"{Parent}/{DatabaseName}"); + /// + /// Gets the connection URI expression for the Oracle database. + /// + /// + /// Format: oracle://{user}:{password}@{host}:{port}/{database}. + /// + public ReferenceExpression UriExpression => + ReferenceExpression.Create($"{Parent.UriExpression}/{DatabaseName:uri}"); + /// /// Gets the JDBC connection string for the Oracle Database. /// @@ -48,6 +57,7 @@ private static string ThrowIfNullOrEmpty([NotNull] string? argument, [CallerArgu IEnumerable> IResourceWithConnectionString.GetConnectionProperties() => Parent.CombineProperties([ new("Database", ReferenceExpression.Create($"{DatabaseName}")), + new("Uri", UriExpression), new("JdbcConnectionString", JdbcConnectionString), ]); } diff --git a/src/Aspire.Hosting.Oracle/OracleDatabaseServerResource.cs b/src/Aspire.Hosting.Oracle/OracleDatabaseServerResource.cs index 0ff0e349728..0f9c2a50dca 100644 --- a/src/Aspire.Hosting.Oracle/OracleDatabaseServerResource.cs +++ b/src/Aspire.Hosting.Oracle/OracleDatabaseServerResource.cs @@ -59,6 +59,15 @@ public OracleDatabaseServerResource(string name, ParameterResource password) : b /// public ReferenceExpression UserNameReference => ReferenceExpression.Create($"{DefaultUserName}"); + /// + /// Gets the connection URI expression for the Oracle server. + /// + /// + /// Format: oracle://{user}:{password}@{host}:{port}. + /// + public ReferenceExpression UriExpression => + ReferenceExpression.Create($"oracle://{UserNameReference:uri}:{PasswordParameter:uri}@{Host}:{Port}"); + internal ReferenceExpression BuildJdbcConnectionString(string? databaseName = null) { var builder = new ReferenceExpressionBuilder(); @@ -105,6 +114,7 @@ IEnumerable> IResourceWithConnectionSt yield return new("Port", ReferenceExpression.Create($"{Port}")); yield return new("Username", UserNameReference); yield return new("Password", ReferenceExpression.Create($"{PasswordParameter}")); + yield return new("Uri", UriExpression); yield return new("JdbcConnectionString", JdbcConnectionString); } } diff --git a/src/Aspire.Hosting.Oracle/README.md b/src/Aspire.Hosting.Oracle/README.md index f298100170a..3ea00df4558 100644 --- a/src/Aspire.Hosting.Oracle/README.md +++ b/src/Aspire.Hosting.Oracle/README.md @@ -23,7 +23,37 @@ var myService = builder.AddProject() .WithReference(db); ``` +## Connection Properties + +When you reference an Oracle database resource using `WithReference`, the following connection properties are made available to the consuming project: + +### Oracle database server + +The Oracle database server resource exposes the following connection properties: + +| Property Name | Description | +|---------------|-------------| +| `Host` | The hostname or IP address of the Oracle server | +| `Port` | The port number the Oracle server is listening on | +| `Username` | The username for authentication | +| `Password` | The password for authentication | +| `Uri` | The connection URI in oracle:// format, with the format `oracle://{Username}:{Password}@{Host}:{Port}` | +| `JdbcConnectionString` | JDBC-format connection string, with the format `jdbc:oracle:thin:{Username}/{Password}@//{Host}:{Port}` | + +### Oracle database + +The Oracle database resource inherits all properties from its parent `OracleDatabaseServerResource` and adds: + +| Property Name | Description | +|---------------|-------------| +| `Uri` | The connection URI in oracle:// format, with the format `oracle://{Username}:{Password}@{Host}:{Port}/{DatabaseName}` | +| `JdbcConnectionString` | JDBC connection string with database name, with the format `jdbc:oracle:thin:{Username}/{Password}@//{Host}:{Port}/{DatabaseName}` | +| `Database` | The name of the database | + +Aspire exposes each property as an environment variable named `[RESOURCE]_[PROPERTY]`. For instance, the `Uri` property of a resource called `db1` becomes `DB1_URI`. + ## Additional documentation + https://learn.microsoft.com/dotnet/aspire/database/oracle-entity-framework-component?tabs=dotnet-cli ## Feedback & contributing diff --git a/src/Aspire.Hosting.PostgreSQL/PostgresServerResource.cs b/src/Aspire.Hosting.PostgreSQL/PostgresServerResource.cs index 26f3879cfb6..7e2d045bd9b 100644 --- a/src/Aspire.Hosting.PostgreSQL/PostgresServerResource.cs +++ b/src/Aspire.Hosting.PostgreSQL/PostgresServerResource.cs @@ -136,9 +136,12 @@ internal ReferenceExpression BuildJdbcConnectionString(string? databaseName = nu builder.Append($"{databaseNameExpression:uri}"); } + builder.Append($"?user={UserNameReference:uri}"); + builder.Append($"&password={PasswordParameter:uri}"); + return builder.Build(); } - + /// /// Gets the JDBC connection string for the PostgreSQL server. /// diff --git a/src/Aspire.Hosting.PostgreSQL/README.md b/src/Aspire.Hosting.PostgreSQL/README.md index bac636101ff..e0986d7e541 100644 --- a/src/Aspire.Hosting.PostgreSQL/README.md +++ b/src/Aspire.Hosting.PostgreSQL/README.md @@ -23,7 +23,37 @@ var myService = builder.AddProject() .WithReference(db); ``` +## Connection Properties + +When you reference a PostgreSQL resource using `WithReference`, the following connection properties are made available to the consuming project: + +### PostgreSQL server + +The PostgreSQL server resource exposes the following connection properties: + +| Property Name | Description | +|---------------|-------------| +| `Host` | The hostname or IP address of the PostgreSQL server | +| `Port` | The port number the PostgreSQL server is listening on | +| `Username` | The username for authentication | +| `Password` | The password for authentication | +| `Uri` | The connection URI in postgresql:// format, with the format `postgresql://{Username}:{Password}@{Host}:{Port}` | +| `JdbcConnectionString` | JDBC-format connection string, with the format `jdbc:postgresql://{Host}:{Port}?user={Username}&password={Password}` | + +### PostgreSQL database + +The PostgreSQL database resource inherits all properties from its parent `PostgresServerResource` and adds: + +| Property Name | Description | +|---------------|-------------| +| `Uri` | The connection URI with the database name, with the format `postgresql://{Username}:{Password}@{Host}:{Port}/{DatabaseName}` | +| `JdbcConnectionString` | JDBC connection string with database name, with the format `jdbc:postgresql://{Host}:{Port}/{DatabaseName}?user={Username}&password={Password}` | +| `DatabaseName` | The name of the database | + +Aspire exposes each property as an environment variable named `[RESOURCE]_[PROPERTY]`. For instance, the `Uri` property of a resource called `db1` becomes `DB1_URI`. + ## Additional documentation + https://learn.microsoft.com/dotnet/aspire/database/postgresql-component https://learn.microsoft.com/dotnet/aspire/database/postgresql-entity-framework-component diff --git a/src/Aspire.Hosting.Qdrant/README.md b/src/Aspire.Hosting.Qdrant/README.md index 94fbfc130cb..218f208fe67 100644 --- a/src/Aspire.Hosting.Qdrant/README.md +++ b/src/Aspire.Hosting.Qdrant/README.md @@ -23,7 +23,28 @@ var myService = builder.AddProject() .WithReference(qdrant); ``` +## Connection Properties + +When you reference a Qdrant resource using `WithReference`, the following connection properties are made available to the consuming project: + +### Qdrant server + +The Qdrant server resource exposes the following connection properties: + +| Property Name | Description | +|---------------|-------------| +| `GrpcHost` | The gRPC hostname of the Qdrant server | +| `GrpcPort` | The gRPC port of the Qdrant server | +| `HttpHost` | The HTTP hostname of the Qdrant server | +| `HttpPort` | The HTTP port of the Qdrant server | +| `ApiKey` | The API key for authentication | +| `Uri` | The gRPC connection URI, with the format `http://{GrpcHost}:{GrpcPort}` | +| `HttpUri` | The HTTP connection URI, with the format `http://{HttpHost}:{HttpPort}` | + +Aspire exposes each property as an environment variable named `[RESOURCE]_[PROPERTY]`. For instance, the `Uri` property of a resource called `db1` becomes `DB1_URI`. + ## Additional documentation + * https://qdrant.tech/documentation ## Feedback & contributing diff --git a/src/Aspire.Hosting.RabbitMQ/README.md b/src/Aspire.Hosting.RabbitMQ/README.md index 8ff5e394007..76f75fe3162 100644 --- a/src/Aspire.Hosting.RabbitMQ/README.md +++ b/src/Aspire.Hosting.RabbitMQ/README.md @@ -23,8 +23,27 @@ var myService = builder.AddProject() .WithReference(rmq); ``` +## Connection Properties + +When you reference a RabbitMQ resource using `WithReference`, the following connection properties are made available to the consuming project: + +### RabbitMQ server + +The RabbitMQ server resource exposes the following connection properties: + +| Property Name | Description | +|---------------|-------------| +| `Host` | The hostname or IP address of the RabbitMQ server | +| `Port` | The port number the RabbitMQ server is listening on | +| `Username` | The username for authentication | +| `Password` | The password for authentication | +| `Uri` | The connection URI, with the format `amqp://{Username}:{Password}@{Host}:{Port}` | + +Aspire exposes each property as an environment variable named `[RESOURCE]_[PROPERTY]`. For instance, the `Uri` property of a resource called `db1` becomes `DB1_URI`. + ## Additional documentation -https://learn.microsoft.com/dotnet/aspire/messaging/rabbitmq-client-component + +* https://learn.microsoft.com/dotnet/aspire/messaging/rabbitmq-client-component ## Feedback & contributing diff --git a/src/Aspire.Hosting.Redis/README.md b/src/Aspire.Hosting.Redis/README.md index 3394b3fceed..a9ee8aa6e7f 100644 --- a/src/Aspire.Hosting.Redis/README.md +++ b/src/Aspire.Hosting.Redis/README.md @@ -23,6 +23,23 @@ var myService = builder.AddProject() .WithReference(redis); ``` +## Connection Properties + +When you reference a Redis resource using `WithReference`, the following connection properties are made available to the consuming project: + +### Redis + +The Redis resource exposes the following connection properties: + +| Property Name | Description | +|---------------|-------------| +| `Host` | The hostname or IP address of the Redis server | +| `Port` | The port number the Redis server is listening on | +| `Password` | The password for authentication | +| `Uri` | The connection URI, with the format `redis://:{Password}@{Host}:{Port}` | + +Aspire exposes each property as an environment variable named `[RESOURCE]_[PROPERTY]`. For instance, the `Uri` property of a resource called `db1` becomes `DB1_URI`. + ## Additional documentation * https://learn.microsoft.com/dotnet/aspire/caching/stackexchange-redis-component diff --git a/src/Aspire.Hosting.Seq/README.md b/src/Aspire.Hosting.Seq/README.md index 018f666aeb4..2085c5ff5e9 100644 --- a/src/Aspire.Hosting.Seq/README.md +++ b/src/Aspire.Hosting.Seq/README.md @@ -23,8 +23,25 @@ var myService = builder.AddProject() .WithReference(seq); ``` +## Connection Properties + +When you reference a Seq resource using `WithReference`, the following connection properties are made available to the consuming project: + +### Seq + +The Seq resource exposes the following connection properties: + +| Property Name | Description | +|---------------|-------------| +| `Host` | The hostname or IP address of the Seq server | +| `Port` | The port number the Seq server is listening on | +| `Uri` | The connection URI, with the format `http://{Host}:{Port}` | + +Aspire exposes each property as an environment variable named `[RESOURCE]_[PROPERTY]`. For instance, the `Uri` property of a resource called `db1` becomes `DB1_URI`. + ## Additional documentation -https://learn.microsoft.com/dotnet/aspire/logging/seq-component + +* https://learn.microsoft.com/dotnet/aspire/logging/seq-component ## Feedback & contributing diff --git a/src/Aspire.Hosting.SqlServer/README.md b/src/Aspire.Hosting.SqlServer/README.md index 1c351b16e6f..284fe155c48 100644 --- a/src/Aspire.Hosting.SqlServer/README.md +++ b/src/Aspire.Hosting.SqlServer/README.md @@ -20,9 +20,38 @@ Then, in the _AppHost.cs_ file of `AppHost`, add a SQL Server resource and consu var db = builder.AddSqlServer("sql").AddDatabase("db") var myService = builder.AddProject() - .WithReference(db); + .WithReference(db); ``` +## Connection Properties + +When you reference a SQL Server resource using `WithReference`, the following connection properties are made available to the consuming project: + +### SQL Server server + +The SQL Server server resource exposes the following connection properties: + +| Property Name | Description | +|---------------|-------------| +| `Host` | The hostname or IP address of the SQL Server | +| `Port` | The port number the SQL Server is listening on | +| `Username` | The username for authentication | +| `Password` | The password for authentication | +| `Uri` | The connection URI in mssql:// format, with the format `mssql://{Username}:{Password}@{Host}:{Port}` | +| `JdbcConnectionString` | JDBC-format connection string, with the format `jdbc:sqlserver://{Host}:{Port};user={Username};password={Password};trustServerCertificate=true` | + +### SQL Server database + +The SQL Server database resource inherits all properties from its parent `SqlServerServerResource` and adds: + +| Property Name | Description | +|---------------|-------------| +| `Uri` | The connection URI in mssql:// format, with the format `mssql://{Username}:{Password}@{Host}:{Port}/{DatabaseName}` | +| `JdbcConnectionString` | JDBC connection string with database name, with the format `jdbc:sqlserver://{Host}:{Port};user={Username};password={Password};trustServerCertificate=true;databaseName={DatabaseName}` | +| `DatabaseName` | The name of the database | + +Aspire exposes each property as an environment variable named `[RESOURCE]_[PROPERTY]`. For instance, the `Uri` property of a resource called `db1` becomes `DB1_URI`. + ## Additional documentation https://learn.microsoft.com/dotnet/aspire/database/sql-server-component https://learn.microsoft.com/dotnet/aspire/database/sql-server-entity-framework-component diff --git a/src/Aspire.Hosting.SqlServer/SqlServerDatabaseResource.cs b/src/Aspire.Hosting.SqlServer/SqlServerDatabaseResource.cs index b7feb9dca34..e23a1d9378c 100644 --- a/src/Aspire.Hosting.SqlServer/SqlServerDatabaseResource.cs +++ b/src/Aspire.Hosting.SqlServer/SqlServerDatabaseResource.cs @@ -37,6 +37,15 @@ public ReferenceExpression ConnectionStringExpression } } + /// + /// Gets the connection URI expression for the SQL Server database. + /// + /// + /// Format: mssql://{host}:{port}/{database}. + /// + public ReferenceExpression UriExpression => + ReferenceExpression.Create($"{Parent.UriExpression}/{DatabaseName:uri}"); + /// /// Gets the JDBC connection string for the SQL Server database. /// @@ -59,6 +68,7 @@ private static string ThrowIfNullOrEmpty([NotNull] string? argument, [CallerArgu IEnumerable> IResourceWithConnectionString.GetConnectionProperties() => Parent.CombineProperties([ new("Database", ReferenceExpression.Create($"{DatabaseName}")), + new("Uri", UriExpression), new("JdbcConnectionString", JdbcConnectionString), ]); } diff --git a/src/Aspire.Hosting.SqlServer/SqlServerServerResource.cs b/src/Aspire.Hosting.SqlServer/SqlServerServerResource.cs index 3805c452560..6b95427a315 100644 --- a/src/Aspire.Hosting.SqlServer/SqlServerServerResource.cs +++ b/src/Aspire.Hosting.SqlServer/SqlServerServerResource.cs @@ -56,6 +56,15 @@ public SqlServerServerResource(string name, ParameterResource password) : base(n /// public ReferenceExpression UserNameReference => ReferenceExpression.Create($"{DefaultUserName}"); + /// + /// Gets the connection URI expression for the SQL Server. + /// + /// + /// Format: mssql://{host}:{port}. + /// + public ReferenceExpression UriExpression => + ReferenceExpression.Create($"mssql://{Host}:{Port}"); + internal ReferenceExpression BuildJdbcConnectionString(string? databaseName = null) { var builder = new ReferenceExpressionBuilder(); @@ -72,7 +81,7 @@ internal ReferenceExpression BuildJdbcConnectionString(string? databaseName = nu { var databaseNameReference = ReferenceExpression.Create($"{databaseName:uri}"); builder.AppendLiteral(";databaseName="); - builder.Append($"{databaseNameReference:uri}"); + builder.Append($"{databaseNameReference}"); } builder.AppendLiteral(";trustServerCertificate=true"); @@ -148,6 +157,7 @@ IEnumerable> IResourceWithConnectionSt yield return new("Port", ReferenceExpression.Create($"{Port}")); yield return new("Username", UserNameReference); yield return new("Password", ReferenceExpression.Create($"{PasswordParameter}")); + yield return new("Uri", UriExpression); yield return new("JdbcConnectionString", JdbcConnectionString); } } diff --git a/src/Aspire.Hosting.Valkey/README.md b/src/Aspire.Hosting.Valkey/README.md index 5a1ffd38ceb..8897fb5356a 100644 --- a/src/Aspire.Hosting.Valkey/README.md +++ b/src/Aspire.Hosting.Valkey/README.md @@ -1,10 +1,12 @@ # Aspire.Hosting.Valkey library -Provides extension methods and resource definitions for an Aspire AppHost to configure Cache for Valkey. +Provides extension methods and resource definitions for an Aspire AppHost to configure a Valkey cache resource. -## Install the package +## Getting started -In your AppHost project, install the `Aspire.Hosting.Valkey` library with [NuGet](https://www.nuget.org): +### Install the package + +In your AppHost project, install the Aspire Valkey Hosting library with [NuGet](https://www.nuget.org): ```dotnetcli dotnet add package Aspire.Hosting.Valkey @@ -12,20 +14,31 @@ dotnet add package Aspire.Hosting.Valkey ## Usage example -Then, in the _AppHost.cs_ file of `AppHost`, register a Valkey server and consume the connection using the following methods: +Then, in the _AppHost.cs_ file of `AppHost`, add a Valkey resource and consume the connection using the following methods: ```csharp -var valkey = builder.AddValkey("cache") +var valkey = builder.AddValkey("cache"); var myService = builder.AddProject() .WithReference(valkey); ``` -The `WithReference` method configures a connection in the `MyService` project named `cache`. In the _Program.cs_ file of `MyService`, the redis connection can be consumed using the client library [Aspire.StackExchange.Redis](https://www.nuget.org/packages/Aspire.StackExchange.Redis): +## Connection Properties -```csharp -builder.AddRedisClient("cache"); -``` +When you reference a Valkey resource using `WithReference`, the following connection properties are made available to the consuming project: + +### Valkey + +The Valkey resource exposes the following connection properties: + +| Property Name | Description | +|---------------|-------------| +| `Host` | The hostname or IP address of the Valkey server | +| `Port` | The port number the Valkey server is listening on | +| `Password` | The password for authentication | +| `Uri` | The connection URI, with the format `valkey://:{Password}@{Host}:{Port}` | + +Aspire exposes each property as an environment variable named `[RESOURCE]_[PROPERTY]`. For instance, the `Uri` property of a resource called `db1` becomes `DB1_URI`. ## Additional documentation diff --git a/tests/Aspire.Hosting.Oracle.Tests/ConnectionPropertiesTests.cs b/tests/Aspire.Hosting.Oracle.Tests/ConnectionPropertiesTests.cs index 3339290a6d9..975a54cd8e2 100644 --- a/tests/Aspire.Hosting.Oracle.Tests/ConnectionPropertiesTests.cs +++ b/tests/Aspire.Hosting.Oracle.Tests/ConnectionPropertiesTests.cs @@ -38,6 +38,11 @@ public void OracleDatabaseServerResourceGetConnectionPropertiesReturnsExpectedVa Assert.Equal("{password.value}", property.Value.ValueExpression); }, property => + { + Assert.Equal("Uri", property.Key); + Assert.Equal("oracle://system:{password.value}@{oracle.bindings.tcp.host}:{oracle.bindings.tcp.port}", property.Value.ValueExpression); + }, + property => { Assert.Equal("JdbcConnectionString", property.Key); Assert.Equal("jdbc:oracle:thin:system/{password.value}@//{oracle.bindings.tcp.host}:{oracle.bindings.tcp.port}", property.Value.ValueExpression); diff --git a/tests/Aspire.Hosting.PostgreSQL.Tests/ConnectionPropertiesTests.cs b/tests/Aspire.Hosting.PostgreSQL.Tests/ConnectionPropertiesTests.cs index 7c8476ba9f6..a53cc160659 100644 --- a/tests/Aspire.Hosting.PostgreSQL.Tests/ConnectionPropertiesTests.cs +++ b/tests/Aspire.Hosting.PostgreSQL.Tests/ConnectionPropertiesTests.cs @@ -46,7 +46,7 @@ public void PostgresServerResourceGetConnectionPropertiesReturnsExpectedValues() property => { Assert.Equal("JdbcConnectionString", property.Key); - Assert.Equal("jdbc:postgresql://{postgres.bindings.tcp.host}:{postgres.bindings.tcp.port}", property.Value.ValueExpression); + Assert.Equal("jdbc:postgresql://{postgres.bindings.tcp.host}:{postgres.bindings.tcp.port}?user={user.value}&password={password.value}", property.Value.ValueExpression); }); } @@ -72,6 +72,6 @@ public void PostgresDatabaseResourceGetConnectionPropertiesIncludesDatabaseSpeci Assert.Contains( properties, property => property.Key == "JdbcConnectionString" && - property.Value.ValueExpression == "jdbc:postgresql://{postgres.bindings.tcp.host}:{postgres.bindings.tcp.port}/Customers"); + property.Value.ValueExpression == "jdbc:postgresql://{postgres.bindings.tcp.host}:{postgres.bindings.tcp.port}/Customers?user={user.value}&password={password.value}"); } } \ No newline at end of file diff --git a/tests/Aspire.Hosting.SqlServer.Tests/ConnectionPropertiesTests.cs b/tests/Aspire.Hosting.SqlServer.Tests/ConnectionPropertiesTests.cs index cc17108794d..14c47e65b92 100644 --- a/tests/Aspire.Hosting.SqlServer.Tests/ConnectionPropertiesTests.cs +++ b/tests/Aspire.Hosting.SqlServer.Tests/ConnectionPropertiesTests.cs @@ -38,6 +38,11 @@ public void SqlServerServerResourceGetConnectionPropertiesReturnsExpectedValues( Assert.Equal("{password.value}", property.Value.ValueExpression); }, property => + { + Assert.Equal("Uri", property.Key); + Assert.Equal("mssql://{sql.bindings.tcp.host}:{sql.bindings.tcp.port}", property.Value.ValueExpression); + }, + property => { Assert.Equal("JdbcConnectionString", property.Key); Assert.Equal("jdbc:sqlserver://{sql.bindings.tcp.host}:{sql.bindings.tcp.port};user=sa;password={password.value};trustServerCertificate=true", property.Value.ValueExpression); diff --git a/tests/Aspire.Hosting.Tests/ManifestGenerationTests.cs b/tests/Aspire.Hosting.Tests/ManifestGenerationTests.cs index 4cd53c05c89..a88c6336b64 100644 --- a/tests/Aspire.Hosting.Tests/ManifestGenerationTests.cs +++ b/tests/Aspire.Hosting.Tests/ManifestGenerationTests.cs @@ -398,7 +398,7 @@ public void VerifyTestProgramFullManifest() "POSTGRESDB_USERNAME": "postgres", "POSTGRESDB_PASSWORD": "{postgres-password.value}", "POSTGRESDB_URI": "postgresql://postgres:{postgres-password.value}@{postgres.bindings.tcp.host}:{postgres.bindings.tcp.port}/postgresdb", - "POSTGRESDB_JDBCCONNECTIONSTRING": "jdbc:postgresql://{postgres.bindings.tcp.host}:{postgres.bindings.tcp.port}/postgresdb", + "POSTGRESDB_JDBCCONNECTIONSTRING": "jdbc:postgresql://{postgres.bindings.tcp.host}:{postgres.bindings.tcp.port}/postgresdb?user=postgres\u0026password={postgres-password-uri-encoded.value}", "POSTGRESDB_DATABASE": "postgresdb" }, "bindings": {