.NET Aspire PostgreSQL Entity Framework Core 통합

아티클
12/15/2024

PostgreSQL 안정성, 기능 견고성 및 성능에 대한 강력한 명성을 얻은 수년간의 활성 개발을 통해 강력한 오픈 소스 개체 관계형 데이터베이스 시스템입니다. .NET Aspire PostgreSQL Entity Framework Core 통합은 기존 PostgreSQL 데이터베이스에 연결하거나 docker.io/library/postgres 컨테이너 이미지사용하여 .NET 새 인스턴스를 만드는 방법을 제공합니다.

호스팅 통합

PostgreSQL 호스팅 통합은 PostgreSQLserver를 PostgresServerResource 유형으로 모델링합니다. 이 형식과 API에 액세스하여 📦Aspire에 추가하려면, 호스팅된 앱 호스트 프로젝트에서PostgreSQL NuGet 패키지를 사용하세요.

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.PostgreSQL

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

자세한 내용은 dotnet add package 또는 .NET 애플리케이션에서 패키지 종속성을 관리하기를 참조하세요.

PostgreSQL server 리소스 추가

앱 호스트 프로젝트에서 builder 인스턴스의 AddPostgres 호출하여 PostgreSQLserver 리소스를 추가한 다음, postgres 인스턴스에서 AddDatabase 호출하여 다음 예제와 같이 데이터베이스 리소스를 추가합니다.

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

.NET .NET Aspire docker.io/library/postgres 이미지와 함께 이전 예제와 같이 앱 호스트에 컨테이너 이미지를 추가하면 로컬 컴퓨터에 새 PostgreSQLserver 인스턴스가 만들어집니다. PostgreSQL server 및 PostgreSQL 데이터베이스 인스턴스(postgresdb 변수)에 대한 참조는 ExampleProject종속성을 추가하는 데 사용됩니다. PostgreSQL server 리소스에는 기본 자격 증명("postgres"의 username)과 CreateDefaultPasswordParameter 메서드를 사용하여 임의로 생성된 password가 포함됩니다.

WithReference 메서드는 "messaging"라는 이름의 ExampleProject 연결을 구성합니다. 자세한 내용은 컨테이너 리소스 수명 주기참조하세요.

팁

기존 PostgreSQLserver연결하려는 경우 대신 AddConnectionString 호출합니다. 자세한 내용은 기존 리소스 참조를 참조하세요.

PostgreSQL pgAdmin 리소스 추가

AddPostgres 메서드를 사용하여 builder에 PostgreSQL 리소스를 추가할 때, WithPgAdmin 호출을 연결하면 dpage/pgadmin4 컨테이너를 추가할 수 있습니다. 이 컨테이너는 웹 기반 관리 대시보드를 제공하는 PostgreSQL 데이터베이스에 대한 플랫폼 간 client. 다음 예제를 고려하세요.

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres")
                      .WithPgAdmin();

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

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

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

앞의 코드는 docker.io/dpage/pgadmin4 이미지를 기반으로 컨테이너를 추가합니다. 컨테이너는 PostgreSQLserver 및 데이터베이스 리소스를 관리하는 데 사용됩니다. WithPgAdmin 메서드는 PostgreSQL 데이터베이스에 대한 웹 기반 관리 대시보드를 제공하는 컨테이너를 추가합니다.

PostgreSQL pgWeb 리소스 추가

AddPostgres 메서드를 사용하여 builder에 PostgreSQL 리소스를 추가할 때, sosedoff/pgweb 컨테이너를 추가하기 위해 WithPgWeb 호출을 연이어 수행할 수 있습니다. 이 컨테이너는 플랫폼 간 client을(를) 위한 PostgreSQL 데이터베이스에 대해 웹 기반 관리 대시보드를 제공합니다. 다음 예제를 고려하세요.

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres")
                      .WithPgWeb();

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

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

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

앞의 코드는 docker.io/sosedoff/pgweb 이미지를 기반으로 컨테이너를 추가합니다. 등록된 모든 PostgresDatabaseResource 인스턴스는 인스턴스당 구성 파일을 만드는 데 사용되며 각 구성은 pgweb 컨테이너 책갈피 디렉터리에 바인딩됩니다. 자세한 내용은 PgWeb 문서: Server 연결 책갈피참조하세요.

