.NET AspireAzurePostgreSQLEntity Framework Core 統合

含まれているもの: ホスティング統合 —および— Client 統合

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

ホスティング統合

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

• PostgresServerResource
• PostgresDatabaseResource
• PgAdminContainerResource
• PgWebContainerResource

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

dotnet add package Aspire.Hosting.Azure.PostgreSQL

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

AzurePostgreSQL ホスティング統合は、📦Aspire.Hosting に依存しています。PostgreSQL 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としてデプロイするように構成します。

プロビジョニングによって生成されたBicep

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

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

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
}

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

output name string = postgres_flexible.name

上記の Bicep は、 AzurePostgreSQL フレキシブル サーバー リソースをプロビジョニングするモジュールです。 さらに、ロールの割り当ては、別のモジュールで Azure リソースに対して作成されます。

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

param postgres_flexible_outputs_name string

param principalType string

param principalId string

param principalName string

resource postgres_flexible 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' existing = {
  name: postgres_flexible_outputs_name
}

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

PostgreSQL フレキシブル サーバーに加えて、すべての Azure IP アドレスを許可する Azure ファイアウォール規則もプロビジョニングします。 最後に、PostgreSQL サーバーの管理者が作成され、接続文字列が出力変数として出力されます。 生成された Bicep は開始点であり、C# のプロビジョニング インフラストラクチャへの変更の影響を受ける。 Bicep ファイルのカスタマイズは直接上書きされるため、C# プロビジョニング API を通じて変更を加えて、生成されたファイルに反映されるようにします。

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

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

builder.AddAzurePostgresFlexibleServer("postgres")
    .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");
    });

上記のコード:

• ConfigureInfrastructure API への呼び出しを連鎖させます。
  • infra パラメーターは、AzureResourceInfrastructure 型のインスタンスです。
  • プロビジョニング可能なリソースは、GetProvisionableResources() メソッドを呼び出すことによって取得されます。
  • 1つのPostgreSqlFlexibleServerが取得されました。
  • sku は PostgreSqlFlexibleServerSkuTier.Burstableで設定されます。
  • 高可用性プロパティは、スタンバイ可用性ゾーン PostgreSqlFlexibleServerHighAvailabilityMode.ZoneRedundantの "2" で設定されます。
  • フレキシブルサーバーに、キーが ExampleKey で値が Example valueのタグが追加されます。

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

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

接続する既存の AzurePostgreSQL フレキシブル サーバーがある場合があります。 AzurePostgresFlexibleServerResourceが既存のリソースであることを注釈する呼び出しをチェーンします。

var builder = DistributedApplication.CreateBuilder(args);

var existingPostgresName = builder.AddParameter("existingPostgresName");
var existingPostgresResourceGroup = builder.AddParameter("existingPostgresResourceGroup");

var postgres = builder.AddAzurePostgresFlexibleServer("postgres")
                      .AsExisting(existingPostgresName, existingPostgresResourceGroup);

builder.AddProject<Projects.ExampleProject>()
       .WithReference(postgres);

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

フレキシブル サーバー リソースAzurePostgreSQL既存のリソースとして扱う方法の詳細については、「既存のAzure リソースを使用する」を参照してください。

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

AzurePostgreSQL ホスティング統合では、PostgreSQL サーバーをローカル コンテナーとして実行できます。 これは、PostgreSQL リソースをプロビジョニングしたり、既存の AzureAzure サーバーに接続したりする必要がないように、開発およびテストのために 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 リソースを構成します。

パスワード認証を使用するように 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 パラメーターがパラメーターとしてアプリ ホストに追加され、パスワード認証を使用するように WithPasswordAuthenticationAzure サーバーを構成するために PostgreSQL メソッドが呼び出されます。 詳細については、「外部パラメーターを参照してください。

Client 統合

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

dotnet add package Aspire.Azure.Npgsql.EntityFrameworkCore.PostgreSQL

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

PostgreSQL接続は、AddAzureNpgsqlDataSourceを呼び出すことによって、クライアント統合を使用して使用できます。

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

上記のコードスニペットは、AddAzureNpgsqlDbContext メソッドを使って、YourDbContext 認証 (Microsoft Entra ID) を使用し、Azure インスタンスを登録する方法を示しています。 この "postgresdb" 接続名は、接続文字列の構成値に対応します。

ビルダーに 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.")));

次に例を示すように、この方法でデータベース コンテキストを作成する際の柔軟性が向上します。

• データベース コンテキストの既存の構成コードは、.NET.NET Aspire用に書き換えることなく再利用できます。
• Entity Framework Core インターセプターを使用して、データベース操作を変更できます。
• コンテキスト プール Entity Framework Core 使用しないことを選択できます。状況によってはパフォーマンスが向上する可能性があります。

