Environment variables

Este conteúdo não está disponível em sua língua ainda.

When you use WithReference to connect resources in the AppHost, Aspire automatically injects environment variables into the consuming resource. This process is called configuration injection.

These environment variable names follow specific conventions based on the referenced resource’s name and type. Understanding the conventions is especially useful for applications that read environment variables directly instead of relying on typed Aspire client integrations.

Naming conventions

Aspire generates environment variables in different formats depending on the type of resource being referenced. The following sections describe each category.

Connection strings

When you reference a resource that exposes a connection string (such as a database, cache, or messaging resource), Aspire generates an environment variable using the ConnectionStrings__ prefix:

ConnectionStrings__{resource-name}

The resource name is used as-is (preserving the original casing and hyphens). For example:

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("my-cache");
var db = builder.AddPostgres("postgres").AddDatabase("my-db");

var api = builder.AddProject<Projects.Api>("api")
    .WithReference(cache)
    .WithReference(db);

// After adding all resources, run the app...
builder.Build().Run();

The api resource receives the following environment variables:

Environment variable	Description
`ConnectionStrings__my-cache`	Connection string for the Redis cache
`ConnectionStrings__my-db`	Connection string for the PostgreSQL database

Endpoint URLs

When you reference a resource that exposes endpoints (such as a project or container service), Aspire generates an environment variable for each endpoint. The resource name and endpoint name are encoded (hyphens and other non-alphanumeric characters are replaced with underscores), then uppercased:

{RESOURCE_NAME}_{ENDPOINT_NAME}

For example:

var builder = DistributedApplication.CreateBuilder(args);

var api = builder.AddProject<Projects.Api>("my-api");

var frontend = builder.AddJavaScriptApp("frontend", "./app")
    .WithReference(api);

// After adding all resources, run the app...
builder.Build().Run();

The frontend resource receives:

Environment variable	Example value
`MY_API_HTTP`	`http://localhost:5000`
`MY_API_HTTPS`	`https://localhost:5001`

The suffix comes from the endpoint name, not necessarily its URI scheme. For example, a named endpoint called admin on my-api produces MY_API_ADMIN. For resource endpoints, Aspire retains the endpoint suffix even when the resource exposes only one endpoint.

Service discovery variables

Aspire also generates service discovery variables for .NET service resolution. These use the format:

services__{resource-name}__{endpoint-key}__{index}

The services prefix and double-underscore (__) separators are fixed, but the resource name preserves the casing used in the AppHost. For example, AddProject<Projects.Api>("MyApi") with an HTTP endpoint produces services__MyApi__http__0. The endpoint key is the scheme for endpoints named http or https; otherwise, Aspire uses the endpoint name. Applications that don’t use .NET service discovery can read the endpoint URL variables instead.

Resource properties

Some integrations expose individual resource properties as environment variables. The resource name is encoded (hyphens replaced with underscores) and uppercased, with the property name appended:

{RESOURCE_NAME}_{PROPERTY}

For example, a ClickHouse resource named my-clickhouse exposes:

Environment variable	Description
`MY_CLICKHOUSE_HOST`	The hostname
`MY_CLICKHOUSE_PORT`	The port number
`MY_CLICKHOUSE_USERNAME`	The username
`MY_CLICKHOUSE_PASSWORD`	The password
`MY_CLICKHOUSE_DATABASENAME`	The database name

Resource name encoding rules

When a resource name is used in an endpoint URL or property variable, Aspire applies the following transformations:

Unsupported characters are replaced with underscores: Hyphens (-), dots (.), and any other characters that aren’t ASCII letters, digits, or underscores are replaced with _.
Leading digits get a prefix: If the name starts with a digit, an underscore (_) is prepended.
The result is uppercased: The encoded name is converted to uppercase for the final environment variable name.

For example, a resource named foundry-demo-proj becomes FOUNDRY_DEMO_PROJ in environment variable prefixes:

Resource name	Encoded prefix	Example variable
`api`	`API`	`API_HTTP`
`my-api`	`MY_API`	`MY_API_HTTPS`
`foundry-demo-proj`	`FOUNDRY_DEMO_PROJ`	`FOUNDRY_DEMO_PROJ_URI`

Accessing environment variables

C#

In .NET applications, Aspire client integrations handle environment variable access automatically. For manual access:

// Connection strings
string cache = builder.Configuration.GetConnectionString("my-cache");

// Endpoint URLs
string apiUrl = builder.Configuration.GetValue<string>("MY_API_HTTP");

// Resource properties
string host = builder.Configuration.GetValue<string>("MY_CLICKHOUSE_HOST");

Python

import os

# Connection strings
cache_conn = os.getenv("ConnectionStrings__my-cache")

# Endpoint URLs
api_url = os.getenv("MY_API_HTTP")

# Resource properties
db_host = os.getenv("MY_CLICKHOUSE_HOST")

JavaScript / TypeScript

// Connection strings (use bracket notation for names with hyphens)
const cacheConn = process.env['ConnectionStrings__my-cache'];

// Endpoint URLs
const apiUrl = process.env.MY_API_HTTP;

// Resource properties
const dbHost = process.env.MY_CLICKHOUSE_HOST;

Custom environment variables

If you need different variable names, use WithEnvironment to set custom environment variables:

var builder = DistributedApplication.CreateBuilder(args);

var db = builder.AddPostgres("postgres").AddDatabase("my-db");

var api = builder.AddPythonApp("api", "../api", "main.py")
    .WithReference(db)
    .WithEnvironment("DB_HOST", db.Resource.Parent.PrimaryEndpoint.Property(EndpointProperty.Host))
    .WithEnvironment("DB_PORT", db.Resource.Parent.PrimaryEndpoint.Property(EndpointProperty.Port));

// After adding all resources, run the app...
builder.Build().Run();

This approach lets you define explicit, predictable variable names without relying on the automatic naming conventions.