Clean Architecture Toolkit for .NET
Clean Architecture Toolkit is a clean, modular architecture foundation for .NET applications. It embraces SOLID principles and focuses on maintainability, testability, and scalability through clear boundaries and pluggable design.
|   HOME   |   MODULE OVERVIEW   |   DEMO   |

Aspire plan

This plan covers the first Aspire AppHost of the demo.
It is part of Demo.md. The demo plan says what Aspire hosts. This plan says how we build it, in which order.

Contents

• The goal
• Decisions
• Starting point
• Projects
• How the AppHost works
• Swapping the price provider
• Phases
• Later
• Open questions

The goal

One command starts the whole demo, and the Aspire dashboard shows it.

• Catalog and Orders run as projects.
• They get their connection strings and service URLs from the AppHost.
• Logs, traces, metrics and health checks are in the dashboard.
• Orders asks Catalog for the current price of every book, instead of using the fake.

React, the gateway, Keycloak, the Service Bus and Inventory are not part of this build. See Later.

Decisions

Starting point

• Catalog and Orders are code first and apply their EF Core migrations at startup in Development.
• Both read their database from the connection strings catalog and orders. These are the names the AppHost will use as well, so the services do not change for it.
• Both have an IsDevelopment seeder and fixed launch profile ports: Catalog 5101, Orders 5102.
• The .http files use those ports.
• Orders registers FakePriceProvider in Orders.Infrastructure.
• Docker Desktop and WSL2 are installed on the owner’s machine, so both modes run here. WSL2 is limited by .wslconfig to 8 GB, 4 processors and 2 GB swap.

Projects

Follow the demo-structure skill. It also keeps CleanArchitectureToolkit.slnx in sync.

demo/
  Cat.Demo.AppHost/
    Cat.Demo.AppHost/
  Cat.Demo.ServiceDefaults/
    Cat.Demo.ServiceDefaults/

• ServiceDefaults. The standard Aspire project: telemetry, health checks, service discovery and the resilience handler for HttpClient.
• AppHost. Describes the system. It references the Api project of each service.
• Service changes. Each Api project references ServiceDefaults and calls AddServiceDefaults() and MapDefaultEndpoints(). Nothing else in the services changes.
• Modules. No module may reference Aspire or ServiceDefaults. Only the demo does.

How the AppHost works

SQL Server modes

A setting in the AppHost configuration, Sql:Mode, picks one of two modes.

• In Existing mode the AppHost reads ConnectionStrings:catalog and ConnectionStrings:orders. The defaults are the strings that sit in the appsettings.Development.json of the services.
• The default mode is Container, because a clone should need one command. A developer without Docker sets Sql:Mode to Existing in the user secrets of the AppHost.
• The services see no difference. They always read GetConnectionString("catalog") and GetConnectionString("orders").
• In Container mode the AppHost limits the memory of SQL Server with MSSQL_MEMORY_LIMIT_MB, as described in the demo plan. Decided: 2048. An idle container uses about 620 MiB.
• Decided: the container uses a named data volume, cat-demo-sql-data, and the default lifetime, so it stops with the AppHost. Aspire generates the sa password and keeps it in the user secrets.
• The database resources are called catalog-db and orders-db, because a resource name must differ from the project names catalog and orders. The databases themselves and the connection names stay catalog and orders.
• Reset is docker volume rm cat-demo-sql-data with the AppHost stopped.

Start order

• In Container mode the services wait for their database. The AppHost makes that explicit.
• Each service applies its migrations and seeds in Development, as it does today. The databases exist by then.
• Orders waits for Catalog, because it asks Catalog for prices.

Ports

Decided: the AppHost keeps the fixed ports 5101 and 5102, with WithHttpEndpoint(port: ...) and no Aspire proxy. The .http files, the Orders to Catalog address and standalone runs all use the same ports. The dashboard runs on 15101 (OTLP on 19101 and the resource service on 20101), set in the launch profile of the AppHost.

Swapping the price provider

IPriceProvider stays as it is. Only the class behind it changes.

Phase 1: plain HttpClient. This is the version we build now.

• A new class CatalogPriceProvider in Orders.Infrastructure, using a typed HttpClient.
• The base address comes from Aspire service discovery. The AppHost gives Orders a reference to Catalog.
• It calls GET /catalog/books/prices?bookIds=<id> with one bookIds value per book.
• It reads the response into a small model that belongs to Orders. Orders does not reference Catalog.Contracts. That is a choice for this call, see Sharing contracts.
• Responses map as follows:

