Introduction

Aspire in .NET is a set of tools and integrations for describing, running, observing and preparing the deployment of distributed applications. It lets me declare the relationship between an API, a web front end, a cache and other resources in an application model, instead of relying on an informal sequence of commands and variables copied between terminals. The most immediate benefit shows up during development: starting the whole set and investigating a call between services becomes more predictable.

That does not mean every application needs to become a set of microservices. I can use Aspire for an API alongside Redis and keep the domain in a well-organized monolith. Nor does it mean a local dashboard solves production operations: identity, availability, persistence, telemetry retention and recovery still require their own decisions. Aspire reduces repetitive composition work; it does not eliminate architecture.

The problem that matters here is concrete. One person knows the API port, another knows which container needs to start first, and a third keeps the correct connection string in a file nobody documented. When the environment finally works, investigating a request means stitching together logs from different processes. The more dependencies take part in that path, the higher the cost of reproducing a failure and of preparing someone new to contribute.

In this article, I separate three pieces that usually show up together: AppHost, ServiceDefaults and the dashboard. Then I walk through the official starter to show where each one fits and how to verify the result. The focus is on understanding the model and making a conscious first adoption, not on presenting a catalog of integrations or promising a production-ready platform. I will use C# and .NET 10 as the reference, but the current documentation calls the product Aspire and also covers applications written in other languages.

Prerequisites

To follow the example, consider:

  • .NET SDK 10 installed in the environment where the starter will run. The runtime alone does not create or build the projects.
  • Compatible SDK and templates. The walkthrough pins the templates to Aspire 13.6.4, without claiming that will be the latest version when you read the article.
  • A compatible container runtime, such as Docker, if you enable Redis or another dependency that runs in a container. This does not require containerizing every local .NET project.
  • Development HTTPS configured. On Linux, certificate trust also depends on the distribution and the browser; do not disable TLS validation to work around the problem.
  • Access to the package and image sources used by the starter. A corporate environment may require a proxy, a registry mirror and dependency approval.

The commands below are intended for an isolated development environment. They do not point to existing infrastructure and do not deploy anything. Since the starter evolves between versions, record the SDK, the templates and the options you chose before turning the example into a team reference.

What Aspire solves, and what is still architecture

A distributed application is not just a list of executables. It has a dependency graph: the front end calls an API, the API accesses a database, a Worker consumes messages and some of those paths need to produce correlated telemetry. Without a shared description, part of that graph ends up scattered across documentation, configuration and personal knowledge.

Aspire offers a way to make those relationships explicit. The model can identify services by logical names, associate dependencies and provide connection settings. Integrations can also simplify client registration, health checks and instrumentation. The gain is not in hiding that Redis exists, but in keeping every developer from rebuilding their configuration through trial and error.

I would distinguish technical composition from business decomposition. Defining that an API uses a cache does not explain where a domain context ends, whether two operations need a transaction or how a consumer avoids processing a message twice. Those decisions still belong to the application. The Transactional Outbox Pattern, for example, deals with a consistency problem that does not go away when the processes start from the same AppHost.

That is why I would not adopt Aspire as a justification for fragmenting a system. A modular application with external dependencies can take advantage of the tool without increasing the number of business services. The useful criterion is a different one: how much repetitive work does the team have composing the environment and investigating behavior across resources? If the answer is small, adoption can probably wait. If it is recurring and expensive, there is a suitable problem to solve.

AppHost describes resources and their relationships

The AppHost is where the application model is composed. On the C# path, it uses Aspire’s hosting APIs to register projects, containers and resources supported by the integrations. That definition lets dependencies be related by name, without spreading a fixed port or a local connection string across every project.

An AppHost that includes a front end and an API can have a configuration like this one. The types in Projects are generated from the AppHost’s project references; they are not namespaces you need to create by hand:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
var builder = DistributedApplication.CreateBuilder(args);

