集成简介

更新: 2026-10-16 15:20:09   字数: 0 字   时长: 0 分钟

什么是 Aspire 集成？

Aspire 集成是 AppHost 包，用于添加定义应用所依赖资源的 API，例如数据库、缓存、消息系统和云服务。

集成告诉 Aspire 如何在您的应用模型中创建、连接并传递资源的连接信息。集成可以：

• 在本地启动一个资源（典型做法：启动容器）。
• 创建或连接云资源。
• 指向已有服务，例如您本机已经装好的 SQL Server。

在 AppHost 中，集成向 IDistributedApplicationBuilder 添加方法，让您可以在应用模型里描述这些资源。

两类包，不要混淆

类型	装在哪里	例子	作用
托管集成（Hosting）	AppHost 项目	Aspire.Hosting.PostgreSQL、Aspire.Hosting.Redis	在应用模型中定义资源。
客户端集成（Client）	业务服务项目	Aspire.Npgsql.EntityFrameworkCore.PostgreSQL、Aspire.StackExchange.Redis	在业务代码中消费资源。

最常见的错误

把 Aspire.Hosting.* 装到业务服务项目里，或者把客户端集成装到 AppHost 里。前者会让服务意外依赖编排能力，后者则完全不起作用。

添加集成

推荐使用 CLI：

aspire add postgresql

它会在 AppHost 项目中添加包引用（项目型 C# AppHost）、#:package 指令（文件型 C# AppHost）或 aspire.config.json 的 packages 条目（TypeScript AppHost），并把变更持久化。

也可以手工添加 NuGet 包引用，效果等价。

官方包的目标分类

官方 Aspire 包会标注为以下几类之一：

• Target：产品本身。
• Integration：集成包。
• Hosting：托管能力包。

除此之外，社区贡献的集成集中在 Community Toolkit 中，详见社区工具包。

能连接什么

类别	代表	文档
数据库	PostgreSQL、SQL Server、MySQL、MongoDB、Oracle、Cosmos DB、SQLite	数据库集成
缓存	Redis、Valkey、Garnet	缓存集成
消息与事件	RabbitMQ、Azure Service Bus、Kafka、NATS	消息与事件集成
云服务	Azure、AWS、GCP（存储、AI、搜索、身份，支持本地模拟器）	云服务集成
可观测性	OpenTelemetry、Seq、Grafana	遥测与 OpenTelemetry
框架与运行时	Node.js、Python、Go、Java、反向代理等	多语言架构

完整的 150+ 集成清单可在集成画廊中按名称、标签或类别检索。

一个完整的集成示例

AppHost（托管侧）

var builder = DistributedApplication.CreateBuilder(args);

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

builder.AddProject<Projects.Api>("api")
    .WithReference(cache)
    .WithReference(db)
    .WithHttpHealthCheck("/health");

builder.Build().Run();

ApiService（客户端侧）

var builder = WebApplication.CreateBuilder(args);

builder.AddServiceDefaults();
builder.AddRedisClient("cache");
builder.AddNpgsqlDbContext<CatalogContext>("catalogdb");

var app = builder.Build();
app.MapDefaultEndpoints();
app.Run();

注意两侧使用的名称完全一致（cache、catalogdb）——这就是集成之间「接头」的方式。

下一步

• 数据库集成
• 缓存集成
• 编写自定义集成