working-with-aspire

使用 .NET Aspire 13

致 AI 助手：使用 MCP 工具

重要： 协助用户调试 Aspire 应用程序时，请使用 Aspire MCP 工具，而不是使用 curl、调用外部 HTTP，或建议用户手动检查仪表板。

任务	MCP 工具	不要这样做
检查资源状态	list_resources	❌ 使用 curl 调用仪表板 API
获取服务日志	list_console_logs	❌ 使用 curl、docker logs
查看跟踪	list_traces	❌ 使用 curl 调用 OTLP 端点
查找跟踪中的错误	list_trace_structured_logs	❌ 手动搜索仪表板
列出可用的 AppHost	list_apphosts	❌ 搜索文件系统

如果未配置 MCP，请引导用户在其 AppHost 目录中运行 aspire mcp init。

快速参考

任务	参考文件
AppHost 模式、资源、生命周期	app-host.md
Azure 集成（数据库、消息传递、AI）	azure-integrations.md
数据库集成（Postgres、SQL、Mongo）	database-integrations.md
缓存（Redis、Valkey、Garnet）	caching-integrations.md
消息传递（Kafka、RabbitMQ、NATS）	messaging-integrations.md
多语言（Node.js、Python、Go、Rust、Java）	polyglot-integrations.md
部署、CLI 和 aspire do 流水线	deployment-cli.md
使用 Aspire 进行测试	testing.md
错误和故障排查	diagnostics.md
面向 AI 助手的 MCP 集成	mcp-integration.md
VS Code 扩展	vs-code-extension.md
证书信任配置	certificate-config.md
从 9.x 迁移到 13.x	aspire-13-migration.md

常见错误

❌ 错误：使用不存在或已弃用的 API

错误	正确	原因
AddPythonUvicornApp	AddUvicornApp	方法名就是 AddUvicornApp
AddNpmApp	AddViteApp 或 AddJavaScriptApp	AddNpmApp 已在 13.0 中移除
对 FastAPI 使用 AddPythonApp	AddUvicornApp	对 ASGI（FastAPI、Starlette）使用 AddUvicornApp
Aspire.Hosting.NodeJs	Aspire.Hosting.JavaScript	包已在 13.0 中重命名

❌ 错误：将机密放入 appsettings.json

// WRONG - secrets exposed in source control
// appsettings.json: { "Parameters": { "api-key": "secret123" } }

// CORRECT - use user-secrets for development
// dotnet user-secrets set "Parameters:api-key" "secret123"

Aspire 13 重大变更

重要： 从 Aspire 9.x 迁移时需要特别注意。完整详情请参阅 aspire-13-migration.md。

JavaScript/Node.js 变更（13.0）

// BEFORE (9.x) - REMOVED IN 13.0
builder.AddNpmApp("frontend", "../app", scriptName: "dev", args: ["--no-open"])

// AFTER (13.0) - Use AddJavaScriptApp or AddViteApp
builder.AddJavaScriptApp("frontend", "../app")
    .WithRunScript("dev")
    .WithArgs("--no-open");

// For Vite/React specifically:
builder.AddViteApp("frontend", "../app")
    .WithHttpEndpoint(env: "PORT");

// Package renamed: Aspire.Hosting.NodeJs → Aspire.Hosting.JavaScript

Azure Redis 变更（13.1）

// BEFORE (13.0) - DEPRECATED
builder.AddAzureRedisEnterprise("cache")

// AFTER (13.1)
builder.AddAzureManagedRedis("cache")

网络上下文变更（13.0）

// BEFORE (9.x) - containerHostName parameter removed
await resource.ProcessArgumentValuesAsync(
    executionContext, processValue, logger,
    containerHostName: "localhost", cancellationToken);

// AFTER (13.0) - Use NetworkIdentifier
await resource.ProcessArgumentValuesAsync(
    executionContext, processValue, logger, cancellationToken);

// Get endpoints with network context
var endpoint = api.GetEndpoint("http", KnownNetworkIdentifiers.DefaultAspireContainerNetwork);

发布 API 变更（13.0）

// BEFORE (9.x)
public class MyPublisher : IDistributedApplicationPublisher { }

// AFTER (13.0) - Use aspire do pipelines instead
// IDistributedApplicationPublisher is deprecated

Aspire 13.0+ 新功能

证书信任自动化

// Automatic - no configuration needed
var pythonApi = builder.AddUvicornApp("api", "./api", "main:app");
var nodeApi = builder.AddJavaScriptApp("frontend", "./frontend");
// Both automatically trust development certificates

面向 AI 助手的 MCP 集成

# Initialize MCP for Claude Code, GitHub Copilot, etc.
aspire mcp init

