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.