Skip to content

[docs] Expand 13.2 Connection property suffix breaking change with migration guidance #944

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
IEvangelist wants to merge 1 commit into
base: main
Choose a base branch
from
+7 −3
Open

[docs] Expand 13.2 Connection property suffix breaking change with migration guidance #944

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 7 additions & 3 deletions src/frontend/src/content/docs/whats-new/aspire-13-2.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1227,21 +1227,23 @@ The `BeforeResourceStartedEvent` now only fires when actually starting a resourc

Several connection properties for "named entity" resources gained an explicit `Name` suffix so the property clearly refers to the entity's name rather than the entity itself. This affects both the connection-property API (`GetConnectionProperty`) and the environment variables Aspire injects via `WithReference(...)` and `ReferenceEnvironmentInjectionFlags.ConnectionProperties`.

A subset of these renames first shipped in 13.1; 13.2 completes the rollout across the remaining built-in resources. The full list of renamed properties as of 13.2 is:
A subset of these renames first shipped in [13.1](/whats-new/aspire-13-1/#connection-properties-rename); 13.2 completes the rollout across the remaining built-in resources, so apps upgrading directly from 13.0 to 13.2 encounter all of them at once. The full list of renamed properties as of 13.2 is:

| Old property name | New property name | Affected resources |
| ----------------- | ----------------- | ------------------ |
| `Database` | `DatabaseName` | `PostgresDatabase`, `AzurePostgresFlexibleServerDatabase`, `MySqlDatabase`, `SqlServerDatabase`, `AzureSqlDatabase`, `OracleDatabase`, `MongoDBDatabase`, `MilvusDatabase`, `AzureCosmosDBDatabase`, `AzureKustoReadWriteDatabase` |
| `Model` | `ModelName` | `OpenAIModel`, `AzureOpenAIDeployment`, `FoundryDeployment`, `GitHubModel` |
| `ConsumerGroup` | `ConsumerGroupName` | `AzureEventHubConsumerGroup` |

Aspire serializes property names directly into environment variable names with the `[RESOURCE]_[PROPERTY]` pattern, so any consuming app that reads the renamed properties from the environment must use the new uppercase names. For example, a SQL Server database resource named `sqldb`:
Aspire serializes property names directly into environment variable names with the `[RESOURCE]_[PROPERTY]` pattern — the resource name is uppercased and any hyphens or dots in it are replaced with underscores — so any consuming app that reads the renamed properties from the environment must use the new names. For example, a SQL Server database resource named `sqldb`:

```diff title="Environment variable"
- SQLDB_DATABASE=catalog
+ SQLDB_DATABASENAME=catalog
```

The renamed suffix flows through that same transformation, so an Event Hubs consumer group resource named `orders-cg` surfaces its `ConsumerGroupName` property as the `ORDERS_CG_CONSUMERGROUPNAME` environment variable.

Update consuming app code that reads the variable directly:

<Tabs syncKey="aspire-consuming-lang">
Expand Down Expand Up @@ -1286,7 +1288,9 @@ If your AppHost code reads connection properties through the `IResourceWithConne
+ var database = sqldb.Resource.GetConnectionProperty("DatabaseName");
```

To migrate, search your solution for the affected uppercase environment variable names (for example, `_DATABASE`, `_MODEL`, and `_CONSUMERGROUP`) along with `GetConnectionProperty("Database")`, `GetConnectionProperty("Model")`, and `GetConnectionProperty("ConsumerGroup")`, and apply the rename. Properties not listed in the table — for example, `Endpoint`, `Host`, `Port`, `Username`, `Password`, `Uri`, and `Key` — are unchanged.
To migrate, search your solution for the affected uppercase environment variable names (for example, `_DATABASE`, `_MODEL`, and `_CONSUMERGROUP`) along with `GetConnectionProperty("Database")`, `GetConnectionProperty("Model")`, and `GetConnectionProperty("ConsumerGroup")`, and apply the rename. Also update any custom Bicep, Helm, or other deployment templates that hard-code the old property keys when emitting connection metadata. Properties not listed in the table — for example, `Endpoint`, `Host`, `Port`, `Username`, `Password`, `Uri`, and `Key` — are unchanged.

C# apps that consume the Aspire client integrations (for example, `AddNpgsqlDataSource`, `AddAzureOpenAIClient`, or `AddMongoDBClient`) don't need source changes. Those packages resolve the connection string through `ConnectionStrings:<resource-name>`, which is unaffected by this rename.

<Aside type="note">
Properties that don't refer to a named entity were not renamed. For example, the
Expand Down
Loading