.NET Aspire PostgreSQL 整合

發行項
01/31/2025

PostgreSQL 是一個強大的開放原始碼對象關係資料庫系統，具有多年的積極開發，因此其可靠性、功能強固性和效能享有盛譽。 .NET Aspire PostgreSQL 整合可讓您連線到現有的 PostgreSQL 資料庫，或使用 .NET從 docker.io/library/postgres 建立新的實例。

託管整合

PostgreSQL 託管整合模型將各種 PostgreSQL 資源建模為如下類型。

若要存取這些類型和 API，以在應用程式主機專案中將其表示為資源，請安裝 📦Aspire.Hosting.PostgreSQL NuGet 套件：

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.PostgreSQL

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

如需詳細資訊，請參閱 dotnet add package 或在 .NET 應用程式中管理套件相依性。

新增 PostgreSQL 伺服器資源

在應用程式主機專案中，呼叫 AddPostgres 實例上的 builder 以新增 PostgreSQL 伺服器資源，然後在 AddDatabase 實例上呼叫 postgres，以新增資料庫資源，如下列範例所示：

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 映像所示，它會在本機計算機上建立新的 PostgreSQL 伺服器實例。 PostgreSQL 伺服器和 PostgreSQL 資料庫實例的參考（postgresdb 變數）可用來將相依性新增至 ExampleProject。 PostgreSQL 伺服器資源包括默認認證，其 username 是 "postgres"，並使用 password 方法隨機生成 CreateDefaultPasswordParameter。

WithReference 方法會在名為 ExampleProject的 "messaging" 中設定連接。如需詳細資訊，請參閱容器資源生命週期。

提示

如果您想要連線到現有的 PostgreSQL 伺服器，請改為呼叫 AddConnectionString。如需詳細資訊，請參閱參考現有資源。

新增 PostgreSQL pgAdmin 資源

使用 PostgreSQL 方法將 builder 資源新增至 AddPostgres 時，您可以將呼叫鏈結至 WithPgAdmin 以新增 dpage/pgadmin4 容器。此容器是適用於 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 映像新增容器。容器可用來管理 PostgreSQL 伺服器和資料庫資源。 WithPgAdmin 方法用於新增容器，提供 PostgreSQL 資料庫的網頁式管理儀表板。

設定 pgAdmin 主機埠

若要設定 pgAdmin 容器的主機埠，請在 PostgreSQL 伺服器資源上呼叫 WithHostPort 方法。下列範例示範如何設定 pgAdmin 容器的主機埠：

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres")
                      .WithPgAdmin(pgAdmin => pgAdmin.WithHostPort(5050));

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

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

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

上述程式代碼會新增並設定 pgAdmin 容器的主機埠。否則會隨機指派主機端口。

新增 PostgreSQL pgWeb 資源

使用 PostgreSQL 方法將 builder 資源新增至 AddPostgres 時，您可以將呼叫鏈結至 WithPgWeb 以新增 sosedoff/pgweb 容器。此容器是適用於 PostgreSQL 資料庫的跨平臺用戶端，可提供 Web 型系統管理員儀錶板。請考慮下列範例：

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 連線書籤。

設定 pgWeb 主機埠

若要設定 pgWeb 容器的主機埠，請在 PostgreSQL 伺服器資源上呼叫 WithHostPort 方法。下列範例示範如何設定 pgAdmin 容器的主機埠：

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres")
                      .WithPgAdmin(pgWeb => pgWeb.WithHostPort(5050));

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

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

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

上述程式代碼會新增並設定 pgWeb 容器的主機埠。如無其他指定，將會隨機指派主機埠。

新增具備資料量的 PostgreSQL 伺服器資源

若要將數據磁碟區新增至 PostgreSQL 伺服器資源，請在 WithDataVolume 伺服器資源上呼叫 PostgreSQL 方法：

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...

數據磁碟區用來將 PostgreSQL 伺服器數據保存在其容器生命週期之外。數據磁碟區會掛接在 /var/lib/postgresql/data 伺服器容器的 PostgreSQL 路徑，若未提供 name 參數，則會隨機生成名稱。如需有關資料卷的詳細資訊，以及為何相較於系結掛接更受到偏好的原因，請參閱 Docker 文件：卷。

