.NET Aspire Azure PostgreSQL 통합

아티클
01/31/2025

Azure Database for PostgreSQL— 유연한 Server 오픈 소스 Postgres 데이터베이스 엔진을 기반으로 하는 관계형 데이터베이스 서비스입니다. 예측 가능한 성능, 보안, 고가용성 및 동적 확장성으로 중요 업무용 워크로드를 처리할 수 있는 완전히 관리되는 서비스로서의 데이터베이스입니다. .NET Aspire Azure PostgreSQL 통합은 기존 AzurePostgreSQL 데이터베이스에 연결하거나 docker.io/library/postgres 컨테이너 이미지사용하여 .NET 새 인스턴스를 만드는 방법을 제공합니다.

호스팅 통합

.NET Aspire Azure PostgreSQL 호스팅 통합은 AzurePostgresFlexibleServerResource 및 AzurePostgresFlexibleServerDatabaseResource 형식으로 PostgreSQL 유연한 서버 및 데이터베이스를 모델화합니다. 호스팅 통합에서 기본적으로 사용할 수 있는 다른 형식은 다음 리소스에 표시됩니다.

앱 호스트 프로젝트에서 리소스로 표현하기 위해 이러한 형식 및 API에 액세스하려면 📦Aspire설치합니다. 호스팅.Azure.PostgreSQL NuGet 패키지:

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.Azure.PostgreSQL

자세한 내용은 dotnet add package을 참조하세요.

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

자세한 내용은 .NET 애플리케이션패키지 종속성 관리를 참조하세요.

Azure PostgreSQL 호스팅 통합은 📦Aspire에 대한 종속성을 가지고 있습니다.PostgreSQL NuGet 패키지를 확장하여 Azure을 지원합니다. .NET Aspire PostgreSQL 통합 .NET AspirePostgreSQLEntity Framework Core 통합으로 수행할 수 있는 모든 이 통합을 통해 수행할 수 있습니다.

Azure PostgreSQL 서버 리소스 추가

.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에 대한 이전 호출은 AzurePostgres 유연한 Server로 배포되도록 PostgreSQL 서버 리소스를 구성합니다.

중요하다

기본적으로 AddAzurePostgresFlexibleServerMicrosoft Entra ID 인증을 구성합니다. 이렇게 하려면 이러한 리소스에 연결해야 하는 애플리케이션을 변경해야 합니다. 자세한 내용은 Client 통합참조하세요.

팁

AddAzurePostgresFlexibleServer호출할 때 암시적으로 AddAzureProvisioning호출합니다. 그러면 앱 시작 중에 Azure 리소스를 동적으로 생성하는 지원이 추가됩니다. 앱은 적절한 구독 및 위치를 구성해야 합니다. 자세한 내용은 로컬 프로비저닝: 구성참조하세요.

생성된 프로비저닝 Bicep

Bicep을 처음 접하는 경우, 이는 Azure 리소스를 정의하기 위한 도메인별 언어입니다. .NET .NET Aspire사용하면 Bicep을 직접 작성할 필요가 없으며 프로비전 API는 Bicep을 생성합니다. 앱을 게시하면 생성된 Bicep이 매니페스트 파일과 함께 출력됩니다. Azure PostgreSQL 리소스를 추가하면 다음 Bicep이 생성됩니다.

Azure PostgreSQL Bicep을 토글합니다.

@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 서버의 스토리지 구성입니다. 기본값은 StorageSizeGB로 설정된 32입니다.
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 리소스를 구성하는 흐름 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");
    });

앞의 코드는 다음과 같습니다.

ConfigureInfrastructure API에 대한 호출을 연결합니다.
- infra 매개 변수는 AzureResourceInfrastructure 형식의 인스턴스입니다.
- 프로비전 가능한 리소스는 GetProvisionableResources() 메서드를 호출하여 검색됩니다.
- 단일 PostgreSqlFlexibleServer가 검색되었습니다.
- sku PostgreSqlFlexibleServerSkuTier.Burstable사용하여 설정됩니다.
- 고가용성 속성은 대기 가용성 영역 "2"PostgreSqlFlexibleServerHighAvailabilityMode.ZoneRedundant 사용하여 설정됩니다.
- 태그가 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]의 줄임말입니다.

Azure PostgreSQL 리소스를 컨테이너로 실행

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는 기본 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 매개 변수가 앱 호스트에 매개 변수로 추가되고 WithPasswordAuthentication 메서드가 호출되어 암호 인증을 사용하도록 AzurePostgreSQL 서버를 구성합니다. 자세한 내용은 외부 매개 변수를 참조하세요.

Client 통합

.NET Aspire PostgreSQL 클라이언트 통합을 시작하려면 클라이언트 사용 프로젝트, 즉 PostgreSQL 클라이언트를 사용하는 애플리케이션을 위한 프로젝트에 📦Aspire.Npgsql NuGet 패키지를 설치하세요. PostgreSQL 클라이언트 통합은 NpgsqlDataSource 인스턴스를 등록하여 PostgreSQL와 상호 작용할 수 있게 합니다.

.NET CLI
패키지 참조

dotnet add package Aspire.Npgsql

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

Npgsql 클라이언트 추가

클라이언트 사용 프로젝트의 Program.cs 파일에서, 모든 IHostApplicationBuilder에 대해 AddNpgsqlDataSource 확장 메서드를 호출하여 NpgsqlDataSource을(를) 종속성 주입 컨테이너를 통해 사용할 수 있도록 등록합니다. 메서드는 연결 이름 매개 변수를 사용합니다.

builder.AddNpgsqlDataSource(connectionName: "postgresdb");

팁

