Support simplified service url ENV format #12141

sebastienros · 2025-10-18T00:32:31Z

Description

Generates polyglot-friendly service endpoint environment variables like WEATHERAPI, WEATHERAPI_HTTPS
Adds the ability to set the name of the service in ENVS
Buids upon the newly added ReferenceEnvironmentInjectionAnnotation to allow the customization per resource or per resource type which should get Service Discovery endpoints or simple ones.

Fixes #12069

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
Does the change require an update in our Aspire docs?
- Yes [New article]: Polyglot environment variables docs-aspire#5308
- No

github-actions · 2025-10-18T00:32:45Z

🚀 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/dotnet/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 12141

Or

Run remotely in PowerShell:

iex "& { $(irm https://raw.githubusercontent.com/dotnet/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 12141"

src/Aspire.Hosting/ResourceBuilderExtensions.cs

davidfowl · 2025-10-18T19:40:25Z

playground/AspireWithJavaScript/README.md


 ### Experiencing the app

+Before starting the app host run `npm install` in each javascript folder.


Will fix this.

Are there not calls to .WithNpmPackageInstallation in the AppHost?

No, didn't know about it then Damian told me. Should I add it in this PR? @IEvangelist note that the Vite sample doesn't work at all, issues with authenticating on npm, not sure if the extension method will take care of this.

No, dont' add it to this PR.

davidfowl · 2025-10-18T19:49:22Z

This approach looks solid. Since we're not trying to do any fancy service discovery, it's a very simple name based scheme.

Copilot

Pull Request Overview

This PR introduces simplified service URL environment variable format that is more polyglot-friendly. It adds the ability to generate environment variables in the format {RESOURCENAME}_{ENDPOINT} (e.g., WEATHERAPI_HTTPS) alongside the existing .NET service discovery format.

Key changes:

Expands ReferenceEnvironmentInjectionFlags enum to support new endpoint injection patterns
Updates environment variable generation logic to emit both service discovery and simplified endpoint formats
Modernizes existing playground JavaScript applications to use the new simplified format

Reviewed Changes

Copilot reviewed 28 out of 28 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
`src/Aspire.Hosting/ApplicationModel/ReferenceEnvironmentInjectionFlags.cs`	Adds new flags for ServiceDiscovery and Endpoints injection
`src/Aspire.Hosting/ResourceBuilderExtensions.cs`	Updates environment variable generation to support both formats and renames method
`src/Aspire.Hosting.DevTunnels/DevTunnelResourceBuilderExtensions.cs`	Updates dev tunnel references to use new injection patterns
`tests/Aspire.Hosting.Tests/WithReferenceTests.cs`	Adds tests for new simplified environment variable format
`playground/AspireWithJavaScript/*`	Updates JavaScript applications to use simplified environment variables
Various test snapshots	Updates expected output to include new environment variable format

src/Aspire.Hosting/ResourceBuilderExtensions.cs

tests/Aspire.Hosting.Tests/WithReferenceTests.cs

src/Aspire.Hosting/ApplicationModel/ReferenceEnvironmentInjectionFlags.cs

davidfowl · 2025-10-18T23:45:12Z

Update this template

aspire/src/Aspire.ProjectTemplates/templates/aspire-py-starter/13.0/frontend/vite.config.ts

Line 11 in 6733971

    
           target: process.env.services__apiservice__https__0 || process.env.services__apiservice__http__0,

src/Aspire.Hosting/ResourceBuilderExtensions.cs

davidfowl · 2025-10-19T00:06:41Z

Dev tunnels as a custom WithReference method that should be updated.

sebastienros · 2025-10-19T00:52:54Z

Dev tunnels as a custom WithReference method that should be updated.

I thought I did, or did I miss another one?

davidfowl

Looks good!

sebastienros · 2025-10-19T17:25:18Z

Simingly unrelated tests are failing on macos now, tried 3 times. These work locally on macos though:

Test summary: total: 38, failed: 0, succeeded: 38, skipped: 0, duration: 2.1s
Build succeeded in 4.3s
➜  Aspire.Hosting.Tests git:(sebros/polyglotservices) dotnet test -- --filter-method="*DistributedApplicationPipelineTests*"

davidfowl · 2025-10-19T17:38:28Z

Those are my bugs #12160, there are still more to delete.

davidfowl · 2025-10-20T06:47:28Z

