Document environment variable naming conventions for resources by Copilot · Pull Request #498 · microsoft/aspire.dev

Copilot · 2026-03-04T02:00:43Z

Original prompt

This section details on the original issue you should resolve

<issue_title>Environment variable naming convention for resources not documented</issue_title>
<issue_description>## Bug Description

Aspire transforms resource names into environment variable prefixes using a specific convention, but this convention is not clearly documented. When a resource is named with hyphens (e.g., foundry-demo-proj), the resulting environment variable prefix is FOUNDRY_DEMO_PROJ (uppercased, hyphens replaced with underscores). Properties are appended as suffixes (e.g., _URI, _MODELNAME).

Current Behavior

There is no clear documentation explaining the resource name → environment variable transformation rules. Users must discover the naming convention by trial and error or by inspecting the Aspire dashboard.

Expected Behavior

The docs should include a section explaining:

Resource names are uppercased

Hyphens (-) are replaced with underscores (_)

Properties are appended as _{PROPERTY} (e.g., _URI, _MODELNAME, _CONNECTIONSTRING)

Connection strings use the format ConnectionStrings__{resource-name}

Examples showing the mapping, e.g.: resource "my-db" → env vars MY_DB_HOST, MY_DB_PORT, ConnectionStrings__my-db

Page URL

Could be added to the app model fundamentals or a dedicated "environment variables" reference page.

Additional Context

We spent significant debugging time because our Python app referenced PROJ_URI when the actual variable was FOUNDRY_DEMO_PROJ_URI (resource was named foundry-demo-proj). This is especially impactful for non-.NET service projects (Python, Node.js) where developers must manually read environment variables rather than using typed Aspire client integrations.
</issue_description>

<agent_instructions>Please use the https://github.com/microsoft/aspire.dev/blob/main/.github/skills/doc-writer/SKILL.md skill to address this issue. Find all places where this content is required.</agent_instructions>

Comments on the Issue (you are @copilot in this section)

Fixes Environment variable naming convention for resources not documented #477

🔒 GitHub Advanced Security automatically protects Copilot coding agent pull requests. You can protect all pull requests by enabling Advanced Security for your repositories. Learn more about Advanced Security.

Create new fundamentals/environment-variables.mdx page documenting: - Connection string naming (ConnectionStrings__{resource-name}) - Endpoint URL naming (RESOURCE_NAME_SCHEME) - Service discovery variables (services__name__scheme__index) - Resource property naming (RESOURCE_NAME_PROPERTY) - Name encoding rules (hyphens to underscores, uppercasing) - Examples for C#, Python, and JavaScript - Custom environment variables with WithEnvironment Update sidebar, Python, JavaScript, and service discovery pages with cross-references to the new page. Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com>

… hyphen Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com>

IEvangelist

This PR looks good so far, but let's double check it for accuracy by using the .github/skills/doc-tester/SKILL.md skill. Please also consider all new comments and feedback/suggestions. @copilot

src/frontend/src/content/docs/fundamentals/environment-variables.mdx

…nMore, remove unused imports Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com>

Copilot · 2026-03-04T02:54:15Z

This PR looks good so far, but let's double check it for accuracy by using the .github/skills/doc-tester/SKILL.md skill. Please also consider all new comments and feedback/suggestions. @copilot

All review suggestions applied in 83b843e:

Rewrote intro with "configuration injection" terminology
Changed bare code blocks to txt
Replaced "See also" with LearnMore components
Removed unused Tabs/TabItem imports

Ran doc-tester verification — confirmed the five key naming convention claims against the EnvironmentVariableNameEncoder source and ResourceBuilderExtensions.cs in dotnet/aspire. All cross-linked pages return HTTP 200 on the dev server.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

