.NET Aspire
更新: 2026-10-16 15:20:09 字数: 0 字 时长: 0 分钟
Aspire 是一个面向代码（code-first）的分布式应用编排与可观测性层。
使用 Aspire 来建模构成您应用程序的服务、前端、数据库、队列、缓存、容器和云依赖。在生产环境中，这些组件作为一个系统协同工作；但在开发过程中，它们通常需要单独启动、手动配置，并在多个终端和仪表板之间来回调试。Aspire 为您提供一个定义系统的地方、一条运行系统的命令，以及一套观察系统的工具链。
本系列文档参考 aspire.dev/docs 官方文档整理，并结合 .NET / C# 开发者的常见使用场景做了补充说明。
一分钟示例
csharp
var builder = DistributedApplication.CreateBuilder(args);
var cache = builder.AddRedis("cache");
var api = builder.AddProject<Projects.ApiService>("apiservice")
.WithReference(cache)
.WithHttpHealthCheck("/health");
builder.AddProject<Projects.Web>("webfrontend")
.WithExternalHttpEndpoints()
.WithReference(api)
.WaitFor(api);
builder.Build().Run();bash
aspire run短短几行代码就描述清楚了「谁依赖谁」：前端等待 API 就绪，API 引用 Redis 缓存。运行 aspire run 之后，所有资源按依赖顺序启动，日志、追踪与资源状态统一出现在 Aspire 仪表板中。
核心概念
| 概念 | 说明 |
|---|---|
| AppHost | 应用主机。用代码描述应用拓扑的编排项目，是整个应用架构的唯一信息来源。 |
| 资源（Resource） | 应用中的每一个组成部分：项目、可执行文件、容器、数据库、缓存、云服务等。 |
| 集成（Integration） | 为 AppHost 提供资源定义能力的包，例如 Aspire.Hosting.PostgreSQL。 |
| 引用（Reference） | 通过 WithReference 建立资源依赖，自动注入连接信息并启用服务发现。 |
| ServiceDefaults | 共享项目，为所有服务统一配置服务发现、弹性、遥测与健康检查。 |
| Aspire 仪表板 | 本地 OpenTelemetry 查看器，集中展示日志、追踪、指标与资源状态。 |
| Aspire CLI | aspire 命令行工具，负责创建、运行、观察、发布与部署应用。 |
文档目录
入门
- 简介：Aspire 是什么、解决什么问题。
- 环境准备：运行 Aspire 所需的 SDK、容器运行时与工具。
- 安装：安装与更新 Aspire CLI。
- 快速开始：使用模板创建并运行第一个 Aspire 应用。
- 模板与项目结构：看清模板生成的每个项目。
- Aspire CLI：命令行工具速查。
基础
- AppHost 应用主机：编排应用的入口项目。
- 资源模型：内置资源与资源生命周期。
- 应用模型与架构：资源、关系与注解。
- 服务发现：用逻辑名称而不是硬编码地址互相访问。
- 健康检查：就绪判定与
WaitFor。 - 环境变量与配置注入：
WithReference到底注入了什么。 - 外部参数与机密：
AddParameter、用户机密与部署时取值。 - 网络与端点：端点、端口分配与容器网络。
- 数据持久化：数据卷与绑定挂载。
- 遥测与 OpenTelemetry：日志、追踪、指标的采集与导出。
- Aspire SDK 与 ServiceDefaults：共享的服务配置。
集成
仪表板
部署
测试
扩展
版本与升级
建议的阅读顺序
- 先读 简介 了解 Aspire 的定位与边界。
- 按 环境准备 → 安装 → 快速开始 把环境跑通。
- 再回到 基础 部分，理解 AppHost、资源与引用这三个核心概念。
- 按需查阅 集成 与 仪表板。
- 最后通过 测试 与 部署 把应用交付到目标环境。
