Update documentation for new polyglot environment variables (issue #5308)

docs/deployment/azd/aca-deployment-azd-in-depth.md

@@ -370,9 +370,13 @@ properties:
         value: "true"
       - name: OTEL_DOTNET_EXPERIMENTAL_OTLP_EMIT_EXCEPTION_LOG_ATTRIBUTES
         value: "true"
-      - name: services__apiservice__0
+      - name: APISERVICE_HTTP
         value: http://apiservice.internal.{{ .Env.AZURE_CONTAINER_APPS_ENVIRONMENT_DEFAULT_DOMAIN }}
-      - name: services__apiservice__1
+      - name: APISERVICE_HTTPS
+        value: https://apiservice.internal.{{ .Env.AZURE_CONTAINER_APPS_ENVIRONMENT_DEFAULT_DOMAIN }}
+      - name: services__apiservice__http__0
+        value: http://apiservice.internal.{{ .Env.AZURE_CONTAINER_APPS_ENVIRONMENT_DEFAULT_DOMAIN }}
+      - name: services__apiservice__https__0
         value: https://apiservice.internal.{{ .Env.AZURE_CONTAINER_APPS_ENVIRONMENT_DEFAULT_DOMAIN }}
 tags:
   azd-service-name: webfrontend

docs/deployment/manifest-format.md

@@ -110,8 +110,10 @@ Publishing the manifest from the default starter template for Aspire produces th
         "OTEL_DOTNET_EXPERIMENTAL_OTLP_EMIT_EXCEPTION_LOG_ATTRIBUTES": "true",
         "OTEL_DOTNET_EXPERIMENTAL_OTLP_EMIT_EVENT_LOG_ATTRIBUTES": "true",
         "ConnectionStrings__cache": "{cache.connectionString}",
-        "services__apiservice__0": "{apiservice.bindings.http.url}",
-        "services__apiservice__1": "{apiservice.bindings.https.url}"
+        "APISERVICE_HTTP": "{apiservice.bindings.http.url}",
+        "APISERVICE_HTTPS": "{apiservice.bindings.https.url}",
+        "services__apiservice__http__0": "{apiservice.bindings.http.url}",
+        "services__apiservice__https__0": "{apiservice.bindings.https.url}"
       },
       "bindings": {
         "http": {
@@ -142,8 +144,10 @@ This dependency is known because the environment variables for the _webfrontend_
 "env": {
   // ... other environment variables omitted for clarity
   "ConnectionStrings__cache": "{cache.connectionString}",
-  "services__apiservice__0": "{apiservice.bindings.http.url}",
-  "services__apiservice__1": "{apiservice.bindings.https.url}"
+  "APISERVICE_HTTP": "{apiservice.bindings.http.url}",
+  "APISERVICE_HTTPS": "{apiservice.bindings.https.url}",
+  "services__apiservice__http__0": "{apiservice.bindings.http.url}",
+  "services__apiservice__https__0": "{apiservice.bindings.https.url}"
 },
 ```
 

docs/extensibility/dev-tunnels-integration.md

@@ -101,6 +101,7 @@ The preceding code:
 When another resource references a dev tunnel, environment variables are injected using the [Aspire service discovery](../service-discovery/overview.md) configuration format. Use the `WithReference` overloads that accept the `IResourceBuilder<DevTunnelResource>` parameter to reference a dev tunnel. This injects environment variables like:
 
 ```env
+WEB_HTTPS=https://myweb-1234.westeurope.devtunnels.ms/
 services__web__https__0=https://myweb-1234.westeurope.devtunnels.ms/
 ```
 

docs/fundamentals/app-host-overview.md

@@ -176,9 +176,16 @@
 | Method | Environment variable |
 |--|--|
 | `WithReference(cache)` | `ConnectionStrings__cache="localhost:62354"` |
-| `WithReference(apiservice)` | `services__apiservice__http__0="http://localhost:5455"` <br /> `services__apiservice__https__0="https://localhost:7356"` |
+| `WithReference(apiservice)` | `APISERVICE_HTTP="http://localhost:5455"` <br /> `APISERVICE_HTTPS="https://localhost:7356"` <br /> `services__apiservice__http__0="http://localhost:5455"` <br /> `services__apiservice__https__0="https://localhost:7356"` |
 
-Adding a reference to the "apiservice" project results in service discovery environment variables being added to the frontend. This is because typically, project-to-project communication occurs over HTTP/gRPC. For more information, see [Aspire service discovery](../service-discovery/overview.md).
+Adding a reference to the "apiservice" project results in service discovery environment variables being added to the frontend. This is because typically, project-to-project communication occurs over HTTP/gRPC. 
+
+Aspire injects two types of environment variables for service references:
+
+- **Simplified format** (e.g., `APISERVICE_HTTP`): Uses the pattern `{RESOURCENAME}_{ENDPOINTNAME}` in uppercase. This format is simpler and more suitable for non-.NET languages and polyglot scenarios.
+- **.NET service discovery format** (e.g., `services__apiservice__http__0`): Uses the pattern `services__{servicename}__{endpointname}__{index}` in lowercase. This format is used by .NET's configuration-based service discovery.
+
+For more information, see [Aspire service discovery](../service-discovery/overview.md).
 
 To get specific endpoints from a <xref:Aspire.Hosting.ApplicationModel.ContainerResource> or an <xref:Aspire.Hosting.ApplicationModel.ExecutableResource>, use one of the following endpoint APIs:
 
@@ -202,31 +209,68 @@
 
 | Method                    | Environment variable                                  |
 |---------------------------|-------------------------------------------------------|
-| `WithReference(endpoint)` | `services__myapp__endpoint__0=https://localhost:9043` |
+| `WithReference(endpoint)` | `MYAPP_ENDPOINT="https://localhost:9043"` <br /> `services__myapp__endpoint__0="https://localhost:9043"` |
 
 The `port` parameter is the port that the container is listening on. For more information on container ports, see [Container ports](networking-overview.md#container-ports). For more information on service discovery, see [Aspire service discovery](../service-discovery/overview.md).
 
 ### Service endpoint environment variable format
 
-In the preceding section, the <xref:Aspire.Hosting.ResourceBuilderExtensions.WithReference*> method is used to express dependencies between resources. When service endpoints result in environment variables being injected into the dependent resource, the format might not be obvious. This section provides details on this format.
+In the preceding section, the <xref:Aspire.Hosting.ResourceBuilderExtensions.WithReference*> method is used to express dependencies between resources. When service endpoints result in environment variables being injected into the dependent resource, the format might not be obvious. This section provides details on the available formats.
+
+When one resource depends on another resource, the AppHost injects environment variables into the dependent resource. These environment variables configure the dependent resource to connect to the resource it depends on. Aspire provides two environment variable formats to support different scenarios:
+
+#### Simplified format (polyglot-friendly)
+
+The simplified format uses the pattern `{RESOURCENAME}_{ENDPOINTNAME}` in uppercase. This format is easier to use from non-.NET languages and is recommended for polyglot scenarios.
+
+Consider the following environment variable examples:
+
+```Environment
+APISERVICE_HTTP
+APISERVICE_HTTPS
+```
+
+The preceding environment variables express HTTP and HTTPS endpoints for the `apiservice` service. A named endpoint might be expressed as follows:
 
-When one resource depends on another resource, the AppHost injects environment variables into the dependent resource. These environment variables configure the dependent resource to connect to the resource it depends on. The format of the environment variables is specific to Aspire and expresses service endpoints in a way that is compatible with [Service Discovery](../service-discovery/overview.md).
+```Environment
+APISERVICE_MYENDPOINT
+```
+
+In the preceding example, the `apiservice` service has a named endpoint called `myendpoint`.
+
+> [!NOTE]
+> The environment variable name is based on the resource name, not the optional connection name parameter. Even when using `WithReference(resource, "customname")` to specify a custom connection name, the generated environment variables still use the resource's name (e.g., `APISERVICE_HTTP`), not the custom name.
+
+#### .NET service discovery format
 
-Service endpoint environment variable names are prefixed with `services__` (double underscore), then the service name, the endpoint name, and finally the index. The index supports multiple endpoints for a single service, starting with `0` for the first endpoint and incrementing for each endpoint.
+The .NET service discovery format is used by .NET's configuration-based service discovery. Service endpoint environment variable names are prefixed with `services__` (double underscore), then the service name, the endpoint name, and finally the index. The index supports multiple endpoints for a single service, starting with `0` for the first endpoint and incrementing for each endpoint.
 
 Consider the following environment variable examples:
 
 ```Environment
 services__apiservice__http__0
+services__apiservice__https__0
 ```
 
-The preceding environment variable expresses the first HTTP endpoint for the `apiservice` service. The value of the environment variable is the URL of the service endpoint. A named endpoint might be expressed as follows:
+The preceding environment variables express the first HTTP and HTTPS endpoints for the `apiservice` service. A named endpoint might be expressed as follows:
 
 ```Environment
 services__apiservice__myendpoint__0
 ```
 
-In the preceding example, the `apiservice` service has a named endpoint called `myendpoint`. The value of the environment variable is the URL of the service endpoint.
+In the preceding example, the `apiservice` service has a named endpoint called `myendpoint`.
+
+#### Using a specific endpoint with WithEnvironment
+
+To specify a custom environment variable name for a specific endpoint, use the <xref:Aspire.Hosting.ResourceBuilderExtensions.WithEnvironment%2A> method combined with <xref:Aspire.Hosting.ResourceBuilderExtensions.GetEndpoint*>:
+
+```csharp
+var projectA = builder.AddProject<Projects.ProjectA>("projecta");
+var projectB = builder.AddProject<Projects.ProjectB>("projectb")
+                      .WithEnvironment("PROJECTA_URL", projectA.GetEndpoint("https"));
+```
+
+This generates a single environment variable `PROJECTA_URL` with the HTTPS endpoint URL of the `projecta` service.
 
 ## Reference existing resources
 

docs/fundamentals/orchestrate-resources.md

@@ -285,7 +285,7 @@ var frontend = builder.AddProject<Projects.Frontend>("frontend")
     .WithReference(api);
 ```
 
-This configuration injects an environment variable like `services__api__https__0=https://api.example.com/` into the frontend project, enabling service discovery through the standard .NET service discovery mechanisms.
+This configuration injects environment variables like `API_HTTPS=https://api.example.com/` and `services__api__https__0=https://api.example.com/` into the frontend project, enabling service discovery through both simplified and .NET-specific service discovery mechanisms.
 
 ### External service lifecycle
 

docs/get-started/build-aspire-apps-with-nodejs.md

@@ -147,7 +147,7 @@ There are several key modifications from the original Angular template. The firs
 
 :::code language="javascript" source="~/aspire-samples/samples/AspireWithJavaScript/AspireJavaScript.Angular/proxy.conf.js":::
 
-The Aspire AppHost sets the `services__weatherapi__http__0` environment variable, which is used to resolve the "weatherapi" service endpoint. The preceding configuration proxies HTTP requests that start with `/api` to the target URL specified in the environment variable.
+The Aspire AppHost sets the `WEATHERAPI_HTTP` environment variable, which is used to resolve the "weatherapi" service endpoint. The preceding configuration proxies HTTP requests that start with `/api` to the target URL specified in the environment variable.
 
 Then include the proxy file to in the _angular.json_ file.
 Update the `serve` target to include the `proxyConfig` option, referencing to the created _proxy.conf.js_ file.
@@ -217,7 +217,7 @@ As the `TheWelcome` integration is `mounted`, it calls the `/api/weatherforecast
 
 :::code language="typescript" source="~/aspire-samples/samples/AspireWithJavaScript/AspireJavaScript.Vue/vite.config.ts":::
 
-Additionally, the Vite config specifies the `server.proxy` property to forward requests to the "weatherapi" service. This is achieved by using the `services__weatherapi__http__0` environment variable, which is set by the Aspire AppHost.
+Additionally, the Vite config specifies the `server.proxy` property to forward requests to the "weatherapi" service. This is achieved by using the `WEATHERAPI_HTTP` environment variable, which is set by the Aspire AppHost.
 
 The final update from the template is made to the _TheWelcome.vue_ file. This file calls the `/api/WeatherForecast` endpoint to retrieve the weather forecast data, and displays the data in a table. It includes [CSS, HTML, and TypeScript updates](https://github.com/dotnet/aspire-samples/blob/ef6868b0999c6eea3d42a10f2b20433c5ea93720/samples/AspireWithJavaScript/AspireJavaScript.Vue/src/components/TheWelcome.vue).