From 5cf51a21179d324ccceb3ba577fbd9ff3186838c Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 20 Oct 2025 15:38:05 +0000 Subject: [PATCH 1/4] Initial plan From a4084e30d0e3d04c9935eb5fe77cc40a35d3f861 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 20 Oct 2025 15:46:51 +0000 Subject: [PATCH 2/4] Update documentation with new polyglot environment variable format Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com> --- .../azd/aca-deployment-azd-in-depth.md | 8 ++- docs/deployment/manifest-format.md | 12 ++-- docs/extensibility/dev-tunnels-integration.md | 1 + docs/fundamentals/app-host-overview.md | 57 ++++++++++++++++--- docs/fundamentals/orchestrate-resources.md | 2 +- .../build-aspire-apps-with-nodejs.md | 4 +- 6 files changed, 67 insertions(+), 17 deletions(-) diff --git a/docs/deployment/azd/aca-deployment-azd-in-depth.md b/docs/deployment/azd/aca-deployment-azd-in-depth.md index 777a532241..d34dc201e8 100644 --- a/docs/deployment/azd/aca-deployment-azd-in-depth.md +++ b/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 diff --git a/docs/deployment/manifest-format.md b/docs/deployment/manifest-format.md index 6fc40d16fc..9d6406a53d 100644 --- a/docs/deployment/manifest-format.md +++ b/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}" }, ``` diff --git a/docs/extensibility/dev-tunnels-integration.md b/docs/extensibility/dev-tunnels-integration.md index 76ba0fbd2d..f98dfbb407 100644 --- a/docs/extensibility/dev-tunnels-integration.md +++ b/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` 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/ ``` diff --git a/docs/fundamentals/app-host-overview.md b/docs/fundamentals/app-host-overview.md index 660e46470f..ce2a1c9cc1 100644 --- a/docs/fundamentals/app-host-overview.md +++ b/docs/fundamentals/app-host-overview.md @@ -176,9 +176,16 @@ Project-to-project references are handled differently than resources that have w | Method | Environment variable | |--|--| | `WithReference(cache)` | `ConnectionStrings__cache="localhost:62354"` | -| `WithReference(apiservice)` | `services__apiservice__http__0="http://localhost:5455"`
`services__apiservice__https__0="https://localhost:7356"` | +| `WithReference(apiservice)` | `APISERVICE_HTTP="http://localhost:5455"`
`APISERVICE_HTTPS="https://localhost:7356"`
`services__apiservice__http__0="http://localhost:5455"`
`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 or an , use one of the following endpoint APIs: @@ -202,31 +209,65 @@ var apiservice = builder.AddProject("apiservice") | Method | Environment variable | |---------------------------|-------------------------------------------------------| -| `WithReference(endpoint)` | `services__myapp__endpoint__0=https://localhost:9043` | +| `WithReference(endpoint)` | `MYAPP_ENDPOINT="https://localhost:9043"`
`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 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 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: + +```Environment +APISERVICE_MYENDPOINT +``` + +In the preceding example, the `apiservice` service has a named endpoint called `myendpoint`. -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). +#### .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 method combined with : + +```csharp +var projectA = builder.AddProject("projecta"); +var projectB = builder.AddProject("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 diff --git a/docs/fundamentals/orchestrate-resources.md b/docs/fundamentals/orchestrate-resources.md index 4c50f3a659..9cb3ae9182 100644 --- a/docs/fundamentals/orchestrate-resources.md +++ b/docs/fundamentals/orchestrate-resources.md @@ -285,7 +285,7 @@ var frontend = builder.AddProject("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 diff --git a/docs/get-started/build-aspire-apps-with-nodejs.md b/docs/get-started/build-aspire-apps-with-nodejs.md index 2aaa6da893..6d78a9449a 100644 --- a/docs/get-started/build-aspire-apps-with-nodejs.md +++ b/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). From 5394d237645a6ea146f3e28020652166bc3182b3 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 20 Oct 2025 15:50:11 +0000 Subject: [PATCH 3/4] Add clarification about resource names in environment variables Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com> --- docs/fundamentals/app-host-overview.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/fundamentals/app-host-overview.md b/docs/fundamentals/app-host-overview.md index ce2a1c9cc1..f7d617f327 100644 --- a/docs/fundamentals/app-host-overview.md +++ b/docs/fundamentals/app-host-overview.md @@ -238,6 +238,9 @@ 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 connection string name. Even when using `WithReference(resource, "customname")`, the environment variables use the resource's name. + #### .NET service discovery format 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. From 0d5d09721c6a3f97b2f017427625500db2156079 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 20 Oct 2025 15:51:36 +0000 Subject: [PATCH 4/4] Improve clarity of note about connection name parameter Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com> --- docs/fundamentals/app-host-overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fundamentals/app-host-overview.md b/docs/fundamentals/app-host-overview.md index f7d617f327..5db9f6821c 100644 --- a/docs/fundamentals/app-host-overview.md +++ b/docs/fundamentals/app-host-overview.md @@ -239,7 +239,7 @@ 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 connection string name. Even when using `WithReference(resource, "customname")`, the environment variables use the resource's name. +> 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