Skip to content

Terms of Orchestration in .NET Aspire

There is some core terminology associated with Aspire Orchestration:

Term Description
App Model The heart of your distributed application. This is the master blueprint for the application and it declares everything your solution needs, from microservices to databases.
App Host/Orchestrator The project responsible for running all the resources. This is a special project typically named AppHost
Resources Any piece of the app (databases, microservices, containers). Any item you manage like an ASP.Net Core Web Project, a Redis cache, or a Docker container.
Integration NuGet packages that model or configure services. This is a way to quickly add a service (e.g. Redis or Postgres) which saves writing boilerplate code.
Reference Declares references between resources. A dependency, for example between a front end refgerencing a Redis cache.

Defining the App Model of Orchestration

Defining the app model means describing the resources like microservices and external services and their relationships. this happens in your app host project, for example:

var builder = DistributedApplication.CreateBuilder(args);

// Add Resources

// Express dependencies

builder.Build().Run();

Start with the DistributedApplication.CreateBuilder() method, which returns a distributed application builder which you can use to declare your resources.

When everything is set up Aspire automates provisioning, deploying, configuring, and running everything in the correct order.

App Host/Orchestrator Project

The AppHost project is an orchestrator project where you physically place your application model code. In the project file there will be a setting <IsAspireHost> which will be set to true and this tells NET Aspire that this project will orchestrate other resources. The NuGet package Aspire.Hosting.AppHost will also be included to provide ther necessary APIs to define the application model.

The SDK will be defined as Aspire.AppHost.Sdk which includes a build task to handle the containerisation and more.

For example, Redis and two projects:

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache");

var apiService = builder.AddProject<Projects.AspireApp_ApiService>("apiservice");

builder.AddProject<Projects.AspireApp_Web>("webfrontend")
       .WithExternalHttpEndpoints()
       .WithReference(cache)
       .WaitFor(cache)
       .WithReference(apiservice)
       .WaitFor(apiservice)

builder.Build().Run();

As you can see here we basically start by creating a distributed application, then use an AddRedis() method to set up a Redis container with the resource name "cache".

Then we use the AddProject() method to include the API services and web front end projects. After this we configure the frontend project with the WithExternalHttpEndpoints() which exposes ports for the front end to allow users to access it from their browsers.

We then add references and wait for the Redis service, so the front end project depends on the Redis service and must wait for it to be ready before starting the web front end.

We then add references and wait for the API services, so the front end project depends on the API services and must wait for them to be ready before starting the web front end.

This ensures the resources are setup and launched in the correct order.

Built-In Resource Types of Orchestration

There are some built in add methods that we can use when configuring our AppHost project. In .NET Aspire you can add various resources into your app host project:

  • AddProject will reference a project in your solution.
  • AddContainer references a container resource, for example any Docker image resource you want to bring into your ecosystem.
  • AddExecutable will add an executable, for example a Node.js application or other executable you rely on.
  • AddParameter to pass external parameters such as environment variables or secrets.

So we define the app model in the AppHost (.AppHost) project, and after that we can add and configure resources like microservice projects, cache, and databases using the built-in integrations. We use references and WaitFor to express dependencies and the start-up order, then build and run will let Aspire automatically launch the containers, orchestrates networking, and injects environment variables.

Everything is connected and ready to go.