Skip to content

Graduate connection-string physical-name metadata - #22161

Merged
Maddy Montaquila (maddymontaquila) merged 1 commit into
release/17.0from
maddymontaquila/stabilize-connection-string-names
Nov 15, 2026
Merged

Maddy Montaquila (maddymontaquila) merged 1 commit into
release/17.0from
maddymontaquila/stabilize-connection-string-names

Conversation

@maddymontaquila

@maddymontaquila Maddy Montaquila (maddymontaquila) commented Nov 11, 2026 •

Copy link
Copy Markdown
Collaborator

Description

Consumers and publishers can use connection-string physical-name metadata without suppressing ASPIRECONNECTIONSTRINGS001. This draft proposes graduating only ConnectionStringEnvironmentVariableNames and ConnectionStringReference.EnvironmentVariableNames, preserving their functionality and public shape.

Removes the two Experimental attributes and their directly related source/test suppressions. Documents diagnostic retirement and the existing record-copy behavior. No injection, normalization, collision, precedence, or publisher-projection code changes; no generated api/*.cs baseline edits.

Contract review required before marking ready

The user explicitly requested proposing both existing contracts as stable in a draft and flagging them for review. This is not a claim of maintainer API approval or upstream GA.

  • Confirm the compatibility contract: capable targets retain original and portable aliases; strict targets project the portable alias; explicit physical names remain exact; alias collisions continue to fail. The existing logical-first client lookup and migration constraints remain unchanged.
  • Confirm public record mutability: all four properties retain init accessors and with copies can independently change names without recomputing the other properties. The constructor remains internal; Create derives consistent names.

Both contracts are included in this proposal, so no replacement experimental diagnostic is introduced. If review decides a portion should remain unstable, split that portion under a focused diagnostic before marking this PR ready rather than changing injection behavior to remove a warning.

User-facing usage

For an existing IResourceWithConnectionString resource, no experimental-warning suppression is needed:

var names = ConnectionStringEnvironmentVariableNames.Create(resource, "my-db");
foreach (var physicalName in names.GetPhysicalNames())
{
    Console.WriteLine(physicalName);
}

This still yields ConnectionStrings__my-db and ConnectionStrings__my_db. Consumers of generated references can read reference.EnvironmentVariableNames; standalone two-argument references still return null metadata.

Original API attribution

cc Sébastien Ros (@sebastienros): the source introducing commit eefbb6d47d adds both APIs in #19729. Source history and the GitHub commit author identity agree on this login; this is a mention, not a reviewer assignment. No attribution uncertainty identified.

Release branch replay

Replayed only the original stabilization commit db05c2a75dee758f01fa671c67f0ba9820881ac6, using its verified main fork point 793dfe6e254fe050af24cb7bcfba214066dcaab8, onto release/17.0 at 9a97ab889bfb731de74ead0280be279ffdd000bf. The new head is 2d33e4cb5aef87bbb76e69b85478b75af454d1a7: one intended commit, 14 changed files, 13 insertions and 25 deletions. No conflicts or release-specific code adaptations were needed; git range-diff confirms the patch is unchanged. Unrelated main history is excluded.

Validation — release/17.0

The following commands were rerun against the release-based head on macOS arm64 with the existing installed .NET SDK; quarantined and outerloop tests were excluded. Existing tests compile without this diagnostic's suppressions.

  • dotnet test --project tests/Aspire.Hosting.Tests/Aspire.Hosting.Tests.csproj --no-launch-profile -- --filter-class '*WithReferenceTests*' --filter-not-trait 'quarantined=true' --filter-not-trait 'outerloop=true' — passed, 65 tests.
  • dotnet test --project tests/Aspire.Hosting.Qdrant.Tests/Aspire.Hosting.Qdrant.Tests.csproj --no-launch-profile -- --filter-method '*.QdrantClientAppWithReferenceContainsConnectionStrings' --filter-method '*.WithReferenceDispatchesQdrantReference' --filter-method '*.WithReferenceRejectsPrimaryAndHttpAliasCollision' --filter-method '*.RepeatedReferencesPreserveDistinctConnectionExpressions' --filter-not-trait 'quarantined=true' --filter-not-trait 'outerloop=true' — passed, 5 tests on sequential retry.
  • dotnet test --project tests/Aspire.Hosting.Foundry.Tests/Aspire.Hosting.Foundry.Tests.csproj --no-launch-profile -- --filter-method '*.GetResolvedEnvironmentVariables_*' --filter-not-trait 'quarantined=true' --filter-not-trait 'outerloop=true' — passed, 6 tests on sequential retry.
  • git diff --check origin/release/17.0...HEAD — passed.
  • git range-diff db05c2a75dee758f01fa671c67f0ba9820881ac6^..db05c2a75dee758f01fa671c67f0ba9820881ac6 origin/release/17.0..HEAD — passed; one unchanged patch.

Initial concurrent Qdrant and Foundry attempts failed during NuGet restore with generated .nuget.g.props files already existing. Both commands passed when rerun individually after the hosting run completed; no source workaround was needed.

Historical main validation (original head db05c2a75dee758f01fa671c67f0ba9820881ac6): the same three test commands previously passed 65, 5 and 6 tests respectively, and git diff --check passed. Those earlier results are not substituted for the release results above.

Full repository build and live deployment tests were not run; runtime behavior is unchanged.

Fixes # (issue)

Checklist

  • Is this feature complete?
    • Yes. Ready to ship.
    • No. Follow-up changes expected.
  • Are you including unit tests for the changes and scenario tests if relevant?
    • Yes
    • No
  • Did you add public API?
    • Yes
      • If yes, did you have an API Review for it?
        • Yes
        • No
      • Did you add <remarks /> and <code /> elements on your triple slash comments?
        • Yes
        • No
    • No
  • Does the change make any security assumptions or guarantees?
    • Yes
      • If yes, have you done a threat model and had a security review?
        • Yes
        • No
    • No

@aspire-repo-bot
aspire-repo-bot Bot requested a balanced review from Copilot November 11, 2026 19:38
@github-actions github-actions Bot added the area-app-model Issues pertaining to the APIs in Aspire.Hosting, e.g. DistributedApplication label Nov 11, 2026
@github-actions

Copy link
Copy Markdown
Contributor

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 22161

Or

  • Run remotely in PowerShell:
iex "& { $(irm https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 22161"

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

Public API graduation still requires maintainer confirmation of alias-projection compatibility and independently mutable init/with record-copy properties as long-term commitments.

No open issues 🎉

What changed in this PR

This draft proposes stabilizing Aspire’s connection-string physical-name metadata APIs introduced in #19729, without changing their public shape or runtime behavior. Compatibility and record-mutability contracts remain subject to maintainer review.

Changes:

  • Removes experimental markers from ConnectionStringEnvironmentVariableNames and ConnectionStringReference.EnvironmentVariableNames.
  • Removes related warning suppressions from consumers and existing tests.
  • Documents diagnostic retirement and independent property initialization in record copies.
File Description
tests/​Aspire.Hosting.Tests/​WithReferenceTests.cs Removes suppression around standalone-reference metadata assertions.
tests/​Aspire.Hosting.Qdrant.Tests/​AddQdrantTests.cs Removes suppression around connection-name metadata assertions.
tests/​Aspire.Hosting.Foundry.Tests/​HostedAgentExtensionTests.cs Removes suppression from reference-resolution coverage.
src/​Aspire.Hosting/​ResourceBuilderExtensions.cs Removes the retired diagnostic suppression.
src/​Aspire.Hosting/​ApplicationModel/​ConnectionStringReference.cs Removes the property’s experimental marker and related suppression.
src/​Aspire.Hosting/​ApplicationModel/​ConnectionStringEnvironmentVariableNames.cs Removes the type’s experimental marker and documents record-copy behavior.
src/​Aspire.Hosting.Radius/​Publishing/​RadiusInfrastructureBuilder.cs Removes the metadata diagnostic suppression.
src/​Aspire.Hosting.Qdrant/​QdrantBuilderExtensions.cs Removes the metadata diagnostic suppression.
src/​Aspire.Hosting.Kubernetes/​KubernetesResource.cs Removes the metadata diagnostic suppression.
src/​Aspire.Hosting.Foundry/​HostedAgent/​AzureHostedAgentResource.cs Removes the metadata diagnostic suppression.
src/​Aspire.Hosting.EntityFrameworkCore/​EFMigrationResourceBuilderExtensions.cs Removes the metadata diagnostic suppression.
src/​Aspire.Hosting.Azure.AppService/​AzureAppServiceWebsiteContext.cs Removes the metadata diagnostic suppression.
docs/​specs/​connection-properties.md Documents stable metadata APIs and record-copy semantics.
docs/​list-of-diagnostics.md Documents retirement of ASPIRECONNECTIONSTRINGS001.

Review effort: Balanced

@github-actions

This comment has been minimized.

@maddymontaquila
Maddy Montaquila (maddymontaquila) changed the base branch from main to release/17.0 November 11, 2026 22:03
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@github-actions

Copy link
Copy Markdown
Contributor

Tests selector

52 / 101 PR test projects · 4 PR jobs, from 12 changed files.

Selected PR test projects (52 / 101)

Aspire.Cli.EndToEnd.Tests, Aspire.Hosting.Analyzers.Tests, Aspire.Hosting.Azure.EntraId.Tests, Aspire.Hosting.Azure.Kubernetes.Tests, Aspire.Hosting.Azure.Kusto.Tests, Aspire.Hosting.Azure.Provisioning.Tests, Aspire.Hosting.Azure.Tests, Aspire.Hosting.Blazor.Tests, Aspire.Hosting.Browsers.Tests, Aspire.Hosting.CodeGeneration.Go.Tests, Aspire.Hosting.CodeGeneration.Java.Tests, Aspire.Hosting.CodeGeneration.Python.Tests, Aspire.Hosting.CodeGeneration.Rust.Tests, Aspire.Hosting.CodeGeneration.TypeScript.Tests, Aspire.Hosting.Containers.Tests, Aspire.Hosting.DevTunnels.Tests, Aspire.Hosting.Docker.Tests, Aspire.Hosting.Dotnet.Tests, Aspire.Hosting.DotnetTool.Tests, Aspire.Hosting.EntityFrameworkCore.Tests, Aspire.Hosting.Foundry.Tests, Aspire.Hosting.Garnet.Tests, Aspire.Hosting.Go.Tests, Aspire.Hosting.Java.Tests, Aspire.Hosting.JavaScript.Tests, Aspire.Hosting.Kafka.Tests, Aspire.Hosting.Keycloak.Tests, Aspire.Hosting.Kubernetes.Tests, Aspire.Hosting.Maui.Tests, Aspire.Hosting.Milvus.Tests, Aspire.Hosting.MongoDB.Tests, Aspire.Hosting.MySql.Tests, Aspire.Hosting.Nats.Tests, Aspire.Hosting.OpenAI.Tests, Aspire.Hosting.Oracle.Tests, Aspire.Hosting.Orleans.Tests, Aspire.Hosting.PostgreSQL.Tests, Aspire.Hosting.Python.Tests, Aspire.Hosting.Qdrant.Tests, Aspire.Hosting.RabbitMQ.Tests, Aspire.Hosting.Radius.Tests, Aspire.Hosting.Redis.Tests, Aspire.Hosting.RemoteHost.Tests, Aspire.Hosting.Rust.Tests, Aspire.Hosting.Seq.Tests, Aspire.Hosting.SqlServer.Tests, Aspire.Hosting.Testing.Tests, Aspire.Hosting.Tests, Aspire.Hosting.Valkey.Tests, Aspire.Hosting.Yarp.Tests, Aspire.Playground.Tests, Aspire.Templates.Tests

Selected PR jobs (4)

cli-starter-validation, extension-e2e, polyglot, typescript-api-compat


How these were chosen — grouped by what changed

⚠️ 36 of the 52 selected test projects come from a single change — src/Aspire.Hosting/ApplicationModel/ConnectionStringEnvironmentVariableNames.cs.

🔧 src/Aspire.Hosting/ApplicationModel/ConnectionStringEnvironmentVariableNames.cs (changed source)
→ 36 via the project graph

show 36

Aspire.Hosting.Analyzers.Tests (2 hops), Aspire.Hosting.Azure.Kusto.Tests (2 hops), Aspire.Hosting.Azure.Provisioning.Tests (3 hops), Aspire.Hosting.Browsers.Tests (2 hops), Aspire.Hosting.CodeGeneration.Go.Tests, Aspire.Hosting.CodeGeneration.Java.Tests, Aspire.Hosting.CodeGeneration.Python.Tests, Aspire.Hosting.CodeGeneration.Rust.Tests, Aspire.Hosting.Containers.Tests (2 hops), Aspire.Hosting.DevTunnels.Tests (2 hops), Aspire.Hosting.DotnetTool.Tests (2 hops), Aspire.Hosting.Garnet.Tests (2 hops), Aspire.Hosting.Go.Tests (2 hops), Aspire.Hosting.Java.Tests (2 hops), Aspire.Hosting.JavaScript.Tests (2 hops), Aspire.Hosting.Kafka.Tests (2 hops), Aspire.Hosting.Keycloak.Tests (2 hops), Aspire.Hosting.Maui.Tests, Aspire.Hosting.Milvus.Tests (2 hops), Aspire.Hosting.MongoDB.Tests (2 hops), Aspire.Hosting.MySql.Tests (2 hops), Aspire.Hosting.Nats.Tests (2 hops), Aspire.Hosting.OpenAI.Tests (2 hops), Aspire.Hosting.Oracle.Tests (2 hops), Aspire.Hosting.Orleans.Tests (2 hops), Aspire.Hosting.PostgreSQL.Tests (2 hops), Aspire.Hosting.Python.Tests (2 hops), Aspire.Hosting.RabbitMQ.Tests (2 hops), Aspire.Hosting.Redis.Tests (2 hops), Aspire.Hosting.Rust.Tests (2 hops), Aspire.Hosting.Seq.Tests (2 hops), Aspire.Hosting.SqlServer.Tests (2 hops), Aspire.Hosting.Testing.Tests (2 hops), Aspire.Hosting.Valkey.Tests (2 hops), Aspire.Hosting.Yarp.Tests (2 hops), Aspire.Playground.Tests

🔧 src/Aspire.Hosting.Azure.AppService/AzureAppServiceWebsiteContext.cs (changed source)
→ 1 directly: Aspire.Hosting.Azure.Tests
→ 3 via the project graph: Aspire.Hosting.Azure.EntraId.Tests, Aspire.Hosting.Azure.Kubernetes.Tests (2 hops), Aspire.Hosting.CodeGeneration.TypeScript.Tests

🔧 src/Aspire.Hosting.Kubernetes/KubernetesResource.cs (changed source)
→ 1 directly: Aspire.Hosting.Kubernetes.Tests
→ 2 via the project graph: Aspire.Hosting.Docker.Tests, Aspire.Hosting.RemoteHost.Tests

🧪 tests/Aspire.Hosting.Tests/WithReferenceTests.cs (changed test)
→ 1 directly: Aspire.Hosting.Tests
→ 2 via the project graph: Aspire.Hosting.Blazor.Tests, Aspire.Hosting.Dotnet.Tests

📦 affected project Aspire.Hosting.Dotnet
→ 2 tests: Aspire.Cli.EndToEnd.Tests, Aspire.Templates.Tests

📦 affected project Aspire.Hosting.EntityFrameworkCore
→ 1 test: Aspire.Cli.EndToEnd.Tests

🔧 src/Aspire.Hosting.EntityFrameworkCore/EFMigrationResourceBuilderExtensions.cs (changed source)
→ 1 directly: Aspire.Hosting.EntityFrameworkCore.Tests

🔧 src/Aspire.Hosting.Foundry/HostedAgent/AzureHostedAgentResource.cs (changed source)
→ 1 directly: Aspire.Hosting.Foundry.Tests

🔧 src/Aspire.Hosting.Qdrant/QdrantBuilderExtensions.cs (changed source)
→ 1 directly: Aspire.Hosting.Qdrant.Tests

🔧 src/Aspire.Hosting.Radius/Publishing/RadiusInfrastructureBuilder.cs (changed source)
→ 1 directly: Aspire.Hosting.Radius.Tests

🧪 tests/Aspire.Hosting.Foundry.Tests/HostedAgentExtensionTests.cs (changed test)
→ 1 directly: Aspire.Hosting.Foundry.Tests

🧪 tests/Aspire.Hosting.Qdrant.Tests/AddQdrantTests.cs (changed test)
→ 1 directly: Aspire.Hosting.Qdrant.Tests

Job reasons

Job Triggered by
cli-starter-validation affected project Aspire.Hosting.Go
extension-e2e • src/Aspire.Hosting/ApplicationModel/ConnectionStringEnvironmentVariableNames.cs, src/Aspire.Hosting/ApplicationModel/ConnectionStringReference.cs, src/Aspire.Hosting/ResourceBuilderExtensions.cs
• affected project Aspire.Hosting
polyglot • affected project Aspire.Hosting.Azure.AppService
• affected project Aspire.Hosting.Azure.Provisioning.AppService
typescript-api-compat affected project Aspire.Hosting.Azure.AppService

Selection computed for commit 2d33e4c.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

Maintainer sign-off is still required on the long-term alias compatibility and independently mutable record-copy guarantees before API stabilization.

No open issues 🎉

Review effort: Balanced

@github-actions

Copy link
Copy Markdown
Contributor

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

@github-actions

Copy link
Copy Markdown
Contributor

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

@github-actions

Copy link
Copy Markdown
Contributor

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

@aspire-repo-bot

Copy link
Copy Markdown
Contributor

Pull request created: #2167

Generated by PR Documentation Check · copilot · auto · 24.6 AIC · ⌖ 1.17 AIC · ⊞ 7.4K

@aspire-repo-bot

Copy link
Copy Markdown
Contributor

📝 Documentation has been drafted in microsoft/aspire.dev#2167 targeting release/17.0.

Updated fundamentals/environment-variables.mdx to remove the experimental caution for ConnectionStringEnvironmentVariableNames / ConnectionStringReference.EnvironmentVariableNames. Signals: diagnostic_documentation_changed (docs/list-of-diagnostics.md), pr_body_has_user_facing_section, pr_body_has_cli_flag_mention.

Note

This draft PR needs human review before merging.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area-app-model Issues pertaining to the APIs in Aspire.Hosting, e.g. DistributedApplication

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants