.NET Aspire PostgreSQL Entity Framework Core 整合

包括：主機整合 和 Client 整合

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

託管整合

PostgreSQL 裝載整合模型將各種 PostgreSQL 資源歸類為以下類型。

• PostgresServerResource
• PostgresDatabaseResource
• PgAdminContainerResource
• PgWebContainerResource

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

.NET 命令行界面

dotnet add package Aspire.Hosting.PostgreSQL

PackageReference

<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 容器的主機埠，請在 WithHostPort 伺服器資源上呼叫 PostgreSQL 方法。 下列範例示範如何設定 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 容器的主機埠，請在 WithHostPort 伺服器資源上呼叫 PostgreSQL 方法。 下列範例示範如何設定 pgAdmin 容器的主機埠：

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres")
                      .WithPgWeb(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 AspirePostgreSQLEntity Framework Core 用戶端整合，請在使用 📦 用戶端的應用程式專案中，安裝 PostgreSQL NuGet 套件。 .NET Aspire PostgreSQL Entity Framework Core 用戶端整合會註冊您想要的 DbContext 子類別實例，讓您可用來與 PostgreSQL互動。

.NET 命令行界面

dotnet add package Aspire.Npgsql.EntityFrameworkCore.PostgreSQL

PackageReference

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

新增 Npgsql 資料庫環境

在用戶端取用專案的 Program.cs 檔案中，在任何 AddNpgsqlDbContext 上呼叫 IHostApplicationBuilder 擴充方法，以註冊您的 DbContext 子類別，以透過相依性插入容器使用。 方法會採用連接名稱參數。

builder.AddNpgsqlDbContext<YourDbContext>(connectionName: "postgresdb");

提示

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

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

public class ExampleService(YourDbContext context)
{
    // Use context...
}

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

擴充 Npgsql 資料庫內容

您可能偏好使用標準 Entity Framework 方法來取得資料庫內容，並將它新增至相依性插入容器：

builder.Services.AddDbContext<YourDbContext>(options =>
    options.UseNpgsql(builder.Configuration.GetConnectionString("postgresdb")
        ?? throw new InvalidOperationException("Connection string 'postgresdb' not found.")));

備註

您傳遞給 GetConnectionString 方法的連接字串名稱必須符合在應用程式主專案中新增 PostgreSQL 伺服器資源時所使用的名稱。 如需詳細資訊，請參閱 新增 PostgreSQL 伺服器資源。

當您以這種方式建立資料庫內容時，更有彈性，例如：

• 您可以重複使用資料庫內容的現有組態程式代碼，而不需將它重寫為 .NET.NET Aspire。
• 您可以使用 Entity Framework Core 攔截器來修改資料庫作業。
• 您可以選擇不使用 Entity Framework Core 上下文池化，在某些情況下可能會有更好的表現。

如果您使用此方法，您可以呼叫 .NET 方法，透過 .NET AspireEnrichNpgsqlDbContext樣式重試、健康情況檢查、記錄和遙測功能來增強資料庫內容：

builder.EnrichNpgsqlDbContext<YourDbContext>(
    configureSettings: settings =>
    {
        settings.DisableRetry = false;
        settings.CommandTimeout = 30;
    });

settings 參數是 NpgsqlEntityFrameworkCorePostgreSQLSettings 類別的實例。

配置

.NET Aspire PostgreSQL Entity Framework Core 整合提供多個組態方法和選項，以符合專案的需求和慣例。

使用連接字串

從 [ConnectionStrings 組態] 區段使用連接字串時，您可以在呼叫 AddNpgsqlDbContext 方法時提供連接字串的名稱：

builder.AddNpgsqlDbContext<MyDbContext>("pgdb");

連接字串是從組態區段 ConnectionStrings 擷取：

{
  "ConnectionStrings": {
    "pgdb": "Host=myserver;Database=test"
  }
}

EnrichNpgsqlDbContext 不會使用 ConnectionStrings 組態區段，因為當呼叫它時，預期 DbContext 已被註冊。

如需詳細資訊，請參閱 ConnectionString。

使用組態提供者

.NET Aspire PostgreSQL Entity Framework Core 整合支援 Microsoft.Extensions.Configuration。 從設定檔，例如 NpgsqlEntityFrameworkCorePostgreSQLSettings，使用 appsettings.json 金鑰載入 Aspire:Npgsql:EntityFrameworkCore:PostgreSQL。 如果您已在 [Aspire:Npgsql:EntityFrameworkCore:PostgreSQL] 區段中設定組態，您可以直接呼叫 方法，而不傳遞任何參數。

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

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

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

使用內聯委派

您也可以傳遞 Action<NpgsqlEntityFrameworkCorePostgreSQLSettings> 委派函式來設定部分或全部的參數，例如設定 ConnectionString：

builder.AddNpgsqlDbContext<YourDbContext>(
    "pgdb",
    static settings => settings.ConnectionString = "<YOUR CONNECTION STRING>");

設定多個 DbContext 類別

如果您想要以不同的組態註冊多個 DbContext，您可以使用 $"Aspire:Npgsql:EntityFrameworkCore:PostgreSQL:{typeof(TContext).Name}" 組態區段名稱。 json 組態看起來會像這樣：

{
  "Aspire": {
    "Npgsql": {
      "EntityFrameworkCore": {
        "PostgreSQL": {
          "ConnectionString": "<YOUR CONNECTION STRING>",
          "DisableHealthChecks": true,
          "DisableTracing": true,
          "AnotherDbContext": {
            "ConnectionString": "<ANOTHER CONNECTION STRING>",
            "DisableTracing": false
          }
        }
      }
    }
  }
}

然後使用 AddNpgsqlDbContext 類型參數呼叫 AnotherDbContext 方法，會從 Aspire:Npgsql:EntityFrameworkCore:PostgreSQL:AnotherDbContext 區段載入設定。

builder.AddNpgsqlDbContext<AnotherDbContext>();

Client 整合性健康檢查

根據預設，.NET.NET Aspire客戶端整合 的 健康檢查 已對所有服務啟用。 同樣地，許多 .NET.NET Aspire代管整合 也會啟用健康檢查端點。 如需詳細資訊，請參閱：

• .NET 在 C# 中應用程式健康情況檢查
• 中的 健康情況檢查

根據預設，.NET AspirePostgreSQLEntity Framework Core 整合會處理下列各項：

• 加入 DbContextHealthCheck，它會呼叫 EF Core的 CanConnectAsync 方法。 健康檢查的名稱是 TContext 類型的名稱。
• 與 /health HTTP 端點整合，要求所有已註冊的健體檢查都必須通過，應用程式才能被視為已準備好接受流量。

可檢視性和遙測

.NET .NET Aspire 整合會自動設定記錄、追蹤和計量組態，有時稱為 可觀察性要素。 如需整合可觀察性和遙測的詳細資訊，請參閱 .NET.NET Aspire 整合概觀。 視支援服務而定，某些整合可能只支援其中一些功能。 例如，某些整合支援記錄和追蹤，但不支援計量。 您也可以使用 組態 一節中呈現的技術來停用遙測功能。

伐木

.NET Aspire PostgreSQL Entity Framework Core 整合會使用下列記錄類別：

• Microsoft.EntityFrameworkCore.ChangeTracking
• Microsoft.EntityFrameworkCore.Database.Command
• Microsoft.EntityFrameworkCore.Database.Connection
• Microsoft.EntityFrameworkCore.Database.Transaction
• Microsoft.EntityFrameworkCore.Migrations
• Microsoft.EntityFrameworkCore.Infrastructure
• Microsoft.EntityFrameworkCore.Migrations
• Microsoft.EntityFrameworkCore.Model
• Microsoft.EntityFrameworkCore.Model.Validation
• Microsoft.EntityFrameworkCore.Query
• Microsoft.EntityFrameworkCore.Update

追蹤

.NET Aspire PostgreSQL Entity Framework Core 整合會使用 OpenTelemetry發出下列追蹤活動：

• Npgsql

指標

.NET Aspire PostgreSQL Entity Framework Core 整合將使用 OpenTelemetry發出下列測量指標：

• Microsoft.EntityFrameworkCore：

  • ec_Microsoft_EntityFrameworkCore_active_db_contexts
  • ec_Microsoft_EntityFrameworkCore_total_queries
  • ec_Microsoft_EntityFrameworkCore_queries_per_second
  • ec_Microsoft_EntityFrameworkCore_total_save_changes
  • ec_Microsoft_EntityFrameworkCore_save_changes_per_second
  • ec_Microsoft_EntityFrameworkCore_compiled_query_cache_hit_rate
  • ec_Microsoft_Entity_total_execution_strategy_operation_failures
  • ec_Microsoft_E_execution_strategy_operation_failures_per_second
  • ec_Microsoft_EntityFramew_total_optimistic_concurrency_failures
  • ec_Microsoft_EntityF_optimistic_concurrency_failures_per_second

• 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

另請參閱

• PostgreSQL 文件
• .NET Aspire Azure PostgreSQL Entity Framework Core 整合
• .NET .NET Aspire 整合
• .NET Aspire GitHub 存放庫