From 0aaedda1dcb7b53e2859173eeae02bc49b3da961 Mon Sep 17 00:00:00 2001
From: "aspire-repo-bot[bot]"
<268009190+aspire-repo-bot[bot]@users.noreply.github.com>
Date: Sun, 15 Nov 2026 16:26:19 +0000
Subject: [PATCH 1/2] Document stable connection-string naming metadata
---
.../src/content/docs/fundamentals/environment-variables.mdx | 4 +---
1 file changed, 1 insertion(+), 3 deletions(-)
diff --git a/src/frontend/src/content/docs/fundamentals/environment-variables.mdx b/src/frontend/src/content/docs/fundamentals/environment-variables.mdx
index 576cab33e1..2a3bd341d3 100644
--- a/src/frontend/src/content/docs/fundamentals/environment-variables.mdx
+++ b/src/frontend/src/content/docs/fundamentals/environment-variables.mdx
@@ -79,9 +79,7 @@ If you must keep an older client integration, set the reference's `connectionNam
For generated injections, inspect `ConnectionStringReference` values in the environment-variable dictionary, not resource annotations. Their `EnvironmentVariableNames` property exposes a `ConnectionStringEnvironmentVariableNames` record with `LogicalName`, `OriginalName`, `PortableName`, and `IsExplicit`. Its `Create` factory derives names from a resource and logical name; `GetPhysicalNames` enumerates the distinct physical aliases.
-:::caution[Experimental naming metadata]
-`ConnectionStringEnvironmentVariableNames` and `ConnectionStringReference.EnvironmentVariableNames` are experimental under `ASPIRECONNECTIONSTRINGS001` and may change. This doesn't make ordinary `WithReference` usage experimental.
-:::
+`ConnectionStringEnvironmentVariableNames` and `ConnectionStringReference.EnvironmentVariableNames` are stable. You don't need to suppress the `ASPIRECONNECTIONSTRINGS001` diagnostic to use them, and the diagnostic is retired. The record properties keep their `init` accessors, so a `with` copy can change names independently without recomputing the other properties.
A standalone reference created with the existing two-argument constructor has no naming metadata. Don't infer that it's a generated alias. Resolve the reference's `ConnectionStringExpression`, not `Resource.ConnectionStringExpression`, because a reference can select another value on the same resource, such as Qdrant's HTTP connection.
From 0d87127a0cb6357047ba32ce8f3b53cf22e642d1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?S=C3=A9bastien=20Ros?=
<1165805+sebastienros@users.noreply.github.com>
Date: Mon, 16 Nov 2026 10:24:41 -0800
Subject: [PATCH 2/2] Clarify connection-string naming stability and document
the retired diagnostic
- Scope the stability statement to Aspire 17.0, tell upgraded projects to
remove ASPIRECONNECTIONSTRINGS001 suppressions, and note that 13.6 still
reports it.
- Warn that a `with` copy of ConnectionStringEnvironmentVariableNames doesn't
recompute the physical names, and point to Create for a consistent set.
- Add a diagnostics page for ASPIRECONNECTIONSTRINGS001 (introduced in 13.6,
removed in 17.0) so the aka.ms help link emitted by 13.6 resolves, plus the
matching overview row and sidebar entry.
---
.../config/sidebar/reference.topics.ts | 4 +
.../aspireconnectionstrings001.mdx | 76 +++++++++++++++++++
.../src/content/docs/diagnostics/overview.mdx | 1 +
.../fundamentals/environment-variables.mdx | 4 +-
4 files changed, 84 insertions(+), 1 deletion(-)
create mode 100644 src/frontend/src/content/docs/diagnostics/aspireconnectionstrings001.mdx
diff --git a/src/frontend/config/sidebar/reference.topics.ts b/src/frontend/config/sidebar/reference.topics.ts
index 2f0f0fea19..898bf31871 100644
--- a/src/frontend/config/sidebar/reference.topics.ts
+++ b/src/frontend/config/sidebar/reference.topics.ts
@@ -723,6 +723,10 @@ export const referenceTopics: StarlightSidebarTopicsUserConfig[number] = {
label: 'ASPIRECOMPUTE003',
link: '/diagnostics/aspirecompute003',
},
+ {
+ label: 'ASPIRECONNECTIONSTRINGS001',
+ link: '/diagnostics/aspireconnectionstrings001',
+ },
{
label: 'ASPIRECONTAINERRUNTIME001',
link: '/diagnostics/aspirecontainerruntime001',
diff --git a/src/frontend/src/content/docs/diagnostics/aspireconnectionstrings001.mdx b/src/frontend/src/content/docs/diagnostics/aspireconnectionstrings001.mdx
new file mode 100644
index 0000000000..d7f3f874da
--- /dev/null
+++ b/src/frontend/src/content/docs/diagnostics/aspireconnectionstrings001.mdx
@@ -0,0 +1,76 @@
+---
+title: Compiler Error ASPIRECONNECTIONSTRINGS001
+seoTitle: 'ASPIRECONNECTIONSTRINGS001: Connection-string naming metadata'
+description: Learn why Aspire 17.0 retired ASPIRECONNECTIONSTRINGS001 now that the connection-string naming metadata APIs are stable.
+---
+
+import { Badge } from '@astrojs/starlight/components';
+
+
+
+:::note[Removed in Aspire 17.0]
+Starting with Aspire 17.0, `ConnectionStringEnvironmentVariableNames` and `ConnectionStringReference.EnvironmentVariableNames` are stable and no longer emit `ASPIRECONNECTIONSTRINGS001`. You can remove suppressions for these APIs after upgrading.
+:::
+
+> 'Aspire.Hosting.ApplicationModel.ConnectionStringEnvironmentVariableNames' is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
+
+In Aspire 13.6, this diagnostic is reported when you use the following experimental APIs from `Aspire.Hosting`:
+
+- `ConnectionStringEnvironmentVariableNames`, the record that describes a connection-string reference's logical name and its original and portable environment-variable names
+- `ConnectionStringReference.EnvironmentVariableNames`, which exposes that record for generated connection-string injections
+
+Ordinary `WithReference` usage never reported this diagnostic. It only applies to custom publishers and integrations that inspect the naming metadata. For more information, see [Custom publishers and integrations](/fundamentals/environment-variables/#custom-publishers-and-integrations).
+
+## Example in Aspire 13.6
+
+In Aspire 13.6, the following code generates `ASPIRECONNECTIONSTRINGS001`:
+
+```csharp title="Publisher.cs"
+if (value is ConnectionStringReference { EnvironmentVariableNames: { } names })
+{
+ foreach (var name in names.GetPhysicalNames())
+ {
+ Console.WriteLine(name);
+ }
+}
+```
+
+## To correct this error
+
+Upgrade to Aspire 17.0 or later. After upgrading, remove `ASPIRECONNECTIONSTRINGS001` suppressions from _.editorconfig_ files, project `NoWarn` properties, and `#pragma warning` directives.
+
+For Aspire 13.6, suppress the error with one of the following methods:
+
+- Set the severity of the rule in the _.editorconfig_ file.
+
+ ```ini title=".editorconfig"
+ [*.{cs,vb}]
+ dotnet_diagnostic.ASPIRECONNECTIONSTRINGS001.severity = none
+ ```
+
+ For more information about editor config files, see [Configuration files for code analysis rules](/diagnostics/overview/#suppress-in-the-editorconfig-file).
+
+- Add the following `PropertyGroup` to your project file:
+
+ ```xml title="C# project file"
+
+ $(NoWarn);ASPIRECONNECTIONSTRINGS001
+
+ ```
+
+- Suppress in code with the `#pragma warning disable ASPIRECONNECTIONSTRINGS001` directive:
+
+ ```csharp title="Suppressing the error"
+ #pragma warning disable ASPIRECONNECTIONSTRINGS001
+ var names = reference.EnvironmentVariableNames;
+ #pragma warning restore ASPIRECONNECTIONSTRINGS001
+ ```
+
+## See also
+
+- [Environment variables: Connection strings](/fundamentals/environment-variables/#connection-strings)
diff --git a/src/frontend/src/content/docs/diagnostics/overview.mdx b/src/frontend/src/content/docs/diagnostics/overview.mdx
index b7ee24986a..52e370b569 100644
--- a/src/frontend/src/content/docs/diagnostics/overview.mdx
+++ b/src/frontend/src/content/docs/diagnostics/overview.mdx
@@ -46,6 +46,7 @@ The following table lists the possible MSBuild and analyzer warnings and errors
| [ASPIRECOMPUTE001](/diagnostics/aspirecompute001/) | (Experimental) Error | Compute related types and members are for evaluation purposes only and is subject to change or removal in future updates. |
| [ASPIRECOMPUTE002](/diagnostics/aspirecompute002/) | (Experimental) Warning | The GetHostAddressExpression method is for evaluation purposes only and is subject to change or removal in future updates. |
| [ASPIRECOMPUTE003](/diagnostics/aspirecompute003/) | (Experimental) Warning | The ContainerRegistryResource type is for evaluation purposes only and is subject to change or removal in future updates. |
+| [ASPIRECONNECTIONSTRINGS001](/diagnostics/aspireconnectionstrings001/) | (Experimental) Error | Removed in Aspire 17.0. Connection-string naming metadata APIs are stable; remove existing suppressions after upgrading. |
| [ASPIRECONTAINERRUNTIME001](/diagnostics/aspirecontainerruntime001/) | (Experimental) Warning | Type is for evaluation purposes only and is subject to change or removal in future updates. |
| [ASPIRECONTAINERSHELLEXECUTION001](/diagnostics/aspirecontainershellexecution001/) | (Experimental) Warning | Container shell execution property is for evaluation purposes only and is subject to change or removal in future updates. |
| [ASPIRECOSMOSDB001](/diagnostics/aspirecosmosdb001/) | (Experimental) Error | is for evaluation purposes only and is subject to change or removal in future updates. |
diff --git a/src/frontend/src/content/docs/fundamentals/environment-variables.mdx b/src/frontend/src/content/docs/fundamentals/environment-variables.mdx
index 2a3bd341d3..7ace9c62cc 100644
--- a/src/frontend/src/content/docs/fundamentals/environment-variables.mdx
+++ b/src/frontend/src/content/docs/fundamentals/environment-variables.mdx
@@ -79,7 +79,9 @@ If you must keep an older client integration, set the reference's `connectionNam
For generated injections, inspect `ConnectionStringReference` values in the environment-variable dictionary, not resource annotations. Their `EnvironmentVariableNames` property exposes a `ConnectionStringEnvironmentVariableNames` record with `LogicalName`, `OriginalName`, `PortableName`, and `IsExplicit`. Its `Create` factory derives names from a resource and logical name; `GetPhysicalNames` enumerates the distinct physical aliases.
-`ConnectionStringEnvironmentVariableNames` and `ConnectionStringReference.EnvironmentVariableNames` are stable. You don't need to suppress the `ASPIRECONNECTIONSTRINGS001` diagnostic to use them, and the diagnostic is retired. The record properties keep their `init` accessors, so a `with` copy can change names independently without recomputing the other properties.
+Starting with Aspire 17.0, `ConnectionStringEnvironmentVariableNames` and `ConnectionStringReference.EnvironmentVariableNames` are stable and no longer emit [`ASPIRECONNECTIONSTRINGS001`](/diagnostics/aspireconnectionstrings001/). After upgrading, remove any suppressions of that diagnostic. Aspire 13.6 still reports it for these APIs.
+
+The record's properties have public `init` accessors, so you can make a modified copy with a `with` expression. A `with` copy doesn't recompute the other properties: changing `LogicalName` leaves `OriginalName` and `PortableName` unchanged. To derive a consistent set of names for another logical name, call `Create` instead.
A standalone reference created with the existing two-argument constructor has no naming metadata. Don't infer that it's a generated alias. Resolve the reference's `ConnectionStringExpression`, not `Resource.ConnectionStringExpression`, because a reference can select another value on the same resource, such as Qdrant's HTTP connection.