.NET Aspire Oracle Entity Framework Core 통합

아티클
01/27/2025

Oracle DatabaseOracle소유하고 개발한 널리 사용되는 관계형 데이터베이스 관리 시스템입니다. .NET Aspire Oracle Entity Framework Core 통합을 사용하면 기존 Oracle 서버에 연결하거나 .NET 컨테이너 이미지를 사용하여 새 서버를 만들 수 있습니다.

호스팅 통합

.NET Aspire Oracle 호스팅 통합은 서버를 OracleDatabaseServerResource 형식으로, 데이터베이스를 OracleDatabaseResource 형식으로 모델화합니다. 이러한 형식과 API에 액세스하려면 📦 프로젝트에서 AspireOracle호스팅 NuGet 패키지를 추가합니다.

.NET CLI
패키지참조

dotnet add package Aspire.Hosting.Oracle

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

자세한 내용은 dotnet add package 또는 manage package dependencies in .NET applications.

Oracle 서버 및 데이터베이스 리소스 추가

앱 호스트 프로젝트에서 AddOracle 호출하여 Oracle 서버 리소스 작성기를 추가하고 반환합니다. 반환된 리소스 빌더에 호출을 연결하여 AddDatabase서버 리소스에 Oracle 데이터베이스를 추가합니다.

var builder = DistributedApplication.CreateBuilder(args);

var oracle = builder.AddOracle("oracle")
                    .WithLifetime(ContainerLifetime.Persistent);

var oracledb = oracle.AddDatabase("oracledb");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(oracledb);
       .WaitFor(oracledb);

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

메모

Oracle 데이터베이스 컨테이너는 시작 속도가 느려질 수 있으므로 불필요한 다시 시작을 방지하기 위해 영구 수명을 사용하는 것이 가장 좋습니다. 자세한 내용은 컨테이너 리소스 수명참조하세요.

.NET .NET Aspire container-registry.oracle.com/database/free 이미지와 함께 이전 예제와 같이 앱 호스트에 컨테이너 이미지를 추가하는 경우 로컬 컴퓨터에 새 Oracle 서버를 만듭니다. Oracle 리소스 작성기(oracle 변수)에 대한 참조는 데이터베이스를 추가하는 데 사용됩니다. 데이터베이스의 이름이 oracledb로 지정되고 그 후 ExampleProject에 추가됩니다. Oracle 리소스에는 password 메서드를 사용하여 생성된 임의 CreateDefaultPasswordParameter 포함됩니다.

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

팁

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

암호 매개 변수를 사용하여 Oracle 리소스 추가

Oracle 리소스에는 임의 암호가 있는 기본 자격 증명이 포함됩니다. Oracle 환경 변수 ORACLE_PWD사용하여 구성 기반 기본 암호를 지원합니다. 암호를 명시적으로 제공하려는 경우 다음 매개 변수로 제공할 수 있습니다.

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

var oracle = builder.AddOracle("oracle", password)
                    .WithLifetime(ContainerLifetime.Persistent);

var oracledb = oracle.AddDatabase("oracledb");

var myService = builder.AddProject<Projects.ExampleProject>()
                       .WithReference(oracledb)
                       .WaitFor(oracledb);

앞의 코드는 AddOracle API에 전달할 매개 변수를 가져오고 내부적으로 ORACLE_PWD 컨테이너의 Oracle 환경 변수에 매개 변수를 할당합니다. password 매개 변수는 일반적으로 사용자 비밀지정됩니다.

{
  "Parameters": {
    "password": "Non-default-P@ssw0rd"
  }
}

자세한 내용은외부 매개 변수를 참조하세요.

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

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

var builder = DistributedApplication.CreateBuilder(args);

var oracle = builder.AddOracle("oracle")
                    .WithDataVolume()
                    .WithLifetime(ContainerLifetime.Persistent);

var oracledb = oracle.AddDatabase("oracle");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(oracledb)
       .WaitFor(oracledb);

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

