In Aspire 13, what is the difference between a hosting integration and a client integration, and which project gets each package?
answer
- two packages, two projects
- Aspire.Hosting.* lives in the AppHost
- client package extends IHostApplicationBuilder
- configuration is the only bridge
- works without an AppHost
basics
~20 sA 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 sThey 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<!-- 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
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.
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.
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.
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.