connectionName 매개 변수는 앱 호스트 프로젝트에서 PostgreSQL 서버 리소스를 추가할 때 사용되는 이름과 일치해야 합니다. 자세한 내용은 PostgreSQL 서버 리소스추가를 참조하세요.

작성기에서 NpgsqlDataSource 추가한 후 종속성 주입을 사용하여 NpgsqlDataSource 인스턴스를 가져올 수 있습니다. 예를 들어 예제 서비스에서 데이터 원본 개체를 검색하려면 생성자 매개 변수로 정의하고 ExampleService 클래스가 종속성 주입 컨테이너에 등록되어 있는지 확인합니다.

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

종속성 주입에 대한 자세한 내용은 .NET 종속성 주입참조하세요.

키 지정된 Npgsql 클라이언트 추가

여러 NpgsqlDataSource 인스턴스를 서로 다른 연결 이름으로 등록하려는 경우가 있을 수 있습니다. 키 Npgsql 클라이언트를 등록하려면 AddKeyedNpgsqlDataSource 메서드를 호출합니다.

builder.AddKeyedNpgsqlDataSource(name: "chat");
builder.AddKeyedNpgsqlDataSource(name: "queue");

그런 다음 종속성 주입을 사용하여 NpgsqlDataSource 인스턴스를 검색할 수 있습니다. 예를 들어 예제 서비스에서 연결을 검색하려면 다음을 수행합니다.

public class ExampleService(
    [FromKeyedServices("chat")] NpgsqlDataSource chatDataSource,
    [FromKeyedServices("queue")] NpgsqlDataSource queueDataSource)
{
    // Use data sources...
}

키 지정된 서비스에 대한 자세한 내용은 .NET 종속성 주입: 키 서비스참조하세요.

구성

.NET Aspire PostgreSQL 통합은 프로젝트의 요구 사항 및 규칙을 충족하는 여러 구성 접근 방식과 옵션을 제공합니다.

연결 문자열 사용

ConnectionStrings 구성 섹션에서 연결 문자열을 사용하는 경우 AddNpgsqlDataSource 메서드를 호출할 때 연결 문자열의 이름을 제공할 수 있습니다.

builder.AddNpgsqlDataSource("postgresdb");

그런 다음 ConnectionStrings 구성 섹션에서 연결 문자열을 검색합니다.

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

자세한 내용은 ConnectionString참조하세요.

구성 공급자 사용

.NET Aspire PostgreSQL 통합은 Microsoft.Extensions.Configuration지원합니다. Aspire:Npgsql 키를 사용하여 appsettings.json 또는 다른 구성 파일에서 NpgsqlSettings 로드합니다. 몇 가지 옵션을 구성하는 예제 appsettings.json:

다음 예제에서는 사용 가능한 옵션 중 일부를 구성하는 appsettings.json 파일을 보여 줍니다.

{
  "Aspire": {
    "Npgsql": {
      "ConnectionString": "Host=myserver;Database=postgresdb",
      "DisableHealthChecks": false,
      "DisableTracing": true,
      "DisableMetrics": false
    }
  }
}

전체 PostgreSQL 클라이언트 통합 JSON 스키마는 Aspire참조하세요. Npgsql/ConfigurationSchema.json.

인라인 대리자 사용

Action<NpgsqlSettings> configureSettings 대리자를 전달하여 상태 검사를 사용하지 않도록 설정하는 등 일부 또는 모든 옵션을 인라인으로 설정할 수도 있습니다.

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

상태 검사

기본적으로 .NET.NET Aspire 통합은 모든 서비스에 대해 상태 검사를 활성화합니다. 자세한 내용은 .NET.NET Aspire 통합 개요참조하세요.

기본 Postgres 데이터베이스에 대해 명령이 성공적으로 실행될 수 있음을 확인하는 NpgSqlHealthCheck추가합니다.
등록된 모든 상태 검사를 통과해야 트래픽을 허용할 준비가 된 것으로 간주되도록 지정하는 /health HTTP 엔드포인트와 통합됩니다.

관찰 가능성 및 원격 분석

.NET .NET Aspire 통합은 로깅, 추적 및 메트릭 구성을 자동으로 설정하며, 이를 관찰성 핵심 요소라고도. 통합 관찰 가능성 및 원격 분석에 대한 자세한 내용은 .NET.NET Aspire 통합 개요참조하세요. 지원 서비스에 따라 일부 통합은 이러한 기능 중 일부만 지원할 수 있습니다. 예를 들어 일부 통합은 로깅 및 추적을 지원하지만 메트릭은 지원하지 않습니다. 구성 섹션에 제시된 기술을 사용하여 원격 분석 기능을 사용하지 않도록 설정할 수도 있습니다.

로깅

.NET Aspire PostgreSQL 통합은 다음 로그 범주를 사용합니다.

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

추적

.NET Aspire PostgreSQL 통합은 OpenTelemetry사용하여 다음 추적 활동을 내보낸다.

Npgsql

지표

.NET Aspire PostgreSQL 통합은 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

Azure 인증된 Npgsql 클라이언트 추가

기본적으로 PostgreSQL 호스팅 통합에서 AddAzurePostgresFlexibleServer을(를) 호출하면 인증을 사용하도록 ID NuGet 패키지가 구성됩니다.📦Azure.

.NET CLI
PackageReference

dotnet add package Azure.Identity

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

클라이언트 통합 및 Azure.Identity을 통해 PostgreSQL 연결을 사용할 수 있습니다.

builder.AddNpgsqlDataSource(
    "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 메서드는 연결 문자열 작성기에서 토큰을 제공하는 데 사용됩니다.

다음을 통해 공유