Environment variables

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:

C# — AppHost.cs

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

提示

In applications that use .NET configuration, access connection strings with builder.Configuration.GetConnectionString("my-cache"), which automatically resolves the ConnectionStrings__ prefix. Applications that read environment variables directly use the full environment variable name.

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:

C# — AppHost.cs

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:

1. Unsupported characters are replaced with underscores: Hyphens (-), dots (.), and any other characters that aren’t ASCII letters, digits, or underscores are replaced with _.
2. Leading digits get a prefix: If the name starts with a digit, an underscore (_) is prepended.
3. 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

注意

Connection string variables (ConnectionStrings__) do not apply encoding to the resource name. The original resource name (including hyphens) is preserved.

Accessing environment variables

C#

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

C# — Program.cs

// 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

Python — main.py

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

JavaScript — app.js

// 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;

警告

In JavaScript, process.env is an object. Property names containing hyphens require bracket notation: process.env["ConnectionStrings__my-cache"].

Custom environment variables

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

C# — AppHost.cs

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.

提示

Use the Aspire dashboard to inspect the actual environment variables that Aspire injects into each resource. This is the fastest way to discover the exact variable names available to your application.

See also

• Service discovery
• Inner-loop networking overview
• Python integration
• JavaScript integration
• Executable resources
• Legacy deployment manifest format