In Aspire 13, how does a WithReference in the AppHost reach a client integration's connection string, and what breaks when the names disagree?
answer
- an environment variable, then configuration
- double underscore becomes a colon
- resource name equals connectionName
- 13.0 adds RECIPESDB_HOST-style properties
- 13.6 adds a portable underscore alias
basics
~20 sWithReference sets ConnectionStrings__<resource name> on the service; the environment-variable provider exposes it as ConnectionStrings:<name>, which the client call reads by the name it is given. If the names differ, the client throws InvalidOperationException for a missing connection string.
solid answer
~40 s`WithReference(recipesDb)` makes the AppHost set `ConnectionStrings__recipesdb` on the recipe API's process. ASP.NET Core's environment-variable configuration provider maps `__` to `:`, so the API sees `ConnectionStrings:recipesdb`, and `builder.AddNpgsqlDbContext<RecipesDbContext>("recipesdb")` looks up exactly that key. Pass the server's name or a typo and nothing is found: the EF Core integration throws `InvalidOperationException` ("ConnectionString is missing") the first time a `RecipesDbContext` is resolved, and the Redis integration throws "No endpoints specified" when `IConnectionMultiplexer` is first resolved. Aspire 13 also injects split connection properties such as `RECIPESDB_HOST` and `RECIPESDB_URI` for apps that build their own strings, and 13.6 adds a portable alias for names with hyphens — `recipes-db` also arrives as `ConnectionStrings__recipes_db`, and Kubernetes-based publishers emit only the alias.
code
csharp · 11 lines// Recipes.Api/Program.cs
var builder = WebApplication.CreateBuilder(args);
// All three read the key set by WithReference(recipesDb):
// environment variable ConnectionStrings__recipesdb -> configuration key ConnectionStrings:recipesdb
var viaConfiguration = builder.Configuration.GetConnectionString("recipesdb");
var viaEnvironment = Environment.GetEnvironmentVariable("ConnectionStrings__recipesdb");
builder.AddNpgsqlDbContext<RecipesDbContext>("recipesdb");
// Wrong: "postgres" is the server resource, which this API never referenced.
// builder.AddNpgsqlDbContext<RecipesDbContext>("postgres");go deeper
Recall that WithReference sets ConnectionStrings__name and that the client call is given the same resource name. Know that __ in a variable name becomes : in configuration.
Trace the path: environment variable, configuration key, client lookup. Explain why referencing the database resource rather than the server gives a string with Database set, and when the missing-string exception fires.
Plan for deployment: supply ConnectionStrings keys where no AppHost runs, avoid hyphenated names for raw readers, and know that 13.6 Kubernetes output carries only the portable alias.
Set a naming convention for resources and connection names across services and languages, and decide which consumers may read split connection properties versus the full connection string.
## The path a connection string travels An Aspire **reference** is the AppHost's statement that one resource depends on another. For a resource that has a connection string — a PostgreSQL database, a Redis cache — the reference becomes **environment variables** on the consuming process. Nothing else is shared: the recipe API has no project reference to the AppHost and makes no call to it. 1. The AppHost declares `var recipesDb = builder.AddPostgres("postgres").AddDatabase("recipesdb");` and calls `.WithReference(recipesDb)` on the recipe API project. 2. When the API starts, the AppHost sets `ConnectionStrings__recipesdb` to the database resource's connection string — the server's `Host`, `Port`, `Username` and `Password` plus `Database=recipesdb`. 3. ASP.NET Core's **environment-variable configuration provider** replaces every `__` in a variable name with `:`, so configuration now holds the key `ConnectionStrings:recipesdb`. 4. `builder.AddNpgsqlDbContext<RecipesDbContext>("recipesdb")` reads that key; `builder.Configuration.GetConnectionString("recipesdb")` would return the same value. The **resource name** is the contract. The optional `connectionName` parameter of `WithReference` can change the logical name the consumer sees, but by default it is the resource's own name. ## When the names disagree | Mistake in the recipe API | What happens | |---|---| | `AddNpgsqlDbContext<RecipesDbContext>("postgres")` while only the database is referenced | no `ConnectionStrings:postgres` key; `InvalidOperationException` the first time a `RecipesDbContext` is requested | | `AddNpgsqlDbContext<RecipesDbContext>("recipesDb")` with a capital D | configuration keys are case-insensitive, so this one still resolves | | `AddRedisClient("redis")` while the resource is `cache` | `InvalidOperationException` ("No endpoints specified") when `IConnectionMultiplexer` is first resolved | | the reference is missing in the AppHost | same failures as a wrong name | The EF Core integration deliberately **delays** the check until the DbContext is first requested, so the app starts and logging is in place before the exception. The message names the keys it tried: `ConnectionStrings:recipesdb`, or a `ConnectionString` key under `Aspire:Npgsql:EntityFrameworkCore:PostgreSQL` or its `RecipesDbContext` sub-section. EF design-time tools are exempt, which is why `dotnet ef` commands can still build the model without a live connection string. ## Connection properties: new in Aspire 13 Aspire 13.0 added **connection properties** for consumers that are not .NET or that want the pieces. Alongside the connection string, a reference to `recipesdb` injects: - `RECIPESDB_HOST`, `RECIPESDB_PORT`, `RECIPESDB_USERNAME`, `RECIPESDB_PASSWORD` - `RECIPESDB_DATABASENAME` (13.2 renamed it from `RECIPESDB_DATABASE`) - `RECIPESDB_URI` (`postgresql://…`) and `RECIPESDB_JDBCCONNECTIONSTRING`, which leaves the credentials out The prefix is the resource name with every non-alphanumeric character turned into `_` and upper-cased. Aspire's .NET client integrations ignore these and keep reading `ConnectionStrings:<name>`. ## Portable names: new in Aspire 13.6 A hyphen is legal in a resource name but not accepted as an environment-variable name by every deployment target. From 13.6, a reference to a resource named `recipes-db` produces both `ConnectionStrings__recipes-db` and a **portable alias** `ConnectionStrings__recipes_db` where the target supports both. Kubernetes-based publishers, Azure App Service and Foundry hosted agents emit **only** the alias. Updated client integrations try the logical key first and fall back to the alias, so `AddNpgsqlDbContext<RecipesDbContext>("recipes-db")` keeps working. Code that reads `Environment.GetEnvironmentVariable("ConnectionStrings__recipes-db")` directly, or an older client package, does not. Names that collapse to the same alias — `recipes-db` and `recipes_db` — now fail when the environment is resolved instead of silently overwriting each other. ## Renaming at the reference When a service already expects a different key — say a legacy API reads `ConnectionStrings:recipes` — the AppHost can rename the logical connection instead of the service changing its code: `.WithReference(recipesDb, connectionName: "recipes")` injects `ConnectionStrings__recipes`, and the split properties take the `RECIPES_` prefix. The resource keeps its own name everywhere else, including the dashboard. ## Practical rules - Name resources in the AppHost with the name the service will ask for, and keep it free of hyphens if any consumer reads environment variables itself. - Reference the **database** resource, not the server, when the client needs a specific database. - In production, supply the same key — `ConnectionStrings__recipesdb` or a `ConnectionStrings` section in configuration — because no AppHost is there to set it. - Upgrade client packages together with the AppHost's hosting packages so both sides agree on naming.
- Why does the recipe API start successfully and only fail on the first request?`AddNpgsqlDbContext` validates the connection string inside the options callback, which runs when a `RecipesDbContext` is first requested, not when the registration runs. The source says this keeps the exception until a logger is established. It also exempts EF design-time tools, so `dotnet ef` can still build the model.
- A Java service in the same AppHost references recipesdb. What does it read?Aspire 13 injects split properties for it: `RECIPESDB_JDBCCONNECTIONSTRING` (`jdbc:postgresql://host:port/recipesdb`, without credentials) plus `RECIPESDB_USERNAME` and `RECIPESDB_PASSWORD`, alongside `RECIPESDB_HOST`, `RECIPESDB_PORT` and `RECIPESDB_URI`. It can also read `ConnectionStrings__recipesdb` like any process.
- After upgrading to Aspire 13.6 and publishing to Kubernetes, code reading ConnectionStrings__recipes-db finds nothing. Why?From 13.6 the Kubernetes publisher keeps only the portable alias, `ConnectionStrings__recipes_db`, because hyphenated names are not portable across its environment projection. Updated client integrations fall back to the alias automatically; hand-written reads must try both names or the resource should use a name without hyphens.
- The client call should pass the PostgreSQL server's name to reach the recipes database.
- AddNpgsqlDbContext throws at registration time when the connection string is missing.
- Aspire's .NET client integrations read RECIPESDB_HOST and RECIPESDB_PORT to build the connection.
- ConnectionStrings__recipes-db is always present after deployment because Aspire set it locally.
- The service must reference the AppHost project to receive its connection strings.
Assumes Aspire 13.6: connection properties such as RECIPESDB_HOST arrived in 13.0, DATABASENAME replaced DATABASE in 13.2, and portable connection-string aliases arrived in 13.6.