데이터 볼륨을 사용하여 PostgreSQLserver 리소스 추가

PostgreSQL server 리소스에 데이터 볼륨을 추가하려면 PostgreSQLserver 리소스에서 WithDataVolume 메서드를 호출합니다.

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres")
                      .WithDataVolume(isReadOnly: false);

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

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

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

데이터 볼륨은 컨테이너의 수명 주기 외부에서 PostgreSQLserver 데이터를 유지하는 데 사용됩니다. 데이터 볼륨은 PostgreSQLserver 컨테이너의 /var/lib/postgresql/data 경로에 탑재되고 name 매개 변수가 제공되지 않으면 이름이 임의로 생성됩니다. 데이터 볼륨에 대한 정보와바인딩 탑재보다 더 선호되는 이유에 대해 알아보려면 문서: 볼륨을 참조하세요.

데이터 바인드 마운트를 설정하여 PostgreSQLserver 리소스를 추가

PostgreSQL server 리소스에 데이터 바인딩 탑재를 추가하려면 WithDataBindMount 메서드를 호출합니다.

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres")
                      .WithDataBindMount(
                          source: @"C:\PostgreSQL\Data",
                          isReadOnly: false);

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

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

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

중요하다

데이터 바인딩 탑재 볼륨비해 기능이 제한되므로 성능, 이식성 및 보안이 향상되어 프로덕션 환경에 더 적합합니다. 그러나 바인딩 탑재를 사용하면 호스트 시스템의 파일에 직접 액세스하고 수정할 수 있으므로 실시간 변경이 필요한 개발 및 테스트에 적합합니다.

데이터 바인드 마운트는 호스트 컴퓨터의 파일 시스템을 사용하여 컨테이너 재시작을 넘어 PostgreSQLserver 데이터를 지속시킵니다. 데이터 바인드 마운트는 PostgreSQLserver 컨테이너의 호스트 기기에서 Windows의 C:\PostgreSQL\Data 경로(또는 Unix경로의 /PostgreSQL/Data)에 마운트됩니다. 데이터 바인딩 탑재에 대한 자세한 내용은 Docker 문서:탑재 바인딩을 참조하세요.

init bind mount을 사용하여 PostgreSQLserver 리소스 추가

초기 바인드 탑재를 PostgreSQLserver 리소스에 추가하려면 WithInitBindMount 메서드를 호출합니다.

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres")
                      .WithInitBindMount(@"C:\PostgreSQL\Init");

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

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

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

init 바인드 마운트는 호스트 머신의 파일 시스템을 이용하여 PostgreSQLserver 데이터베이스를 컨테이너의 init 폴더로 초기화합니다. 이 폴더는 postgres-data 폴더를 만든 후 실행 파일 셸 스크립트 또는 .sql 명령 파일을 실행하는 초기화에 사용됩니다. init 바인드 탑재는 PostgreSQLserver 컨테이너의 호스트 컴퓨터에서 Windows의 C:\PostgreSQL\Init(또는 Unix/PostgreSQL/Init) 경로에 탑재됩니다.

매개 변수를 사용하여 PostgreSQLserver 리소스 추가

컨테이너 이미지에서 사용하는 사용자 이름 및 암호를 명시적으로 제공하려는 경우 이러한 자격 증명을 매개 변수로 제공할 수 있습니다. 다음 대체 예제를 고려합니다.

var builder = DistributedApplication.CreateBuilder(args);

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

var postgres = builder.AddPostgres("postgres", username, password);
var postgresdb = postgres.AddDatabase("postgresdb");

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

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

매개 변수를 제공하는 방법에 대한 자세한 내용은 외부 매개 변수참조하세요.

통합 상태 검사를 위한 호스팅

PostgreSQL 호스팅 통합은 PostgreSQLserver 리소스에 대한 상태 검사를 자동으로 추가합니다. 상태 검사는 PostgreSQLserver이 실행 중인지와 연결이 설정될 수 있는지를 확인합니다.

호스팅 통합은 📦 AspNetCore.HealthChecks.Npgsql NuGet 패키지에 의존합니다.

Client 통합