var api = builder.AddProject<Projects.LojaAspire_ApiService>("apiservice")
  .WithHttpHealthCheck("/health");

// The configuration reference and the startup dependency are explicit.
builder.AddProject<Projects.LojaAspire_Web>("webfrontend")
  .WithExternalHttpEndpoints()
  .WithHttpHealthCheck("/health")
    .WithReference(api)
    .WaitFor(api);

builder.Build().Run();

ℹ️ Info: The snippet adapts the composition from the official starter. The complete code is generated by the aspire-starter template; examples maintained by the team are in the official aspire-samples repository.

There is an important distinction: WithReference does not mean waiting. The reference makes available the configuration needed to consume the resource, according to its type. WaitFor expresses a startup dependency and can take the configured health checks into account. If the resource has no representative check, waiting for it does not prove that all of its operations are available.

There is no implicit permanent recovery either. A database can become unavailable after the API has started; at that point, the application needs to handle timeouts, cancellation and transient failures. The model helps start the environment coherently, but it does not turn a successful startup into a guarantee of availability for the whole execution. Separating those responsibilities avoids a false sense of operational protection.

The Aspire AppHost references web, API and Redis; the services send telemetry to the dashboard

ServiceDefaults configures the services, not the domain

ServiceDefaults is usually a shared project created by the template. It concentrates extensions that apply common settings to .NET services, such as OpenTelemetry instrumentation, health checks, service discovery and HTTP client resilience. The name describes a useful convention, not a central server that every request has to go through.

The effect depends on each application adopting those extensions. In the starter, look for calls such as builder.AddServiceDefaults() during configuration and app.MapDefaultEndpoints() when mapping endpoints. Merely keeping the project inside the solution does not automatically enable everything in the other projects. That detail matters when bringing Aspire into an existing application: composing the environment and configuring the services internally are related but different changes.

I would keep this project small. Telemetry configuration and common technical policies belong in it; order approval rules, contracts specific to a module and access to business data do not. Otherwise, an infrastructure helper becomes a mandatory dependency library for the entire domain, raising the cost of changing services independently.

I would also review the defaults before adopting them. The resilience configuration of an HTTP client has to respect the semantics of the operation. Retrying a read does not carry the same risk as retrying a charge or a command without duplicate protection. Configure the appropriate policy, use idempotency when needed and propagate cancellation.

The same care applies to health. In the default ServiceDefaults, the health check endpoints are mapped in development. If you need probes in production, configure that exposure deliberately, with the appropriate scope and protections. A technical endpoint should not leak internal details just because it was already available in the local environment.

The dashboard and OpenTelemetry make the flow investigable

The Aspire dashboard presents resources and observability information, such as the logs, metrics and traces provided by instrumentation. Its usefulness shows up when I can go from the symptom visible in the front end and follow the path to the API, observing the behavior of each step instead of hunting for loose sentences in different terminals.

That experience depends on instrumentation and context. A service needs to produce the signals, and a call between services needs to propagate the identifiers required for the spans to appear related. Using an uninstrumented library or breaking propagation in a queue can leave gaps. The dashboard helps you see what was emitted; it does not invent what the application never recorded.

I would also separate technical observability from business telemetry. A successful, fast HTTP request does not, by itself, show that an order was invoiced correctly. For that, I still need to define events, metrics and attributes that represent the relevant behavior. When choosing those attributes, I avoid personal data and dimensions with uncontrolled cardinality, such as using a different identifier as a label for each metric.

The article on structured logging in .NET goes deeper into log context and properties. Here, the complementary point is correlation between components and the composition of the environment. In production, retention, access control, export, sampling and alerts require a defined operational solution. OpenTelemetry makes it easier to instrument and export signals; it does not, on its own, provide all the storage and the incident response process.

⚠️ Warning: Do not expose the development dashboard publicly as a monitoring shortcut. Logs and traces can reveal URLs, resource names and sensitive information. Review authentication, network and telemetry content before making any operational interface available.