src/Aspire.Hosting/ApplicationModel/ReferenceEnvironmentInjectionFlags.cs

+/// Specifies which connection or endpoint information should be injected into environment variables when <c>WithReference()</c> is invoked.
 /// </summary>
 [Flags]
 public enum ReferenceEnvironmentInjectionFlags


We can follow up on naming.

eerhardt · 2025-10-20T15:57:48Z

src/Aspire.Hosting/ApplicationModel/ReferenceEnvironmentInjectionFlags.cs

+    /// <summary>
+    /// Each endpoint defined on the resource will be injected using the format "{RESOURCENAME}_{ENDPOINTNAME}".
+    /// </summary>
+    Endpoints = 1 << 3,


I'm not sure Endpoints is the right name here. Maybe SimplifiedEndpoints? or SimpleEndpoints?

Follow up API review, I think this whole enum is unclear.

eerhardt · 2025-10-20T15:59:05Z

src/Aspire.Hosting/ApplicationModel/ReferenceEnvironmentInjectionFlags.cs

+    /// Each endpoint defined on the resource will be injected using the format "services__{resourceName}__{endpointName}__{endpointIndex}".
    /// </summary>
-    All = ConnectionString | ConnectionProperties
+    ServiceDiscovery = 1 << 2,


Is ServiceDiscovery enough in this context? Is it really .NET ServiceDiscovery? Even using the Endpoints format is still "service discovery", right? Just not the Microsoft.Extensions.ServiceDiscovery format.

eerhardt · 2025-10-20T15:59:58Z

src/Aspire.Hosting/ApplicationModel/ReferenceEnvironmentInjectionFlags.cs


    /// <summary>
-    /// Both connection string and connection properties will be injected as environment variables.
+    /// Each endpoint defined on the resource will be injected using the format "services__{resourceName}__{endpointName}__{endpointIndex}".


endpointIndex

What is the reason we have an index at the end? How are those scenarios going to work with the Endpoints format?

We don't need index because each endpoint gets a single env variable. The service discovery format has a one to many relationship with endpoints. You can have 5 endpoints named differently with an http scheme and use the resource name (e.g. http://foo to refer to it). That will load balance across those 5 addresses at runtime.

