You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Connection-string environment variables currently preserve the logical resource name, so a resource such as my-db produces ConnectionStrings__my-db. Names containing characters such as - are rejected or mishandled by strict deployment targets, which can make an otherwise valid AppHost fail during deployment.
This change separates logical connection names from physical environment-variable names:
WithReference preserves the logical .NET configuration name and emits both the legacy and portable physical aliases when the target supports them.
Portable aliases use a shared encoder, avoid nested __ configuration delimiters, and fail early on case-insensitive collisions.
Azure App Service and Kubernetes project only the portable alias while retaining validation for unrelated invalid environment variables.
Aspire client integrations resolve the logical key through the composed configuration first, then fall back to the portable key.
Qdrant supplemental HTTP references and EF migration bundles use the same naming contract.
The migration path and guidance for direct IConfiguration consumers are documented.
Capable targets receive ConnectionStrings__my-db and ConnectionStrings__my_db. Strict targets receive ConnectionStrings__my_db, and updated Aspire integrations resolve it using the logical name my-db.
Applications using older integrations or direct configuration lookup on strict targets can migrate explicitly:
This recovery advice is incorrect when either conflicting reference uses an explicit physical name. For example, two Application Insights references always target APPLICATIONINSIGHTS_CONNECTION_STRING; changing connectionName does not change that physical name, so following this message produces the same exception. Tailor the guidance for IsExplicit collisions so it points callers toward changing/avoiding the explicit physical-name conflict.
throw new DistributedApplicationException(
$"Connection-string references '{existing.EnvironmentVariableNames.LogicalName}' and " +
$"'{candidate.EnvironmentVariableNames.LogicalName}' on resource '{destination.Name}' both use " +
$"the environment variable '{conflictingName}'. Use unique connectionName values when calling WithReference.");
The collision covered by the new test uses already-unique caller-supplied names (search and search_http), so telling the caller to use unique connectionName values does not explain how to resolve it. The conflict is with Qdrant's generated _http alias; identify that constraint in the message so callers know to choose names whose primary and supplemental aliases do not overlap.
throw new DistributedApplicationException(
$"Connection-string references '{existing.EnvironmentVariableNames.LogicalName}' and " +
$"'{candidate.EnvironmentVariableNames.LogicalName}' on resource '{destination.Name}' both use " +
$"the environment variable '{conflictingName}'. Use unique connectionName values when calling WithReference.");
This changes the deployed App Service environment contract, but the new coverage only validates the generated Bicep. It does not prove that App Service preserves ConnectionStrings__my_db at runtime or that an Aspire client registered with the logical name my-db can consume it. Please extend an App Service deployment E2E scenario with a dashed connection resource and verify the deployed workload successfully uses that client; this is the regression the PR is intended to fix.
The Kubernetes path now changes which environment variable reaches a real pod, but the added coverage stops at Helm/YAML snapshots. It does not catch API-server validation, Helm projection, or .NET configuration binding failures after deployment. Please extend an AKS/Kubernetes deployment E2E test with a dashed connection name and verify a deployed Aspire client can use the connection.
ConnectionStringExpression is mode/configuration dependent for resources such as Azure Cosmos DB and Storage. Capturing its current expression here makes the annotation stale if the source is later switched to an emulator; a subsequent reference to the same resource is then incorrectly rejected because equivalence compares the old and new strings. Use the resource's stable manifest expression (the same contract used by ConnectionStringReference) instead.
This public constructor accepts null for all three non-nullable names and stores an invalid instance. Consumers such as the App Service projector then pass PortableName to Dictionary.ContainsKey, which throws for a null key. Add constructor validation for LogicalName, LegacyName, and PortableName (or make construction private and require Create).
public sealed record ConnectionStringEnvironmentVariableNames(
string LogicalName,
string LegacyName,
string PortableName,
bool IsExplicit)
Test value: https://portable-alias-test.vault.azure.net/
The workload used the current Aspire.Azure.Security.KeyVault integration and called AddAzureKeyVaultClient("my-vault"). Its endpoint injected SecretClient and returned SecretClient.VaultUri, so a successful response proves that the updated integration
resolved the portable environment variable under the original dashed logical name.
Live deployment matrix
Target
Deployment
Environment variables
Client integration
Docker Compose
Passed
Legacy and portable aliases
Resolved my-vault
Azure Container Apps
Passed
Legacy and portable aliases
Resolved my-vault
Azure App Service
Passed
Portable alias only
Resolved my-vault
Azure Kubernetes Service
Passed
Portable alias only
Resolved my-vault
Kubernetes Helm publisher
Passed on the AKS cluster
Portable alias only
Resolved my-vault
Radius
Passed on the AKS cluster
Portable alias only
Resolved my-vault
Foundry Hosted Agents
Provisioning passed
Portable alias only
See Foundry limitation below
Docker Compose and Container Apps intentionally retain both aliases because they support
dashes. App Service, AKS/Kubernetes, Radius, and Foundry project generated connection-string
references to the portable alias only.
Foundry Hosted Agents
Foundry deployment completed successfully and created an active hosted-agent version. The
deployed version contained ConnectionStrings__my_vault with the expected value and did not
contain ConnectionStrings__my-vault.
The exact published linux/amd64 image was pulled and run locally. Its /readiness endpoint
returned HTTP 200, and its diagnostics endpoint showed:
Cloud invocation returned session_not_ready even after using the documented port and
readiness contract. This is consistent with the existing Foundry deployment-test blocker
tracked by #16330, so hosted-agent runtime invocation is inconclusive. The deployment payload
and locally executed deployment image both verify the connection-string behavior.
The connection-string portion of the reported stack trace is fixed. Generated references such
as ConnectionStrings__ai-light-model now have a portable alias that Foundry can deploy.
The issue also reported service-discovery variables such as services__analytics-api__http__0. A focused reproduction against the current PR confirms
that this generated key still reaches Foundry validation and is rejected because it contains
a dash. Therefore, #19674 is not fully fixed for every environment-variable kind.
This PR should not claim that service-discovery names are normalized: changing analytics-api to analytics_api would also change the .NET configuration key and break
lookup by the original logical service name. That requires a separate compatibility design.
Permanent coverage
The App Service and AKS deployment E2E tests now install the current Key Vault client
integration, register AddAzureKeyVaultClient("deployment-test"), inject SecretClient, and
assert its resolved URI. They no longer read deployment_test directly from configuration.
This preserves coverage of the important compatibility boundary: strict publisher emits the
portable physical key while the application continues using the original logical name.
The deployment E2E test project builds with zero warnings and errors.
Cleanup
Docker Compose resources removed.
Kubernetes Helm release and namespace removed.
Radius application and control plane removed.
Container Apps, App Service, and Foundry resource groups deleted.
AKS resource-group deletion initiated and monitored.
Port-forward processes stopped.
Temporary source-linked deployment harnesses removed from the worktree.
Result
Portable connection-string alias behavior is verified across all publisher targets.
Issue #19674 is only partially fixed: its connection-string failures are addressed, but
the reported dashed service-discovery environment variables remain unsupported by Foundry.
The remediation is misleading for normalization collisions: my-db and my_db are already distinct connectionName values, yet this exception tells users only to make them unique. Tell users to choose names whose portable environment-variable aliases are distinct (or show the encoded aliases), so the error explains how to resolve the failure.
throw new DistributedApplicationException(
$"Connection-string references '{existing.EnvironmentVariableNames.LogicalName}' and " +
$"'{candidate.EnvironmentVariableNames.LogicalName}' on resource '{destination.Name}' both use " +
$"the environment variable '{conflictingName}'. Use unique connectionName values when calling WithReference.");
For a primary/HTTP collision this produces references 'search_http' and 'search_http' and then recommends unique connectionName values, even though the caller used the distinct names search and search_http. Explain that each Qdrant reference reserves both the primary alias and its _http companion, and advise choosing names whose generated aliases do not overlap.
throw new DistributedApplicationException(
$"Connection-string references '{existing.EnvironmentVariableNames.LogicalName}' and " +
$"'{candidate.EnvironmentVariableNames.LogicalName}' on resource '{destination.Name}' both use " +
$"the environment variable '{conflictingName}'. Use unique connectionName values when calling WithReference.");
Use original terminology for connection-string metadata, publisher consumers, documentation, and the alias test without changing behavior.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: af599a10-84bd-4288-8f55-3e9915433275
When connection-string injection is disabled, this annotation does not exist (ResourceBuilderExtensions only adds it under the ConnectionString flag), but connection properties are still splatted using an explicit connectionName. For example, WithReferenceEnvironment(ConnectionProperties).WithReference(sql, "admin") emits ADMIN_PASSWORD, while this method records only the relationship fallback SQL_; Radius then misclassifies the genuine injected credential as unrelated and can emit ASPIRERADIUS070. Preserve the logical alias independently of connection-string emission (without re-enabling collision checks for suppressed strings), and cover this flags-plus-alias case.
Document double-underscore normalization in portable aliases
The portable alias is also generated when the logical name contains __, even though underscores are valid environment-variable characters, because __ would become a nested configuration delimiter. As written, the public documentation incorrectly describes only unsupported-character replacement and omits this observable normalization (for example, db__primary becomes db_primary).
This guidance cannot resolve collisions involving an explicit IResourceWithConnectionString.ConnectionStringEnvironmentVariable: Create deliberately ignores connectionName and preserves that physical name. Emit guidance that tells users to change the explicit physical name when applicable (or distinguish explicit from generated aliases), rather than always recommending connectionName.
The reason will be displayed to describe this comment to others. Learn more.
Copilot review overview
🔵 Needs a closer look
Properties-only aliased Radius references lose required logical metadata, and the new runtime package dependency is missing from conditional-test routing.
Review effort: Balanced Findings: None
Previously missed (2)
In code that hasn't changed since last review
Preserve logical reference metadata without connection-string injection
Recording this metadata only when the connection string itself is injected loses the custom logical name for properties-only references. Radius now derives connection-property provenance from this annotation; with .WithReferenceEnvironment(ConnectionProperties).WithReference(sql, "admin"), no annotation is added, the relationship fallback records sql, and the generated ADMIN_PASSWORD is incorrectly reported as an unrelated credential use (ASPIRERADIUS070). Preserve the logical reference metadata even when connection-string injection is disabled, while keeping physical-name collision validation limited to references that actually inject connection strings.
Add Key Vault package to deployment E2E trigger mapping
This adds Aspire.Azure.Security.KeyVault as a runtime-only dependency of this deployment scenario (and the App Service scenario), but eng/github-ci/test-trigger-map.yml routes only Aspire.Hosting.Azure* and related projects to job:deployment-e2e. Changes to the Key Vault client package therefore won't report this advisory deployment coverage. Add Aspire.Azure.Security.KeyVault to the deployment E2E affected-project rule and cover the edge in TestTriggerMapTests.
ConnectionStringReference metadata tracks connection-string injection, not connection-property injection, so it cannot reliably identify splat prefixes here. With ConnectionString only, this records the logical prefix even though no properties were emitted and can suppress ASPIRERADIUS070 for a user-authored <LOGICAL>_PASSWORD; with ConnectionProperties only, no reference annotation is added, so an aliased property such as ADMIN_PASSWORD is incorrectly reported as unrelated. Persist dedicated connection-property injection metadata (including the logical name and flags) and build these prefixes only from references that actually splatted properties.
Document ArgumentNullException in the public method XML docs
This new public method throws ArgumentNullException for both parameters, but its XML documentation omits that contract. Public APIs under src/ must document thrown exceptions; add an <exception> entry naming both parameters.
This adds a runtime-only dependency on the repository-built Aspire.Azure.Security.KeyVault package, but eng/github-ci/test-trigger-map.yml has no rule routing changes to that component to job:deployment-e2e (the existing rule covers Aspire.Hosting.Azure*, not Aspire.Azure.*). A future change to this package can therefore skip the deployment scenario that now validates portable aliases; add the package to the deployment E2E affected-project/path routing and its focused map coverage.
Route Key Vault package changes to deployment E2E tests
This adds a runtime-only dependency on the repository-built Aspire.Azure.Security.KeyVault package, but eng/github-ci/test-trigger-map.yml has no rule routing changes to that component to job:deployment-e2e (the existing rule covers Aspire.Hosting.Azure*, not Aspire.Azure.*). A future change to this package can therefore skip the deployment scenario that now validates portable aliases; add the package to the deployment E2E affected-project/path routing and its focused map coverage.
Document OriginalName behavior for explicit physical overrides
OriginalName is documented as derived directly from logicalName, but Create returns resource.ConnectionStringEnvironmentVariable when an explicit physical override exists and assigns that value to both names. The public metadata is therefore misleading for explicit resources; document that exception here as well.
🔧 src/Components/Aspire.Oracle.EntityFrameworkCore/Aspire.Oracle.EntityFrameworkCore.csproj(changed source)
→ 1 via the project graph: Aspire.Hosting.Oracle.Tests
The release notes already cover portable aliases and migration. The canonical environment-variable guide still claimed connection-string names were never encoded and showed original-only lookups. This draft fixes that one page; it doesn't duplicate the release notes or modify the open release rollup, microsoft/aspire.dev#1599.
docs_required, no exclusion. All four signals are addressed: experimental_attribute_added (ASPIRECONNECTIONSTRINGS001 on the naming record/property); new_public_type (ConnectionStringEnvironmentVariableNames); integration_readme_changed (App Service physical-name exceptions and Radius property-prefix distinction); and pr_body_has_user_facing_section (logical/portable names and migration). The guide now covers strict targets, encoding, collisions, explicit overrides, logical-first configuration fallback, and experimental custom-publisher metadata.
The target is an exact match for milestone 13.6. No feature-specific duplicate was found. Rendering, anchors, and changed consumer examples were checked locally.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Connection-string environment variables currently preserve the logical resource name, so a resource such as
my-dbproducesConnectionStrings__my-db. Names containing characters such as-are rejected or mishandled by strict deployment targets, which can make an otherwise valid AppHost fail during deployment.This change separates logical connection names from physical environment-variable names:
WithReferencepreserves the logical .NET configuration name and emits both the legacy and portable physical aliases when the target supports them.__configuration delimiters, and fail early on case-insensitive collisions.IConfigurationconsumers are documented.User-facing usage
Existing AppHost code remains unchanged:
Capable targets receive
ConnectionStrings__my-dbandConnectionStrings__my_db. Strict targets receiveConnectionStrings__my_db, and updated Aspire integrations resolve it using the logical namemy-db.Applications using older integrations or direct configuration lookup on strict targets can migrate explicitly:
Validation
Fixes # (issue)
Checklist
<remarks />and<code />elements on your triple slash comments?