skip to content

AppHost Resource Model

The AppHost is a C# project that declares services, containers and databases, wires them with WithReference and WaitFor, and starts them together. Interviewers test the resource model.

on this pageshow

explore

questions

5

In Aspire 13, what is the AppHost project, and what do its project file and AppHost.cs contain?

level: juniorimportance: must knowfreq 62%

answer

  1. an orchestrator, not a service
  2. Project Sdk="Aspire.AppHost.Sdk/13.x"
  3. DistributedApplication.CreateBuilder(args)
  4. ProjectReference generates a Projects.* class
  5. Build().Run() starts the whole graph

basics

~10 s

The AppHost is a small C# executable that only describes and starts the distributed app: its project file uses Aspire.AppHost.Sdk, and AppHost.cs calls DistributedApplication.CreateBuilder, adds resources such as AddProject<Projects.X>, then Build().Run().

solid answer

~40 s

The AppHost is the orchestration project of an Aspire solution. It holds no business code: it declares a resource graph and starts it locally. In Aspire 13 its project file is `<Project Sdk="Aspire.AppHost.Sdk/13.x">`, and the SDK brings `Aspire.Hosting.AppHost` implicitly, where 9.x needed an explicit `PackageReference`. It also carries a `UserSecretsId` and `ProjectReference` items to the service projects plus hosting packages such as `Aspire.Hosting.PostgreSQL`. Each project reference makes the build generate a class such as `Projects.PizzaShop_Api` that only holds the project path; the AppHost never loads the service's assembly. `AppHost.cs` calls `DistributedApplication.CreateBuilder(args)`, adds resources with `AddProject`, `AddPostgres` or `AddRedis`, wires them with `WithReference` and `WaitFor`, and ends with `builder.Build().Run()`, which launches every resource as its own process or container and starts the dashboard.

code

xml · 21 lines
xml
<Project Sdk="Aspire.AppHost.Sdk/13.6.0">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net10.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <UserSecretsId>5d1c2f0e-8a8b-4f7e-9b3a-2a6c0d4e7f11</UserSecretsId>
  </PropertyGroup>

  <ItemGroup>
    <ProjectReference Include="..\PizzaShop.Api\PizzaShop.Api.csproj" />
    <ProjectReference Include="..\PizzaShop.Worker\PizzaShop.Worker.csproj" />
  </ItemGroup>

  <ItemGroup>
    <PackageReference Include="Aspire.Hosting.PostgreSQL" Version="13.6.0" />
    <PackageReference Include="Aspire.Hosting.Redis" Version="13.6.0" />
  </ItemGroup>

</Project>

go deeper

for a junior

Recall the two files: a project on Aspire.AppHost.Sdk and an AppHost.cs that creates a DistributedApplication builder, adds resources and calls Build().Run().

for a middle

Explain how a ProjectReference turns into a generated Projects.* class that carries only the project path, and why the AppHost never loads the service's assembly.

for a senior

Show you know what the 13.0 SDK changed for an upgrade from 9.x, and that the AppHost describes the system for local runs and publishing but is not a production supervisor.

for a principal

Be ready to argue where the AppHost's resource graph is the single source of truth for a team and where deployment tooling or platform manifests should own the shape instead.

