.NET Aspire Orchestration
Relevant source files
The following files were used as context for generating this wiki page:
.NET Aspire Orchestration serves as the central coordination layer for the DDD and Event-Driven Architecture project. Its primary purpose is to manage the lifecycle, configuration, and inter-service communication of various components, including microservices, messaging brokers, and frontend applications. By utilizing .NET Aspire, the project achieves a unified development experience with integrated service discovery, observability, and health monitoring.
Sources: claude.md:144-149, Aspire.AppHost/AppHost.cs:22-24
Core Architecture and Components
The orchestration logic is primarily defined within the Aspire.AppHost project. It acts as the "distributed application" coordinator, responsible for spinning up containers, projects, and executable dependencies.
Orchestration Flow
The following diagram illustrates how the AppHost coordinates the various services and resources within the system.
The diagram shows the AppHost as the orchestrator initiating all resources and the subsequent dependencies between those resources.
Sources: Aspire.AppHost/AppHost.cs:113-176
Key Orchestrated Resources
| Resource | Type | Description |
|---|---|---|
messaging | Container/Cloud | Abstracted broker (RabbitMQ or Azure Service Bus) for event-driven messaging. |
identity-webapi | Project | Duende IdentityServer authority for OIDC/OAuth2. |
scheduling-webapi | Project | Core domain service for healthcare appointment scheduling. |
billing-webapi | Project | Domain service for billing operations. |
scheduling-angularapp | JavaScript App | Angular SPA frontend integrated via AddJavaScriptApp. |
Sources: Aspire.AppHost/AppHost.cs:113-176, claude.md:89-106
Service Defaults and Observability
Every orchestrated service in the project references the ServiceDefaults project, which standardizes common cross-cutting concerns through the AddServiceDefaults() extension method.
Integrated Capabilities
- OpenTelemetry Configuration: Sets up logging, metrics, and tracing. It includes instrumentation for ASP.NET Core, HttpClient, Runtime, MassTransit, and Entity Framework Core.
- Health Checks: Defines a default
/health(readiness) and/alive(liveness) endpoint for orchestration monitoring. - Service Discovery: Configures HttpClient defaults to support logical service naming instead of hardcoded URLs.
- Resilience: Automatically adds standard resilience handlers (Polly-based) to HttpClients.
Sources: ServiceDefaults/Extensions.cs:21-41, WebApplications/Billing.WebApi/Program.cs:17-19
Observability Data Flow
The diagram depicts the flow of observability data from services through the ServiceDefaults configuration to the Aspire Dashboard.
Sources: ServiceDefaults/Extensions.cs:43-76, ServiceDefaults/Extensions.cs:100-116
Worktree Slots and Port Management
A unique feature of this project's orchestration is the Worktree Slot system. This allows multiple developers or automated agents to run independent instances of the entire system on the same host without port or database name collisions.
Slot Resolution Logic
The slot (integer 1-5) is resolved with the following priority:
worktree-slotenvironment variable.- The first line of a gitignored
.worktree-slotfile. - Default value of
1.
Sources: Aspire.AppHost/WorktreeSlot.cs:28-48
Resource Isolation
When a slot greater than 1 is detected, the orchestrator automatically performs:
- Port Offsetting: Offsets the dashboard, OTLP, and project ports by
100 * (slot - 1). - Database Isolation: Suffixes SQL Server
Initial Catalogtokens with_S{slot}. - Auth Configuration: Overwrites OIDC Authority, Cookie Names, and CORS origins with slot-specific values.
Sources: Aspire.AppHost/AppHost.cs:134-171, Aspire.AppHost/WorktreeSlot.cs:58-82
Messaging Broker Selection
The AppHost facilitates a switchable messaging infrastructure. Developers can choose between RabbitMQ (local development default) and Azure Service Bus (via emulator or real namespace).
Broker Selection Logic
Sources: Aspire.AppHost/AppHost.cs:49-111
Azure Service Bus Emulator Handling
Special orchestration logic is applied for the Service Bus emulator (v2.0.0+) to handle the separate management/HTTP plane required by MassTransit for topology creation. The AppHost builds and injects a messaging-admin connection string derived from the emulatorhealth endpoint.
Sources: Aspire.AppHost/AppHost.cs:72-96
Summary
.NET Aspire Orchestration provides the project with a robust, repeatable environment that abstracts infrastructure complexities. Through the AppHost, the system manages dynamic port allocation, service dependencies, and isolated development environments via "Worktree Slots." Simultaneously, the ServiceDefaults layer ensures that all services are natively equipped with enterprise-grade observability, health monitoring, and resilience.
Sources: Aspire.AppHost/AppHost.cs:7-20, ServiceDefaults/Extensions.cs:16-20