Aspire — 多语言分布式应用编排

Aspire 是一个代码优先、多语言的工具链，用于构建可观测、可投入生产的分布式应用。它通过一个单一的 AppHost 项目编排容器、可执行文件和云资源——无论工作负载是 C#、Python、JavaScript/TypeScript、Go、Java、Rust、Bun、Deno 还是 PowerShell。

心智模型： AppHost 是一个指挥——它不演奏乐器，而是告诉每个服务何时启动、如何找到彼此，并监控问题。

详细的参考资料位于 references/ 文件夹中——可按需加载。

参考文档

1. 研究 Aspire 文档

Aspire 团队提供了一个MCP 服务器，可在 AI 助手中直接提供文档工具。有关设置详情，请参阅 MCP 服务器。

Aspire CLI 13.2+（推荐 — 内置文档搜索）

如果运行的 Aspire CLI 是 13.2 或更高版本 (aspire --version)，MCP 服务器包含文档搜索工具：

这些工具是在 PR #14028 中添加的。要更新：aspire update --self --channel daily。

有关此方法的更多信息，请参阅 David Pine 的文章：https://davidpine.dev/posts/aspire-docs-mcp-tools/

Aspire CLI 13.1（仅集成工具）

在 13.1 上，MCP 服务器提供集成查找功能，但不提供文档搜索：

对于 13.1 上的常规文档查询，请使用 Context7 作为主要来源（见下文）。

备用方案：Context7

当 Aspire MCP 文档工具不可用（13.1）或 MCP 服务器未运行时，请使用 Context7 (mcp_context7)：

步骤 1 — 解析库 ID（每个会话一次）：

使用 libraryName: ".NET Aspire" 调用 mcp_context7_resolve-library-id。

步骤 2 — 查询文档：

libraryId: "/microsoft/aspire.dev", query: "Python 集成 AddPythonApp 服务发现"
libraryId: "/communitytoolkit/aspire", query: "Golang Java Node.js 社区集成"

备用方案：GitHub 搜索（当 Context7 也不可用时）

在 GitHub 上搜索官方文档仓库：

• 文档仓库： microsoft/aspire.dev — 路径：src/frontend/src/content/docs/
• 源代码仓库： dotnet/aspire
• 示例仓库： dotnet/aspire-samples
• 社区集成： CommunityToolkit/Aspire

2. 先决条件与安装

# Linux / macOS
curl -sSL https://aspire.dev/install.sh | bash

# Windows PowerShell
irm https://aspire.dev/install.ps1 | iex

# 验证
aspire --version

# 安装模板
dotnet new install Aspire.ProjectTemplates

3. 项目模板

4. AppHost 快速开始（多语言）

AppHost 编排所有服务。非 .NET 工作负载作为容器或可执行文件运行。

var builder = DistributedApplication.CreateBuilder(args);

// 基础设施
var redis = builder.AddRedis("cache");
var postgres = builder.AddPostgres("pg").AddDatabase("catalog");

// .NET API
var api = builder.AddProject<Projects.CatalogApi>("api")
    .WithReference(postgres).WithReference(redis);

// Python 机器学习服务
var ml = builder.AddPythonApp("ml-service", "../ml-service", "main.py")
    .WithHttpEndpoint(targetPort: 8000).WithReference(redis);

// React 前端 (Vite)
var web = builder.AddViteApp("web", "../frontend")
    .WithHttpEndpoint(targetPort: 5173).WithReference(api);

// Go 工作进程
var worker = builder.AddGolangApp("worker", "../go-worker")
    .WithReference(redis);

builder.Build().Run();

有关完整的 API 签名，请参阅 多语言 API。

5. 核心概念（摘要）

6. CLI 快速参考

Aspire CLI 13.1 中的有效命令：

带有标志的完整命令参考：CLI 参考。

7. 常见模式

添加新服务

1. 创建你的服务目录（任何语言）
2. 添加到 AppHost：Add*App() 或 AddProject<T>()
3. 连接依赖项：.WithReference()
4. 如果需要，基于健康检查进行门控：.WaitFor()
5. 运行：aspire run

从 Docker Compose 迁移

1. aspire new aspire-apphost-singlefile（空的 AppHost）
2. 将每个 docker-compose 服务替换为 Aspire 资源
3. depends_on → .WithReference() + .WaitFor()
4. ports → .WithHttpEndpoint()
5. environment → .WithEnvironment() 或 .WithReference()

8. 关键链接