.NET Aspire PostgreSQL 集成

项目
12/13/2024

PostgreSQL 是一个强大的开源对象关系数据库系统，经过多年的积极开发，它赢得了可靠性、功能稳定性和性能的强烈声誉。 .NET Aspire PostgreSQL 集成提供了一种方式，可连接到现有的 PostgreSQL 数据库，或使用 docker.io/library/postgres 容器映像从 .NET 创建新实例。

托管集成

托管集成 PostgreSQL 将 PostgreSQLserver 建模为 PostgresServerResource 类型。若要访问此类型和 API，可将其添加到 📦Aspire的 .Hosting.PostgreSQL NuGet 包中，在应用主机项目中。

.NET 命令行界面
PackageReference

dotnet add package Aspire.Hosting.PostgreSQL

<PackageReference Include="Aspire.Hosting.PostgreSQL"
                  Version="*" />

有关详细信息，请参阅 dotnet add package 或管理 .NET 应用程序中的包依赖性。

添加 PostgreSQLserver 资源

在应用主机项目中，对 builder 实例调用 AddPostgres 以添加 PostgreSQLserver 资源，然后在 postgres 实例上调用 AddDatabase 以添加数据库资源，如以下示例所示：

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres");
var postgresdb = postgres.AddDatabase("postgresdb");

var exampleProject = builder.AddProject<Projects.ExampleProject>()
                            .WithReference(postgresdb);

// After adding all resources, run the app...

当 .NET.NET Aspire 向应用主机添加容器映像时，如前面的 docker.io/library/postgres 映像所示，它会在本地计算机上创建一个新的 PostgreSQLserver 实例。引用您的 PostgreSQLserver 和您的 PostgreSQL 数据库实例（即 postgresdb 变量）被用于向 ExampleProject添加依赖项。 PostgreSQL server 资源包括默认凭据，这些凭据具有 username 为 "postgres"，并使用 CreateDefaultPasswordParameter 方法随机生成 password。

WithReference 方法在名为 "messaging"的 ExampleProject 中配置连接。有关详细信息，请参阅容器资源生命周期。

提示

如果想要连接到现有 PostgreSQLserver，请改为拨打 AddConnectionString。有关详细信息，请参阅引用现有资源。

添加 PostgreSQL pgAdmin 资源

使用 AddPostgres 方法将 PostgreSQL 资源添加到 builder 时，可以链接调用 WithPgAdmin 以添加 dpage/pgadmin4 容器。此容器是一个跨平台的 client，适用于 PostgreSQL 数据库，并提供基于 Web 的管理仪表板。请考虑以下示例：

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres")
                      .WithPgAdmin();

var postgresdb = postgres.AddDatabase("postgresdb");

var exampleProject = builder.AddProject<Projects.ExampleProject>()
                            .WithReference(postgresdb);

// After adding all resources, run the app...

前面的代码基于 docker.io/dpage/pgadmin4 镜像添加了一个容器。容器用于管理 PostgreSQLserver 和数据库资源。 WithPgAdmin 方法添加一个容器，该容器为 PostgreSQL 数据库提供基于 Web 的管理仪表板。

添加 PostgreSQL pgWeb 资源

使用 AddPostgres 方法将 PostgreSQL 资源添加到 builder 时，可以通过链式调用 WithPgWeb 以添加 sosedoff/pgweb 容器。此容器是跨平台的 client，用于 PostgreSQL 数据库，提供网页管理仪表板。请考虑以下示例：

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres")
                      .WithPgWeb();

var postgresdb = postgres.AddDatabase("postgresdb");

var exampleProject = builder.AddProject<Projects.ExampleProject>()
                            .WithReference(postgresdb);

// After adding all resources, run the app...

前面的代码基于 docker.io/sosedoff/pgweb 镜像添加容器。所有已注册的 PostgresDatabaseResource 实例都用于为每个实例创建配置文件，每个配置都绑定到 pgweb 容器书签目录。有关详细信息，请参阅 PgWeb 文档：Server 连接书签。

