aspire
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
Chinese.NET Aspire 13.x Skill
.NET Aspire 13.x Skill
.NET Aspire 13.x provides orchestration for this distributed ledger platform. The AppHost () orchestrates 7 microservices with PostgreSQL, MongoDB, and Redis. Services use for consistent OpenTelemetry, health checks, and service discovery. JWT signing keys are generated once and shared across all services via environment variables.
src/Apps/Sorcha.AppHost/AppHost.csAddServiceDefaults().NET Aspire 13.x 为该分布式账本平台提供编排能力。AppHost(路径:)负责编排7个微服务,并集成了PostgreSQL、MongoDB和Redis。服务通过来统一配置OpenTelemetry、健康检查和服务发现功能。JWT签名密钥仅生成一次,并通过环境变量在所有服务之间共享。
src/Apps/Sorcha.AppHost/AppHost.csAddServiceDefaults()Version Info
版本信息
| Component | Version | Notes |
|---|---|---|
| Aspire.AppHost.Sdk | 13.0.0 | SDK in |
| Aspire.Hosting.* | 13.1.0 | AppHost hosting packages |
| Aspire.StackExchange.Redis | 13.1.0 | Service-level Redis integration |
| Aspire.Hosting.Testing | 13.1.0 | Integration/E2E test infrastructure |
| Aspire Dashboard | 9.0.0 | Docker image (separate versioning) |
Sorcha Package Locations:
- AppHost:
src/Apps/Sorcha.AppHost/Sorcha.AppHost.csproj - ServiceDefaults:
src/Common/Sorcha.ServiceDefaults/Extensions.cs - Services: Blueprint, Register, Wallet, Validator (each has )
Aspire.StackExchange.Redis - Tests: Gateway Integration, Wallet Integration, UI E2E (each has )
Aspire.Hosting.Testing
| 组件 | 版本 | 说明 |
|---|---|---|
| Aspire.AppHost.Sdk | 13.0.0 | |
| Aspire.Hosting.* | 13.1.0 | AppHost托管包 |
| Aspire.StackExchange.Redis | 13.1.0 | 服务级Redis集成包 |
| Aspire.Hosting.Testing | 13.1.0 | 集成/端到端测试基础设施 |
| Aspire Dashboard | 9.0.0 | Docker镜像(版本独立管理) |
Sorcha包位置:
- AppHost:
src/Apps/Sorcha.AppHost/Sorcha.AppHost.csproj - ServiceDefaults:
src/Common/Sorcha.ServiceDefaults/Extensions.cs - 服务:Blueprint、Register、Wallet、Validator(每个服务均引用)
Aspire.StackExchange.Redis - 测试:网关集成测试、钱包集成测试、UI端到端测试(每个测试项目均引用)
Aspire.Hosting.Testing
Quick Start
快速开始
Adding a Service to AppHost
向AppHost添加服务
csharp
// In AppHost.cs - Add project with resource references
var myService = builder.AddProject<Projects.Sorcha_MyService>("my-service")
.WithReference(redis) // Service discovery
.WithReference(walletDb) // Database connection
.WithEnvironment("JwtSettings__SigningKey", jwtSigningKey); // Shared configcsharp
// 在AppHost.cs中 - 添加带有资源引用的项目
var myService = builder.AddProject<Projects.Sorcha_MyService>("my-service")
.WithReference(redis) // 服务发现
.WithReference(walletDb) // 数据库连接
.WithEnvironment("JwtSettings__SigningKey", jwtSigningKey); // 共享配置Named References (v13+)
命名引用(v13+)
csharp
// Control the environment variable prefix for a resource reference
var myService = builder.AddProject<Projects.Sorcha_MyService>("my-service")
.WithReference(postgres.AddDatabase("mydb"), "primary-db"); // ConnectionStrings__primary-dbcsharp
// 控制资源引用的环境变量前缀
var myService = builder.AddProject<Projects.Sorcha_MyService>("my-service")
.WithReference(postgres.AddDatabase("mydb"), "primary-db"); // 对应环境变量ConnectionStrings__primary-dbConsuming Aspire in a Service
在服务中使用Aspire
csharp
// In Program.cs - Every service starts with this
var builder = WebApplication.CreateBuilder(args);
builder.AddServiceDefaults(); // OpenTelemetry, health checks, discovery
builder.AddRedisOutputCache("redis"); // Reference by resource name
builder.AddRedisDistributedCache("redis");
var app = builder.Build();
app.MapDefaultEndpoints(); // /health and /alivecsharp
// 在Program.cs中 - 所有服务均以此开头
var builder = WebApplication.CreateBuilder(args);
builder.AddServiceDefaults(); // 配置OpenTelemetry、健康检查和服务发现
builder.AddRedisOutputCache("redis"); // 按资源名称引用Redis
builder.AddRedisDistributedCache("redis");
var app = builder.Build();
app.MapDefaultEndpoints(); // 暴露/health和/alive端点Key Concepts
核心概念
| Concept | Usage | Example |
|---|---|---|
| Resource Name | Identifier for service discovery | |
| WithReference | Injects connection string/URL | |
| Named Reference | Custom env var prefix (v13+) | |
| WithEnvironment | Pass config to service | |
| WithExternalHttpEndpoints | Expose outside Aspire network | |
| AddServiceDefaults | Shared Aspire configuration | |
| Connection Properties | Access individual fields (v13+) | |
| WithHttpsCertificate | TLS termination (v13.1+) | |
| ContainerRegistryResource | Registry config (v13.1+ exp.) | |
| 概念 | 用途 | 示例 |
|---|---|---|
| 资源名称 | 服务发现的标识符 | |
| WithReference | 注入连接字符串/URL | |
| 命名引用 | 自定义环境变量前缀(v13+) | |
| WithEnvironment | 向服务传递配置 | |
| WithExternalHttpEndpoints | 暴露到Aspire网络外部 | |
| AddServiceDefaults | 配置共享的Aspire默认项 | |
| 连接属性 | 访问单个字段(v13+) | |
| WithHttpsCertificate | TLS终止(v13.1+) | |
| ContainerRegistryResource | 容器注册表配置(v13.1+ 实验性) | |
What's New in Aspire 13.x
.NET Aspire 13.x 新特性
v13.0 Highlights
v13.0 重点特性
- New SDK format: Single replaces dual-SDK
<Project Sdk="Aspire.AppHost.Sdk/13.0.0"> - Polyglot connections: Resources expose ,
HostName,PortJdbcConnectionString - Named references: for env var prefixes
WithReference(resource, "customName") - MCP dashboard: Aspire dashboard exposes MCP endpoints for AI assistants
- Container file artifacts: for frontend-in-backend
PublishWithContainerFiles() - Pipeline system: for coordinated build/publish/deploy
aspire do - aspire init: Interactive solution initialization and discovery
- VS Code extension: Native project creation, debugging, deployment
- 新SDK格式:单个替代双SDK格式
<Project Sdk="Aspire.AppHost.Sdk/13.0.0"> - 多语言连接:资源暴露、
HostName、Port等属性JdbcConnectionString - 命名引用:支持自定义环境变量前缀
WithReference(resource, "customName") - MCP仪表盘:Aspire仪表盘为AI助手暴露MCP端点
- 容器文件制品:支持前端与后端打包
PublishWithContainerFiles() - 流水线系统:命令用于协调构建/发布/部署流程
aspire do - aspire init:交互式解决方案初始化与发现
- VS Code扩展:原生项目创建、调试、部署支持
v13.1 Highlights
v13.1 重点特性
- aspire mcp init: Configure MCP for AI coding agents
- TLS termination: for YARP, Redis, Keycloak, Vite
WithHttpsCertificate() - Container registry: Experimental
ContainerRegistryResource - Dashboard Parameters tab: Dedicated parameter inspection
- GenAI visualizer: Tool definitions, evaluations, preview media
- Azure Managed Redis: Replaces
AddAzureRedisEnterprise() - DevTunnels stabilized: No longer preview
- aspire mcp init:为AI编码代理配置MCP
- TLS终止:支持YARP、Redis、Keycloak、Vite
WithHttpsCertificate() - 容器注册表:实验性
ContainerRegistryResource - 仪表盘参数标签页:专门的参数检查界面
- 生成式AI可视化工具:工具定义、评估、预览媒体
- Azure托管Redis:替代
AddAzureRedisEnterprise() - DevTunnels稳定版:不再处于预览阶段
Breaking Changes (v9 -> v13)
从v9升级到v13的破坏性变更
| Old API | New API | Notes |
|---|---|---|
| | Removed in v13 |
| Refactored | Different parameter ordering |
| | Package renamed |
| | OpenAI/GitHub models |
| | Milvus/MongoDB/MySQL/Oracle |
Dual-SDK | Single SDK | Optional migration |
| 旧API | 新API | 说明 |
|---|---|---|
| | v13中已移除 |
| 重构 | 参数顺序不同 |
| | 包名已重命名 |
| | 适用于OpenAI/GitHub模型 |
| | 适用于Milvus/MongoDB/MySQL/Oracle |
双SDK格式 | 单SDK格式 | 可选迁移 |
Sorcha AppHost Architecture
Sorcha AppHost 架构
AppHost.cs orchestrates:
postgres ──┬── tenant-db ───── tenant-service
└── wallet-db ───── wallet-service
mongodb ───── register-db ──── register-service
redis ────── (shared by all services)
tenant-service ──── (JWT issuer, auth provider)
blueprint-service ─── (workflow engine)
validator-service ──── wallet-service, register-service, peer-service, blueprint-service
api-gateway ──── (routes to all services, external HTTP)
ui-web ──── api-gateway (Blazor WASM frontend)AppHost.cs 负责编排:
postgres ──┬── tenant-db ───── tenant-service
└── wallet-db ───── wallet-service
mongodb ───── register-db ──── register-service
redis ────── (所有服务共享)
tenant-service ──── (JWT签发者、认证提供者)
blueprint-service ─── (工作流引擎)
validator-service ──── wallet-service, register-service, peer-service, blueprint-service
api-gateway ──── (路由到所有服务,对外提供HTTP访问)
ui-web ──── api-gateway (Blazor WASM前端)Common Patterns
常见模式
Database Resources
数据库资源
csharp
// PostgreSQL with multiple databases
var postgres = builder.AddPostgres("postgres").WithPgAdmin();
var tenantDb = postgres.AddDatabase("tenant-db", "sorcha_tenant");
var walletDb = postgres.AddDatabase("wallet-db", "sorcha_wallet");
// MongoDB for document storage
var mongodb = builder.AddMongoDB("mongodb").WithMongoExpress();
var registerDb = mongodb.AddDatabase("register-db", "sorcha_register");
// Redis for caching
var redis = builder.AddRedis("redis").WithRedisCommander();csharp
// 带有多个数据库的PostgreSQL
var postgres = builder.AddPostgres("postgres").WithPgAdmin();
var tenantDb = postgres.AddDatabase("tenant-db", "sorcha_tenant");
var walletDb = postgres.AddDatabase("wallet-db", "sorcha_wallet");
// 用于文档存储的MongoDB
var mongodb = builder.AddMongoDB("mongodb").WithMongoExpress();
var registerDb = mongodb.AddDatabase("register-db", "sorcha_register");
// 用于缓存的Redis
var redis = builder.AddRedis("redis").WithRedisCommander();Service Dependencies
服务依赖
csharp
// Service references other services for discovery
var validatorService = builder.AddProject<Projects.Sorcha_Validator_Service>("validator-service")
.WithReference(redis)
.WithReference(walletService)
.WithReference(registerService)
.WithReference(peerService)
.WithReference(blueprintService);csharp
// 服务引用其他服务以实现发现
var validatorService = builder.AddProject<Projects.Sorcha_Validator_Service>("validator-service")
.WithReference(redis)
.WithReference(walletService)
.WithReference(registerService)
.WithReference(peerService)
.WithReference(blueprintService);Health Endpoints
健康检查端点
csharp
// ServiceDefaults provides these automatically
app.MapHealthChecks("/health"); // Readiness - all checks
app.MapHealthChecks("/alive", new HealthCheckOptions
{
Predicate = r => r.Tags.Contains("live") // Liveness - tagged checks only
});csharp
// ServiceDefaults自动提供这些端点
app.MapHealthChecks("/health"); // 就绪检查 - 所有检查项
app.MapHealthChecks("/alive", new HealthCheckOptions
{
Predicate = r => r.Tags.Contains("live") // 存活检查 - 仅包含标记为"live"的检查项
});TLS Termination (v13.1+)
TLS终止(v13.1+)
csharp
// Configure HTTPS certificates on containers
var redis = builder.AddRedis("redis")
.WithHttpsCertificate(cert);
// YARP with TLS
var gateway = builder.AddProject<Projects.Sorcha_ApiGateway>("api-gateway")
.WithHttpsCertificate();csharp
// 为容器配置HTTPS证书
var redis = builder.AddRedis("redis")
.WithHttpsCertificate(cert);
// 启用TLS的YARP网关
var gateway = builder.AddProject<Projects.Sorcha_ApiGateway>("api-gateway")
.WithHttpsCertificate();See Also
相关链接
- patterns - AppHost patterns, SDK format, named references, TLS, MCP
- workflows - CLI commands, testing, deployment, troubleshooting
- patterns - AppHost模式、SDK格式、命名引用、TLS、MCP
- workflows - CLI命令、测试、部署、故障排查
Related Skills
相关技能
- See the dotnet skill for .NET 10 patterns
- See the minimal-apis skill for endpoint configuration
- See the redis skill for cache configuration
- See the postgresql skill for database patterns
- See the mongodb skill for document storage
- See the docker skill for containerization
- 查看dotnet技能了解.NET 10模式
- 查看minimal-apis技能了解端点配置
- 查看redis技能了解缓存配置
- 查看postgresql技能了解数据库模式
- 查看mongodb技能了解文档存储
- 查看docker技能了解容器化
Documentation Resources
文档资源
Fetch latest .NET Aspire documentation with Context7.
How to use Context7:
- Use to search for "aspire"
mcp__context7__resolve-library-id - Prefer website documentation (IDs starting with ) over source code repositories when available
/websites/ - Query with using the resolved library ID
mcp__context7__query-docs
Library ID: (High reputation, 3264 code snippets)
/dotnet/docs-aspireRecommended Queries:
- "AppHost service orchestration configuration"
- "service discovery WithReference patterns"
- "OpenTelemetry observability setup"
- "health checks readiness liveness"
- "aspire 13 breaking changes migration"
- "TLS termination WithHttpsCertificate"
- "MCP model context protocol dashboard"
使用Context7获取最新的.NET Aspire文档。
Context7使用方法:
- 使用搜索"aspire"
mcp__context7__resolve-library-id - 优先选择网站文档(ID以开头)而非源代码仓库
/websites/ - 使用解析后的库ID,通过查询文档
mcp__context7__query-docs
库ID: (高可信度,包含3264个代码片段)
/dotnet/docs-aspire推荐查询词:
- "AppHost service orchestration configuration"
- "service discovery WithReference patterns"
- "OpenTelemetry observability setup"
- "health checks readiness liveness"
- "aspire 13 breaking changes migration"
- "TLS termination WithHttpsCertificate"
- "MCP model context protocol dashboard"