数据库集成

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

Aspire 为常见数据库提供托管集成，让您用一行代码就能在本地拉起一个版本固定的数据库容器，并在发布时把它映射为托管服务。

支持的数据库

数据库	托管集成包	添加方法
PostgreSQL	Aspire.Hosting.PostgreSQL	AddPostgres(name)
SQL Server	Aspire.Hosting.SqlServer	AddSqlServer(name)
MySQL	Aspire.Hosting.MySql	AddMySql(name)
MongoDB	Aspire.Hosting.MongoDB	AddMongoDB(name)
Oracle	Aspire.Hosting.Oracle	AddOracle(name)
Cosmos DB	Aspire.Hosting.Azure.CosmosDB	AddAzureCosmosDB(name)
SQLite	Aspire.Hosting.Sqlite	AddSqlite(name)

使用 CLI 添加：

aspire add postgresql

基本用法

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("pg")
    .WithDataVolume()
    .WithPgAdmin();              // 附带一个 pgAdmin 管理界面（开发用）

var catalogDb = postgres.AddDatabase("catalogdb");

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

builder.Build().Run();

要点：

• AddPostgres 创建服务器资源，AddDatabase 在其上创建逻辑数据库子资源。
• .WithDataVolume() 保证数据跨运行保留，但必须同时固定密码，见数据持久化。
• .WithPgAdmin() 会额外启动一个管理界面资源，方便直接查看数据库。
• WithReference(catalogDb) 注入的是指向该数据库的连接字符串。

在服务中消费

EF Core

PostgreSQL

builder.AddNpgsqlDbContext<CatalogContext>("catalogdb");

SQL Server

builder.AddSqlServerDbContext<CatalogContext>("catalogdb");

MySQL

builder.AddMySqlDbContext<CatalogContext>("catalogdb");

MongoDB

builder.AddMongoDBClient("catalogdb");

直接使用 ADO.NET / 原生客户端

// 读取连接字符串
var connectionString = builder.Configuration.GetConnectionString("catalogdb");

// 或者使用客户端集成注册强类型客户端
builder.AddNpgsqlDataSource("catalogdb");

名称必须与 AppHost 一致

客户端注册方法里传的名字，就是 AppHost 中 AddDatabase("catalogdb") 的名字。写错时不会报编译错误，但运行时连接字符串会是 null。

固定镜像版本

生产环境建议固定版本，避免「上周还好好的，今天容器升级了」：

var postgres = builder.AddPostgres("pg")
    .WithImageTag("16.3");

用生命周期钩子跑迁移

数据库容器就绪后再执行迁移，可以彻底消除「应用启动比数据库快」导致的报错：

var postgres = builder.AddPostgres("pg").WithDataVolume();

var catalogDb = postgres.AddDatabase("catalogdb");

var api = builder.AddProject<Projects.Api>("api")
    .WithReference(catalogDb)
    .WaitFor(catalogDb);

postgres.OnResourceReady(async (resource, evt, ct) =>
{
    // 在这里执行 EF Core 迁移或初始化脚本
    await ApplyMigrationsAsync(ct);
});

关于 EF Core 迁移

AppHost 中执行迁移需要能访问到 DbContext 程序集，常见的两种做法：

1. 在 AppHost 中引用数据访问项目，直接调用迁移 API（简单直接）。
2. 在业务服务启动时执行迁移（更贴近生产形态，但要处理好并发）。

无论选哪种，都应配合 WaitFor 使用。

发布与部署

同一个数据库资源在发布时会被翻译成不同的目标：

var postgres = builder.AddAzurePostgresFlexibleServer("pg")
    .RunAsContainer();           // 本地以容器运行，发布时使用 Azure Database for PostgreSQL

目标平台	映射结果
Docker Compose	数据库容器 + 持久卷。
Kubernetes	StatefulSet / 容器 + PersistentVolume。
Azure Container Apps	Azure Database for PostgreSQL（或托管服务）。

如果生产数据库是已有的外部实例，可以在发布模式下改用连接字符串：

IResourceBuilder<IResourceWithConnectionString> db = builder.ExecutionContext.IsRunMode
    ? builder.AddPostgres("pg").AddDatabase("catalogdb")
    : builder.AddConnectionString("catalogdb");

下一步

• 缓存集成
• 数据持久化
• 部署总览