使用数据卷添加 PostgreSQLserver 资源

若要将数据卷添加到 PostgreSQLserver 资源，请在 PostgreSQLserver 资源上调用 WithDataVolume 方法：

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres")
                      .WithDataVolume(isReadOnly: false);

var postgresdb = postgres.AddDatabase("postgresdb");

var exampleProject = builder.AddProject<Projects.ExampleProject>()
                            .WithReference(postgresdb);

// After adding all resources, run the app...

数据卷用于在容器的生命周期之外保留 PostgreSQLserver 数据。数据卷装载在 PostgreSQLserver 容器中的 /var/lib/postgresql/data 路径上，如果未提供 name 参数，则会随机生成名称。有关数据卷的详细信息，以及它们为何优先于绑定装载的详细信息，请参阅 Docker 文档：卷。

使用数据绑定装载添加 PostgreSQLserver 资源

若要将数据绑定挂载添加到 PostgreSQLserver 资源，请调用 WithDataBindMount 方法：

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres")
                      .WithDataBindMount(
                          source: @"C:\PostgreSQL\Data",
                          isReadOnly: false);

var postgresdb = postgres.AddDatabase("postgresdb");

var exampleProject = builder.AddProject<Projects.ExampleProject>()
                            .WithReference(postgresdb);

// After adding all resources, run the app...

重要

与卷相比，绑定装载的数据功能有限，从而提供更好的性能、可移植性和安全性，使它们更适用于生产环境。但是，绑定装载允许直接访问和修改主机系统上的文件，非常适合在需要实时更改的情况下进行开发和测试。

数据绑定挂载依赖主机文件系统在容器重启期间保留 PostgreSQLserver 数据。数据绑定装载在 Windows 主机中的 PostgreSQLserver 容器的 C:\PostgreSQL\Data 路径（或 Unix上的 /PostgreSQL/Data）被挂载。有关数据绑定装载的详细信息，请参阅 Docker 文档：绑定装载。

使用初始化绑定挂载来添加 PostgreSQLserver 资源

若要将 init 绑定装载添加到 PostgreSQLserver 资源，请调用 WithInitBindMount 方法：

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres")
                      .WithInitBindMount(@"C:\PostgreSQL\Init");

var postgresdb = postgres.AddDatabase("postgresdb");

var exampleProject = builder.AddProject<Projects.ExampleProject>()
                            .WithReference(postgresdb);

// After adding all resources, run the app...

init 绑定装载依赖于主机的文件系统，使用容器 init 文件夹初始化 PostgreSQLserver 数据库。创建 postgres-data 文件夹后，此文件夹用于初始化、运行任何可执行 shell 脚本或 .sql 命令文件。 init 绑定装载安装在 windows 上的 C:\PostgreSQL\Init（或 Unix上的 /PostgreSQL/Init）路径上的 PostgreSQLserver 容器中的主机上。

添加带参数的 PostgreSQLserver 资源

如果要显式提供容器映像使用的用户名和密码，可以将这些凭据作为参数提供。请考虑以下替代示例：

var builder = DistributedApplication.CreateBuilder(args);

var username = builder.AddParameter("username", secret: true);
var password = builder.AddParameter("password", secret: true);

var postgres = builder.AddPostgres("postgres", username, password);
var postgresdb = postgres.AddDatabase("postgresdb");

var exampleProject = builder.AddProject<Projects.ExampleProject>()
                            .WithReference(postgresdb);

// After adding all resources, run the app...

有关提供参数的详细信息，请参阅外部参数。

托管集成运行状况检查

托管集成 PostgreSQL 会自动为 PostgreSQLserver 资源添加运行状况检查。运行状况检查会验证 PostgreSQLserver 是否正在运行，并且确认是否可以建立连接。

托管集成依赖于 📦 AspNetCore.HealthChecks.Npgsql NuGet 包。

Client 集成

若要开始 .NET AspirePostgreSQLclient 集成，请安装 📦Aspire。npgsql 使用 client项目中的 NuGet 包，即使用 PostgreSQLclient的应用程序的项目。 PostgreSQL client 整合会注册一个 NpgsqlDataSource 实例，该实例可用于与 PostgreSQL进行交互。

