.NET Aspire PostgreSQL Entity Framework Core 統合

[アーティクル]
12/15/2024

PostgreSQL は、信頼性、機能の堅牢性、およびパフォーマンスに対する高い評価を得ている、長年にわたるアクティブな開発を行う、強力なオープンソースのオブジェクトリレーショナルデータベースシステムです。 .NET Aspire PostgreSQL Entity Framework Core 統合により、既存の PostgreSQL データベースに接続したり、docker.io/library/postgres コンテナーイメージを使用して .NET から新しいインスタンスを作成したりできます。

ホスティング統合

PostgreSQL ホスティング統合は、PostgresServerResource の種類として PostgreSQLserver をモデル化します。この型と、API にアクセスして、📦Aspireホスティングに追加するには、アプリホストプロジェクトで NuGet パッケージPostgreSQL を使用します。

.NET コマンドラインインターフェイス（CLI）
PackageReference

dotnet add package Aspire.Hosting.PostgreSQL

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

詳細については、「dotnet パッケージの追加」または「.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 リソースには、CreateDefaultPasswordParameter メソッドを使用して、"postgres" とランダムに生成された password の username を持つ既定の資格情報が含まれています。

WithReference メソッドは、"messaging"という名前の ExampleProject で接続を構成します。詳細については、「コンテナーリソースのライフサイクルの」を参照してください。

ヒント

既存の PostgreSQLserverに接続する場合は、代わりに AddConnectionString 呼び出します。詳細については、「既存のリソースを参照する」を参照してください。

PostgreSQL の pgAdmin リソースを追加する

AddPostgres メソッドを使用して builder に PostgreSQL リソースを追加する場合は、WithPgAdmin への呼び出しをチェーンして、dpage/pgadmin4 コンテナーを追加できます。このコンテナーは、web ベースの管理ダッシュボードを提供する、PostgreSQL データベースのクロスプラットフォーム client です。次の例を考えてみましょう。

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 データベース用の Web ベースの管理者ダッシュボードを提供するコンテナーを追加します。

pgWeb リソース PostgreSQL 追加する

AddPostgres メソッドを使用して PostgreSQL リソースを builder に追加する場合は、WithPgWeb への呼び出しをチェーンして、sosedoff/pgweb コンテナーを追加できます。このコンテナーは、web ベースの管理ダッシュボードを提供する、PostgreSQL データベースのクロスプラットフォーム client です。次の例を考えてみましょう。

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 のリソースを追加します

PostgreSQL server リソースにデータボリュームを追加するには、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 リソースを追加する

PostgreSQL server リソースにデータバインドマウントを追加するには、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 データを保持します。データバインドマウントは、PostgreSQLserver コンテナー内のホストコンピューター上の Windows 上の C:\PostgreSQL\Data (または Unixで /PostgreSQL/Data) パスにマウントされます。データバインドマウントの詳細については、「Docker ドキュメント: バインドマウント」を参照してください。

PostgreSQL server リソースを、init バインドマウントで追加する

PostgreSQL server リソースに init バインドマウントを追加するには、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 バインドマウントは、ホストマシンのファイルシステムを利用して、PostgreSQLserver データベースを コンテナーの init フォルダーで初期化します。このフォルダーは、postgres-data フォルダーの作成後に、実行可能なシェルスクリプトまたは .sql コマンドファイルを実行する初期化に使用されます。 init バインドマウントは、PostgreSQLserver コンテナー内のホストコンピューター上の Windows 上の C:\PostgreSQL\Init (または Unix上の /PostgreSQL/Init) パスにマウントされます。

PostgreSQL server のパラメーターを持つリソースを追加する

コンテナーイメージで使用されるユーザー名とパスワードを明示的に指定する場合は、これらの資格情報をパラメーターとして指定できます。次の代替例を考えてみましょう。

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 が実行されていることと、PostgreSQLserver への接続を確立できることを確認します。

ホスティング統合は、📦 AspNetCore.HealthChecks.Npgsql NuGet パッケージに依存します。

Client 統合

.NET Aspire PostgreSQL Entity Framework Core client 統合を開始するには、📦Aspire.Npgsql.EntityFrameworkCorePostgreSQL NuGet パッケージを、clientを使用するプロジェクト、つまり PostgreSQLclientを使用するアプリケーションのプロジェクトにインストールします。 .NET Aspire PostgreSQL Entity Framework Core client 統合により、PostgreSQLとの対話に使用できる目的の DbContext サブクラスインスタンスが登録されます。