使用數據系結掛接新增 PostgreSQL 伺服器資源

若要將數據系結掛接新增至 PostgreSQL 伺服器資源，請呼叫 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...

重要

相較於磁碟區，數據系結掛接的功能有限，可提供更佳的效能、可移植性和安全性，使其更適合生產環境。不過，系結掛接允許直接存取和修改主機系統上的檔案，非常適合用於開發和測試需要即時變更的場景。

數據系結掛接依賴主計算機的檔案系統，在容器重新啟動時保存 PostgreSQL 伺服器數據。數據掛載會被掛載到 C:\PostgreSQL\Data 伺服器容器中主電腦的 Windows 中的 /PostgreSQL/Data 路徑上（或 Unix 上的 PostgreSQL路徑上）。如需資料系結掛接的詳細資訊，請參閱 Docker 檔：系結掛接。

使用 init 綁定掛載新增 PostgreSQL 伺服器資源

若要將 init 系結掛接新增至 PostgreSQL 伺服器資源，請呼叫 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 系結掛接依賴主計算機的檔案系統，以容器 PostgreSQL 資料夾初始化伺服器資料庫。建立 postgres-data 資料夾之後，此資料夾會用於初始化、執行任何可執行的殼層腳本或 .sql 命令檔案。 init 系結掛接會掛接在 C:\PostgreSQL\Init 伺服器容器中主電腦上的 /PostgreSQL/Init 上（或 Unix上 PostgreSQL）。

使用參數新增 PostgreSQL 伺服器資源

當您想要明確提供容器映像所使用的使用者名稱和密碼時，您可以提供這些認證做為參數。請考慮下列替代範例：

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 會自動為 PostgreSQL 伺服器資源新增健康檢查。健康檢查會確認 PostgreSQL 伺服器正在運行，而且可以建立連線。

主機整合依賴 📦 AspNetCore.HealthChecks.Npgsql NuGet 套件。

Client 整合

若要開始使用 .NET AspirePostgreSQL 用戶端整合，請在取用 📦 用戶端的應用程式專案中安裝 PostgreSQL NuGet 套件。 PostgreSQL 用戶端整合會註冊 NpgsqlDataSource 實例，您可用來與 PostgreSQL互動。

.NET CLI
PackageReference

dotnet add package Aspire.Npgsql

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

新增 Npgsql 用戶端

在您的客戶端消費專案的 Program.cs 檔案中，呼叫任何 AddNpgsqlDataSource 上的 IHostApplicationBuilder 擴充方法，以便註冊 NpgsqlDataSource，以供相依性注入容器使用。方法會採用連接名稱參數。

builder.AddNpgsqlDataSource(connectionName: "postgresdb");

提示

connectionName 參數必須符合在應用程式主專案中新增 PostgreSQL 伺服器資源時所使用的名稱。如需詳細資訊，請參閱新增 PostgreSQL 伺服器資源。

將 NpgsqlDataSource 新增至產生器之後，您可以使用相依性插入取得 NpgsqlDataSource 實例。例如，若要從範例服務擷取數據源物件，請將其定義為建構函式參數，並確定已向相依性插入容器註冊 ExampleService 類別：

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

如需相依性插入的詳細資訊，請參閱 .NET 相依性插入。

新增具有鍵控功能的 Npgsql 用戶端

在某些情況下，您可能想要以不同的連線名稱註冊多個 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。它會使用 NpgsqlSettings 金鑰，從 appsettings.json 或其他組態檔載入 Aspire:Npgsql。設定部分選項的範例 appsettings.json：

下列範例顯示 appsettings.json 檔案，可設定一些可用的選項：

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

如需完整的 PostgreSQL 用戶端整合 JSON 架構，請參閱 Aspire。Npgsql/ConfigurationSchema.json。

使用內嵌委派

您也可以傳遞 Action<NpgsqlSettings> configureSettings 委託來內嵌設定部分或全部選項，例如停用健康檢查：

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

健康檢查

根據預設，.NET.NET Aspire 整合會為所有服務啟用健康檢查。如需詳細資訊，請參閱 .NET.NET Aspire 整合概觀。

新增 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

共用方式為