.NET CLI
PackageReference

dotnet add package Aspire.Npgsql

<PackageReference Include="Aspire.Npgsql" Version="*" />

添加 Npgsql client

在 client消耗项目的 Program.cs 文件中，对任何 IHostApplicationBuilder 调用 AddNpgsqlDataSource 扩展方法，以注册 NpgsqlDataSource，以便通过依赖项注入容器使用。该方法采用连接名称参数。

builder.AddNpgsqlDataSource(connectionName: "postgresdb");

提示

connectionName 参数必须与在应用主机项目中添加 PostgreSQLserver 资源时使用的名称匹配。有关详细信息，请参阅添加 PostgreSQLserver 资源。

将 NpgsqlDataSource 添加到生成器后，可以使用依赖项注入获取 NpgsqlDataSource 实例。例如，若要从示例服务中检索数据源对象，请将其定义为构造函数参数，并确保 ExampleService 类注册到依赖项注入容器：

public class ExampleService(NpgsqlDataSource dataSource)
{
    // Use dataSource...
}

有关依赖项注入的详细信息，请参阅 .NET 依赖项注入。

添加密钥 Npgsql client

在某些情况下，可能需要使用不同的连接名称注册多个 NpgsqlDataSource 实例。若要注册密钥 Npgsql 客户端，请调用 AddKeyedNpgsqlDataSource 方法：

builder.AddKeyedNpgsqlDataSource(name: "chat");
builder.AddKeyedNpgsqlDataSource(name: "queue");

然后，可以使用依赖项注入检索 NpgsqlDataSource 实例。例如，若要从示例服务检索连接，

public class ExampleService(
    [FromKeyedServices("chat")] NpgsqlDataSource chatDataSource,
    [FromKeyedServices("queue")] NpgsqlDataSource queueDataSource)
{
    // Use data sources...
}

有关密钥服务的详细信息，请参阅 .NET 依赖项注入：键式服务。

配置

.NET Aspire PostgreSQL 集成提供了多种配置方法和选项，以满足项目的要求和约定。

使用连接字符串

使用 ConnectionStrings 配置部分中的连接字符串时，可以在调用 AddNpgsqlDataSource 方法时提供连接字符串的名称：

builder.AddNpgsqlDataSource("postgresdb");

然后，将从 ConnectionStrings 配置部分检索连接字符串：

{
  "ConnectionStrings": {
    "postgresdb": "Host=myserver;Database=postgresdb"
  }
}

有关详细信息，请参阅 ConnectionString。

使用配置提供程序

.NET Aspire PostgreSQL 集成支持 Microsoft.Extensions.Configuration。它通过使用 Aspire:Npgsql 密钥从 appsettings.json 或其他配置文件加载 NpgsqlSettings。配置某些选项的示例 appsettings.json：

以下示例显示了一个 appsettings.json 文件，该文件配置了一些可用选项：

{
  "Aspire": {
    "Npgsql": {
      "ConnectionString": "Host=myserver;Database=postgresdb",
      "DisableHealthChecks": false,
      "DisableTracing": true,
      "DisableMetrics": false
    }
  }
}

有关完整的 PostgreSQLclient 集成 JSON 架构，请参阅 Aspire。Npgsql/ConfigurationSchema。json。

使用内联委托

您还可以传递 Action<NpgsqlSettings> configureSettings 委托来直接设置某些或所有选项，例如禁用健康检查：

builder.AddNpgsqlDataSource(
    "postgresdb",
     static settings => settings.DisableHealthChecks = true);

运行状况检查

默认情况下，.NET.NET Aspire 集成为所有服务启用健康检查。有关详细信息，请参阅 .NET.NET Aspire 集成概述。

将 NpgSqlHealthCheck添加到系统中，该 NpgSqlHealthCheck用于验证是否可以成功对底层 Postgres 数据库执行命令。
与 /health HTTP 端点集成，该端点要求所有已注册的健康检查都必须通过，应用才能被视为准备好接受流量。

