docs: expand Connection Property Suffix migration guidance for Aspire 13.2 - #1167
docs: expand Connection Property Suffix migration guidance for Aspire 13.2#1167David Pine (IEvangelist) with Copilot wants to merge 2 commits into
Conversation
… in 13.2 Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
Expands the Aspire 13.2 “Connection property suffix” breaking-change entry to give actionable migration guidance for users whose consuming apps or AppHost code reads connection properties/environment variables directly.
Changes:
- Adds a rename table covering
Database→DatabaseName,Model→ModelName, andConsumerGroup→ConsumerGroupNameacross multiple resource types. - Adds before/after environment variable examples to show the concrete injected name changes.
- Adds step-by-step migration instructions, including guidance for updating
GetConnectionProperty()calls.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| ### Connection property suffix | ||
|
|
||
| A connection property suffix has been added which may require updates to code that accesses connection properties directly. | ||
| To make it unambiguous that connection properties like `Database` and `Model` carry *name* strings rather than data objects, Aspire 13.2 adds an explicit `Name` suffix to those properties across all built-in resource types (see [microsoft/aspire#13471](https://github.com/microsoft/aspire/pull/13471)). |
| 1. **Find all reads of the old environment variable names.** Search your consuming apps for the old pattern, for example `_DATABASE`, `_MODEL`, or `_CONSUMERGROUP`: | ||
|
|
||
| ```bash title="Bash — Finding affected reads" | ||
| grep -r "_DATABASE\|_MODEL\|_CONSUMERGROUP" ./src |
There was a problem hiding this comment.
#944 already merged this surface, so I think this PR should close as superseded rather than be updated. The merged guidance appears to have the same release-boundary and example problems I left inline; those need a follow-up against main.
| ### Connection property suffix | ||
|
|
||
| A connection property suffix has been added which may require updates to code that accesses connection properties directly. | ||
| To make it unambiguous that connection properties like `Database` and `Model` carry *name* strings rather than data objects, Aspire 13.2 adds an explicit `Name` suffix to those properties across all built-in resource types (see [microsoft/aspire#13471](https://github.com/microsoft/aspire/pull/13471)). |
There was a problem hiding this comment.
This shipped in 13.1 via backport #13516 (commit d6668f5 is in v13.1.0), so this section is on the wrong release page and the 13.2/≤13.1 boundaries are off by one. Could we move this to the 13.1 page and use ≤13.0/13.1?
|
|
||
| | Old property name | New property name | Affected resources | | ||
| | --- | --- | --- | | ||
| | `Database` | `DatabaseName` | PostgreSQL database, SQL Server database, MySQL database, MongoDB database, Oracle database, Milvus database, Azure Cosmos DB database, Azure PostgreSQL Flexible Server database, Azure SQL database, Azure Data Explorer (Kusto) database | |
There was a problem hiding this comment.
Several Azure resources listed here never shipped with the old unsuffixed names; their connection properties were introduced already suffixed in 13.1. Could we limit the migration table to resources that actually had a released rename?
| ``` | ||
|
|
||
| ```bash title="Bash — After (Aspire 13.2)" | ||
| CHAT_MODELNAME=gpt-4o-mini |
There was a problem hiding this comment.
AzureOpenAIDeploymentResource.ModelName resolves to the deployment name, not the underlying model ID, so gpt-4o-mini is misleading here. Could we use a GitHub Models example, or show the actual deployment name?
| 1. **Find all reads of the old environment variable names.** Search your consuming apps for the old pattern, for example `_DATABASE`, `_MODEL`, or `_CONSUMERGROUP`: | ||
|
|
||
| ```bash title="Bash — Finding affected reads" | ||
| grep -r "_DATABASE\|_MODEL\|_CONSUMERGROUP" ./src |
There was a problem hiding this comment.
This also matches already-migrated names like _DATABASENAME/_MODELNAME, and it doesn't find the direct GetConnectionProperty("...") calls covered in step 3. Could we anchor the old suffixes and add a second search for those property keys?
The
### Connection property suffixbreaking-change entry inwhats-new/aspire-13-2.mdxwas a single placeholder sentence with no actionable guidance for users upgrading from 13.1.Changes
whats-new/aspire-13-2.mdxto cover microsoft/aspire#13471:Database→DatabaseName— PostgreSQL, SQL Server, MySQL, MongoDB, Oracle, Milvus, Azure Cosmos DB, Azure PostgreSQL Flexible Server, Azure SQL, Azure Data ExplorerModel→ModelName— Azure AI Foundry, Azure OpenAI, OpenAI, GitHub ModelsConsumerGroup→ConsumerGroupName— Azure Event Hubs consumer groups<Steps>) covering: grep search pattern, updating env var reads in consuming apps, and updatingGetConnectionProperty()calls in AppHost codeBefore/after snapshot: