.NET Aspire Oracle Entity Framework Core 統合

[アーティクル]
02/21/2025

含まれるもの: ホスティング統合と統合Client

Oracle データベースは、Oracleが所有および開発した広く使用されているリレーショナルデータベース管理システムです。 .NET Aspire Oracle Entity Framework Core 統合により、既存の Oracle サーバーに接続したり、.NET コンテナーイメージを使用してから新しいサーバーを作成したりできます。

ホスティング統合

.NET Aspire Oracle ホスティング統合は、サーバーを OracleDatabaseServerResource の種類として、データベースを OracleDatabaseResource の種類としてモデル化します。これらの型と API にアクセスするには、📦Aspire.Hosting. の NuGet パッケージOracle をアプリホストプロジェクトに追加します。

.NET コマンドラインインターフェース
PackageReference

dotnet add package Aspire.Hosting.Oracle

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

詳細については、「dotnet パッケージの追加」または「.NET アプリケーションでのパッケージの依存関係の管理」を参照してください。

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 クライアント統合を開始するには、📦Aspireをインストールします。Oracle.EntityFrameworkCore クライアントを使用するプロジェクト、つまり、Oracle クライアントを使用するアプリケーションのプロジェクトの NuGet パッケージです。 Oracle クライアント統合では、DbContextとの対話に使用できる Oracle インスタンスが登録されます。

.NET コマンドラインインターフェース
PackageReference

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データベースのコンテキストを充実させる

標準の Entity Framework メソッドを使用してデータベースコンテキストを取得し、依存関係挿入コンテナーに追加することもできます。

builder.Services.AddDbContext<ExampleDbContext>(options =>
    options.UseOracle(builder.Configuration.GetConnectionString("oracledb")
        ?? throw new InvalidOperationException("Connection string 'oracledb' not found.")));

手記

GetConnectionString メソッドに渡す接続文字列名は、アプリホストプロジェクトに Oracle リソースを追加するときに使用する名前と一致する必要があります。詳細については、「Oracle サーバーおよびデータベースリソース追加する」を参照してください。

次に例を示すように、この方法でデータベースコンテキストを作成する際の柔軟性が向上します。

データベースコンテキストの既存の構成コードは、.NET.NET Aspire用に書き換えることなく再利用できます。
Entity Framework Core インターセプターを使用して、データベース操作を変更できます。
コンテキストプール Entity Framework Core 使用しないことを選択できます。状況によってはパフォーマンスが向上する可能性があります。

このメソッドを使用する場合は、.NET メソッドを呼び出すことで、.NET AspireEnrichOracleDatabaseDbContextスタイルの再試行、正常性チェック、ログ記録、テレメトリ機能を使用してデータベースコンテキストを拡張できます。

builder.EnrichOracleDatabaseDbContext<ExampleDbContext>(
    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ホスティング統合もヘルスチェックエンドポイントを有効にします。詳細については、以下を参照してください。

C#でのアプリ正常性チェック .NET
ASP.NET Core での正常性チェック

既定では、.NET AspireOracleEntity Framework Core 統合によって次の処理が行われます。

OracleEntityFrameworkCoreSettings.DisableHealthChecks が trueされているかどうかを確認します。
その場合は、DbContextHealthCheckを追加し、EF Core's CanConnectAsync メソッドを呼び出します。ヘルスチェックの名前は、TContext 型の名前です。

可観測性とテレメトリ

統合により、ログ記録、トレース、メトリックの構成が自動的に設定されます。これは、監視の柱とも呼ばれます。統合の可観測性とテレメトリの詳細については、統合の概要参照してください。バッキングサービスによっては、一部の統合でこれらの機能の一部のみがサポートされる場合があります。たとえば、一部の統合ではログ記録とトレースがサポートされますが、メトリックはサポートされません。テレメトリ機能は、「構成」セクションに記載されている手法を使用して無効にすることもできます。

伐採

.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

次の方法で共有

.NET Aspire Oracle Entity Framework Core 統合

ホスティング統合

Oracleのサーバーリソースとデータベースリソースを追加する

パスワードパラメーター Oracle リソースを追加する

データボリューム Oracle リソースを追加する

データバインドマウントを用いてOracleリソースを追加する

ホスティング統合の正常性チェック

Client 統合

クライアント Oracle 追加する

Oracleデータベースのコンテキストを充実させる

構成

接続文字列を使用する

構成プロバイダーを使用する

インラインデリゲートを使用する

構成オプション

Client 統合ヘルスチェック

可観測性とテレメトリ

伐採

トレーシング

メトリック

関連項目

その他のリソース

次の方法で共有

.NET Aspire Oracle Entity Framework Core 統合

ホスティング統合

Oracleのサーバーリソースとデータベースリソースを追加する

パスワード パラメーター Oracle リソースを追加する

データ ボリューム Oracle リソースを追加する

データバインドマウントを用いてOracleリソースを追加する

ホスティング統合の正常性チェック

Client 統合

クライアント Oracle 追加する

Oracleデータベースのコンテキストを充実させる

構成

接続文字列を使用する

構成プロバイダーを使用する

インライン デリゲートを使用する

構成オプション

Client 統合ヘルスチェック

可観測性とテレメトリ

伐採

トレーシング

メトリック

関連項目

その他のリソース

パスワードパラメーター Oracle リソースを追加する

データボリューム Oracle リソースを追加する

インラインデリゲートを使用する