aspire do 流水线系统

aspire do build           # Build container images
aspire do push            # Push to registry
aspire do deploy          # Full deployment
aspire do diagnostics     # Show available steps

aspire init（将现有项目转换为 Aspire 项目）

aspire init               # Interactive setup
aspire init --single-file # Create .cs AppHost without .csproj

单文件 AppHost

// apphost.cs - no project file needed
#:package Aspire.Hosting@*
#:package Aspire.Hosting.Redis@*

var builder = DistributedApplication.CreateBuilder(args);
var cache = builder.AddRedis("cache");
builder.Build().Run();

常见模式

FastAPI + React（Vite）全栈

// Required packages:
// dotnet add package Aspire.Hosting.Python
// dotnet add package Aspire.Hosting.JavaScript  (NOT NodeJs!)
// dotnet add package Aspire.Hosting.PostgreSQL

var builder = DistributedApplication.CreateBuilder(args);

// Database
var db = builder.AddPostgres("db")
    .AddDatabase("appdata")
    .WithDataVolume();

// FastAPI backend - use AddUvicornApp (NOT AddPythonApp!)
var api = builder.AddUvicornApp("api", "../api", "main:app")
    .WithHttpEndpoint(port: 8000, env: "PORT")
    .WithReference(db)
    .WaitFor(db);

// React frontend - use AddViteApp (NOT AddNpmApp!)
builder.AddViteApp("frontend", "../frontend")
    .WithHttpEndpoint(env: "PORT")
    .WithExternalHttpEndpoints()
    .WithReference(api);

builder.Build().Run();

前端从环境变量读取 API URL：process.env.services__api__http__0

基本 AppHost 结构

var builder = DistributedApplication.CreateBuilder(args);

// Database
var db = builder.AddPostgres("db")
    .AddDatabase("appdata")
    .WithDataVolume();

// API with database reference
var api = builder.AddProject<Projects.Api>("api")
    .WithReference(db)
    .WaitFor(db);

// Frontend with API reference
builder.AddViteApp("frontend", "../frontend")
    .WithHttpEndpoint(env: "PORT")
    .WithReference(api);

builder.Build().Run();

服务发现模式

// Producer exposes endpoint
var api = builder.AddProject<Projects.Api>("api")
    .WithHttpEndpoint(port: 5000, name: "api");

// Consumer references it (gets services__api__api__0 env var)
builder.AddProject<Projects.Web>("web")
    .WithReference(api);

健康检查与等待

var db = builder.AddPostgres("db");
var cache = builder.AddRedis("cache");

builder.AddProject<Projects.Api>("api")
    .WithReference(db)
    .WithReference(cache)
    .WaitFor(db)           // Wait for running
    .WaitForHealthy(cache); // Wait for healthy (requires health check)

何时阅读特定文件

在以下情况下阅读 app-host.md：

• 设置新的 AppHost 项目
• 了解资源生命周期事件
• 配置端点和网络
• 使用参数和机密

在以下情况下阅读 azure-integrations.md：

• 使用 Azure 服务（Cosmos、Service Bus、Storage）
• 在本地运行 Azure 模拟器
• 使用 RunAsEmulator() 或 RunAsContainer()
• 自定义 Bicep 输出

在以下情况下阅读 polyglot-integrations.md：

• 添加 Node.js、Python、Go、Rust 或 Java 应用
• 使用前端框架（Vite、Angular、React）
• 使用基于容器的多语言服务
• 从 AddNpmApp 迁移到 AddJavaScriptApp

在以下情况下阅读 deployment-cli.md：

• 使用 aspire deploy、aspire publish 或 aspire do
• 使用 aspire init 将现有项目 Aspirify 化
• 设置 CI/CD 管道
• 了解清单格式

在以下情况下阅读 mcp-integration.md：

• 设置 AI 助手集成
• 配置 Claude Code、GitHub Copilot 或 Cursor
• 将资源排除在 MCP 访问范围之外

在以下情况下阅读 vs-code-extension.md：

• 在 VS Code 中使用 Aspire
• 调试多语言应用
• 在 VS Code 中创建新的 Aspire 项目

在以下情况下阅读 certificate-config.md：

• 为多语言应用配置 HTTPS
• 使用自定义证书颁发机构
• 排查服务之间的证书信任问题

在以下情况下阅读 aspire-13-migration.md：

• 从 Aspire 9.x 升级
• 遇到已弃用 API 的警告
• 升级后出现容器网络问题

在以下情况下阅读 diagnostics.md：

• 遇到 ASPIRE* 编译器错误
• 调试服务发现问题
• 排查容器启动问题