Integrations and service discovery do not eliminate contracts

Aspire distinguishes the configuration of the resource in the AppHost from the configuration of the client in the application. In the case of Redis, a hosting integration lets you add the resource to the model. In the consuming application, a client integration can register the implementation used by the code, including its configuration and available technical features.

That separation avoids a frequent misreading: adding Redis to the AppHost does not make the API start using a cache. The service still needs to reference the resource and register a compatible client. The business code also needs to decide what to store, how to compose keys, which expiration to apply and what to do when the cache fails. Aspire helps with the connection; it does not choose the caching policy.

The names have to match. If the resource is called cache, the client configuration must look for that connection, instead of assuming any available Redis will be found. For HTTP calls, discovery lets you work with logical names and resolve the configured endpoints. That is not the same as creating public DNS, configuring an API Gateway or protecting an API with authorization.

There is also a difference between having a connection and using the resource safely. A reachable Redis can still suffer from huge values, keys without expiration or contention between applications. The article Redis: Big Keys Destroy Shared Performance covers exactly that risk. I would keep those decisions explicit even after simplifying how the environment is created.

For a first adoption, I would start with a single path: front end calling the API. Then I would add an external dependency and check what changed in the configuration, the health checks and the telemetry. That incremental growth makes it visible what each integration actually delivers.

Practical Example

I will use the official starter, which already provides a web front end, an API, the AppHost and the service defaults project. The idea is to understand a working composition before adapting the model to an existing repository. There is no need to copy business classes or create a separate sample project to reproduce these steps.

In a working folder, install the reference version of the templates and create the solution:

1
2
3
4
5
# Pin the version so the walkthrough does not depend on the latest template.
dotnet new install [email protected]

# Create the starter with projects targeting .NET 10.
dotnet new aspire-starter --name LojaAspire --output LojaAspire --framework net10.0

Read the options presented by the template and record the ones you select. The core of this example does not depend on enabling Redis. If you choose a container-based cache option, the container runtime must be available before running. Also keep the versions of the generated projects together as a set, instead of updating only one integration without checking compatibility.

In the generated structure, identify these responsibilities:

ProjectWhat to check
LojaAspire.AppHostRegistered resources and references between front end and API
LojaAspire.ServiceDefaultsTelemetry, health, discovery and resilience extensions
LojaAspire.ApiServiceApplication endpoints and adoption of the common defaults
LojaAspire.WebHTTP client that reaches the API through the logical name

Before starting, check the development HTTPS certificate. The trust command below applies to the local environment and may depend on additional configuration on Linux; it is not guidance for changing production certificates:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
# Configure certificate trust in the development environment.
dotnet dev-certs https --trust

# Restore and build the generated solution.
dotnet restore LojaAspire
dotnet build LojaAspire --no-restore

# Also review transitive dependencies before adopting the example.
dotnet list LojaAspire package --vulnerable --include-transitive

# Start the composition from the AppHost, not from four separate terminals.
dotnet run --project LojaAspire/LojaAspire.AppHost

When validating this walkthrough, the 13.6.4 starter was generated with .NET SDK 10.0.402 and built with zero errors and zero warnings. The audit including transitive dependencies found no known vulnerable packages at that moment; that result does not replace new checks when the security advisory databases are updated.

Use the dashboard URL shown in the console, without assuming a fixed port or removing the generated access mechanism. Open the web front end from the resource list and trigger the page that queries the API. In the starter, the demo usually uses weather forecast data; the important point is observing a real request between the projects, not the domain chosen for the example.

My verification would have four parts: the expected resources show up as running; the front end can query the API; the call produces telemetry signals; and the logs make it possible to tell where a failure originated. If there is no trace, I would check instrumentation, export and propagation, instead of immediately concluding that the call did not happen.