데이터 볼륨은 컨테이너의 수명 주기 외부에서 Oracle 데이터를 유지하는 데 사용됩니다. 데이터 볼륨은 /opt/oracle/oradata 컨테이너의 Oracle 경로에 탑재되고 name 매개 변수가 제공되지 않으면 이름이 임의로 생성됩니다. 데이터 볼륨에 대한 자세한 내용 및 바인딩 탑재보다 선호하는 이유에 대한 자세한 내용은 Docker 문서: 볼륨참조하세요.

경고

암호는 데이터 볼륨에 저장됩니다. 데이터 볼륨을 사용하는 경우 암호가 변경되면 볼륨을 삭제할 때까지 작동하지 않습니다.

데이터 바인딩 탑재를 사용하여 Oracle 리소스 추가

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

var builder = DistributedApplication.CreateBuilder(args);

var oracle = builder.AddOracle("oracle")
                    .WithDataBindMount(source: @"C:\Oracle\Data");

var oracledb = oracle.AddDatabase("oracledb");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(oracledb)
       .WaitFor(oracledb);

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

중요하다

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

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

통합 시스템의 호스팅 건강 검사

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

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

Client 통합

데이터베이스에 액세스하려면 Oracle 데이터베이스 및 연결 문자열이 필요합니다. .NET Aspire Oracle 클라이언트 통합을 시작하려면, 클라이언트를 사용하는 애플리케이션에 대한 프로젝트, 즉 📦 클라이언트를 사용하는 프로젝트에서 Oracle NuGet 패키지를 설치합니다. Oracle 클라이언트 통합은 DbContext상호 작용하는 데 사용할 수 있는 Oracle 인스턴스를 등록합니다.

.NET CLI
패키지참조

dotnet add package Aspire.Oracle.EntityFrameworkCore

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

Oracle 클라이언트 추가

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

builder.AddOracleDatabaseDbContext<ExampleDbContext>(connectionName: "oracledb");

팁

connectionName 매개 변수는 앱 호스트 프로젝트에 Oracle 데이터베이스 리소스를 추가할 때 사용되는 이름과 일치해야 합니다. 즉, AddDatabase을 호출하고 oracledb의 이름을 제공할 때, AddOracleDatabaseDbContext를 호출할 때도 동일한 이름을 사용해야 합니다. 자세한 내용은 Oracle 서버 및 데이터베이스 리소스추가를 참조하세요.

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

public class ExampleService(ExampleDbContext context)
{
    // Use database context...
}

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

보강을 사용하여 Oracle 데이터베이스 컨텍스트 추가

자동 재시도, 상태 검사, 로깅 및 원격 분석과 같은 추가 서비스로 DbContext 보강하려면 EnrichOracleDatabaseDbContext 메서드를 호출합니다.

builder.EnrichOracleDatabaseDbContext<ExampleDbContext>(
    connectionName: "oracledb",
    configureSettings: settings =>
    {
        settings.DisableRetry = false;
        settings.CommandTimeout = 30 // seconds
    });

settings 매개 변수는 OracleEntityFrameworkCoreSettings 클래스의 인스턴스입니다.

구성

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

연결 문자열 사용

ConnectionStrings 구성 섹션에서 연결 문자열을 사용하는 경우 builder.AddOracleDatabaseDbContext<TContext>()호출할 때 연결 문자열의 이름을 제공합니다.

builder.AddOracleDatabaseDbContext<ExampleDbContext>("oracleConnection");

연결 문자열은 ConnectionStrings 구성 섹션에서 검색됩니다.

{
  "ConnectionStrings": {
    "oracleConnection": "Data Source=TORCL;User Id=OracleUser;Password=Non-default-P@ssw0rd;"
  }
}

EnrichOracleDatabaseDbContext는 호출 시점에 ConnectionStrings가 등록되어 있기를 기대하기 때문에 DbContext 구성 섹션을 사용하지 않습니다.

자세한 내용은 ODP.NET 설명서참조하세요.

구성 공급자 사용