## What the AppHost is, and what it is not An Aspire solution for a pizza-ordering system typically holds an ordering API, a background worker that drives the oven queue, a **ServiceDefaults** project, and one extra project: the **AppHost**. The AppHost is a console executable whose only job is to describe the distributed application as a graph of **resources** and to start that graph on a developer machine. It contains no endpoints, no `DbContext` and no domain logic. - It is **not** a reverse proxy the services run behind. - It does **not** host the services in its own process: each project runs as a separate process and each container runs in Docker or Podman. - It is **not** what runs in production. Publishing reads the same model to produce deployment artifacts, but the AppHost process does not stay in production supervising anything. ## The project file Since Aspire 13.0 the AppHost names its SDK directly in the `Project` element: `<Project Sdk="Aspire.AppHost.Sdk/13.6.0">`. The SDK sets `IsAspireHost` to `true`, imports the ordinary .NET SDK, and adds an implicit `PackageReference` to **`Aspire.Hosting.AppHost`** unless the project already references it. In 9.x the file started from `Microsoft.NET.Sdk`, added `<Sdk Name="Aspire.AppHost.Sdk" .../>` as a second element, and listed `Aspire.Hosting.AppHost` by hand. The rest of the file is familiar: - `OutputType` is `Exe` and the template's default framework is `net10.0`. - `UserSecretsId` is present, because parameters and generated passwords are stored in the AppHost's user secrets. - One `ProjectReference` per .NET service the AppHost will orchestrate. - One `PackageReference` per **hosting integration**, for example `Aspire.Hosting.PostgreSQL` or `Aspire.Hosting.Redis`. ## How `Projects.X` types appear The SDK treats every `ProjectReference` as an Aspire project resource unless the item says `IsAspireProjectResource="false"`. For those references it sets `ReferenceOutputAssembly` to `false`, `ExcludeAssets` to `all` and `Private` to `false`, so the service's DLL is never copied into or loaded by the AppHost. Instead the build writes a small generated class into the `Projects` namespace: 1. The class name is the project file name with periods, dashes and spaces turned into underscores, so `PizzaShop.Api.csproj` becomes `Projects.PizzaShop_Api`. 2. The class implements `IProjectMetadata` and exposes `ProjectPath`, the full path of the project file. 3. `AddProject<Projects.PizzaShop_Api>("pizza-api")` uses that path to read the project's `launchSettings.json` and derive its endpoints. When two projects normalize to the same class name, the `AspireProjectMetadataTypeName` metadata on the `ProjectReference` overrides it. ## AppHost.cs The entry file is a top-level program. `DistributedApplication.CreateBuilder(args)` returns an `IDistributedApplicationBuilder`, which offers `Configuration`, `Services` and `Environment` like other .NET builders, plus the `Add*` methods that create resources: - `AddProject<T>(name)` for a .NET project, `AddContainer(name, image)` for any image, `AddExecutable(name, command, workingDirectory)` for a host process. - Integration methods such as `AddPostgres("postgres").AddDatabase("ordersdb")` and `AddRedis("cache")`. - `AddParameter(name, secret: true)` for values that come from configuration. Each `Add*` returns an `IResourceBuilder<T>`, and fluent calls such as `WithReference`, `WaitFor` or `WithEnvironment` annotate the resource. The **name** passed to each `Add*` call is the resource's identity: it is shown in the dashboard and becomes the key the consuming service uses to find a connection string or an endpoint. `builder.Build().Run()` then hands the model to the orchestrator, which starts the resources in dependency order and opens the dashboard. ## Running it `aspire run` finds the AppHost, records it in `aspire.config.json`, checks the local development certificate, builds the AppHost and its referenced projects, starts everything and prints the dashboard URL with a login token. Running the AppHost project directly from the IDE or with `dotnet run` also works, because the template ships a launch profile that sets the dashboard's URLs. | Aspect | Aspire 9.x | Aspire 13 | |---|---|---| | SDK declaration | `Microsoft.NET.Sdk` plus `<Sdk Name="Aspire.AppHost.Sdk" .../>` | `<Project Sdk="Aspire.AppHost.Sdk/13.x">` | | `Aspire.Hosting.AppHost` | explicit `PackageReference` | implicit, added by the SDK | | Supported .NET | .NET 8 or .NET 9 | the .NET 10 SDK or later | | Single-file AppHost | not available | `#:sdk [email protected]` | Upgrading from 8.x goes through 9.x first, and `aspire update` rewrites the SDK version and the Aspire package versions. ## Misreadings interviewers listen for - Calling `builder.AddServiceDefaults()` in the AppHost: that call belongs in each service, not in the orchestrator. - Expecting an edit to `AppHost.cs` to apply while the AppHost runs: by default `aspire run` starts the graph once, so the AppHost is stopped and run again after editing it. - Treating the resource name as cosmetic: renaming `ordersdb` changes the key every consumer reads.

  • Why does the AppHost reference each service project but never load the service's assembly?
    The SDK marks each `ProjectReference` as an Aspire project resource and sets `ReferenceOutputAssembly` to `false`, `ExcludeAssets` to `all` and `Private` to `false`. The reference still makes the build compile the service first and lets it generate the `Projects.*` class with the project path, but the service runs as its own process. A library the AppHost really calls, such as a custom hosting integration, gets `IsAspireProjectResource="false"`.
  • Two projects named Pizza.Api and Pizza-Api both normalize to Projects.Pizza_Api. How do you resolve the clash?
    Put `AspireProjectMetadataTypeName="..."` on one of the `ProjectReference` items. The SDK uses that value instead of the file name when it generates the class, so `AddProject<T>` gets two distinct types.
  • Does an AppHost have to be started with aspire run?
    No. `aspire run` adds conveniences: it locates the AppHost, records it in `aspire.config.json`, checks the development certificate and prints the dashboard URL with its login token. Starting the AppHost project from the IDE or with `dotnet run` also works, because the template's launch profile sets `ASPNETCORE_ENVIRONMENT` and the dashboard's OTLP and resource-service URLs.

  • The AppHost process runs in production and supervises the services there.
  • AddProject loads the service's assembly and runs the API inside the AppHost process.
  • An Aspire 13 AppHost still needs an explicit Aspire.Hosting.AppHost PackageReference.
  • The AppHost starts with WebApplication.CreateBuilder because it is just another web app.
  • Projects.PizzaShop_Api has to be written by hand as a class implementing IProjectMetadata.

Assumes Aspire 13.6; since 13.0 the Aspire.AppHost.Sdk brings Aspire.Hosting.AppHost implicitly and needs the .NET 10 SDK, while 9.x projects referenced the package by hand.

open as a page

In an Aspire AppHost, what is the difference between WithReference and WaitFor, and why does a pizza-ordering API usually need both on its database?

level: middleimportance: must knowfreq 58%

basics

~20 s

WithReference tells the consumer where a dependency is by injecting its connection string or endpoints at start; WaitFor holds the consumer back until that dependency is running and healthy. Without WaitFor the API can start before PostgreSQL accepts connections.

open as a page

In an Aspire AppHost, how do AddProject, AddContainer and AddExecutable differ, and when would you pick each one?

level: middleimportance: should knowfreq 42%

basics

~20 s

AddProject runs a referenced .NET project as a process and reads its launch profile for endpoints; AddContainer runs any image through Docker or Podman; AddExecutable runs any host command. All three share WithReference, WaitFor and WithEnvironment.

open as a page

In an Aspire AppHost, how does AddParameter with secret: true get its value at run time, and what does marking it secret actually change?

level: seniorimportance: should knowfreq 38%

basics

~20 s

AddParameter creates a parameter resource whose value comes from the AppHost configuration key Parameters:{name}, from user secrets, appsettings or environment variables, or else from a dashboard prompt. secret: true masks it and makes publishing treat it as a secret; it encrypts nothing.

open as a page

An Aspire AppHost uses AddPostgres with WithDataVolume, and after a teammate clears user secrets PostgreSQL rejects the password: why, and how do you fix it?

level: seniorimportance: should knowfreq 27%

basics

~20 s

AddPostgres generates a postgres-password parameter that the run saves to the AppHost's user secrets. The data volume was initialized with that password, so clearing secrets makes Aspire generate and inject a new one the existing database rejects.

open as a page