skip to content

Hosting & Client Integrations

Aspire integrations come in pairs: a hosting package models a resource in the AppHost, and a client package like AddNpgsqlDbContext reads its connection string. Interviewers ask what each adds.

on this pageshow

explore

questions

6

In Aspire 13, what is the difference between a hosting integration and a client integration, and which project gets each package?

level: middleimportance: must knowfreq 45%

answer

  1. two packages, two projects
  2. Aspire.Hosting.* lives in the AppHost
  3. client package extends IHostApplicationBuilder
  4. configuration is the only bridge
  5. works without an AppHost

basics

~20 s

A hosting integration (an Aspire.Hosting.* package) goes in the AppHost and models a resource such as a PostgreSQL container. A client integration goes in the consuming service and registers a configured client, health check and telemetry from a connection string.

solid answer

~40 s

They are the two halves of one dependency. In a recipe solution the AppHost references `Aspire.Hosting.PostgreSQL` and `Aspire.Hosting.Redis`, calls `AddPostgres("postgres").AddDatabase("recipesdb")` and `AddRedis("cache")`, and `WithReference` hands the recipe API `ConnectionStrings__recipesdb` and `ConnectionStrings__cache` as environment variables. The recipe API references the client packages `Aspire.Npgsql.EntityFrameworkCore.PostgreSQL` and `Aspire.StackExchange.Redis` and calls `builder.AddNpgsqlDbContext<RecipesDbContext>("recipesdb")` and `builder.AddRedisClient("cache")`. Those calls read `ConnectionStrings:recipesdb` and `ConnectionStrings:cache` from configuration and register the DbContext or `IConnectionMultiplexer` with retries, a health check and tracing. The halves meet only through configuration, so each is optional: a service can read the variable by hand, and a client package works in a deployment with no AppHost as long as the connection string is supplied.

code

xml · 17 lines
xml
<!-- Recipes.AppHost.csproj: hosting packages -->
<Project Sdk="Aspire.AppHost.Sdk/13.6.0">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net10.0</TargetFramework>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Aspire.Hosting.PostgreSQL" Version="13.6.0" />
    <PackageReference Include="Aspire.Hosting.Redis" Version="13.6.0" />
  </ItemGroup>
</Project>

<!-- Recipes.Api.csproj (excerpt): client packages -->
<ItemGroup>
  <PackageReference Include="Aspire.Npgsql.EntityFrameworkCore.PostgreSQL" Version="13.6.0" />
  <PackageReference Include="Aspire.StackExchange.Redis" Version="13.6.0" />
</ItemGroup>

go deeper

for a junior

Recall the split: Aspire.Hosting.* packages go in the AppHost and describe resources; client packages go in the service and register the client. Name one pair, such as Aspire.Hosting.Redis and Aspire.StackExchange.Redis.

for a middle

Explain the bridge: WithReference sets ConnectionStrings__name, configuration maps it to ConnectionStrings:name, and the client call reads that key by the same name. Say what the client package adds over a hand-written registration.

for a senior

Show that the halves are decoupled on purpose: the client package runs in production without an AppHost, so deployment must supply the same connection-string key. Watch for name drift between the reference and the client call.

for a principal

Weigh whether the team standardises on client packages for their defaults or keeps plain registrations for control, and how package versions stay aligned across AppHost and services in the same release train.

