aspire

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Aspire — Polyglot Distributed-App Orchestration

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

Aspire is a code-first, polyglot toolchain for building observable, production-ready distributed applications. It orchestrates containers, executables, and cloud resources from a single AppHost project — regardless of whether the workloads are C#, Python, JavaScript/TypeScript, Go, Java, Rust, Bun, Deno, or PowerShell.

Mental model: The AppHost is a conductor — it doesn't play the instruments, it tells every service when to start, how to find each other, and watches for problems.

Detailed reference material lives in the

references/

folder — load on demand.

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

心智模型： AppHost就像一个指挥家——它不亲自演奏乐器，而是指挥每个服务何时启动、如何相互发现，并监控运行中的问题。

详细参考资料位于

references/

文件夹中——可按需加载。

References

参考资料

Reference	When to load
CLI Reference	Command flags, options, or detailed usage
MCP Server	Setting up MCP for AI assistants, available tools
Integrations Catalog	Discovering integrations via MCP tools, wiring patterns
Polyglot APIs	Method signatures, chaining options, language-specific patterns
Architecture	DCP internals, resource model, service discovery, networking, telemetry
Dashboard	Dashboard features, standalone mode, GenAI Visualizer
Deployment	Docker, Kubernetes, Azure Container Apps, App Service
Testing	Integration tests against the AppHost
Troubleshooting	Diagnostic codes, common errors, and fixes

参考文档	加载场景
CLI参考	命令标志、选项或详细用法
MCP服务器	为AI助手设置MCP、可用工具
集成目录	通过MCP工具发现集成、连接模式
多语言API	方法签名、链式调用选项、语言特定模式
架构	DCP内部机制、资源模型、服务发现、网络、遥测
仪表板	仪表板功能、独立模式、生成式AI可视化工具
部署	Docker、Kubernetes、Azure容器应用、应用服务
测试	针对AppHost的集成测试
故障排查	诊断代码、常见错误及修复方案

1. Researching Aspire Documentation

1. 查阅Aspire文档

The Aspire team ships an MCP server that provides documentation tools directly inside your AI assistant. See MCP Server for setup details.

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

Aspire CLI 13.2+ (recommended — has built-in docs search)

Aspire CLI 13.2+（推荐版本——内置文档搜索功能）

If running Aspire CLI 13.2 or later (

aspire --version

), the MCP server includes docs search tools:

Tool	Description
`list_docs`	Lists all available documentation from aspire.dev
`search_docs`	Performs weighted lexical search across indexed documentation
`get_doc`	Retrieves a specific document by its slug

These tools were added in PR #14028. To update:

aspire update --self --channel daily

For more on this approach, see David Pine's post: https://davidpine.dev/posts/aspire-docs-mcp-tools/

如果运行Aspire CLI 13.2或更高版本（执行

aspire --version

查看），MCP服务器包含文档搜索工具：

工具	描述
`list_docs`	列出aspire.dev上所有可用文档
`search_docs`	在已索引文档中执行加权词法搜索
`get_doc`	通过slug检索特定文档

这些工具是在PR #14028中添加的。如需更新，请执行：

aspire update --self --channel daily

。

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

Aspire CLI 13.1 (integration tools only)

Aspire CLI 13.1（仅包含集成工具）

On 13.1, the MCP server provides integration lookup but not docs search:

Tool	Description
`list_integrations`	Lists available Aspire hosting integrations
`get_integration_docs`	Gets documentation for a specific integration package

For general docs queries on 13.1, use Context7 as your primary source (see below).

在13.1版本中，MCP服务器提供集成查询功能，但不支持文档搜索：

工具	描述
`list_integrations`	列出可用的Aspire托管集成
`get_integration_docs`	获取特定集成包的文档

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

Fallback: Context7

备选方案：Context7

Use Context7 (

mcp_context7

) when the Aspire MCP docs tools are unavailable (13.1) or the MCP server isn't running:

Step 1 — Resolve the library ID (one-time per session):

Call

mcp_context7_resolve-library-id

with

libraryName: ".NET Aspire"

Rank	Library ID	Use when
1	`/microsoft/aspire.dev`	Primary source. Guides, integrations, CLI reference, deployment.
2	`/dotnet/aspire`	API internals, source-level implementation details.
3	`/communitytoolkit/aspire`	Non-Microsoft polyglot integrations (Go, Java, Node.js, Ollama).

Step 2 — Query docs:

libraryId: "/microsoft/aspire.dev", query: "Python integration AddPythonApp service discovery"
libraryId: "/communitytoolkit/aspire", query: "Golang Java Node.js community integrations"

当Aspire MCP文档工具不可用（13.1版本）或MCP服务器未运行时，使用Context7（

mcp_context7

）：

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

调用

mcp_context7_resolve-library-id

，参数为

libraryName: ".NET Aspire"

。

