다음을 통해 공유


.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 호스팅 통합은 AzurePostgresFlexibleServerResourceAzurePostgresFlexibleServerDatabaseResource 형식으로 PostgreSQL 유연한 서버 및 데이터베이스를 모델화합니다. 호스팅 통합에서 기본적으로 사용할 수 있는 다른 형식은 다음 리소스에 표시됩니다.

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

dotnet add package Aspire.Hosting.Azure.PostgreSQL

자세한 내용은 dotnet 패키지 추가을 참조하세요.

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

중요하다

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

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

생성된 프로비저닝 Bicep

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


Azure PostgreSQL 바이셉 토글.

@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 리소스를 구성하는 흐름 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]입니다.

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

Client 통합

.NET Aspire PostgreSQL Entity Framework Core 클라이언트 통합을 시작하려면, 📦Aspire.Npgsql.EntityFrameworkCore.PostgreSQL NuGet 패키지를 설치합니다. 이 패키지는 클라이언트를 사용하는 애플리케이션의 프로젝트, 즉 PostgreSQL 클라이언트를 사용하는 프로젝트에 설치해야 합니다. .NET Aspire PostgreSQL Entity Framework Core 클라이언트 통합은 PostgreSQL상호 작용하는 데 사용할 수 있는 원하는 DbContext 하위 클래스 인스턴스를 등록합니다.

dotnet add package Aspire.Npgsql.EntityFrameworkCore.PostgreSQL

Npgsql 데이터베이스 컨텍스트 추가

클라이언트 사용 프로젝트의 Program.cs 파일에서 모든 IHostApplicationBuilderAddNpgsqlDbContext 확장 메서드를 호출하여 종속성 주입 컨테이너를 통해 사용할 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

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

기본적으로 PostgreSQL 통합 호스팅에서 AddAzurePostgresFlexibleServer을(를) 호출할 때, 인증을 활성화하려면 📦Azure. 아이덴티티 NuGet 패키지가 필요합니다.

dotnet add package Azure.Identity

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

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

참고