Back to Details

working-with-aspire

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Working with .NET Aspire 13

.NET Aspire 13 使用指南

For AI Assistants: Use MCP Tools

面向AI助手：使用MCP工具

CRITICAL: When helping users debug Aspire applications, use the Aspire MCP tools instead of curl, external HTTP calls, or suggesting manual dashboard inspection.
TaskMCP ToolNOT This
Check resource status
list_resources
❌ curl to dashboard API
Get service logs
list_console_logs
❌ curl, docker logs
View traces
list_traces
❌ curl to OTLP endpoint
Find errors in traces
list_trace_structured_logs
❌ manual dashboard search
List available AppHosts
list_apphosts
❌ file system search
If MCP is not configured, guide the user to run 
aspire mcp init
in their AppHost directory.
重要提示： 帮助用户调试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
。

Quick Reference

快速参考

TaskReference File
AppHost patterns, resources, lifecycle
app-host.md
Azure integrations (databases, messaging, AI)
azure-integrations.md
Database integrations (Postgres, SQL, Mongo)
database-integrations.md
Caching (Redis, Valkey, Garnet)
caching-integrations.md
Messaging (Kafka, RabbitMQ, NATS)
messaging-integrations.md
Polyglot (Node.js, Python, Go, Rust, Java)
polyglot-integrations.md
Deployment, CLI, and aspire do pipelines
deployment-cli.md
Testing with Aspire
testing.md
Errors and troubleshooting
diagnostics.md
MCP integration for AI assistants
mcp-integration.md
VS Code extension
vs-code-extension.md
Certificate trust configuration
certificate-config.md
Migration from 9.x to 13.x
aspire-13-migration.md
任务参考文档
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

Common Mistakes

常见错误

❌ Wrong: Using non-existent or deprecated APIs

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

WrongCorrectWhy
AddPythonUvicornApp
AddUvicornApp
Method is just 
AddUvicornApp
AddNpmApp
AddViteApp
or 
AddJavaScriptApp
AddNpmApp
removed in 13.0
AddPythonApp
for FastAPI
AddUvicornApp
Use AddUvicornApp for ASGI (FastAPI, Starlette)
Aspire.Hosting.NodeJs
Aspire.Hosting.JavaScript
Package renamed in 13.0
错误用法正确用法原因
AddPythonUvicornApp
AddUvicornApp
方法已简化为
AddUvicornApp
AddNpmApp
AddViteApp
或 
AddJavaScriptApp
AddNpmApp
在13.0版本中已移除
为FastAPI使用
AddPythonApp
AddUvicornApp
对于ASGI应用（FastAPI、Starlette）请使用AddUvicornApp
Aspire.Hosting.NodeJs
Aspire.Hosting.JavaScript
包名在13.0版本中已重命名

❌ Wrong: Putting secrets in appsettings.json

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

csharp
// 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"
csharp
// 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 Breaking Changes

.NET Aspire 13 重大变更

Critical: Migration from Aspire 9.x requires attention. See 
aspire-13-migration.md
for full details.
关键提示： 从Aspire 9.x版本迁移时需要特别注意。详细内容请参阅
aspire-13-migration.md
。

JavaScript/Node.js Changes (13.0)

JavaScript/Node.js变更（13.0版本）

csharp
// 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
csharp
// 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 Changes (13.1)

Azure Redis变更（13.1版本）

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

// AFTER (13.1)
builder.AddAzureManagedRedis("cache")
csharp
// BEFORE (13.0) - DEPRECATED
builder.AddAzureRedisEnterprise("cache")

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

Network Context Changes (13.0)

网络上下文变更（13.0版本）

csharp
// 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);
csharp
// 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);

Publishing API Changes (13.0)

发布API变更（13.0版本）

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

// AFTER (13.0) - Use aspire do pipelines instead
// IDistributedApplicationPublisher is deprecated
csharp
// BEFORE (9.x)
public class MyPublisher : IDistributedApplicationPublisher { }

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

Aspire 13.0+ New Features

.NET Aspire 13.0+ 新特性

Certificate Trust Automation

证书信任自动化

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

MCP Integration for AI Assistants

面向AI助手的MCP集成

bash
undefined
bash
undefined

Initialize MCP for Claude Code, GitHub Copilot, etc.

Initialize MCP for Claude Code, GitHub Copilot, etc.

aspire mcp init
undefined
aspire mcp init
undefined

aspire do Pipeline System

aspire do 流水线系统

bash
aspire do build           # Build container images
aspire do push            # Push to registry
aspire do deploy          # Full deployment
aspire do diagnostics     # Show available steps
bash
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 (Aspirify Existing Projects)

aspire init（将现有项目Aspirify化）

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

Single-File AppHost

单文件AppHost

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

Common Patterns

常见模式

FastAPI + React (Vite) Full Stack

FastAPI + React (Vite) 全栈示例

csharp
// 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();
Frontend reads API URL from env: 
process.env.services__api__http__0
csharp
// 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地址：
process.env.services__api__http__0

Basic AppHost Structure

基础AppHost结构

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

Service Discovery Pattern

服务发现模式

csharp
// 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);
csharp
// 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);

Health Checks and Wait

健康检查与等待机制

csharp
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)
csharp
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)

When to Read Specific Files

何时阅读特定文档

Read 
app-host.md
when:
  • Setting up new AppHost project
  • Understanding resource lifecycle events
  • Configuring endpoints and networking
  • Using parameters and secrets
Read 
azure-integrations.md
when:
  • Using Azure services (Cosmos, Service Bus, Storage)
  • Running Azure emulators locally
  • Using 
    RunAsEmulator()
    or 
    RunAsContainer()
  • Customizing Bicep output
Read 
polyglot-integrations.md
when:
  • Adding Node.js, Python, Go, Rust, or Java apps
  • Frontend frameworks (Vite, Angular, React)
  • Container-based polyglot services
  • Migrating from AddNpmApp to AddJavaScriptApp
Read 
deployment-cli.md
when:
  • Using 
    aspire deploy
    , 
    aspire publish
    , or 
    aspire do
  • Using 
    aspire init
    to Aspirify existing projects
  • Setting up CI/CD pipelines
  • Understanding manifest format
Read 
mcp-integration.md
when:
  • Setting up AI assistant integration
  • Configuring Claude Code, GitHub Copilot, or Cursor
  • Excluding resources from MCP access
Read 
vs-code-extension.md
when:
  • Using Aspire in VS Code
  • Debugging polyglot applications
  • Creating new Aspire projects in VS Code
Read 
certificate-config.md
when:
  • Configuring HTTPS for polyglot apps
  • Custom certificate authorities
  • Certificate trust issues between services
Read 
aspire-13-migration.md
when:
  • Upgrading from Aspire 9.x
  • Seeing deprecated API warnings
  • Container networking issues after upgrade
Read 
diagnostics.md
when:
  • Seeing ASPIRE* compiler errors
  • Debugging service discovery issues
  • Troubleshooting container startup
当以下情况时阅读
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*编译错误
  • 调试服务发现问题
  • 排查容器启动问题