排名	库ID	使用场景
1	`/microsoft/aspire.dev`	主要来源。指南、集成、CLI参考、部署相关内容。
2	`/dotnet/aspire`	API内部机制、源代码级实现细节。
3	`/communitytoolkit/aspire`	非微软的多语言集成（Go、Java、Node.js、Ollama）。

步骤2 — 查询文档：

libraryId: "/microsoft/aspire.dev", query: "Python integration AddPythonApp service discovery"
libraryId: "/communitytoolkit/aspire", query: "Golang Java Node.js community integrations"

Fallback: GitHub search (when Context7 is also unavailable)

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

Search the official docs repo on GitHub:

Docs repo:

microsoft/aspire.dev

— path:

src/frontend/src/content/docs/

Source repo:
```
dotnet/aspire
```
Samples repo:
```
dotnet/aspire-samples
```
Community integrations:
```
CommunityToolkit/Aspire
```

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

文档仓库：

microsoft/aspire.dev

— 路径：

src/frontend/src/content/docs/

源代码仓库：
```
dotnet/aspire
```
示例仓库：
```
dotnet/aspire-samples
```
社区集成：
```
CommunityToolkit/Aspire
```

2. Prerequisites & Install

2. 前提条件与安装

Requirement	Details
.NET SDK	10.0+ (required even for non-.NET workloads — the AppHost is .NET)
Container runtime	Docker Desktop, Podman, or Rancher Desktop
IDE (optional)	VS Code + C# Dev Kit, Visual Studio 2022, JetBrains Rider

bash

undefined

要求	详情
.NET SDK	10.0+（即使是非.NET工作负载也需要——因为AppHost是.NET项目）
容器运行时	Docker Desktop、Podman或Rancher Desktop
IDE（可选）	VS Code + C# Dev Kit、Visual Studio 2022、JetBrains Rider

bash

undefined

Linux / macOS

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

Windows PowerShell

irm https://aspire.dev/install.ps1 | iex

Verify

验证版本

aspire --version

Install templates

安装模板

dotnet new install Aspire.ProjectTemplates

---

dotnet new install Aspire.ProjectTemplates

---

3. Project Templates

3. 项目模板

Template	Command	Description
aspire-starter	`aspire new aspire-starter`	ASP.NET Core/Blazor starter + AppHost + tests
aspire-ts-cs-starter	`aspire new aspire-ts-cs-starter`	ASP.NET Core/React starter + AppHost
aspire-py-starter	`aspire new aspire-py-starter`	FastAPI/React starter + AppHost
aspire-apphost-singlefile	`aspire new aspire-apphost-singlefile`	Empty single-file AppHost

模板	命令	描述
aspire-starter	`aspire new aspire-starter`	ASP.NET Core/Blazor启动模板 + AppHost + 测试
aspire-ts-cs-starter	`aspire new aspire-ts-cs-starter`	ASP.NET Core/React启动模板 + AppHost
aspire-py-starter	`aspire new aspire-py-starter`	FastAPI/React启动模板 + AppHost
aspire-apphost-singlefile	`aspire new aspire-apphost-singlefile`	空的单文件AppHost

4. AppHost Quick Start (Polyglot)

4. AppHost快速入门（多语言）

The AppHost orchestrates all services. Non-.NET workloads run as containers or executables.

csharp

var builder = DistributedApplication.CreateBuilder(args);

// Infrastructure
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 ML service
var ml = builder.AddPythonApp("ml-service", "../ml-service", "main.py")
    .WithHttpEndpoint(targetPort: 8000).WithReference(redis);

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

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

builder.Build().Run();

For complete API signatures, see Polyglot APIs.

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

csharp

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. Core Concepts (Summary)

5. 核心概念（摘要）

Concept	Key point
Run vs Publish	`aspire run` = local dev (DCP engine). `aspire publish` = generate deployment manifests.
Service discovery	Automatic via env vars: `ConnectionStrings__<name>` , `services__<name>__http__0`
Resource lifecycle	DAG ordering — dependencies start first. `.WaitFor()` gates on health checks.
Resource types	`ProjectResource` , `ContainerResource` , `ExecutableResource` , `ParameterResource`
Integrations	144+ across 13 categories. Hosting package (AppHost) + Client package (service).
Dashboard	Real-time logs, traces, metrics, GenAI visualizer. Runs automatically with `aspire run` .
MCP Server	AI assistants can query running apps and search docs via CLI (STDIO).
Testing	`Aspire.Hosting.Testing` — spin up full AppHost in xUnit/MSTest/NUnit.
Deployment	Docker, Kubernetes, Azure Container Apps, Azure App Service.

