次の方法で共有

.NET Aspire Azure PostgreSQL Entity Framework Core 統合

  • [アーティクル]

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

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

ホスティング統合

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

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

dotnet add package Aspire.Hosting.Azure.PostgreSQL

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

Azure PostgreSQL ホスティング統合は、📦Aspire.Hosting に依存しています。PostgreSQL NuGet パッケージを拡張して、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 リソースを動的に生成するためのサポートが追加されます。 アプリは、適切なサブスクリプションと場所を構成する必要があります。 詳細については、「ローカル プロビジョニング: 構成」を参照してください。

生成されたプロビジョニングのBicep

Bicep を初めてする場合は、Azure リソースを定義するためのドメイン固有の言語です。 .NET .NET Aspireでは、Bicep を手動で記述する必要はありません。代わりに、プロビジョニング API によって Bicep が生成されます。 アプリを発行すると、生成された Bicep がマニフェスト ファイルと共に出力されます。 Azure PostgreSQL リソースを追加すると、次の Bicep が生成されます。


Bicep AzurePostgreSQL 切り替えます。 

@description('The location for the resource(s) to be deployed.')
param location string = resourceGroup().location

param principalId string

param principalType string

param principalName string

resource postgres_flexible 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = {
  name: take('postgresflexible-${uniqueString(resourceGroup().id)}', 63)
  location: location
  properties: {
    authConfig: {
      activeDirectoryAuth: 'Enabled'
      passwordAuth: 'Disabled'
    }
    availabilityZone: '1'
    backup: {
      backupRetentionDays: 7
      geoRedundantBackup: 'Disabled'
    }
    highAvailability: {
      mode: 'Disabled'
    }
    storage: {
      storageSizeGB: 32
    }
    version: '16'
  }
  sku: {
    name: 'Standard_B1ms'
    tier: 'Burstable'
  }
  tags: {
    'aspire-resource-name': 'postgres-flexible'
  }
}

resource postgreSqlFirewallRule_AllowAllAzureIps 'Microsoft.DBforPostgreSQL/flexibleServers/firewallRules@2024-08-01' = {
  name: 'AllowAllAzureIps'
  properties: {
    endIpAddress: '0.0.0.0'
    startIpAddress: '0.0.0.0'
  }
  parent: postgres_flexible
}

resource postgres_flexible_admin 'Microsoft.DBforPostgreSQL/flexibleServers/administrators@2024-08-01' = {
  name: principalId
  properties: {
    principalName: principalName
    principalType: principalType
  }
  parent: postgres_flexible
  dependsOn: [
    postgres_flexible
    postgreSqlFirewallRule_AllowAllAzureIps
  ]
}

output connectionString string = 'Host=${postgres_flexible.properties.fullyQualifiedDomainName};Username=${principalName}'

上記の Bicep は、次の既定値で AzurePostgreSQL フレキシブル サーバーをプロビジョニングするモジュールです。

  • authConfig: PostgreSQL サーバーの認証構成。 既定値は ActiveDirectoryAuth 有効で、PasswordAuth 無効です。
  • availabilityZone: PostgreSQL サーバーの可用性ゾーン。 既定値は 1です。
  • backup: PostgreSQL サーバーのバックアップ構成。 既定値は BackupRetentionDays7 に設定され、GeoRedundantBackupDisabledに設定されます。
  • highAvailability: PostgreSQL サーバーの高可用性構成。 既定値は Disabledです。
  • storage: PostgreSQL サーバーのストレージ構成。 既定値は StorageSizeGB32に設定されます。
  • version: PostgreSQL サーバーのバージョン。 既定値は 16です。
  • sku: PostgreSQL サーバーの SKU。 既定値は Standard_B1msです。
  • tags: PostgreSQL サーバーのタグ。 既定値は aspire-resource-nameAspire リソースの名前 (この場合は postgres-flexible) に設定されます。

PostgreSQL フレキシブル サーバーに加えて、すべての Azure IP アドレスを許可する Azure ファイアウォール規則もプロビジョニングします。 最後に、PostgreSQL サーバーの管理者が作成され、接続文字列が出力変数として出力されます。 生成された Bicep は開始点であり、特定の要件を満たすようにカスタマイズできます。

プロビジョニング インフラストラクチャをカスタマイズする

すべての .NET AspireAzure リソースは、AzureProvisioningResource 型のサブクラスです。 この型を使用すると、ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>) API を利用して Azure リソースを構成するための fluent API を提供し、生成された Bicep のカスタマイズを可能にします。 たとえば、kind、consistencyPolicy、locationsなどを構成できます。 次の例では、AzureAzure Cosmos DB リソースをカスタマイズする方法を示します。

builder.AddAzureCosmosDB("cosmos-db")
    .ConfigureInfrastructure(infra =>
    {
        var flexibleServer = infra.GetProvisionableResources()
                                  .OfType<PostgreSqlFlexibleServer>()
                                  .Single();

        flexibleServer.Sku = new PostgreSqlFlexibleServerSku
        {
            Tier = PostgreSqlFlexibleServerSkuTier.Burstable,
        };
        flexibleServer.HighAvailability = new PostgreSqlFlexibleServerHighAvailability
        {
            Mode = PostgreSqlFlexibleServerHighAvailabilityMode.ZoneRedundant,
            StandbyAvailabilityZone = "2",
        };
        flexibleServer.Tags.Add("ExampleKey", "Example value");
    });

上記のコード:

