.NET Aspire PostgreSQL Entity Framework Core 整合

發行項
12/12/2024

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

託管整合

PostgreSQL 主機整合會將 PostgreSQLserver 模型化為 PostgresServerResource 類型。若要存取此類型和 API，您可以將它新增至 📦Aspire的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 實例。 PostgreSQL server 和 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 資料庫的網頁系統管理儀錶板。

新增 PostgreSQL pgWeb 資源

使用 AddPostgres 方法將 PostgreSQL 資源新增至 builder 時，您可以將呼叫鏈結至 WithPgWeb 以新增 sosedoff/pgweb 容器。此容器是適用於 PostgreSQL 資料庫的跨平臺 client，可提供 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 連線書籤。

以數據量新增 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 的 C:\PostgreSQL\Data 上，或在 Unix上的 /PostgreSQL/Data，掛載於主機中的 PostgreSQLserver 容器中。如需資料系結掛接的詳細資訊，請參閱 Docker 檔：系結掛接。

使用 init bind mount 新增 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 系結掛接會掛接在 PostgreSQLserver 容器中主機上的 Windows 路徑 C:\PostgreSQL\Init 上（或 Unix上的 /PostgreSQL/Init 路徑）。

新增帶有參數的 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 AspirePostgreSQLEntity Framework Coreclient 的整合，請在包含 client的專案（即使用 PostgreSQLclient的應用程式專案）中，安裝 📦AspireNpgsql.EntityFrameworkCore 和PostgreSQL NuGet 套件。 .NET Aspire PostgreSQL Entity Framework Core client 整合會註冊您想要的 DbContext 子類別實例，以便用來與 PostgreSQL互動。

.NET 命令列介面
PackageReference

dotnet add package Aspire.Npgsql.EntityFrameworkCore.PostgreSQL

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

新增 Npgsql 資料庫環境

在 client專案的 Program.cs 檔案中，您可以在任何 IHostApplicationBuilder 上呼叫 AddNpgsqlDbContext 擴充方法，將您的 DbContext 子類別註冊至相依性注入容器中以供使用。方法會採用連接名稱參數。

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

提示

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

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

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

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

使用增強新增 Npgsql 資料庫內容

若要使用其他服務擴充 DbContext，例如自動重試、健康情況檢查、記錄和遙測，請呼叫 EnrichNpgsqlDbContext 方法：

builder.EnrichNpgsqlDbContext<YourDbContext>(
    connectionName: "postgresdb",
    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。從設定檔，例如 appsettings.json，使用 Aspire:Npgsql:EntityFrameworkCore:PostgreSQL 金鑰載入 NpgsqlEntityFrameworkCorePostgreSQLSettings。如果您已在 [Aspire:Npgsql:EntityFrameworkCore:PostgreSQL] 區段中設定組態，您可以直接呼叫方法，而不傳遞任何參數。

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

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

如需完整的 PostgreSQLEntity Framework Coreclient 整合 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>",
          "DbContextPooling": true,
          "DisableHealthChecks": true,
          "DisableTracing": true,
          "AnotherDbContext": {
            "ConnectionString": "<ANOTHER CONNECTION STRING>",
            "DisableTracing": false
          }
        }
      }
    }
  }
}

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

builder.AddNpgsqlDbContext<AnotherDbContext>();

健康檢查

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

根據預設，.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.Infrastructure
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

Azure PostgreSQL 主機整合

若要將 PostgreSQL 資源部署至 Azure，請安裝 📦Aspire.Hosting.Azure.PostgreSQL NuGet 套件：

.NET 命令列介面
套件引用

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 整合。

新增 Azure 經過驗證的 Npgsql client

根據預設，當您在 PostgreSQL 主機整合中呼叫 AddAzurePostgresFlexibleServer 時，它會設定 📦Azure身分識別 NuGet 套件來啟用驗證：

.NET 命令列介面 (CLI)
PackageReference

dotnet add package Azure.Identity

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

您可以使用 client 整合和 Azure.Identity來取用 PostgreSQL 連線：

builder.AddNpgsqlDbContext<YourDbContext>(
    "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 方法可用來將令牌提供給連接字串產生器。

共用方式為