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..979e644be 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`: +When Aspire injects a connection property with the `[RESOURCE]_[PROPERTY]` pattern, it transforms the two parts differently. For the resource-name prefix, Aspire replaces each character that isn't an ASCII letter or digit with an underscore, prefixes an underscore when the name starts with a digit, and uppercases the result. For the property suffix, Aspire only uppercases the property key. 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 ``` +For an Event Hubs consumer group resource named `orders-cg`, the resource-name encoder produces `ORDERS_CG`; separately, uppercasing the `ConsumerGroupName` property key produces `CONSUMERGROUPNAME`. Aspire joins them as `ORDERS_CG_CONSUMERGROUPNAME`. + 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.