telemetry.astro.build
- Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node node /home/REDACTED/work/aspire.dev/aspire.dev/src/frontend/node_modules/.bin/../astro/astro.js dev --host 0.0.0.0 (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

Configure Actions setup steps to set up my environment, which run before the firewall is enabled
Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

src/frontend/src/content/docs/fundamentals/environment-variables.mdx

Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com>

Copilot · 2026-03-04T03:01:13Z

Just as a heads up, I was blocked by some firewall rules while working on your feedback. Expand below for details.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

telemetry.astro.build
- Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node node /home/REDACTED/work/aspire.dev/aspire.dev/src/frontend/node_modules/.bin/../astro/astro.js dev --host 0.0.0.0 (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

Configure Actions setup steps to set up my environment, which run before the firewall is enabled
Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

IEvangelist · 2026-03-04T03:05:55Z

Hey @copilot, could you please update this PR to ensure that npx astro telemetry disable is ran on all CI or instructions/skills, etc. We need to make sure that when aspire.dev is building or running, we're not sending telemetry.

Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com>

Copilot · 2026-03-04T03:10:03Z

Hey @copilot, could you please update this PR to ensure that npx astro telemetry disable is ran on all CI or instructions/skills, etc. We need to make sure that when aspire.dev is bu...

Added npx astro telemetry disable in three places in 7c9e616:

.github/workflows/frontend-build.yml — new step after deps install
.github/workflows/integration.yml — new step after deps install
.devcontainer/devcontainer.json — added to postCreateCommand

The security-scan.yml workflow was not updated since it only runs pnpm audit and doesn't invoke Astro build/dev commands.

Copilot

Pull request overview

This PR adds a new fundamentals documentation page explaining how Aspire transforms resource names into environment variable names — a convention that was previously undocumented and caused significant debugging pain for non-.NET developers (Python, Node.js, Go). The new page covers connection strings, endpoint URLs, service discovery variables, and resource properties, with language-specific examples. Cross-references are added to related pages, and CI/devcontainer configs are updated to disable Astro telemetry.

Changes:

Added new fundamentals/environment-variables.mdx page documenting naming conventions for connection strings, endpoint URLs, service discovery variables, and resource properties
Updated Python, JavaScript, and service discovery pages with cross-references to the new documentation
Added Astro telemetry disabling to CI workflows and devcontainer configuration

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
`src/frontend/src/content/docs/fundamentals/environment-variables.mdx`	New fundamentals page documenting env var naming conventions with examples in C#, Python, and JavaScript
`src/frontend/src/content/docs/integrations/frameworks/python.mdx`	Added connection string example and cross-reference to new env vars page
`src/frontend/src/content/docs/integrations/frameworks/javascript.mdx`	Added `WithReference` example with connection string access and cross-reference
`src/frontend/src/content/docs/fundamentals/service-discovery.mdx`	Added Aside tip cross-referencing the new env vars page
`src/frontend/config/sidebar/docs.topics.ts`	Added sidebar entry with all locale translations for the new page
`.github/workflows/frontend-build.yml`	Added `npx astro telemetry disable` step
`.github/workflows/integration.yml`	Added `npx astro telemetry disable` step
`.devcontainer/devcontainer.json`	Added `npx astro telemetry disable` to `postCreateCommand`

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

BethMassi · 2026-03-06T15:43:13Z

I didn't see a section on custom parameters i.e. var repository = builder.AddParameter("registry-repository"); ends up as an environment var: Parameters__registry_repository - is this explained in another topic?

Initial plan

761e2d3

Copilot AI assigned Copilot and IEvangelist Mar 4, 2026

Copilot started work on behalf of IEvangelist March 4, 2026 02:00 View session

Copilot AI and others added 2 commits March 4, 2026 02:12

Fix JavaScript connection string example to use bracket notation with…

a3daa4f

… hyphen Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] Update documentation for environment variable naming convention~~ Document environment variable naming conventions for resources Mar 4, 2026

Copilot finished work on behalf of IEvangelist March 4, 2026 02:16

IEvangelist approved these changes Mar 4, 2026

View reviewed changes

Copilot started work on behalf of IEvangelist March 4, 2026 02:49 View session

Address review feedback: rewrite intro, use txt code blocks, add Lear…

83b843e

…nMore, remove unused imports Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com>

IEvangelist reviewed Mar 4, 2026

View reviewed changes

src/frontend/src/content/docs/fundamentals/environment-variables.mdx Outdated Show resolved Hide resolved

Fix LearnMore component formatting to match existing patterns

e76ba5e

Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com>

Copilot finished work on behalf of IEvangelist March 4, 2026 02:56

Copilot started work on behalf of IEvangelist March 4, 2026 02:56 View session

Replace stacked LearnMore components with standard See also section

6a64285

Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com>

Copilot finished work on behalf of IEvangelist March 4, 2026 03:01

Copilot started work on behalf of IEvangelist March 4, 2026 03:06 View session

Add npx astro telemetry disable to CI workflows and devcontainer

7c9e616

Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com>

Copilot finished work on behalf of IEvangelist March 4, 2026 03:10

IEvangelist marked this pull request as ready for review March 5, 2026 12:41

IEvangelist requested review from aaronpowell and eerhardt as code owners March 5, 2026 12:41

Copilot AI review requested due to automatic review settings March 5, 2026 12:41

Copilot started reviewing on behalf of IEvangelist March 5, 2026 12:42 View session

Copilot AI reviewed Mar 5, 2026

View reviewed changes

IEvangelist enabled auto-merge (squash) March 5, 2026 12:49

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Document environment variable naming conventions for resources#498

Document environment variable naming conventions for resources#498
Copilot wants to merge 7 commits intomainfrom
copilot/update-env-var-naming-docs

Copilot AI commented Mar 4, 2026 •

edited

Loading

Uh oh!

IEvangelist left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI commented Mar 4, 2026 •

edited

Loading

I tried to connect to the following addresses, but was blocked by firewall rules:

Uh oh!

Uh oh!

Copilot AI commented Mar 4, 2026

I tried to connect to the following addresses, but was blocked by firewall rules:

Uh oh!

IEvangelist commented Mar 4, 2026

Uh oh!

Copilot AI commented Mar 4, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

BethMassi commented Mar 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

Copilot AI commented Mar 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Current Behavior

Expected Behavior

Page URL

Additional Context

Comments on the Issue (you are @copilot in this section)

Uh oh!

IEvangelist left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI commented Mar 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

I tried to connect to the following addresses, but was blocked by firewall rules:

Uh oh!

Uh oh!

Copilot AI commented Mar 4, 2026

I tried to connect to the following addresses, but was blocked by firewall rules:

Uh oh!

IEvangelist commented Mar 4, 2026

Uh oh!

Copilot AI commented Mar 4, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

BethMassi commented Mar 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Copilot AI commented Mar 4, 2026 •

edited

Loading

Copilot AI commented Mar 4, 2026 •

edited

Loading