.NET Aspire PostgreSQL Entity Framework Core 통합

포함:호스팅 통합 및 Client 통합

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

호스팅 통합

PostgreSQL 호스팅 통합은 다양한 PostgreSQL 리소스를 다음과 같은 형식으로 모델화합니다.

• PostgresServerResource
• PostgresDatabaseResource
• PgAdminContainerResource
• PgWebContainerResource

앱 호스트 프로젝트에서 이 형식들과 API를 리소스로 표현할 수 있도록 하려면, 📦Aspire.Hosting.PostgreSQL NuGet 패키지를 설치하십시오.

.NET CLI

dotnet add package Aspire.Hosting.PostgreSQL

PackageReference

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

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

PostgreSQL 서버 리소스 추가

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

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 이미지와 함께 이전 예제와 같이 앱 호스트에 컨테이너 이미지를 추가하는 경우 로컬 컴퓨터에 새 PostgreSQL 서버 인스턴스를 만듭니다. PostgreSQL 서버 및 PostgreSQL 데이터베이스 인스턴스(postgresdb 변수)에 대한 참조는 ExampleProject종속성을 추가하는 데 사용됩니다. PostgreSQL 서버 리소스에는 username이 "postgres"인 기본 자격 증명이 포함되어 있으며 password이 CreateDefaultPasswordParameter 메서드를 사용하여 임의로 생성됩니다.

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

팁

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

PostgreSQL pgAdmin 리소스 추가

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

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 이미지를 기반으로 컨테이너를 추가합니다. 컨테이너는 PostgreSQL 서버 및 데이터베이스 리소스를 관리하는 데 사용됩니다. WithPgAdmin 메서드는 PostgreSQL 데이터베이스에 대한 웹 기반 관리 대시보드를 제공하는 컨테이너를 추가합니다.

pgAdmin 호스트 포트 구성

pgAdmin 컨테이너에 대한 호스트 포트를 구성하려면 PostgreSQL 서버 리소스에서 WithHostPort 메서드를 호출합니다. 다음 예제에서는 pgAdmin 컨테이너에 대한 호스트 포트를 구성하는 방법을 보여줍니다.

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres")
                      .WithPgAdmin(pgAdmin => pgAdmin.WithHostPort(5050));

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

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

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

위의 코드는 pgAdmin 컨테이너에 대한 호스트 포트를 추가하고 구성합니다. 그렇지 않으면 호스트 포트가 임의로 할당됩니다.

PostgreSQL pgWeb 리소스 추가

PostgreSQL 메서드를 사용하여 builder에 AddPostgres 리소스를 추가할 때, WithPgWeb 컨테이너를 추가하기 위해 호출을 연이어 수행할 수 있습니다. 이 컨테이너는 웹 기반 관리 대시보드를 제공하는 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 연결 책갈피참조하세요.

pgWeb 호스트 포트 구성

pgWeb 컨테이너에 대한 호스트 포트를 구성하려면 PostgreSQL 서버 리소스에서 WithHostPort 메서드를 호출합니다. 다음 예제에서는 pgAdmin 컨테이너에 대한 호스트 포트를 구성하는 방법을 보여줍니다.

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres")
                      .WithPgAdmin(pgWeb => pgWeb.WithHostPort(5050));

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

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

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

위의 코드는 pgWeb 컨테이너에 대한 호스트 포트를 추가하고 구성합니다. 그렇지 않으면 호스트 포트가 임의로 할당됩니다.

데이터 볼륨을 사용하여 PostgreSQL 서버 리소스 추가

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

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

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

데이터 바인드 마운트를 사용하여 PostgreSQL 서버 리소스를 추가합니다.

PostgreSQL 서버 리소스에 데이터 바인딩 탑재를 추가하려면 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...

중요하다

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

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

init bind mount을 사용하여 PostgreSQL 서버 리소스 추가

PostgreSQL 서버 리소스에 init 바인딩 탑재를 추가하려면 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 바인드 마운트는 호스트 컴퓨터의 파일 시스템을 사용하여 컨테이너의 PostgreSQL 폴더를 통해 서버 데이터베이스를 초기화합니다. 이 폴더는 초기화에 사용되며, postgres-data 폴더를 만든 후 실행 파일 셸 스크립트 또는 .sql 명령 파일을 실행합니다. init 바인드 마운트는 C:\PostgreSQL\Init 서버 컨테이너의 호스트 컴퓨터에서 Windows의 /PostgreSQL/Init 경로(또는 Unix의 PostgreSQL 경로)에 마운트됩니다.

매개 변수를 사용하여 PostgreSQL 서버 리소스 추가

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

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 호스팅 통합은 PostgreSQL 서버 리소스에 대한 상태 검사를 자동으로 추가합니다. 상태 검사는 PostgreSQL 서버가 실행 중이며 서버에 대한 연결을 설정할 수 있는지 확인합니다.

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

Client 통합

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

.NET CLI

dotnet add package Aspire.Npgsql.EntityFrameworkCore.PostgreSQL

PackageReference

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

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는 호출되는 시점에 ConnectionStrings가 등록될 것으로 예상하기 때문에 DbContext 구성 섹션을 사용하지 않습니다.

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

구성 공급자 사용

.NET Aspire PostgreSQL Entity Framework Core 통합은 Microsoft.Extensions.Configuration지원합니다. 구성 파일 예를 들어 NpgsqlEntityFrameworkCorePostgreSQLSettings에서 appsettings.json 키를 사용해 Aspire:Npgsql:EntityFrameworkCore:PostgreSQL을 로드합니다. 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
          }
        }
      }
    }
  }
}

그런 다음 AddNpgsqlDbContext 형식 매개 변수를 사용하여 AnotherDbContext 메서드를 호출하면 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.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

참고

• PostgreSQL 문서들
• .NET Aspire Azure PostgreSQL Entity Framework Core 통합
• .NET .NET Aspire 통합
• .NET Aspire GitHub 리포지토리