.NET Aspire PostgreSQL Entity Framework Core client 통합을 시작하려면, client-consuming 프로젝트, 즉 PostgreSQLclient을 사용하는 애플리케이션의 프로젝트에서 📦AspireNpgsql.EntityFrameworkCore NuGet 패키지를PostgreSQL 설치합니다. .NET Aspire PostgreSQL Entity Framework Core client 통합은 원하는 DbContext 하위 클래스 인스턴스를 등록하여 PostgreSQL와 상호 작용할 수 있도록 합니다.

.NET CLI
PackageReference

dotnet add package Aspire.Npgsql.EntityFrameworkCore.PostgreSQL

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

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

client을 사용하는 프로젝트의 Program.cs 파일에서 IHostApplicationBuilder 상에서 DbContext 서브클래스를 등록하기 위해 AddNpgsqlDbContext 확장 메서드를 호출합니다. 이 서브클래스는 종속성 주입 컨테이너를 통해 사용할 수 있습니다. 메서드는 연결 이름 매개 변수를 사용합니다.

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

팁

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

작성기에서 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지원합니다. 구성 파일 예를 들어 appsettings.json에서 Aspire:Npgsql:EntityFrameworkCore:PostgreSQL 키를 사용해 NpgsqlEntityFrameworkCorePostgreSQLSettings을 로드합니다. Aspire:Npgsql:EntityFrameworkCore:PostgreSQL 섹션에서 구성을 설정한 경우 매개 변수를 전달하지 않고 메서드를 호출할 수 있습니다.

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

{
  "Aspire": {
    "Npgsql": {
      "EntityFrameworkCore": {
        "PostgreSQL": {
          "ConnectionString": "Host=myserver;Database=postgresdb",
          "DbContextPooling": true,
          "DisableHealthChecks": true,
          "DisableTracing": true
        }
      }
    }
  }
}

전체 PostgreSQLEntity Framework Coreclient 통합 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>",
          "DbContextPooling": true,
          "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 통합은 다음을 처리합니다.

DbContextHealthCheck를 추가하여 EF Core의 CanConnectAsync 메서드를 호출합니다. 상태 검사의 이름은 TContext 타입의 이름입니다.
/health HTTP 엔드포인트와 통합되며, 이 엔드포인트는 등록된 모든 상태 검사를 통과해야 애플리케이션이 트래픽을 수락할 준비가 된 것으로 간주된다고 지정합니다.

관찰 가능성 및 원격 분석

통합은 로깅, 추적 및 메트릭 구성을 자동으로 설정하며, 이를 관찰성핵심 요소라고도 . 통합 관찰 가능성 및 원격 분석에 대한 자세한 내용은 .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.Infrastructure
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 PostgreSQL 호스팅 통합

PostgreSQL 리소스를 Azure에 배포하려면, 📦Aspire호스팅AzurePostgreSQL NuGet 패키지를 설치하세요.

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.Azure.PostgreSQL

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

Azure PostgreSQL server 리소스 추가

.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 server 리소스를 AzurePostgres 유연한 Server로 배포하도록 구성합니다.

중요하다

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

인증된 Azure Npgsql client 추가

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

.NET CLI
PackageReference

dotnet add package Azure.Identity

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

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

다음을 통해 공유

.NET Aspire PostgreSQL Entity Framework Core 통합

호스팅 통합

PostgreSQL server 리소스 추가

PostgreSQL pgAdmin 리소스 추가

PostgreSQL pgWeb 리소스 추가

데이터 볼륨을 사용하여 PostgreSQLserver 리소스 추가

데이터 바인드 마운트를 설정하여 PostgreSQLserver 리소스를 추가

init bind mount을 사용하여 PostgreSQLserver 리소스 추가

매개 변수를 사용하여 PostgreSQLserver 리소스 추가

통합 상태 검사를 위한 호스팅

Client 통합

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

개선 기능을 사용하여 Npgsql 데이터베이스 컨텍스트 추가

구성

연결 문자열 사용

구성 공급자 사용

인라인 대리자 사용

여러 DbContext 클래스 구성

건강 검진

관찰 가능성 및 원격 분석

로깅

추적

메트릭

Azure PostgreSQL 호스팅 통합

Azure PostgreSQL server 리소스 추가

인증된 Azure Npgsql client 추가

참고

추가 리소스