Then, in a controlled local test, stop only the sample API and repeat the query. Observe the error, the timeouts and the recovery when the service comes back. Do not do this in a shared environment. This exercise shows an important boundary: a configured dependency does not mean an always-available dependency. Before using the model in a product, the failure behavior has to be as understandable as the success path.

Aspire, Docker Compose and Kubernetes play different roles

Comparing Aspire with Docker Compose or Kubernetes as if they were perfectly equivalent alternatives tends to produce a bad decision. They can take part in the same flow, but they work at different levels. Aspire offers an application model and tooling for development, observability and deployment; Compose describes and runs services in containers; Kubernetes operates workloads in a cluster with its own reconciliation and availability mechanisms.

NeedWhere I would start evaluating
Developing services and dependencies with explicit references and integrated telemetryAspire
Running a small set of already containerized services, with configuration known to the teamDocker Compose
Operating workloads in a cluster with policies, reconciliation and scalabilityKubernetes and its operational platform
Introducing an application model and producing artifacts for a supported targetAspire with the appropriate deployment integration

The AppHost is especially relevant for development composition, but the claim that Aspire is only for starting local processes is also incomplete. Current versions have publishing and deployment features, with integrations for targets such as Docker Compose and Kubernetes. The maturity and requirements of each integration must be checked in the version you adopt; preview features should not be treated as stable contracts without evaluation.

That does not turn the AppHost into the permanent production orchestrator. Even when a flow generates or applies artifacts, someone still needs to define images, secrets, storage, network, probes, policies, backup and recovery. The target still has its own operational model. I would evaluate both the generated result and the update and rollback process.

For a team that already operates well with Compose, adoption needs to show a concrete gain, not just swap YAML for C#. For an existing Kubernetes platform, I would start with the development experience and the integration with the current delivery process, avoiding a second publishing path without a clear owner. Aspire can reduce friction; a tool change still has to respect what already works.

Tips and Good Practices

  • Start with the smallest useful graph. A front end and an API are already enough to observe discovery and correlation. Add a database, cache or messaging only when the application needs them, not to fill up the dashboard.
  • Version the configuration that reproduces the environment. Record the SDK, templates, packages and options used. Update the set with review and testing, without treating the word “latest” as a compatibility strategy.
  • Distinguish reference, readiness and resilience. WithReference, WaitFor and failure policies solve different problems. Check the behavior after startup, including unavailability, cancellation and time limits.
  • Review what goes into telemetry. An observable environment does not need to record tokens, sensitive payloads or personal data. Define useful attributes, control cardinality and treat the dashboard as an interface with security requirements.
  • Keep ServiceDefaults out of the domain. Share small, explicit technical defaults. Avoid a central library that forces every service to import business contracts and rules unnecessarily.
  • Plan persistence and secrets separately. A database created for development is not a production data strategy. Define local retention, restoration and credential handling before using real information.
  • Test a real failure in the isolated environment. Make a call, observe the trace and stop a dependency of the example with a known scope. The learning lies in understanding how the application reacts, not just in getting green indicators.

Objective Summary

  • Aspire provides tools and integrations to compose, run, observe and prepare the deployment of distributed applications; using it does not require turning a monolith into microservices.
  • AppHost describes resources and relationships. WithReference provides reference configuration; WaitFor expresses a startup dependency and does not guarantee permanent availability.
  • ServiceDefaults is a project of technical defaults adopted by the services, with settings such as OpenTelemetry, discovery, health checks and HTTP resilience.
  • The Aspire dashboard shows signals emitted by the application. Correlation depends on instrumentation and context propagation; retention, alerts and security require operational decisions.
  • Hosting and client integrations have different responsibilities: adding a resource to the model does not make business code start consuming it automatically.
  • Deployment with Aspire can use integrations for targets such as Docker Compose and Kubernetes, but it does not eliminate configuring secrets, persistence, network, availability and recovery.
  • Reference starter: the commands in the article use Aspire ProjectTemplates 13.6.4 and .NET 10; versions and options need to be recorded to reproduce the environment.

Read Also

References