このメソッドを使用する場合は、.NET メソッドを呼び出すことで、.NET AspireEnrichAzureNpgsqlDbContextスタイルの再試行、正常性チェック、ログ記録、テレメトリ機能を使用してデータベース コンテキストを拡張できます。

builder.EnrichAzureNpgsqlDbContext<YourDbContext>(
    configureSettings: settings =>
    {
        settings.DisableRetry = false;
        settings.CommandTimeout = 30;
    });

settings パラメーターは、AzureNpgsqlEntityFrameworkCorePostgreSQLSettings クラスのインスタンスです。

また、Npgsql の特定のオプションを構成したり、他の方法で DbContext を登録したりする必要がある場合もあります。 この場合は、次の例に示すように、 EnrichAzureNpgsqlDbContext 拡張メソッドを呼び出します。

var connectionString = builder.Configuration.GetConnectionString("postgresdb");

builder.Services.AddDbContextPool<YourDbContext>(
    dbContextOptionsBuilder => dbContextOptionsBuilder.UseNpgsql(connectionString));

builder.EnrichAzureNpgsqlDbContext<YourDbContext>();

設定

.NET AspireAzurePostgreSQL EntityFrameworkCore Npgsql 統合には、プロジェクトの要件と規則に基づいてデータベース接続を構成するための複数のオプションが用意されています。

接続文字列を使用する

ConnectionStrings構成セクションで定義されている接続文字列を使用する場合は、AddAzureNpgsqlDataSourceを呼び出すときに接続文字列の名前を指定します。

builder.AddAzureNpgsqlDbContext<YourDbContext>("postgresdb");

接続文字列は、 ConnectionStrings 構成セクションから取得されます。たとえば、次の JSON 構成を考えてみましょう。

{
  "ConnectionStrings": {
    "postgresdb": "Host=myserver;Database=test"
  }
}

接続文字列を構成する方法の詳細については、 Npgsql 接続文字列のドキュメントを参照してください。

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

.NET AspireAzurePostgreSQL EntityFrameworkCore Npgsql 統合では、Microsoft.Extensions.Configurationがサポートされます。 AzureNpgsqlEntityFrameworkCorePostgreSQLSettings キーを使用して、構成からAspire:Npgsql:EntityFrameworkCore:PostgreSQLを読み込みます。 たとえば、使用可能なオプションの一部を構成する次の appsettings.json ファイルについて考えてみます。

{
  "Aspire": {
    "Npgsql": {
      "EntityFrameworkCore": {
        "PostgreSQL": {
          "DisableHealthChecks": true,
          "DisableTracing": true
        }
      }
    }
  }
}

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

コードで設定を構成するには、 Action<AzureNpgsqlEntityFrameworkCorePostgreSQLSettings> configureSettings デリゲートを渡して、一部またはすべてのオプションをインラインで設定します。たとえば、コードから正常性チェックを無効にすることができます。

builder.AddAzureNpgsqlDbContext<YourDbContext>(
    "postgresdb",
    settings => settings.DisableHealthChecks = true);

または、 EnrichAzureNpgsqlDbContext 拡張メソッドを使用して設定を構成することもできます。

builder.EnrichAzureNpgsqlDbContext<YourDbContext>(
    settings => settings.DisableHealthChecks = true);

接続を確立するには、 AzureNpgsqlEntityFrameworkCorePostgreSQLSettings.Credential プロパティを使用します。 資格情報が構成されていない場合は、DefaultAzureCredential が使用されます。

接続文字列にユーザー名とパスワードが含まれている場合、資格情報は無視されます。

トラブルシューティング

まれに、 Username プロパティが指定されておらず、アプリケーションのマネージド ID を使用して統合で検出できない場合、Npgsql は次のようなメッセージで例外をスローします。

Npgsql.PostgresException (0x80004005): 28P01: ユーザーのパスワード認証に失敗しました...

この場合は、接続文字列で Username プロパティを構成し、 EnrichAzureNpgsqlDbContextを使用して接続文字列を UseNpgsql渡すことができます。

builder.Services.AddDbContextPool<YourDbContext>(
    options => options.UseNpgsql(newConnectionString));

builder.EnrichAzureNpgsqlDbContext<YourDbContext>();

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

伐採

.NET AspirePostgreSQLEntity 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 AspirePostgreSQLEntity Framework Core 統合では、OpenTelemetryを使用して次のトレース アクティビティが出力されます。

• Npgsql

メトリック

.NET AspirePostgreSQLEntity 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

参考

• PostgreSQL ドキュメント
• Azure のためのデータベース PostgreSQL
• .NET AspirePostgreSQLEntity Framework Core 統合
• .NET.NET Aspire 統合
• .NET AspireGitHub リポジトリ