• The resilience handler from ServiceDefaults adds retries and a circuit breaker to the call.
• Catalog reads are public, so no token is sent. Once Keycloak arrives, the call forwards the token.
• Registration picks the real provider only when the AppHost gives Orders a Catalog address. Without it, dotnet run keeps working with FakePriceProvider.
• A unit test per row of the table above, with a fake HttpMessageHandler. These tests need no database and no running service.
• The IPriceProvider summary and the demo plan still say that Api.Client implements it. Adjust both while building.

In the future: Cat.Api.Client.

• When the Cat.Api.Client module exists, CatalogPriceProvider is replaced by a typed client from the module, and the call goes through the gateway.
• Build the module from this working code, not up front. Then the design follows what we learned: how a client is declared, how the token is forwarded, how error responses map to ICatResponse and how it works with Cat.Resilience.
• Only the registration in Orders.Infrastructure changes. IPriceProvider, the workflow step and the tests stay.

Phases

1. ServiceDefaults. Create the project. Both Api projects call it. Build and run both services standalone to check that nothing broke.
2. AppHost, Existing mode. (Built. The .http requests pass and the traces show in the dashboard.) Create the AppHost with Catalog and Orders. Both show up in the dashboard with logs, traces and health. Run every request of both .http files against the AppHost.
3. Price provider. (Built. A POST /orders trace shows the call to Catalog and the GET /catalog/books/prices span.) Add CatalogPriceProvider and its tests. Place an order through the AppHost and check in the dashboard that the Catalog call is part of the trace.
4. AppHost, Container mode. (Built. A fresh start from an empty volume gives empty orders and seeded books. A restart keeps a placed order.) Needs Docker on the machine. Add the SQL Server container, the data volume and the databases. Check a fresh start from an empty volume and a restart that keeps the data.
5. Documents. (Built. demo/README.md has the run steps for both modes, the Docker memory notes and the AppHost chapter. The drawing shows the dashboard box as built.) Update demo/README.md with the run steps for both modes and the Docker memory notes. Update Demo.md.

Phases 1 to 3 do not need Docker. Phase 4 does.

Later

These come after the first AppHost build, in the order of the demo plan.

• The Cat.Api.Client module, replacing CatalogPriceProvider.
• Cat.Demo.PaymentService, a separate fake payment service that the AppHost starts and that can fail on purpose. See the payment provider decision in Demo.md.
• The API gateway, Keycloak, JWT validation in the services and the real ICurrentUser.
• The React client, started by the AppHost.
• The Service Bus emulator, with Cat.Messaging.
• Inventory, database first.

Open questions

• Tracing sources. Settled in phase 1. ServiceDefaults adds the wildcard source Cat.*, which covers Cat.ServiceRequests and Cat.FluentWorkFlows. Check in phase 2 that the activities show up in the dashboard.
• Phase 2 check. Done for the requests: every request of both .http files gives the expected status under the AppHost, and both health checks answer. Seen in the dashboard: traces with the Cat.ServiceRequests and Cat.FluentWorkFlows sources.
• ASPIRE010 warning. Settled. The AppHost builds with AspireUseCliBundle false, the SDK default, so the dashboard and DCP come from NuGet and dotnet run needs no extra tool. The warning is suppressed in the AppHost project. Setting it to true would need the Aspire CLI on every machine.
• Dashboard login. Settled. The http launch profile of the AppHost sets ASPIRE_DASHBOARD_UNSECURED_ALLOW_ANONYMOUS, so the dashboard opens without a login token. The token changes on every start, which made scripted checks (Playwright) impossible. Anyone on the machine can open the dashboard on localhost, which is fine for a local demo.
• Development certificate. The dashboard shows “No trusted development certificate was found” when the machine has not run dotnet dev-certs https --trust. It is harmless now, because the AppHost, the dashboard and the services all run on HTTP. It matters once HTTPS is used, for example with the gateway or Keycloak. Decide whether the run steps in demo/README.md (phase 5) tell a developer to trust the certificate, and whether the AppHost keeps ASPIRE_ALLOW_UNSECURED_TRANSPORT.
• Existing mode and Trusted_Connection. The default strings use Windows authentication. That works for a local process but not for a container. Fine for Existing mode, since nothing runs in a container there.