Build your first Aspire app

Select your programming language to get started

In this quickstart, you’ll create and run your first Aspire application using the Aspire CLI. This guide walks you through generating a new Aspire solution from a template, running the application locally with Aspire’s dev-time orchestration, and exploring the Aspire dashboard.

This starter template uses modern .NET technologies:

Minimal APIs for lightweight HTTP APIs
Blazor for interactive web UIs using C#
Service Defaults for shared configuration of observability and resilience

The following diagram shows the architecture of the sample app you’re creating:

architecture-beta

  service api(logos:dotnet)[API service]
  service frontend[Blazor front end]

  frontend:L --> R:api

This starter template combines a modern Python and JavaScript stack:

FastAPI for building APIs with Python
Uv for Python package installation and environment management
React for building user interfaces with JavaScript

The following diagram shows the architecture of the sample app you’re creating:

architecture-beta
  service api(logos:fastapi)[API service]
  service frontend(logos:react)[React front end]

  frontend:L --> R:api

Create a new app

To create your first Aspire application, use the Aspire CLI to generate a new solution from a starter template. These template include multiple projects, such as an API service, a web frontend, and an Aspire AppHost.

Create a new Aspire solution from a template:
Create a new aspire solution
```
aspire new aspire-starter -n AspireApp -o AspireApp
```
Create a new aspire solution
```
aspire new aspire-py-starter -n aspire-app -o aspire-app
```
Create a new aspire solution
```
aspire new aspire-js-starter -n aspire-app -o aspire-app
```
The template provides several projects, including an API service, web frontend, and AppHost.
CLI flags
The following flags are used in the command:
- -n: specifies the name of the solution.
- -o: specifies the output directory.
For further CLI reference, see aspire new command information.

If prompted for additional selections, use the Up Arrow Up Arrow Up Arrow and Down Arrow Down Arrow Down Arrow keys to navigate the options. Press Return Enter Enter to confirm your selection.

Review the template code

Examine the created template structure. The Aspire CLI creates a new folder with the name you provided in the current directory. This folder contains the solution file and several projects, including:
- AspireApp.sln
- DirectoryAspireApp.ApiService mock weather data API
  DirectoryProperties/
  …
  appsettings.Development.json
  appsettings.json
  AspireApp.ApiService.csproj
  Program.cs
- DirectoryAspireApp.AppHost dev-time orchestrator
  DirectoryProperties/
  …
  appsettings.Development.json
  appsettings.json
  AspireApp.AppHost.csproj
  AppHost.cs
- DirectoryAspireApp.ServiceDefaults
  Extensions.cs
  AspireApp.ServiceDefaults.csproj
- DirectoryAspireApp.Web ASP.NET Core Blazor front end
  DirectoryProperties/
  …
  Directorywwwroot/
  …
  appsettings.Development.json
  appsettings.json
  AspireApp.Web.csproj
  Program.cs
  WeatherApiClient.cs
- Directoryaspire-app/
  Directoryapp/ FastAPI mock weather data API
  .dockerignore
  .python-version
  main.py
  pyproject.toml
  telemetry.py
  Directoryfrontend/ Vite + React web front end
  .dockerignore
  Directorypublic/
  Aspire.png
  github.svg
  Directorysrc/
  App.css
  App.tsx
  index.css
  main.tsx
  vite-env.d.ts
  .gitignore
  eslint.config.js
  index.html
  package-lock.json
  package.json
  tsconfig.app.json
  tsconfig.json
  tsconfig.node.json
  vite.config.ts
  apphost.cs dev-time orchestrator
  apphost.run.json
  NuGet.config
This solution structure is based on the Aspire templates. If they’re not installed already, the CLI will install them for you.
Explore the AppHost code that orchestrates your app.

The AppHost is the heart of your Aspire application—it defines which services run, how they connect, and in what order they start. Let’s look at the generated code:
C# — AppHost.cs project-based orchestrator
```
var builder = DistributedApplication.CreateBuilder(args);

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

builder.AddProject<Projects.AspireApp_Web>("webfrontend")
    .WithExternalHttpEndpoints()
    .WithHttpHealthCheck("/health")
    .WithReference(apiService)
    .WaitFor(apiService);

builder.Build().Run();
```
What’s happening here?
- CreateBuilder creates the distributed application builder
- AddProject registers your API service and web frontend
- WithReference creates a connection between services (the web app can call the API)
- WaitFor ensures services start in the correct order
- WithHttpHealthCheck monitors service health
C# — apphost.cs file-based orchestrator
```
#:sdk Aspire.AppHost.Sdk@13.0.0
#:package Aspire.Hosting.JavaScript@13.0.0
#:package Aspire.Hosting.Python@13.0.0

var builder = DistributedApplication.CreateBuilder(args);

var app = builder.AddUvicornApp("app", "./app", "main:app")
    .WithUv()
    .WithExternalHttpEndpoints()
    .WithHttpHealthCheck("/health");

var frontend = builder.AddViteApp("frontend", "./frontend")
    .WithReference(app)
    .WaitFor(app);

app.PublishWithContainerFiles(frontend, "./static");

builder.Build().Run();
```
What’s happening here?
- AddUvicornApp adds a Uvicorn-based Python app
- AddUv adds a Uv environment setup task: uv sync
- AddViteApp registers your React frontend
- WithReference connects the frontend to the API
- WaitFor ensures the API starts before the frontend
- PublishWithContainerFiles bundles the frontend for production deployment
Your application topology is defined in code, making it easy to understand, modify, and version control. Learn more about the AppHost.

Run the app

Change to the output directory:
Change directories
```
cd ./AspireApp
```
Change directories
```
cd ./aspire-app
```

Call aspire run to start dev-time orchestration:

aspire run

When you run this command, the Aspire CLI:

Automatically finds the AppHost
Builds your solution
Launches dev-time orchestration

Once the dashboard is ready, its URL (with a login token—highlighted in the example output below) appears in your terminal. The dashboard provides a live, real-time view of your running resources and their current states.

🔍  Finding apphosts...
AspireApp.AppHost/AspireApp.AppHost.csproj

🗄  Created settings file at '.aspire/settings.json'.

     AppHost:  AspireApp.AppHost/AspireApp.AppHost.csproj

   Dashboard:  https://localhost:17068/login?t=ea559845d54cea66b837dc0ff33c3bd3

        Logs:  %USERPROFILE%/.aspire/cli/logs/apphost-13024-2025-10-31-19-40-58.log

               Press CTRL+C to stop the apphost and exit.

🔍  Finding apphosts...
apphost.cs

🗄  Created settings file at '.aspire/settings.json'.

     AppHost:  apphost.cs

   Dashboard:  https://localhost:17213/login?t=2b4a2ebc362b7fef9b5ccf73e702647b

        Logs:  $HOME/.aspire/cli/logs/apphost-27732-2025-10-31-19-21-27.log

               Press CTRL+C to stop the apphost and exit.

For further CLI reference, see aspire run command information.

Explore the running distributed application. From the dashboard, open the HTTPS endpoint from each resource.

To learn more, see Aspire dashboard overview.

Stop the app

Stop the AppHost and close the dashboard by pressing ⌘+C Control + C Control + C in your terminal.
Stop dev-time orchestration
```
🛑  Stopping Aspire.
```
🥳 Congratulations! You’ve created your first Aspire app.

FAQ Collaborate Community Discuss Watch