From c86c69ede99b1abd9646c90d84170ef339790964 Mon Sep 17 00:00:00 2001 From: David Pine Date: Wed, 13 May 2026 19:15:58 -0500 Subject: [PATCH] [docs] Expand 13.2 Connection property suffix breaking change with migration guidance The 13.2 `Connection property suffix` breaking change was only a single sentence on the live changelog, which left readers without enough detail to confidently migrate apps upgrading directly from 13.0 to 13.2. Expand the section with: - A short explanation of the rename pattern (properties whose value is the name of a sub-entity now end with `Name`). - A canonical table covering all 15 affected resource types grouped by rename (`Database` -> `DatabaseName`, `Model` -> `ModelName`, `ConsumerGroup` -> `ConsumerGroupName`). - Before/after environment-variable examples showing the impact on consuming apps that read connection properties through `WithReference`. - Before/after C# examples for `GetConnectionProperty` callers in the AppHost. - A migration checklist for searching solutions, including a clear note that C# apps consuming the standard Aspire client integrations do not need source changes. - Cross-link to the partial 13.1 changelog entry, with the 13.2 entry as the canonical reference. Anchor `#connection-property-suffix` is preserved so external links keep working. Fixes #413 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../src/content/docs/whats-new/aspire-13-2.mdx | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/src/frontend/src/content/docs/whats-new/aspire-13-2.mdx b/src/frontend/src/content/docs/whats-new/aspire-13-2.mdx index a49d3df8b..b014d02f3 100644 --- a/src/frontend/src/content/docs/whats-new/aspire-13-2.mdx +++ b/src/frontend/src/content/docs/whats-new/aspire-13-2.mdx @@ -1227,7 +1227,7 @@ 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 | | ----------------- | ----------------- | ------------------ | @@ -1235,13 +1235,15 @@ A subset of these renames first shipped in 13.1; 13.2 completes the rollout acro | `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: @@ -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:`, which is unaffected by this rename.