.NET AspireAzurePostgreSQL 統合

2025-06-18

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

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

ホスティング統合

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

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

.NET コマンドラインインターフェース
パッケージリファレンス

dotnet add package Aspire.Hosting.Azure.PostgreSQL

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

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

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

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

大事な

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

ヒント

AddAzurePostgresFlexibleServerを呼び出すと、暗黙的に AddAzureProvisioningが呼び出されます。これによって、アプリの起動時に Azure リソースを動的に生成するためのサポートが追加されます。アプリは、適切なサブスクリプションと場所を構成する必要があります。詳細については、「ローカルプロビジョニング: 構成」を参照してください。

プロビジョニングによって生成された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 フレキシブルサーバーリソースをカスタマイズするために、さらに多くの構成オプションを使用できます。詳細については、とを参照してください。プロビジョニングのカスタマイズについてもご覧ください。

既存の 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 フレキシブルサーバーリソースを表す代わりに、接続文字列をアプリホストに追加することもできます。このアプローチは弱く型指定されており、ロールの割り当てやインフラストラクチャのカスタマイズでは機能しません。詳細については、「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 リソースを構成します。

ヒント

RunAsContainer メソッドは、ローカルの開発とテストに役立ちます。 API は、基になる PostgresServerResource 構成をカスタマイズできる省略可能なデリゲートを公開します。たとえば、pgAdmin と pgWeb を追加し、データボリュームまたはデータバインドマウントを追加し、init バインドマウントを追加できます。詳細については、「.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 パラメーターがパラメーターとしてアプリホストに追加され、パスワード認証を使用するように WithPasswordAuthenticationAzure サーバーを構成するために PostgreSQL メソッドが呼び出されます。詳細については、「外部パラメーターを参照してください。

Client 統合

.NET AspireAzurePostgreSQL クライアント統合を開始するには、📦Aspire.Azureをインストールします。クライアントを使用するプロジェクト (つまり、PostgreSQL クライアントを使用するアプリケーションのプロジェクト) の Npgsql NuGet パッケージ。 PostgreSQL クライアント統合は、との対話に使用できる PostgreSQL インスタンスを登録します。

.NET コマンドラインインターフェース
パッケージリファレンス

dotnet add package Aspire.Azure.Npgsql

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

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

builder.AddAzureNpgsqlDataSource(connectionName: "postgresdb");

ヒント

connectionName パラメーターは、アプリホストプロジェクトに PostgreSQL サーバーリソースを追加するときに使用する名前と一致する必要があります。

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

ビルダーに NpgsqlDataSource を追加した後、依存関係の挿入を使用して NpgsqlDataSource インスタンスを取得できます。たとえば、サンプルサービスからデータソースオブジェクトを取得するには、それをコンストラクターパラメーターとして定義し、ExampleService クラスが依存関係挿入コンテナーに登録されていることを確認します。

public class ExampleService(NpgsqlDataSource dataSource)
{
    // Use dataSource...
}

依存関係の挿入の詳細については .NET を参照してください (依存関係の挿入).

キー付きのNpgsqlクライアントを追加する

接続名が異なる複数の NpgsqlDataSource インスタンスを登録する場合があります。キー付き Npgsql クライアントを登録するには、AddKeyedAzureNpgsqlDataSource メソッドを呼び出します。

builder.AddKeyedAzureNpgsqlDataSource(name: "sales_db");
builder.AddKeyedAzureNpgsqlDataSource(name: "inventory_db");

その後、依存関係の挿入を使用して NpgsqlDataSource インスタンスを取得できます。たとえば、サービスの例から接続を取得するには、次のようにします。

public class ExampleService(
    [FromKeyedServices("sales_db")] NpgsqlDataSource salesDataSource,
    [FromKeyedServices("inventory_db")] NpgsqlDataSource inventoryDataSource)
{
    // Use data sources...
}

キー付きサービスの詳細については、「.NET 依存関係の挿入: キー付きサービスの」を参照してください。

設定

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

接続文字列を使用する

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

builder.AddAzureNpgsqlDataSource("postgresdb");

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

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

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

手記

ユーザー名とパスワードは、設定で指定された資格情報から自動的に推論されます。

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

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

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

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

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

builder.AddAzureNpgsqlDataSource(
    "postgresdb",
    settings => settings.DisableHealthChecks = true);

接続を確立するには、 AzureNpgsqlSettings.Credential プロパティを使用します。資格情報が構成されていない場合は、DefaultAzureCredential が使用されます。接続文字列にユーザー名とパスワードが含まれている場合、資格情報は無視されます。

Client 統合ヘルスチェック

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

C#でのアプリ正常性チェック .NET
ASP.NET Core における健康診断

基になる NpgSqlHealthCheck データベースに対してコマンドが正常に実行できることを確認する Postgresを追加します。
/health HTTP エンドポイントと統合します。このエンドポイントは、アプリがトラフィックを受け入れる準備ができていると見なされるために、登録されているすべての正常性チェックに合格する必要があります

可観測性とテレメトリ

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

伐採

.NET AspirePostgreSQL 統合では、次のログカテゴリが使用されます。

Npgsql.Connection
Npgsql.Command
Npgsql.Transaction
Npgsql.Copy
Npgsql.Replication
Npgsql.Exception

追跡

.NET AspirePostgreSQL 統合では、OpenTelemetryを使用して次のトレースアクティビティが出力されます。

Npgsql

メトリック

.NET AspirePostgreSQL 統合では、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