.NET Aspire Azure PostgreSQL 統合

含まれるもの:ホスティング統合 と Client 統合

Azure Database for PostgreSQL—フレキシブル Server は、オープンソースの Postgres データベース エンジンに基づくリレーショナル データベース サービスです。 これは、予測可能なパフォーマンス、セキュリティ、高可用性、動的なスケーラビリティを備えたミッション クリティカルなワークロードを処理できる、フル マネージドのサービスとしてのデータベースです。 .NET Aspire Azure PostgreSQL 統合により、既存の AzurePostgreSQL データベースに接続したり、docker.io/library/postgresを使用して から新しいインスタンスを作成したりできます。

ホスティング統合

.NET Aspire Azure PostgreSQL ホスティング統合は、PostgreSQL フレキシブル サーバーとデータベースを AzurePostgresFlexibleServerResource および AzurePostgresFlexibleServerDatabaseResource の種類としてモデル化します。 ホスティング統合で本質的に使用できるその他の種類は、次のリソースで表されます。

• PostgresServerResource
• PostgresDatabaseResource
• PgAdminContainerResource
• PgWebContainerResource

これらの型と API にアクセスして、アプリ ホスト プロジェクト内のリソースとして表現するには、📦Aspire.Hosting.Azure.PostgreSQL NuGet パッケージをインストールします。

.NET コマンドラインインターフェース

dotnet add package Aspire.Hosting.Azure.PostgreSQL

詳細については、「dotnet add package」を参照してください。

PackageReference

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

詳細については、「.NET アプリケーション でのパッケージの依存関係の管理」を参照してください。

Azure PostgreSQL ホスティング統合は 📦Aspire.Hosting に依存しています。NuGet パッケージPostgreSQL を拡張して Azureをサポートします。 .NET Aspire PostgreSQL 統合 と .NET AspirePostgreSQLEntity Framework Core 統合を使用して実行できることはすべて、この統合でも実行。

サーバー リソース AzurePostgreSQL 追加する

.NET Aspire Azure PostgreSQL ホスティング統合をインストールしたら、アプリ ホスト プロジェクトで 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 Aspire PostgreSQL クライアント統合を開始するには、クライアントを使用するプロジェクト、つまり、📦 クライアントを使用するアプリケーションのプロジェクトに、PostgreSQL NuGet パッケージをインストールします。 PostgreSQL クライアント統合は、との対話に使用できる PostgreSQL インスタンスを登録します。

.NET コマンドラインインターフェース

dotnet add package Aspire.Npgsql

PackageReference

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

Client 統合ヘルスチェック

既定では、.NET.NET Aspireクライアント統合 すべてのサービスで 正常性チェック 有効になっています。 同様に、多くの .NET.NET Aspireホスティング統合 もヘルスチェックエンドポイントを有効にします。 詳細については、以下を参照してください。

• C#でのアプリ正常性チェック .NET
• ASP.NET Core での正常性チェック

• 基になる 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 パッケージ が構成されます。

.NET コマンドラインインターフェース

dotnet add package Azure.Identity

PackageReference

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

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 メソッドを使用して、接続文字列ビルダーにトークンを提供します。

関連項目

• PostgreSQL ドキュメント
• Azure の PostgreSQL 用データベース
• .NET Aspire PostgreSQL 統合
• .NET .NET Aspire 統合
• .NET Aspire GitHub リポジトリの