Chapter 1: Getting started with distributed systems and Aspire

Introduction

The introduction explains why a multi-component application is difficult to run locally and how Aspire’s AppHost gives developers one place to model and work with it.

• Distributed application composition: Describe a distributed application as independently executing components that work together as one system, using the online shop as an example.
  Why it matters: This picture of the whole system explains why running only the storefront is not enough.
• Local development difficulties: Explain why running and debugging the shop locally is harder than running one application.
  Why it matters: These everyday development problems are the reason the chapter introduces Aspire.
• AppHost model and boundaries: Explain how Aspire’s AppHost models services, infrastructure resources, and their relationships, and what Aspire can do with that model. Distinguish this development role from merging services or replacing their production platform.
  Why it matters: AppHost gives developers a view of the complete system without turning its services into one program.

Key terms: distributed application, storefront, catalog API, configuration, dependencies, logs, Aspire, AppHost, code-first application model, resources

1.1 The online shop as a distributed workflow

The section traces a shopper’s journey through the online shop’s independently running components, starting with catalog browsing and showing why later cross-component workflows need observability.

• Storefront and catalog API flow: Trace what happens when a shopper opens the product catalog, identifying the storefront and catalog API roles and the HTTP request and response between them.
  Why it matters: This small interaction is the starting point for understanding how the shop’s components work together.
• Background order processing flow: Explain why the shop sends checkout work through a message broker to a background service and what the storefront can do as a result.
  Why it matters: It illustrates how the customer journey extends beyond a direct storefront-to-API exchange.
• Cross component observability: Explain why the shop produces logs, metrics, and distributed traces as requests cross independently running components.
  Why it matters: When a request spans services, finding where it failed requires visibility across the whole path.

Key terms: storefront, catalog API, HTTP request, message broker, background service, checkout requests, logs, metrics, distributed traces, observability

1.2 Why the application is difficult to develop locally

The section explains how the online shop’s independently running components form one distributed application, how that differs from a monolith, and why the flexibility adds development complexity.

• Distributed shop as one application: Explain how independently running components with distinct responsibilities work together to deliver the online shop’s customer experience.
  Why it matters: It establishes why the shop must be understood as a working system, not just a collection of separate services.
• Distributed and monolithic boundaries: Distinguish the process and communication boundaries of a distributed application from those of a monolith, including a modular monolith.
  Why it matters: Separating code into modules is not the same thing as running components across network boundaries.
• Flexibility and development tradeoff: Explain the flexibility gained from distributed boundaries and the development convenience lost compared with a monolith.
  Why it matters: This tradeoff explains why developing the distributed shop locally needs more attention than running a single application.

Key terms: distributed application, components, storefront, catalog API, REST API, monolith, modular monolith, in-process method calls, network requests, deployment unit

1.2.1 Starting several resources

Explains why starting a distributed application locally is harder than launching one application: developers must start multiple resources and account for dependencies and readiness.

• Multiple resource startup: Describe the resources a distributed application may need and why starting them manually is inconvenient.
  Why it matters: The number of resources makes local startup a coordination task rather than a single launch.
• Dependency order and readiness: Explain why startup order and actual readiness matter, and what can happen when dependent resources are used too early.
  Why it matters: A process appearing to run does not guarantee that the workflow can use it successfully.

Key terms: distributed application, resources, containers, configuration, dependencies, ready to accept requests, temporary failure

1.2.2 Managing addresses and configuration

This section explains why separately running application and infrastructure components need accurate, environment-specific addresses and configuration.

• Changing service addresses: Explain why the storefront needs the catalog API’s hostname and port, and why that address may differ across local machines, containers, and deployed environments.
  Why it matters: A correct address on one machine may not reach the service elsewhere.
• Infrastructure configuration synchronization: Describe the connection details infrastructure resources may require and explain why hardcoded values or separate configuration files can become difficult to keep correct.
  Why it matters: Configuration that does not match running resources can prevent components from connecting.

Key terms: hostname, port, DNS name, localhost address, connection string, cache endpoint, message-broker credentials, configuration files

1.2.3 Dealing with network boundaries

This section explains why communication between distributed components can fail even during local development, leaving an application only partly operational.

• Network boundary failure modes: Explain how communication across a network boundary differs from a direct call within one process, and describe why a service dependency may be temporarily unavailable even when all services run on one machine.
  Why it matters: Running every service locally does not remove the possibility of network-request failures.
• Partial operation and dependencies: Describe how one unavailable component can affect dependent features without stopping the whole application, and explain why developers need to identify which components and dependencies are healthy.
  Why it matters: An application that starts successfully may still have broken features because a dependency is failing.

Key terms: network boundary, network request, dependency, HTTP, WebSocket, partially operational, healthy, catalog API, message broker

1.2.4 Finding failures across multiple components

This section explains why a failure in a distributed application is hard to locate and how distributed tracing helps reveal a request’s path.

• Request path and failure location: Trace the product-display request across the storefront, catalog API, cache, and, on a cache miss, database. Explain why a failure visible in the storefront may originate elsewhere.
  Why it matters: Following the request path helps you look beyond the component where the error first appears.
• Distributed diagnostic signals: Explain why separate component logs and metrics make a failed request hard to diagnose, and describe what distributed tracing adds.
  Why it matters: A page error alone cannot show which call failed or where the request spent its time.

Key terms: storefront, catalog API, cache, database, logs, metrics, distributed tracing, traces

1.2.5 Testing the complete workflow

This section explains why independently passing service tests cannot establish that a distributed workflow works, and why testing the complete workflow is difficult to coordinate.

• Limits of isolated tests: Explain why a working catalog API and storefront can still fail as a complete workflow, giving examples of failures that arise when components interact.
  Why it matters: A passing test for each service can miss a broken customer-facing workflow.
• Complete workflow test setup: Describe what an integration test of a distributed application may need to do and why arranging it manually is difficult.
  Why it matters: Testing the whole workflow requires more than sending a request to one service.

Key terms: isolated tests, complete workflow, integration test, real components, ready, test environment

1.2.6 The need for development-time orchestration

This section explains why coordinating independently running resources calls for development-time orchestration and how Aspire provides it without combining the services into one process.

• Development-time orchestration needs: Explain why the online shop’s development challenges come from coordinating independent resources rather than from its business logic, and describe the activities that orchestration brings together on a development machine.
  Why it matters: It separates the work of coordinating a distributed system from the shop’s business logic.
• Aspire AppHost model: Describe how Aspire uses an AppHost code model of the application and its relationships to coordinate resources, while leaving services as independent processes.
  Why it matters: It clarifies what Aspire unifies—the development experience—without confusing that with a change to the application’s distributed structure.

Key terms: development-time orchestration, resources, application topology, Aspire, AppHost project, central model, shared dashboard

1.3 Overview of orchestration

This section explains how orchestration coordinates a distributed application’s independent resources, from startup and configuration to readiness and system-wide visibility, while distinguishing Aspire’s development-time role from production orchestration.

• Orchestration and service boundaries: Explain that orchestration manages and coordinates separate services so they function as one application without becoming a single component.
  Why it matters: This distinction explains why an orchestrated application still has to manage connections and dependencies between services.
• Coordinated startup and readiness: Trace how an orchestrator starts the online shop’s resources and waits for dependencies to be ready before dependent services begin work.
  Why it matters: Starting everything is not enough if a service begins using a dependency before that dependency is ready.
• Supplied connection configuration: Describe how the orchestrator supplies services with the addresses and connection details they need, rather than requiring those details to be hardcoded.
  Why it matters: Supplying connection details keeps services connected when their environment changes.
• System visibility and environment scope: Distinguish Aspire’s development-time orchestration from the broader responsibilities of production platforms, and describe the system-wide visibility orchestration provides.
  Why it matters: It sets realistic expectations for what Aspire helps developers do locally versus what a production platform may do.

Key terms: orchestration, services, components, boundaries, orchestrator, dependencies, readiness, health information, configuration, addresses

1.4 How Aspire changes the game

The section explains how Aspire simplifies .NET applications with external components through integrated development, declarative orchestration, observability, and cloud-ready configuration.

• Aspire application scope: Explain that Aspire is intended for distributed .NET systems but can also help a web-hosted monolithic application that relies on an external component such as a database or message broker.
  Why it matters: You need not be building microservices to benefit from Aspire.
• Integrated declarative orchestration: Explain how Aspire simplifies running interconnected services and infrastructure components: its application model defines services and dependencies declaratively, reducing boilerplate and configuration.
  Why it matters: It explains why a multi-component application can be easier to run and maintain during development.
• Built-in application observability: Describe Aspire's built-in support for tracing, logging, and metrics, and explain how it helps developers follow requests across services and diagnose problems.
  Why it matters: Visibility across services makes distributed problems easier to locate.
• Cloud-ready configuration: Explain that Aspire's configuration is designed to adapt to cloud environments, easing the move from local development to production deployment across cloud hosts.
  Why it matters: It connects Aspire's development experience to a smoother path toward production.

Key terms: cloud-native application stack, external component, monolithic applications, microservice orchestration, application model, declaratively, dependencies, shared debugger process, observability, OpenTelemetry

1.5 Getting started with the Aspire Starter Project

Introduces the projects in the OnlineShop solution created from the Aspire Starter Project template and identifies their roles.

• OnlineShop solution component roles: Describe the roles of OnlineShop.Web, OnlineShop.ApiService, OnlineShop.AppHost, and OnlineShop.ServiceDefaults, including how the web application obtains data from the API.
  Why it matters: These roles provide a map of the solution before the book examines how its applications are orchestrated.

Key terms: OnlineShop.Web, OnlineShop.ApiService, OnlineShop.AppHost, OnlineShop.ServiceDefaults

1.6 Orchestrating with Aspire

This section shows how to launch an Aspire-hosted application, inspect its services in the dashboard, and open the UI to verify that it retrieves data from the API.

• AppHost launch role: Explain that launching OnlineShop.AppHost starts the other applications in the distributed application and brings up the Aspire dashboard after the services build.
  Why it matters: Starting the host is how you bring up the example application as a whole.
• Dashboard service visibility: Describe how the Aspire dashboard shows the services in the application and how to check whether they are running and view their logs.
  Why it matters: The dashboard lets you check the applications without inspecting each one separately.
• Endpoint and API verification: Trace how to open the OnlineShop.Web endpoint from the Resources tab and use the Weather tab to see data the Blazor UI retrieved from the API.
  Why it matters: Opening the UI gives you a visible check that the frontend and API are working together.

Key terms: host application, OnlineShop.AppHost, Aspire dashboard, State, Console tab, service logs, Resources tab, endpoint URL, OnlineShop.Web, Weather tab

1.7 Setting up Aspire’s orchestrator

Introduces the upcoming setup of Aspire’s orchestrator by previewing its dependencies and application registration.

1.7.1 Installing Aspire dependencies

This subsection identifies the dependencies and project references an Aspire host needs before it can orchestrate the online shop applications.

• Starter Project dependencies: State that Aspire applications require specific NuGet packages and that the default Aspire Starter Project template already includes them.
  Why it matters: It clarifies which dependencies the starter project provides before you configure orchestration.
• Host project references: Explain that OnlineShop.AppHost is the orchestrator and must reference the applications it will orchestrate: the Blazor UI, OnlineShop.Web, and the REST API, OnlineShop.ApiService.
  Why it matters: The host needs references to the applications it will orchestrate before they can be configured in its startup code.

Key terms: NuGet packages, Aspire Starter Project template, host application, orchestrator, OnlineShop.AppHost, OnlineShop.Web, OnlineShop.ApiService

1.7.2 Host application startup and service registration

This section explains how the Aspire AppHost creates its host builder, registers the API project, and adds a health check.

• Aspire host builder: Explain that OnlineShop.AppHost startup code in AppHost.cs creates a host builder using Aspire’s DistributedApplication class rather than an ordinary ASP.NET Core host builder.
  Why it matters: The Aspire-specific builder is the starting point for registering applications with the host.
• API project registration: Describe how AddProject registers OnlineShop.ApiService under the name apiservice, using the autogenerated Projects.OnlineShop_ApiService type to identify the project the host can orchestrate.
  Why it matters: This connects a project in the solution to a named service managed by the Aspire host.
• API health-check registration: Explain that WithHttpHealthCheck("/health") registers a health-check endpoint so the orchestrator can tell whether the API service is healthy.
  Why it matters: The registered endpoint lets orchestration reflect whether the service is healthy.

Key terms: OnlineShop.AppHost, AppHost.cs, DistributedApplication, host builder, AddProject(), Projects.OnlineShop_ApiService, OnlineShop.ApiService, apiservice, WithHttpHealthCheck("/health"), health-check endpoint

1.7.3 Registering the UI application

Shows how the Aspire host registers the online shop’s UI, exposes it externally, connects it to the API, and waits for the API to be ready.

• UI project registration: Describe how the OnlineShop.Web project is registered with AddProject() under the name webfrontend, and explain that the dashboard displays the names assigned during registration.
  Why it matters: It connects the host’s registration code to the service name you see in the dashboard.
• External frontend and internal API: Explain why the UI registration uses WithExternalHttpEndpoints() while the API registration does not, and how the frontend can still reach the API.
  Why it matters: The distinction explains how users can reach the UI without unnecessarily exposing its API.
• Frontend API reference: Explain that WithReference() receives the previously registered API service reference so the Blazor UI can refer to the API through service discovery.
  Why it matters: The reference establishes how the frontend identifies the API it depends on.
• API readiness dependency: Explain that WaitFor() delays frontend startup until the API is fully ready because the frontend pulls data from it.
  Why it matters: The startup order protects frontend functionality that depends on API data.

Key terms: AddProject(), OnlineShop.Web, webfrontend, WithExternalHttpEndpoints(), internal network, public network, WithReference(), API service reference, service discovery, WaitFor()

1.8 Introducing service defaults

Introduces Aspire service defaults as a customizable class library of extension methods for shared application setup, and explains the references it needs.

• Service defaults and their purpose: Explain what Aspire service defaults are and name the shared tasks they enable for orchestrated applications.
  Why it matters: This identifies the shared setup that service defaults provide to Aspire applications.
• Customizable shared setup library: Explain why the service-default extension methods are kept in a class library inside the solution.
  Why it matters: The defaults are a starting point that developers can tailor rather than fixed behavior.
• Service defaults project references: Describe why the OnlineShop.ServiceDefaults class library references Microsoft.AspNetCore.App and other functionality-specific packages.
  Why it matters: The library needs the types and feature packages required by the startup extensions it provides.

Key terms: service defaults, extension methods, Aspire orchestrator, service discovery, health, metrics, class library, metrics library, OnlineShop.ServiceDefaults, Microsoft.AspNetCore.App

1.8.1 Adding extension methods

This section identifies the service-default extension methods, summarizes what they add, and explains where applications invoke them.

• Service defaults and telemetry: Explain that ConfigureOpenTelemetry registers services to collect metrics, AddOpenTelemetryExporters configures their export for monitoring, and AddServiceDefaults calls both while registering additional dependencies such as service discovery.
  Why it matters: It clarifies what an application gains when it adds service defaults.
• Startup extensions and endpoints: Distinguish the startup roles of IHostApplicationBuilder and WebApplication, and describe how MapDefaultEndpoints adds health-check endpoints. State that relevant applications must invoke these extension methods from their startup code.
  Why it matters: It connects the shared extension methods to the startup code where they take effect.

Key terms: ConfigureOpenTelemetry(), AddOpenTelemetryExporters(), AddServiceDefaults(), service discovery, Extensions.cs, OnlineShop.ServiceDefaults, IHostApplicationBuilder, WebApplication, MapDefaultEndpoints(), health-check endpoints

1.8.2 Using the extension methods

Shows that both online shop applications invoke the shared service-default extension methods in their startup code.

• Shared service defaults in startup: Describe where the service-default extension methods are invoked in the online shop projects and what the explained invocation does for Aspire.
  Why it matters: It connects the shared service defaults to the startup code of both applications.

Key terms: Program.cs, service defaults, extension methods, Aspire orchestrator, OnlineShop.Web, OnlineShop.ApiService

1.9 Service discovery in Aspire

This section explains how service discovery lets distributed services find one another and outlines registration, querying, dynamic updates, and its relationship to load balancing.

• Purpose of service discovery: Explain why service discovery is useful when independent services communicate over a network.
  Why it matters: It addresses the problem of finding other services as a distributed application changes.
• Registry registration and querying: Trace how a starting service makes its location available and how another service finds it, including how updates reflect services joining or leaving.
  Why it matters: Registration and querying explain how a client can find a service even as available services change.
• Discovery and load balancing: Distinguish load balancing from service discovery and explain why they are often used together.
  Why it matters: Finding available instances and spreading requests across them are related but distinct jobs.

Key terms: service discovery, microservices, service registration, service registry, service querying, dynamic updates, load balancing

1.9.1 Registering service-discovery components

This subsection identifies the package installation required before enabling Aspire service discovery.

• Service discovery package prerequisite: State that applications being added to the Aspire orchestrator need the service-discovery NuGet package installed before service discovery can be enabled, and identify OnlineShop.ServiceDefaults as the project used here.
  Why it matters: This is the setup step the example takes before enabling service discovery.

Key terms: service discovery, Microsoft .Extensions.ServiceDiscovery, OnlineShop.ServiceDefaults, NuGet package

1.9.2 Enabling service discovery

The section explains how Aspire service discovery lets hosted applications communicate by name and identifies the calls that enable it in the online shop.

• Name-based service communication: Explain that Aspire-hosted services can communicate without developers supplying exact IP addresses: developers give each service a unique name, and service discovery finds its address.
  Why it matters: This explains why service addresses do not have to be specified directly when Aspire-hosted applications communicate.
• Service discovery registration calls: Distinguish the two calls in AddServiceDefaults(): builder.Services.AddServiceDiscovery() adds core service-discovery components, while http.AddServiceDiscovery() adds them to HTTP clients so they can use labels as URIs instead of exact IP addresses.
  Why it matters: The two calls show what enables discovery generally and what makes it available to HTTP clients.

Key terms: service discovery, unique name, IP addresses, AddServiceDefaults(), builder.Services.AddServiceDiscovery(), http.AddServiceDiscovery(), HTTP clients, URIs

1.9.3 Using service discovery

Shows how the web frontend uses a service name instead of a fixed API address, letting Aspire resolve where to connect.

• Service-discovery client configuration: Describe how OnlineShop.Web configures its API HTTP client for service discovery: call AddServiceDefaults() and use the Aspire-registered service name as the base address rather than a fixed URL.
  Why it matters: The client can refer to the API without hard-coding its network address.
• Protocol preference and address resolution: Explain what https+http://apiservice means and why the client can keep using it when the API's server, address, or port changes.
  Why it matters: Service discovery keeps the client's configuration stable even when the API's location changes.

Key terms: AddServiceDefaults(), HTTP client, base address, apiservice, https+http, HTTPS, HTTP, Aspire host application

1.10 Summary