.NET Aspire PostgreSQL Entity Framework Core 統合

[アーティクル]
02/07/2025

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

ホスティング統合

PostgreSQL ホスティング統合は、さまざまな PostgreSQL リソースを次の種類としてモデル化します。

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

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

dotnet add package Aspire.Hosting.PostgreSQL

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

詳細については、「dotnet パッケージの追加」または「.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 コンテナーを追加できます。このコンテナーは、Web ベースの管理ダッシュボードを提供する、PostgreSQL データベース用のクロスプラットフォームクライアントです。次の例を考えてみましょう。

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

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 コンテナーのホストポートを追加して構成します。それ以外の場合、ホストポートはランダムに割り当てられます。

pgWeb リソース PostgreSQL 追加する

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

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サーバーリソースを追加する

PostgreSQL サーバーリソースに 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 バインドマウントは、ホストコンピューターのファイルシステムに依存して、コンテナー PostgreSQL フォルダーを使用してサーバーデータベースを初期化します。このフォルダーは、postgres-data フォルダーの作成後に、実行可能なシェルスクリプトまたは .sql コマンドファイルを実行する初期化に使用されます。 init バインドマウントは、C:\PostgreSQL\Init サーバーコンテナー内のホストコンピューター上の Windows 上の /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 Aspire PostgreSQL Entity Framework Core クライアント統合を開始するには、📦Aspire.Npgsql.EntityFrameworkCore、PostgreSQL NuGet パッケージをクライアントを使用するプロジェクト、つまり PostgreSQL クライアントを利用するアプリケーションのプロジェクトにインストールします。 .NET Aspire PostgreSQL Entity Framework Core クライアント統合により、DbContextとの対話に使用できる目的の PostgreSQL サブクラスインスタンスが登録されます。

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

dotnet add package Aspire.Npgsql.EntityFrameworkCore.PostgreSQL

<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ホスティング統合もヘルスチェックエンドポイントを有効にします。詳細については、以下を参照してください。

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

既定では、.NET AspirePostgreSQLEntity Framework Core 統合では次の処理が行われます。

DbContextHealthCheckの EF Core メソッドを呼び出す CanConnectAsyncを追加します。ヘルスチェックの名前は、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.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

次の方法で共有

.NET Aspire PostgreSQL Entity Framework Core 統合

ホスティング統合

サーバーリソース PostgreSQL を追加する

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

pgAdmin ホストポートを構成する

pgWeb リソース PostgreSQL 追加する

pgWeb ホストポートを構成する

データボリュームを持つ PostgreSQL サーバーリソースを追加する

データバインドマウントを使用してPostgreSQLサーバーリソースを追加する

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

パラメーターを指定して PostgreSQL サーバーリソースを追加する

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

Client 統合

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

Npgsql データベースコンテキストを強化する

設定

接続文字列を使用する

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

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

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

Client 統合ヘルスチェック

可観測性とテレメトリ

伐採

トレーシング

メトリック

関連項目

その他のリソース

次の方法で共有

.NET Aspire PostgreSQL Entity Framework Core 統合

ホスティング統合

サーバー リソース PostgreSQL を追加する

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

pgAdmin ホスト ポートを構成する

pgWeb リソース PostgreSQL 追加する

pgWeb ホスト ポートを構成する

データボリュームを持つ PostgreSQL サーバーリソースを追加する

データバインドマウントを使用してPostgreSQLサーバーリソースを追加する

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

パラメーターを指定して PostgreSQL サーバーリソースを追加する

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

Client 統合

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

Npgsql データベース コンテキストを強化する

設定

接続文字列を使用する

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

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

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

Client 統合ヘルスチェック

可観測性とテレメトリ

伐採

トレーシング

メトリック

関連項目

その他のリソース

サーバーリソース PostgreSQL を追加する

pgAdmin ホストポートを構成する

pgWeb ホストポートを構成する

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

Npgsql データベースコンテキストを強化する

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