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 (
src/Apps/Sorcha.AppHost/AppHost.cs
) orchestrates 7 microservices with PostgreSQL, MongoDB, and Redis. Services use
AddServiceDefaults()
for consistent OpenTelemetry, health checks, and service discovery. JWT signing keys are generated once and shared across all services via environment variables.
.NET Aspire 13.x 为该分布式账本平台提供编排能力。AppHost(路径:
src/Apps/Sorcha.AppHost/AppHost.cs
)负责编排7个微服务,并集成了PostgreSQL、MongoDB和Redis。服务通过
AddServiceDefaults()
来统一配置OpenTelemetry、健康检查和服务发现功能。JWT签名密钥仅生成一次,并通过环境变量在所有服务之间共享。

Version Info

版本信息

ComponentVersionNotes
Aspire.AppHost.Sdk13.0.0SDK in
.csproj
— legacy dual-SDK format
Aspire.Hosting.*13.1.0AppHost hosting packages
Aspire.StackExchange.Redis13.1.0Service-level Redis integration
Aspire.Hosting.Testing13.1.0Integration/E2E test infrastructure
Aspire Dashboard9.0.0Docker 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.Sdk13.0.0
.csproj
中的SDK — 旧版双SDK格式
Aspire.Hosting.*13.1.0AppHost托管包
Aspire.StackExchange.Redis13.1.0服务级Redis集成包
Aspire.Hosting.Testing13.1.0集成/端到端测试基础设施
Aspire Dashboard9.0.0Docker镜像(版本独立管理)
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 config
csharp
// 在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-db
csharp
// 控制资源引用的环境变量前缀
var myService = builder.AddProject<Projects.Sorcha_MyService>("my-service")
    .WithReference(postgres.AddDatabase("mydb"), "primary-db");  // 对应环境变量ConnectionStrings__primary-db

Consuming 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 /alive
csharp
// 在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

核心概念

ConceptUsageExample
Resource NameIdentifier for service discovery
"redis"
,
"tenant-service"
WithReferenceInjects connection string/URL
.WithReference(postgres)
Named ReferenceCustom env var prefix (v13+)
.WithReference(db, "mydb")
WithEnvironmentPass config to service
.WithEnvironment("Key", value)
WithExternalHttpEndpointsExpose outside Aspire network
.WithExternalHttpEndpoints()
AddServiceDefaultsShared Aspire configuration
builder.AddServiceDefaults()
Connection PropertiesAccess individual fields (v13+)
resource.GetConnectionProperty("HostName")
WithHttpsCertificateTLS termination (v13.1+)
.WithHttpsCertificate(cert)
ContainerRegistryResourceRegistry config (v13.1+ exp.)
builder.AddContainerRegistry(...)
概念用途示例
资源名称服务发现的标识符
"redis"
,
"tenant-service"
WithReference注入连接字符串/URL
.WithReference(postgres)
命名引用自定义环境变量前缀(v13+)
.WithReference(db, "mydb")
WithEnvironment向服务传递配置
.WithEnvironment("Key", value)
WithExternalHttpEndpoints暴露到Aspire网络外部
.WithExternalHttpEndpoints()
AddServiceDefaults配置共享的Aspire默认项
builder.AddServiceDefaults()
连接属性访问单个字段(v13+)
resource.GetConnectionProperty("HostName")
WithHttpsCertificateTLS终止(v13.1+)
.WithHttpsCertificate(cert)
ContainerRegistryResource容器注册表配置(v13.1+ 实验性)
builder.AddContainerRegistry(...)

What's New in Aspire 13.x

.NET Aspire 13.x 新特性

v13.0 Highlights

v13.0 重点特性

  • New SDK format: Single
    <Project Sdk="Aspire.AppHost.Sdk/13.0.0">
    replaces dual-SDK
  • Polyglot connections: Resources expose
    HostName
    ,
    Port
    ,
    JdbcConnectionString
  • Named references:
    WithReference(resource, "customName")
    for env var prefixes
  • MCP dashboard: Aspire dashboard exposes MCP endpoints for AI assistants
  • Container file artifacts:
    PublishWithContainerFiles()
    for frontend-in-backend
  • Pipeline system:
    aspire do
    for coordinated build/publish/deploy
  • aspire init: Interactive solution initialization and discovery
  • VS Code extension: Native project creation, debugging, deployment
  • 新SDK格式:单个
    <Project Sdk="Aspire.AppHost.Sdk/13.0.0">
    替代双SDK格式
  • 多语言连接:资源暴露
    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:
    WithHttpsCertificate()
    for YARP, Redis, Keycloak, Vite
  • 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终止
    WithHttpsCertificate()
    支持YARP、Redis、Keycloak、Vite
  • 容器注册表:实验性
    ContainerRegistryResource
  • 仪表盘参数标签页:专门的参数检查界面
  • 生成式AI可视化工具:工具定义、评估、预览媒体
  • Azure托管Redis:替代
    AddAzureRedisEnterprise()
  • DevTunnels稳定版:不再处于预览阶段

Breaking Changes (v9 -> v13)

从v9升级到v13的破坏性变更

Old APINew APINotes
AddNpmApp()
AddJavaScriptApp()
Removed in v13
AddNodeApp()
RefactoredDifferent parameter ordering
Aspire.Hosting.NodeJs
Aspire.Hosting.JavaScript
Package renamed
.Model
property
.ModelName
OpenAI/GitHub models
.Database
property
.DatabaseName
Milvus/MongoDB/MySQL/Oracle
Dual-SDK
.csproj
Single SDK
.csproj
Optional migration
旧API新API说明
AddNpmApp()
AddJavaScriptApp()
v13中已移除
AddNodeApp()
重构参数顺序不同
Aspire.Hosting.NodeJs
Aspire.Hosting.JavaScript
包名已重命名
.Model
属性
.ModelName
适用于OpenAI/GitHub模型
.Database
属性
.DatabaseName
适用于Milvus/MongoDB/MySQL/Oracle
双SDK格式
.csproj
单SDK格式
.csproj
可选迁移

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:
  1. Use
    mcp__context7__resolve-library-id
    to search for "aspire"
  2. Prefer website documentation (IDs starting with
    /websites/
    ) over source code repositories when available
  3. Query with
    mcp__context7__query-docs
    using the resolved library ID
Library ID:
/dotnet/docs-aspire
(High reputation, 3264 code snippets)
Recommended 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使用方法:
  1. 使用
    mcp__context7__resolve-library-id
    搜索"aspire"
  2. 优先选择网站文档(ID以
    /websites/
    开头)而非源代码仓库
  3. 使用解析后的库ID,通过
    mcp__context7__query-docs
    查询文档
库ID:
/dotnet/docs-aspire
(高可信度,包含3264个代码片段)
推荐查询词:
  • "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"