可观测性和遥测

.NET .NET Aspire 集成会自动设置日志记录、跟踪和指标配置，这些配置有时称为 可观测性的支柱。有关集成可观测性和遥测的详细信息，请参阅 .NET.NET Aspire 集成概述。根据支持服务，某些集成可能仅支持其中一些功能。例如，某些集成支持日志记录和跟踪，但不支持指标。也可以使用配置部分中介绍的技术禁用遥测功能。

伐木

.NET Aspire PostgreSQL 集成使用以下日志类别：

Npgsql.Connection
Npgsql.Command
Npgsql.Transaction
Npgsql.Copy
Npgsql.Replication
Npgsql.Exception

描图

.NET Aspire PostgreSQL 集成将使用 OpenTelemetry发出以下跟踪活动：

Npgsql

指标

.NET Aspire PostgreSQL 集成将通过 OpenTelemetry发出以下指标：

Npgsql：
- ec_Npgsql_bytes_written_per_second
- ec_Npgsql_bytes_read_per_second
- ec_Npgsql_commands_per_second
- ec_Npgsql_total_commands
- ec_Npgsql_current_commands
- ec_Npgsql_failed_commands
- ec_Npgsql_prepared_commands_ratio
- ec_Npgsql_connection_pools
- ec_Npgsql_multiplexing_average_commands_per_batch
- ec_Npgsql_multiplexing_average_write_time_per_batch

Azure PostgreSQL 托管集成

若要将 PostgreSQL 资源部署到 Azure，请安装 📦Aspire托管Azure.PostgreSQL NuGet 包：

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.Azure.PostgreSQL

<PackageReference Include="Aspire.Hosting.Azure.PostgreSQL"
                  Version="*" />

添加 AzurePostgreSQLserver 资源

安装 .NET AspireAzurePostgreSQL 托管集成后，请在应用主机项目中调用 AddAzurePostgresFlexibleServer 扩展方法：

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddAzurePostgresFlexibleServer("postgres");
var postgresdb = postgres.AddDatabase("postgresdb");

var exampleProject = builder.AddProject<Projects.ExampleProject>()
                            .WithReference(postgresdb);

上述调用 AddAzurePostgresFlexibleServer 将 PostgresSQL server 资源配置为 AzurePostgres 灵活 Server。

重要

默认情况下，AddAzurePostgresFlexibleServer 配置 Microsoft Entra ID 身份验证。这需要更改需要连接到这些资源的应用程序。有关详细信息，请参阅 Client 集成。

添加经过身份验证的 Npgsql Azureclient

默认情况下，在 PostgreSQL 托管集成中调用 AddAzurePostgresFlexibleServer 时，它会配置 📦Azure标识 NuGet 包来启用身份验证：

.NET CLI
PackageReference

dotnet add package Azure.Identity

<PackageReference Include="Azure.Identity"
                  Version="*" />

可以通过 client 集成和 Azure.Identity来消耗 PostgreSQL 连接。

builder.AddNpgsqlDataSource(
    "postgresdb", 
    configureDataSourceBuilder: (dataSourceBuilder) =>
{
    if (!string.IsNullOrEmpty(dataSourceBuilder.ConnectionStringBuilder.Password))
    {
        return;
    }

    dataSourceBuilder.UsePeriodicPasswordProvider(async (_, ct) =>
    {
        var credentials = new DefaultAzureCredential();
        var token = await credentials.GetTokenAsync(
            new TokenRequestContext([
                "https://ossrdbms-aad.database.windows.net/.default"
            ]), ct);

        return token.Token;
    },
    TimeSpan.FromHours(24),
    TimeSpan.FromSeconds(10));
});

前面的代码片段演示如何使用 Azure.Identity 包中的 DefaultAzureCredential 类通过 Microsoft Entra ID 进行身份验证，并检索用于连接到 PostgreSQL 数据库的令牌。 UsePeriodicPasswordProvider 方法用于向连接字符串生成器提供令牌。

通过