Skip to content
Katabench
Try free
Course preview Katabench Labs for .NET developers

Build a distributed app with the Aspire CLI.
From an empty folder to Docker Compose.

Start from an empty folder and one in-memory API. With the Aspire CLI you add an AppHost, Redis and PostgreSQL, wire the API to them, add telemetry and a background worker, keep data and secrets safe, operate the app from the terminal, and publish it as Docker Compose. Twelve lessons, about 90 minutes.

Get notified when Labs opens See the lessons

Intermediate · C#, Aspire CLI 13.6.1, PostgreSQL, Redis · About 90 minutes · Disposable browser workspace · Pro workspace in private beta

The Shortly app model: an AppHost created with aspire new orchestrates the api and stats projects, a PostgreSQL database with a data volume and a Redis cache, passes an admin-key secret to the api, sends telemetry to the dashboard, and publishes everything as a Docker Compose file.

Outcomes

What you will be able to do

  • Create a file-based AppHost and add hosting integrations with aspire new and aspire add
  • Wire services to PostgreSQL and Redis with references, client integrations and startup ordering
  • Turn on telemetry and health checks with ServiceDefaults and read traces with aspire otel
  • Keep data in volumes and secrets in parameters, and operate resources with aspire resource, wait, logs and export
  • Publish the app model as Docker Compose and know which deployment inputs stay yours

12 lessons in 3 modules

One app, built up from an empty folder

Each lesson starts where the previous one stopped. You add one piece from the terminal, watch it start, and press Check, so the last lesson publishes the app you built.

Module 1

Start from an empty folder

Create a file-based AppHost with the Aspire CLI and let it run a real Redis container.

2 lessons · 13 minutes

  1. Lesson 1 7 min

    Create the AppHost

    Scaffold a file-based AppHost next to the API, start it in the background, and ask the CLI what is running.

  2. Lesson 2 6 min

    Add a Redis container

    Add the Redis hosting integration with aspire add and watch the AppHost start a real container.

Module 2

Wire the API to real infrastructure

Put the API under the AppHost, move its links into PostgreSQL, cache redirects in Redis, and turn on telemetry.

4 lessons · 32 minutes

  1. Lesson 3 7 min

    Orchestrate the API

    Reference the API project from the AppHost, give it a health check, and call it through Aspire's proxy.

  2. Lesson 4 9 min

    Store links in PostgreSQL

    Add PostgreSQL, inject its connection string into the API, and prove a link survives an API restart.

  3. Lesson 5 8 min

    Cache redirects in Redis

    Serve hot redirects from Redis with cache-aside and count every click with one atomic increment.

  4. Lesson 6 8 min

    Add service defaults

    Scaffold ServiceDefaults, wire it into the API, and follow one redirect as a trace from the terminal.

Module 3

Grow, operate and ship

Add a background worker, keep data and secrets safe, operate the app from the CLI, and publish it as Docker Compose.

6 lessons · 45 minutes

  1. Lesson 7 6 min

    Scaffold a worker

    Create a worker service with dotnet new and add it to the AppHost with the same references as the API.

  2. Lesson 8 8 min

    Flush clicks to PostgreSQL

    Turn the worker into a batch job that moves click counters from Redis into PostgreSQL.

  3. Lesson 9 7 min

    Keep data across restarts

    Watch a restart wipe the database, then give PostgreSQL a named volume so links survive.

  4. Lesson 10 8 min

    Protect stats with a secret

    Add an admin endpoint, guard it with a secret parameter, and set the secret with aspire secret.

  5. Lesson 11 8 min

    Operate Shortly from the terminal

    Stop the worker, watch clicks queue up in Redis, start it again, and export the evidence.

  6. Lesson 12 8 min

    Publish for Docker Compose

    Add a Docker Compose environment, publish the app model, fill in what is yours to provide, and run the published infrastructure.

Build a distributed app with the Aspire CLI

1 lab · 12 lessons · about 90 minutes · Intermediate

See the lesson loop

The lesson loop

Real commands, a few lines of C#

The Aspire CLI pane is where the course happens. You run aspire new, add, start, wait, logs, and otel, read what they print, and edit the AppHost, the API, or the worker when a lesson adds code. If you get stuck, Reveal solution loads the working files for the lesson.

AppHost/apphost.cs
var builder = DistributedApplication.CreateBuilder(args);

var adminKey = builder.AddParameter("admin-key", secret: true);

var db = builder.AddPostgres("postgres")
    .WithDataVolume()
    .AddDatabase("shortly");

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

builder.AddProject<Projects.Api>("api")
    .WithHttpHealthCheck("/health")
    .WithReference(db).WaitFor(db)
    .WithReference(cache).WaitFor(cache)
    .WithEnvironment("ADMIN_KEY", adminKey);
// the stats worker gets the same db and cache references
  1. 1

    Run

    Every command is in the guide, pinned to Aspire 13.6.1, so the output you see matches the output you read.

  2. 2

    Read

    Ask the CLI what is running. aspire ps, describe, and wait report each resource and its health.

  3. 3

    Change

    Add a resource, a reference, or a few lines in the API, then start the AppHost again.

  4. 4

    Check

    Check reads the line you saw and probes the running app, so the AppHost has to be up when you press it.

Executable evidence

The check asks the running app, not your source

Resources

A running AppHost from your apphost.cs, healthy Redis and PostgreSQL, and the api and stats projects with their references.

Data

A link survives an API restart and a full stop and start, redirects are cached in Redis, and clicks reach PostgreSQL.

Telemetry and secrets

aspire otel shows the API's PostgreSQL span, and the admin endpoint answers 401 without the secret and 200 with it.

Publish

aspire publish writes a Docker Compose file with every service, and its PostgreSQL service runs.

More Labs courses

Build another system

  • Implement the Transactional Outbox pattern

    Store the event with the order, relay it to RabbitMQ, and make duplicates and poison messages harmless.

    4 lessons · about 30 minutes

    See the course

  • Build an async API: 202 Accepted, background jobs, and polling

    Turn a slow endpoint into 202 Accepted, a background worker, and polling on real PostgreSQL, then make it survive retries and crashes.

    11 lessons · about 85 minutes

    See the course

Get notified when Labs opens

Live Pro workspaces are in private beta. The opening is announced in the Katabench newsletter, a short note when fresh kata land. No spam, unsubscribe anytime.

Try a graded kata while you wait