## Two packages for one dependency Aspire splits every backing service — a database, a cache, a broker — into two NuGet packages that live in **different projects** and never reference each other. - A **hosting integration** is an AppHost package. Its id starts with `Aspire.Hosting.` (`Aspire.Hosting.PostgreSQL`, `Aspire.Hosting.Redis`) and the docs tag it `hosting`. It adds extension methods to `IDistributedApplicationBuilder` so the AppHost can describe a **resource**: start a container, point at an existing server, or provision a cloud service. - A **client integration** is a package for the **consuming app**. Its id names the client library it wraps (`Aspire.Npgsql.EntityFrameworkCore.PostgreSQL`, `Aspire.StackExchange.Redis`). It adds extension methods to `IHostApplicationBuilder` — the type `WebApplication.CreateBuilder` returns — that register a ready-to-use client in dependency injection. The divergence matters because the two halves run in different processes: the AppHost orchestrates, and the recipe API serves requests. ## The recipe service, end to end The AppHost project models the database and the cache, then references them from the API: ```csharp var builder = DistributedApplication.CreateBuilder(args); var recipesDb = builder.AddPostgres("postgres").AddDatabase("recipesdb"); var cache = builder.AddRedis("cache"); builder.AddProject<Projects.Recipes_Api>("recipes-api") .WithReference(recipesDb) .WithReference(cache); builder.Build().Run(); ``` The recipe API's `Program.cs` uses the client packages with the **same names**: ```csharp var builder = WebApplication.CreateBuilder(args); builder.AddServiceDefaults(); builder.AddNpgsqlDbContext<RecipesDbContext>("recipesdb"); builder.AddRedisClient("cache"); ``` ## What each half is responsible for | Concern | Hosting integration (AppHost) | Client integration (service) | |---|---|---| | Package example | `Aspire.Hosting.PostgreSQL` | `Aspire.Npgsql.EntityFrameworkCore.PostgreSQL` | | Extends | `IDistributedApplicationBuilder` | `IHostApplicationBuilder` | | Typical call | `AddPostgres(...).AddDatabase("recipesdb")` | `AddNpgsqlDbContext<RecipesDbContext>("recipesdb")` | | Output | a running resource plus a connection string | a DbContext or client in DI | | Extras | dashboard state, deployment model | retries, health check, tracing, metrics | | Needed at run time in production | no — the AppHost does not ship with the service | yes — it is part of the service | ## Telling the two kinds apart When a package name alone does not settle it, three checks do: - **The id.** Official hosting packages start with `Aspire.Hosting.`; official client packages start with `Aspire.` followed by the wrapped library's name (`Aspire.Npgsql`, `Aspire.StackExchange.Redis`, `Aspire.Microsoft.EntityFrameworkCore.SqlServer`). - **The receiver type.** A hosting method extends `IDistributedApplicationBuilder` or an `IResourceBuilder<T>`; a client method extends `IHostApplicationBuilder`. - **What it returns.** Hosting methods return an `IResourceBuilder<T>` you can chain `WithReference` on; client methods return nothing you chain on in the AppHost, because they only add services. One resource can have several client packages: a PostgreSQL database can be consumed through `Aspire.Npgsql` (a raw data source) or `Aspire.Npgsql.EntityFrameworkCore.PostgreSQL` (a DbContext), and both read the same connection string. ## Configuration is the only bridge `WithReference(recipesDb)` makes the AppHost set the environment variable `ConnectionStrings__recipesdb` on the recipe API's process. ASP.NET Core's environment-variable configuration provider turns `__` into `:`, so the API sees the key `ConnectionStrings:recipesdb` — exactly what `builder.Configuration.GetConnectionString("recipesdb")` returns and what `AddNpgsqlDbContext` reads. Nothing else crosses: no project reference, no network call to the AppHost. Three consequences follow: 1. **The client package is optional.** A service can call plain `AddDbContext` with `GetConnectionString("recipesdb")`, or a non-.NET app can read the variable directly. It loses only the defaults the client package adds. 2. **The hosting package is optional for the service.** In production there is no AppHost; whoever deploys the API supplies `ConnectionStrings__recipesdb` (or an `appsettings` entry) and the same client code connects. 3. **The names must match.** The `connectionName` passed to the client call is the resource name used in the AppHost reference. A mismatch is a missing connection string, not a compile error. ## Version notes for Aspire 13 - Aspire 13 needs the .NET 10 SDK for the AppHost, but the 13.6 client packages still target `net8.0`, `net9.0` and `net10.0`, so a service on an older target framework can use them. - Hosting and client packages ship in the same release train (13.6.0 here); upgrading one side and not the other is how naming conventions drift apart. ## Mistakes interviewers listen for - Adding `Aspire.Hosting.PostgreSQL` to the API project so that `AddNpgsqlDbContext` compiles — that method lives in the client package. - Calling `builder.Services.AddNpgsqlDbContext(...)` — the client methods extend the host builder, not `IServiceCollection`, because they also read configuration. - Believing the client package starts the container. Only the AppHost starts resources.

  • Can the recipe API run under the AppHost without any Aspire client package?
    Yes. `WithReference` only sets `ConnectionStrings__recipesdb`; plain `AddDbContext<RecipesDbContext>(o => o.UseNpgsql(builder.Configuration.GetConnectionString("recipesdb")))` connects fine. What you give up is what the client package adds by default: DbContext pooling, the retrying execution strategy, a health check named after the context, and Npgsql tracing and metrics.
  • Does a service that uses Aspire client packages need .NET 10?
    Not as its target framework. An Aspire 13 AppHost needs the .NET 10 SDK, but the 13.6 client packages are built for `net8.0`, `net9.0` and `net10.0`, so a recipe API still targeting `net8.0` can reference `Aspire.StackExchange.Redis` 13.6.0 while the solution is built with the .NET 10 SDK.