PostgreSQL フレキシブル サーバー リソースをカスタマイズするために、さらに多くの構成オプションを使用できます。 詳細については、Azure.Provisioning.PostgreSqlを参照してください。 詳細については、「カスタマイズのプロビジョニング 」に関するAzureを参照してください。

既存の AzurePostgreSQL フレキシブル サーバーに接続する

接続する既存の AzurePostgreSQL フレキシブル サーバーがある場合があります。 新しい AzurePostgreSQL フレキシブル サーバー リソースを表す代わりに、接続文字列をアプリ ホストに追加できます。 既存の AzurePostgreSQL フレキシブル サーバーに接続を追加するには、AddConnectionString メソッドを呼び出します。

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddConnectionString("postgres");

builder.AddProject<Projects.WebApplication>("web")
       .WithReference(postgres);

// After adding all resources, run the app...

手記

接続文字列は、データベース接続、メッセージ ブローカー、エンドポイント URI、その他のサービスなど、さまざまな接続情報を表すために使用されます。 .NET .NET Aspire 命名法では、"接続文字列" という用語は、あらゆる種類の接続情報を表すために使用されます。

接続文字列は、アプリ ホストの構成 (通常は ConnectionStrings セクションの ユーザー シークレット) で構成されます。 アプリ ホストは、この接続文字列を環境変数としてすべての依存リソースに挿入します。次に例を示します。

{
    "ConnectionStrings": {
        "postgres": "Server=<PostgreSQL-server-name>.postgres.database.azure.com;Database=<database-name>;Port=5432;Ssl Mode=Require;User Id=<username>;"
    }
}

依存リソースは、GetConnectionString メソッドを呼び出し、接続名をパラメーターとして渡すことによって、挿入された接続文字列にアクセスできます(この場合 "postgres"。 GetConnectionString API は、IConfiguration.GetSection("ConnectionStrings")[name]の短縮形です。

コンテナーとしてリソース AzurePostgreSQL 実行する

Azure PostgreSQL ホスティング統合では、PostgreSQL サーバーをローカル コンテナーとして実行できます。 これは、Azure リソースをプロビジョニングしたり、既存の AzurePostgreSQL サーバーに接続したりする必要がないように、開発およびテストのために PostgreSQL サーバーをローカルで実行する場合に役立ちます。

PostgreSQL サーバーをコンテナーとして実行するには、RunAsContainer メソッドを呼び出します。

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddAzurePostgresFlexibleServer("postgres")
                      .RunAsContainer();

var postgresdb = postgres.AddDatabase("postgresdb");

var exampleProject = builder.AddProject<Projects.ExampleProject>()
                            .WithReference(postgresdb);

上記のコードでは、コンテナー内でローカルに実行するように AzurePostgreSQL フレキシブル Server リソースを構成します。

先端 / アドバイス

RunAsContainer メソッドは、ローカルの開発とテストに役立ちます。 この API では、pgAdmin、pgWeb の追加、データ ボリュームまたはデータ バインド マウントの追加、init バインド マウントの追加など、基になる PostgresServerResource 構成をカスタマイズできる省略可能なデリゲートが公開されています。 詳細については、「.NET AspirePostgreSQL ホスティング統合の」セクションを参照してください。

パスワード認証を使用するように AzurePostgreSQL サーバーを構成する

既定では、AzurePostgreSQL サーバーは Microsoft Entra ID 認証 使用するように構成されています。 パスワード認証を使用する場合は、WithPasswordAuthentication メソッドを呼び出して、パスワード認証を使用するようにサーバーを構成できます。

var builder = DistributedApplication.CreateBuilder(args);

var username = builder.AddParameter("username", secret: true);
var password = builder.AddParameter("password", secret: true);

var postgres = builder.AddAzurePostgresFlexibleServer("postgres")
                      .WithPasswordAuthentication(username, password);

var postgresdb = postgres.AddDatabase("postgresdb");

var exampleProject = builder.AddProject<Projects.ExampleProject>()
                            .WithReference(postgresdb);

前のコードでは、パスワード認証を使用するように AzurePostgreSQL サーバーを構成します。 username パラメーターと password パラメーターがパラメーターとしてアプリ ホストに追加され、パスワード認証を使用するように AzurePostgreSQL サーバーを構成するために WithPasswordAuthentication メソッドが呼び出されます。 詳細については、「外部パラメーター を参照してください。

Client 統合

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

dotnet add package Aspire.Npgsql.EntityFrameworkCore.PostgreSQL

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

クライアントを使用するプロジェクトの Program.cs ファイルで、任意の IHostApplicationBuilder で AddNpgsqlDbContext 拡張メソッドを呼び出して、依存関係挿入コンテナーを介して使用する DbContext サブクラスを登録します。 このメソッドは、接続名パラメーターを受け取ります。

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

ヒント

connectionName パラメーターは、アプリ ホスト プロジェクトに PostgreSQL サーバー リソースを追加するときに使用する名前と一致する必要があります。 詳細については、「PostgreSQL サーバー リソースを追加する」を参照してください。

ビルダーに 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",
          "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
          }
        }
      }
    }
  }
}

次に、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 .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.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

認証された Npgsql クライアント Azure 追加する

既定では、PostgreSQL ホスティング統合で AddAzurePostgresFlexibleServer を呼び出すとき、認証を有効にするには、NuGet パッケージと📦Azureが必要です。

dotnet add package Azure.Identity

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

関連項目