You can have 5 endpoints named differently with an http scheme and use the resource name (e.g. http://foo/ to refer to it). That will load balance across those 5 addresses at runtime.

In that case is endpointName correct above? Or is it uri.scheme?

If you have 5 endpoints named differently, why isn't services__{resourceName}__{endpointName} enough?

The service discovery implementation relies on IConfiguration and that is how you represent arrays:

{ "services": { "foo": [ "http://locahost:5006", "http://locahost:5002" "http://locahost:5004" ] } }

"services__foo__http__0" The system does some munging to support different configuration formats but they are all ugly to support this model.

cc @ReubenBond

and that is how you represent arrays

But in this new format, we aren't going to support arrays?

There isn't any ENV defined by aspire that is not __0. We only have it because it's an array, but always use a single value right now. So for the new ENV there is no reason to have it used at all.

Correct. We don't need it here.

eerhardt · 2025-10-20T16:01:40Z

src/Aspire.Hosting/ResourceBuilderExtensions.cs

-            builder.WithEnvironment(envVarName, uri.ToString());
+            if (flags.HasFlag(ReferenceEnvironmentInjectionFlags.Endpoints))
+            {
+                var envVarName = $"{externalService.Resource.Name.ToUpperInvariant()}";


Does this need the uri.Scheme in it?

I only added these if it was necessary to discriminate from other resources. Here the resource is ExternalServiceResource and has a single scheme, so there could only be a conflict if the same resource was also referenced using another interface WithReference call. And in these cases the endpoint name will be used as a discriminator. So I think it's safe to not include it here.

eerhardt · 2025-10-20T16:02:45Z

src/Aspire.Hosting/ResourceBuilderExtensions.cs

                    // In publish mode we can't read the parameter value to get the scheme so use 'default'
-                    envVarName = $"services__{externalService.Resource.Name}__default__0";
+                    discoveryEnvVarName = $"services__{externalService.Resource.Name}__default__0";
+                    endpointEnvVarName = externalService.Resource.Name.ToUpperInvariant();


Does this need _default in it?

Also, how is someone supposed to code against this scenario where it changes from uri.Schema to default after publish?

I don't fully understand why we need the scheme at all. We just need to decide if we should have another prefix for external services so they don't collide (though resource names are unique).

src/Aspire.ProjectTemplates/templates/aspire-py-starter/13.0/frontend/vite.config.ts

eerhardt

LGTM. Except one fat fingers.

…rontend/vite.config.ts Co-authored-by: Eric Erhardt <[email protected]>

sebastienros force-pushed the sebros/polyglotservices branch from 368ccc6 to 41399a4 Compare October 18, 2025 00:34

sebastienros requested a review from eerhardt October 18, 2025 00:45

davidfowl reviewed Oct 18, 2025

View reviewed changes

src/Aspire.Hosting/ResourceBuilderExtensions.cs Show resolved Hide resolved

Support simplified service url ENV format

5863688

sebastienros force-pushed the sebros/polyglotservices branch from a269804 to 5863688 Compare October 18, 2025 18:07

Fix naming

e3f71d2

davidfowl reviewed Oct 18, 2025

View reviewed changes

sebastienros added 2 commits October 18, 2025 13:32

Update unit tests

a47fc40

Fix tests

3da02bd

sebastienros mentioned this pull request Oct 18, 2025

[New article]: Polyglot environment variables dotnet/docs-aspire#5308

Closed

sebastienros marked this pull request as ready for review October 18, 2025 23:17

sebastienros requested a review from mitchdenny as a code owner October 18, 2025 23:17

Copilot AI review requested due to automatic review settings October 18, 2025 23:17

Copilot AI reviewed Oct 18, 2025

View reviewed changes

davidfowl reviewed Oct 19, 2025

View reviewed changes

src/Aspire.Hosting/ResourceBuilderExtensions.cs Outdated Show resolved Hide resolved

sebastienros added 3 commits October 18, 2025 17:42

Add unit test

2ce645e

Update vite template

a7dbbf8

Feedback

4868cc9

davidfowl approved these changes Oct 19, 2025

View reviewed changes

Merge remote-tracking branch 'origin/main' into sebros/polyglotservices

a54147d

davidfowl reviewed Oct 20, 2025

View reviewed changes

Copilot AI mentioned this pull request Oct 20, 2025

Update documentation for new polyglot environment variables (issue #5308) dotnet/docs-aspire#5313

Merged

8 tasks

eerhardt reviewed Oct 20, 2025

View reviewed changes

src/Aspire.ProjectTemplates/templates/aspire-py-starter/13.0/frontend/vite.config.ts Outdated Show resolved Hide resolved

eerhardt approved these changes Oct 20, 2025

View reviewed changes

Update src/Aspire.ProjectTemplates/templates/aspire-py-starter/13.0/f…

9d12378

…rontend/vite.config.ts Co-authored-by: Eric Erhardt <[email protected]>

sebastienros enabled auto-merge (squash) October 20, 2025 19:30

sebastienros merged commit 6a43c5e into main Oct 20, 2025
1176 of 1187 checks passed

dotnet-policy-service bot added this to the 13.0 milestone Oct 20, 2025

sebastienros deleted the sebros/polyglotservices branch October 20, 2025 20:16

Copilot AI mentioned this pull request Oct 21, 2025

Update environment variable format to polyglot-friendly pattern dotnet/docs-aspire#5320

Merged


		### Experiencing the app

		Before starting the app host run `npm install` in each javascript folder.

Support simplified service url ENV format #12141

Support simplified service url ENV format #12141

Uh oh!

Conversation

sebastienros commented Oct 18, 2025 • edited by davidfowl Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Uh oh!

github-actions bot commented Oct 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

davidfowl commented Oct 18, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

davidfowl commented Oct 18, 2025

Uh oh!

Uh oh!

davidfowl commented Oct 19, 2025

Uh oh!

sebastienros commented Oct 19, 2025

Uh oh!

davidfowl left a comment

Choose a reason for hiding this comment

Uh oh!

sebastienros commented Oct 19, 2025

Uh oh!

davidfowl commented Oct 19, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

davidfowl Oct 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

davidfowl Oct 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

sebastienros commented Oct 18, 2025 •

edited by davidfowl

Loading

github-actions bot commented Oct 18, 2025 •

edited

Loading

davidfowl Oct 20, 2025 •

edited

Loading

davidfowl Oct 20, 2025 •

edited

Loading