概念	关键点
运行 vs 发布	`aspire run` = 本地开发（DCP引擎）。 `aspire publish` = 生成部署清单。
服务发现	通过环境变量自动实现： `ConnectionStrings__<name>` 、 `services__<name>__http__0`
资源生命周期	DAG排序——依赖项优先启动。 `.WaitFor()` 基于健康检查进行阻塞。
资源类型	`ProjectResource` 、 `ContainerResource` 、 `ExecutableResource` 、 `ParameterResource`
集成	144+个集成，覆盖13个类别。托管包（AppHost） + 客户端包（服务）。
仪表板	实时日志、追踪、指标、生成式AI可视化工具。运行 `aspire run` 时自动启动。
MCP服务器	AI助手可通过CLI（标准输入输出）查询运行中的应用并搜索文档。
测试	`Aspire.Hosting.Testing` ——在xUnit/MSTest/NUnit中启动完整的AppHost。
部署	Docker、Kubernetes、Azure容器应用、Azure应用服务。

6. CLI Quick Reference

6. CLI快速参考

Valid commands in Aspire CLI 13.1:

Command	Description	Status
`aspire new <template>`	Create from template	Stable
`aspire init`	Initialize in existing project	Stable
`aspire run`	Start all resources locally	Stable
`aspire add <integration>`	Add an integration	Stable
`aspire publish`	Generate deployment manifests	Preview
`aspire config`	Manage configuration settings	Stable
`aspire cache`	Manage disk cache	Stable
`aspire deploy`	Deploy to defined targets	Preview
`aspire do <step>`	Execute a pipeline step	Preview
`aspire update`	Update integrations (or `--self` for CLI)	Preview
`aspire mcp init`	Configure MCP for AI assistants	Stable
`aspire mcp start`	Start the MCP server	Stable

Full command reference with flags: CLI Reference.

Aspire CLI 13.1中的有效命令：

命令	描述	状态
`aspire new <template>`	从模板创建项目	稳定
`aspire init`	在现有项目中初始化Aspire	稳定
`aspire run`	本地启动所有资源	稳定
`aspire add <integration>`	添加集成	稳定
`aspire publish`	生成部署清单	预览
`aspire config`	管理配置设置	稳定
`aspire cache`	管理磁盘缓存	稳定
`aspire deploy`	部署到指定目标	预览
`aspire do <step>`	执行流水线步骤	预览
`aspire update`	更新集成（或使用 `--self` 更新CLI）	预览
`aspire mcp init`	为AI助手配置MCP	稳定
`aspire mcp start`	启动MCP服务器	稳定

包含标志的完整命令参考：CLI参考。

7. Common Patterns

7. 常见模式

Adding a new service

添加新服务

Create your service directory (any language)
Add to AppHost:
```
Add*App()
```
or
```
AddProject<T>()
```
Wire dependencies:
```
.WithReference()
```
Gate on health:
```
.WaitFor()
```
if needed
Run:
```
aspire run
```

创建服务目录（支持任意语言）
在AppHost中添加：
```
Add*App()
```
或
```
AddProject<T>()
```
连接依赖项：
```
.WithReference()
```
如需基于健康检查阻塞，使用
```
.WaitFor()
```
运行：
```
aspire run
```

Migrating from Docker Compose

从Docker Compose迁移

```
aspire new aspire-apphost-singlefile
```
(empty AppHost)
Replace each
```
docker-compose
```
service with an Aspire resource
```
depends_on
```
→
```
.WithReference()
```
+
```
.WaitFor()
```
```
ports
```
→
```
.WithHttpEndpoint()
```

environment

→

.WithEnvironment()

.WithReference()

```
aspire new aspire-apphost-singlefile
```
（空的AppHost）
将每个
```
docker-compose
```
服务替换为Aspire资源
```
depends_on
```
→
```
.WithReference()
```
+
```
.WaitFor()
```
```
ports
```
→
```
.WithHttpEndpoint()
```

environment

→

.WithEnvironment()

或

.WithReference()

8. Key URLs

8. 关键链接

Resource	URL
Documentation	https://aspire.dev
Runtime repo	https://github.com/dotnet/aspire
Docs repo	https://github.com/microsoft/aspire.dev
Samples	https://github.com/dotnet/aspire-samples
Community Toolkit	https://github.com/CommunityToolkit/Aspire
Dashboard image	`mcr.microsoft.com/dotnet/aspire-dashboard`
Discord	https://aka.ms/aspire/discord
Reddit	https://www.reddit.com/r/aspiredotdev/

资源	URL
官方文档	https://aspire.dev
运行时仓库	https://github.com/dotnet/aspire
文档仓库	https://github.com/microsoft/aspire.dev
示例仓库	https://github.com/dotnet/aspire-samples
社区工具包	https://github.com/CommunityToolkit/Aspire
仪表板镜像	`mcr.microsoft.com/dotnet/aspire-dashboard`
Discord社区	https://aka.ms/aspire/discord
Reddit社区	https://www.reddit.com/r/aspiredotdev/