共用方式為

.NET Aspire Azure PostgreSQL 整合

  • 發行項

包括：託管整合 和 Client 整合

Azure 資料庫 for PostgreSQL— 彈性 Server 是以開放 Postgres 原始碼資料庫引擎為基礎的關係資料庫服務。 它是完全受控的資料庫即服務，可透過可預測的效能、安全性、高可用性和動態延展性來處理任務關鍵性工作負載。 .NET Aspire Azure PostgreSQL 整合可讓您連線到現有的 AzurePostgreSQL 資料庫，或使用 docker.io/library/postgres從 建立新的實例。

主機整合

.NET Aspire Azure PostgreSQL 的託管整合將 PostgreSQL 彈性伺服器和資料庫模型化為 AzurePostgresFlexibleServerResource 和 AzurePostgresFlexibleServerDatabaseResource 類型。 主機整合中固有可用的其他類型示如下列資源所示：

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

dotnet add package Aspire.Hosting.Azure.PostgreSQL

如需詳細資訊，請參閱 dotnet add package。

托管整合 AzurePostgreSQL 取決於 📦Aspire.HostingPostgreSQL NuGet 套件，將其擴充以支援 Azure。 您可以使用此整合實現所有您能用 .NET AspirePostgreSQL 整合 和 .NET AspirePostgreSQLEntity Framework Core 整合 所做的事情。

新增 AzurePostgreSQL 伺服器資源

安裝 .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 伺服器資源設定為 AzurePostgres 彈性 Server。

重要

根據預設，AddAzurePostgresFlexibleServer 會設定 Microsoft Entra ID 驗證。 這需要變更需要連線到這些資源的應用程式。 如需詳細資訊，請參閱 Client 整合。

提示

當您呼叫 AddAzurePostgresFlexibleServer時，它會隱含地呼叫 AddAzureProvisioning，這可新增在應用程式啟動期間動態產生 Azure 資源的支援。 應用程式必須設定適當的訂用帳戶和位置。 如需詳細資訊，請參閱 本機配置：組態。

Client 整合

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

dotnet add package Aspire.Npgsql

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

Client 整合性健康檢查

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

  • .NET 在 C# 中應用程式健康情況檢查
  • 中的 健康情況檢查
  • 新增 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

新增已驗證的 Npgsql 用戶端 Azure

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

dotnet add package Azure.Identity

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

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));
});

上述代碼段示範如何使用 DefaultAzureCredential 套件中的 Azure.Identity 類別，以 Microsoft Entra ID 進行驗證，並擷取令牌以聯機到 PostgreSQL 資料庫。 UsePeriodicPasswordProvider 方法可用來將令牌提供給連接字串產生器。

另請參閱