A hosting integration is the utility company: it lays the gas line to the house and writes the line's details on the meter label. A client integration is the certified fitter who connects the stove using only what the label says, adding a safety valve and a gauge — and it would connect just as well to a line some other company laid.

  • The client package starts the PostgreSQL container when the service boots.
  • The API project needs Aspire.Hosting.PostgreSQL before AddNpgsqlDbContext will compile.
  • AddNpgsqlDbContext fetches its connection string from the AppHost over the network.
  • Client integrations only work when the service is launched by aspire run.
  • AddRedisClient is called on builder.Services like any other registration.

Assumes Aspire 13.6: an Aspire 13 AppHost needs the .NET 10 SDK, while the 13.6 client packages still target net8.0, net9.0 and net10.0.

open as a page

In an Aspire 13 service, what do AddNpgsqlDbContext<RecipesDbContext>("recipesdb") and AddRedisClient("cache") register beyond a bare DbContext and Redis connection?

level: middleimportance: should knowfreq 35%

basics

~20 s

AddNpgsqlDbContext registers a pooled DbContext with Npgsql's retrying execution strategy, a health check named after the context, and Npgsql tracing and metrics. AddRedisClient registers a singleton IConnectionMultiplexer that tolerates a slow start, plus a Redis health check and tracing.

open as a page

In Aspire 13, how does a WithReference in the AppHost reach a client integration's connection string, and what breaks when the names disagree?

level: middleimportance: should knowfreq 40%

basics

~20 s

WithReference 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.

open as a page

With Aspire 13 client integrations, how do the Aspire:* configuration sections, the Disable* settings and the configureSettings delegate combine, and when would you switch a feature off?

level: seniorimportance: should knowfreq 25%

basics

~20 s

Each client package binds a settings class from its Aspire:* section, lets ConnectionStrings:<name> override the connection string, then runs the configureSettings delegate last. Disable* flags turn off retries, health checks, tracing or metrics per client.

open as a page

An ASP.NET Core 10 recipe API already calls AddDbContext<RecipesDbContext>; what happens when Aspire 13's AddNpgsqlDbContext is added, and what should you call instead?

level: seniorimportance: should knowfreq 20%

basics

~10 s

In the Development environment AddNpgsqlDbContext throws InvalidOperationException because RecipesDbContext is already registered; elsewhere the check is skipped. Keep the existing registration and call EnrichNpgsqlDbContext<RecipesDbContext>(), which adds retries, a health check and telemetry to it.

open as a page

What does the Aspire 13 CLI command aspire add install, and where do the Aspire Community Toolkit's integrations fit?

level: juniorimportance: nice to knowfreq 25%

basics

~20 s

aspire add searches NuGet for hosting integrations — Aspire.Hosting.* and CommunityToolkit.Aspire.Hosting.* packages — and adds the chosen one to the AppHost. The matching client package goes into the service separately, for example with dotnet package add.

open as a page