.NET Aspire Oracle Entity Framework Core 통합은 Microsoft.Extensions.Configuration 키를 사용하여 appsettings.json 같은 구성 파일의 Aspire:Oracle:EntityFrameworkCore 지원합니다. Aspire:Oracle:EntityFrameworkCore 섹션에서 구성을 설정한 경우 매개 변수를 전달하지 않고 메서드를 호출할 수 있습니다.

다음은 사용 가능한 옵션 중 일부를 구성하는 appsettings.json 예입니다.

{
  "Aspire": {
    "Oracle": {
      "EntityFrameworkCore": {
        "DisableHealthChecks": true,
        "DisableTracing": true,
        "DisableRetry": false,
        "CommandTimeout": 30
      }
    }
  }
}

팁

CommandTimeout 속성은 초 단위입니다. 앞의 예제와 같이 설정하면 시간 제한은 30초입니다.

인라인 대리자 사용

Action<OracleEntityFrameworkCoreSettings> 델리게이트를 전달하여 일부 또는 모든 옵션을 인라인으로 설정할 수 있으며, 예를 들어 코드 내에서 상태 검사를 비활성화할 수 있습니다.

builder.AddOracleDatabaseDbContext<ExampleDbContext>(
    "oracle",
    static settings => settings.DisableHealthChecks  = true);

또는

builder.EnrichOracleDatabaseDbContext<ExampleDbContext>(
    static settings => settings.DisableHealthChecks  = true);

구성 옵션

해당 기본값을 사용하여 구성할 수 있는 옵션은 다음과 같습니다.

이름	묘사
`ConnectionString`	연결할 Oracle 데이터베이스의 연결 문자열입니다.
`DisableHealthChecks`	데이터베이스 상태 검사가 비활성화되어 있는지를 나타내는 부울 값입니다.
`DisableTracing`	OpenTelemetry 추적이 비활성화되었는지 여부를 나타내는 부울 값입니다.
`DisableRetry`	명령 재시도를 사용하지 않도록 설정해야 하는지 여부를 나타내는 부울 값입니다.
`CommandTimeout`	명령이 실행되기를 기다리는 시간(초)입니다.

Client 통합 시스템 상태 점검

기본적으로 .NET.NET Aspire클라이언트 통합에는 모든 서비스에 대해 상태 검사 사용하도록 설정될 있습니다. 마찬가지로, 많은 .NET.NET Aspire호스팅 통합도 상태 검사 엔드포인트를 활성화합니다. 자세한 내용은 다음을 참조하세요.

.NET C# 애플리케이션 상태 검사
의 ASP.NET Core 상태 검사

기본적으로 .NET AspireOracleEntity Framework Core 통합은 다음을 처리합니다.

OracleEntityFrameworkCoreSettings.DisableHealthChecks이 true인지 확인합니다.
이 경우 DbContextHealthCheckEF Core 메서드를 호출하는 CanConnectAsync추가합니다. 건강 검진의 이름은 TContext 형식의 이름입니다.

관찰 가능성 및 원격 분석

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

로깅

.NET Aspire Oracle Entity Framework Core 통합은 다음 로그 범주를 사용합니다.

Microsoft.EntityFrameworkCore.ChangeTracking
Microsoft.EntityFrameworkCore.Database.Command
Microsoft.EntityFrameworkCore.Database.Connection
Microsoft.EntityFrameworkCore.Database.Transaction
Microsoft.EntityFrameworkCore.Infrastructure
Microsoft.EntityFrameworkCore.Migrations
Microsoft.EntityFrameworkCore.Model
Microsoft.EntityFrameworkCore.Model.Validation
Microsoft.EntityFrameworkCore.Query
Microsoft.EntityFrameworkCore.Update

추적

.NET Aspire Oracle Entity Framework Core 통합은 OpenTelemetry을 사용하여 다음 추적 활동을 출력합니다.

OpenTelemetry.Instrumentation.EntityFrameworkCore

메트릭스

.NET Aspire Oracle Entity Framework Core 통합은 현재 다음 메트릭을 지원합니다.

Microsoft.EntityFrameworkCore

다음을 통해 공유