快速开始

更新: 2026-10-16 15:20:09   字数: 0 字   时长: 0 分钟

这一节用大约五分钟，从零创建并运行一个 Aspire 应用。请先完成环境准备与安装。

1. 创建一个新应用

使用 Aspire CLI 从模板生成新的解决方案。模板包含多个项目，例如 API 服务、Web 前端和 Aspire AppHost。

aspire new aspire-starter -n AspireApp -o AspireApp

参数说明：

参数	含义
-n	解决方案名称。
-o	输出目录。不传时以模板名作为目录名，重名时自动追加数字后缀。

如果命令出现交互式提问，用上下方向键选择、回车确认。其中会询问：

Would you like to configure AI agent environments for this project?

选择 y 会为项目配置 AI 编码助手的工作区设置（Aspire 技能文件与 MCP 服务器配置）。

也可以选择其他模板

aspire new aspire-empty            # 最小模板，只有 AppHost + ServiceDefaults
aspire new aspire-ts-starter       # TypeScript AppHost + Express + React
aspire new aspire-py-starter       # TypeScript AppHost + FastAPI + React

更多模板见模板与项目结构。

2. 查看模板代码

AppHost 是 Aspire 应用的核心。它定义了哪些服务运行、它们如何连接以及启动的顺序：

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();

• CreateBuilder 用于创建分布式应用构建器。
• AddProject 用于注册您的 API 服务和 Web 前端。
• WithReference 连接多个服务：它会把 API 的 URL 注入为环境变量，并设置服务发现，使您能够使用服务名称而非硬编码 URL。
• WaitFor 确保 API 正常运行后再启动前端，避免因竞态条件导致的连接错误。
• WithHttpHealthCheck 用于监控服务的健康状态。

3. 本地运行

cd ./AspireApp

aspire run

该命令会：自动找到 AppHost → 构建解决方案 → 启动编排。仪表板就绪后，终端会打印它的地址：

🔍 Finding apphosts...
AspireApp.AppHost/AspireApp.AppHost.csproj
🗄 Created settings file at 'aspire.config.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.

打开 Dashboard 后面的地址（注意要带上登录令牌），即可看到资源列表与遥测数据。按 Ctrl+C 停止应用。

后台运行

需要让应用在后台跑、然后继续用终端做别的事时：

aspire start        # 后台启动
aspire describe     # 查看资源状态
aspire logs         # 查看日志
aspire stop         # 停止

4. 添加一个集成

模板里还没有数据库。用一条命令加上 PostgreSQL：

aspire add postgresql

然后在 AppHost 中声明资源并引用：

var builder = DistributedApplication.CreateBuilder(args);

var db = builder.AddPostgres("pg")
    .WithDataVolume()
    .AddDatabase("catalogdb");

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

builder.Build().Run();

数据卷要让密码持久

使用 WithDataVolume() 时，请固定数据库密码，否则每次运行生成的新密码会让旧数据无法访问：

aspire secret set Parameters:pg-password "your-password"

详见数据持久化。

5. 部署

添加对应的托管部署包，即可把应用部署到目标环境：

Docker Compose

aspire add docker

Azure

aspire add azure-appcontainers

在 AppHost 中配置部署环境：

Docker Compose

var builder = DistributedApplication.CreateBuilder(args);

// 添加下面这行以配置 Docker Compose 环境
builder.AddDockerComposeEnvironment("env");

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();

Azure

var builder = DistributedApplication.CreateBuilder(args);

// 添加下面这行以配置 Azure 容器应用环境
builder.AddAzureContainerAppEnvironment("env");

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();

现在就可以部署了：

aspire deploy

下一步

• 模板与项目结构：搞清模板生成的每个项目。
• AppHost 应用主机：理解编排的核心概念。
• 集成简介：把数据库、缓存、消息队列接进来。
• 仪表板简介：学会看日志与追踪。
• 编写第一个测试：为分布式应用写集成测试。