.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 では、呼び出された時点で DbContext が登録されることを想定しているため、ConnectionStrings 構成セクションは使用されません。

詳細については、ConnectionStringを参照してください。

構成プロバイダーを使用する

.NET Aspire PostgreSQL Entity Framework Core 統合では、Microsoft.Extensions.Configurationがサポートされています。 Aspire:Npgsql:EntityFrameworkCore:PostgreSQL キーを使用して、appsettings.json などの構成ファイルから 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 統合では次の処理が行われます。

EF Coreの CanConnectAsync メソッドを呼び出す DbContextHealthCheckを追加します。ヘルスチェックの名前は、TContext 型の名前です。
/health HTTP エンドポイントと統合します。このエンドポイントは、アプリがトラフィックを受け入れる準備ができていると見なされるために、登録されているすべての正常性チェックに合格する必要があります

可観測性とテレメトリ

統合により、ログ記録、トレース、メトリックの構成が自動的に設定されます。これは、監視の柱とも呼ばれます。統合の可観測性とテレメトリの詳細については、統合の概要参照してください。バッキングサービスによっては、一部の統合でこれらの機能の一部のみがサポートされる場合があります。たとえば、一部の統合ではログ記録とトレースがサポートされますが、メトリックはサポートされません。テレメトリ機能は、「構成」セクションに記載されている手法を使用して無効にすることもできます。

伐採

.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ホスティングAzure.PostgreSQL の NuGet パッケージをインストールします。

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

dotnet add package Aspire.Hosting.Azure.PostgreSQL

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

リソース AzurePostgreSQLserver 追加する

.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 server リソースを AzurePostgres フレキシブル Serverとしてデプロイするように構成します。

大事な

既定では、AddAzurePostgresFlexibleServer は Microsoft Entra ID 認証を構成します。これには、これらのリソースに接続する必要があるアプリケーションを変更する必要があります。詳細については、Client を参照し、統合について確認してください。

Azure 認証された Npgsql client を追加する

既定では、ホスティング統合でを呼び出すと、認証を有効にする NuGet パッケージを構成するために、が設定されます。

.NET CLI（コマンドラインインターフェース）
PackageReference

dotnet add package Azure.Identity

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

PostgreSQL 接続は、client 統合と Azure.Identityを活用して利用できます。

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

次の方法で共有

.NET Aspire PostgreSQL Entity Framework Core 統合

ホスティング統合

リソース PostgreSQLserver 追加する

PostgreSQL の pgAdmin リソースを追加する

pgWeb リソース PostgreSQL 追加する

データ量ボリュームのある PostgreSQLserver のリソースを追加します

データバインドマウントで PostgreSQLserver リソースを追加する

PostgreSQL server リソースを、init バインドマウントで追加する

PostgreSQL server のパラメーターを持つリソースを追加する

ホスティング統合の正常性チェック

Client 統合

Npgsql データベースコンテキストの追加

エンリッチメントを使用して Npgsql データベースコンテキストを追加する

設定

接続文字列を使用する

構成プロバイダーを使用する

インラインデリゲートを使用する

複数の DbContext クラスを構成する

健康診断

可観測性とテレメトリ

伐採

トレーシング

メトリック

Azure PostgreSQL ホスティング統合

リソース AzurePostgreSQLserver 追加する

Azure 認証された Npgsql client を追加する

関連項目

その他のリソース

次の方法で共有

.NET Aspire PostgreSQL Entity Framework Core 統合

ホスティング統合

リソース PostgreSQLserver 追加する

PostgreSQL の pgAdmin リソースを追加する

pgWeb リソース PostgreSQL 追加する

データ量ボリュームのある PostgreSQLserver のリソースを追加します

データバインドマウントで PostgreSQLserver リソースを追加する

PostgreSQL server リソースを、init バインドマウントで追加する

PostgreSQL server のパラメーターを持つリソースを追加する

ホスティング統合の正常性チェック

Client 統合

Npgsql データベース コンテキストの追加

エンリッチメントを使用して Npgsql データベース コンテキストを追加する

設定

接続文字列を使用する

構成プロバイダーを使用する

インライン デリゲートを使用する

複数の DbContext クラスを構成する

健康診断

可観測性とテレメトリ

伐採

トレーシング

メトリック

Azure PostgreSQL ホスティング統合

リソース AzurePostgreSQLserver 追加する

Azure 認証された Npgsql client を追加する

関連項目

その他のリソース

Npgsql データベースコンテキストの追加

エンリッチメントを使用して Npgsql データベースコンテキストを追加する

インラインデリゲートを使用する