1. 開発者ガイド
  2. Oracle Data Provider for .NET Entity Framework Core
  3. Application Program Interface

Application Program Interface

ODP.NET EF Coreは、標準のEF Core Application Program Interfaceをサポートしています。プロバイダには、プロバイダに固有の追加の拡張メソッドが含まれています。

DatabaseFacadeクラス

ODP.NET EF Coreには、追加の拡張メソッド、およびDatabaseFacadeクラスのメソッドのデフォルト動作に対する変更が含まれています。

DatabaseFacade.IsOracle

ODP.NETが現在使用されているデータベース・プロバイダの場合、このメソッドはtrueを戻します。

// C#
public static bool IsOracle()

ブール値を戻します。

ノート:

プロバイダは、DbContextにプロバイダが設定された後にのみ認識されます。

DatabaseFacade.EnsureCreated

このプロパティによって、現在のコンテキストに定義されたスキーマの表が存在することが保証されます。

宣言

// C#
public static bool EnsureCreated()

戻り値

bool

備考

スキーマ内にいずれかの表が存在する場合は、何も処理が実行されません。既存の表は、EF Coreコンテキスト・モデルとの互換性がチェックされません。

スキーマ内に表が存在しない場合は、すべての定義済コンテキスト・モデル・オブジェクトが作成されます。

接続文字列に指定されたユーザー/スキーマが存在しない場合は、エラーがスローされ、ユーザー/スキーマを作成する処理は実行されません。管理者は、このメソッドを使用する前に、ユーザー/スキーマを作成して、適切な権限を割り当てる必要があります。

コンテキストに定義されたすべてのオブジェクトが作成される場合、戻り値はtrueです。スキーマにいずれかの表がすでに存在する場合は、falseです。

例外

存在しないユーザー/スキーマが接続文字列で指定された場合は、NotSupportedException()がスローされます。

タイプ: NotSupportedException()

メッセージ: 必要なユーザーが存在しないか、指定されたユーザー名/パスワードが無効です

DatabaseFacade.EnsureCreated(string[])

このプロパティによって、文字列配列内の指定されたスキーマの表が存在することが保証されます。

宣言

// C#
public static bool EnsureCreated (string[] schemas)

パラメータ

  • schemas – EF Coreコンテキストの既存の表をチェックするスキーマのリスト。スキーマ名は大/小文字が区別されます。

戻り値

bool

備考

文字列配列スキーマ・リスト内にいずれかの表が存在する場合は、何も処理が実行されません。既存の表は、EF Coreコンテキスト・モデルとの互換性がチェックされません。

文字列配列スキーマ・リスト内に表が存在しない場合は、すべての定義済コンテキスト・モデル・オブジェクトが作成されます。

接続文字列に指定されたユーザー/スキーマが存在しない場合は、エラーがスローされ、ユーザー/スキーマを作成する処理は実行されません。管理者は、このメソッドを使用する前に、ユーザー/スキーマを作成して、適切な権限を割り当てる必要があります。

このメソッドに渡されたスキーマに、接続文字列に指定されたユーザー/スキーマが含まれない場合、そのスキーマは暗黙的にスキーマの配列に追加されます。

スキーマの配列がNULLまたは長さ0 (ゼロ)の場合は、DatabaseFacade.EnsureCreated() APIがコールされます。

コンテキストに定義されたすべてのオブジェクトが作成される場合、戻り値はtrueです。スキーマにいずれかの表がすでに存在する場合は、falseです。

例外

存在しないユーザー/スキーマが接続文字列で指定された場合は、NotSupportedException()がスローされます。

タイプ: NotSupportedException()

メッセージ: 必要なユーザーが存在しないか、指定されたユーザー名/パスワードが無効です

サンプル・コード

using (var db = DbContext())
{
    db.Database.EnsureCreated(new string[]{"SCOTT", "HR", "EFUser"});
}

DatabaseFacade.EnsureDeleted

このプロパティによって、スキーマ・ユーザーの作成したオブジェクトがすべて削除されることが保証されます。

宣言

// C#
public static bool EnsureDeleted()

戻り値

bool

備考

EF Coreコンテキスト・モデル・オブジェクトが存在しない場合は、何も処理が実行されません。オブジェクトが存在する場合、Oracleデータ・ディクショナリ・オブジェクトを除いて、すべてのユーザー/スキーマ・オブジェクトが削除されます。

警告: 削除されたオブジェクトには、EF Coreコンテキスト・モデル以外のスキーマ・オブジェクトが含まれます(ユーザー/スキーマにこれらのオブジェクトを削除する権限がある場合)。

現在のコンテキストで定義されたスキーマが存在しない場合は、何も処理が実行されません。

現在のコンテキストでスキーマに関連するユーザー作成オブジェクトをすべて削除しようとする場合、戻り値はtrueです。接続文字列に指定されたスキーマが存在しない場合は、falseです。

DatabaseFacade.EnsureDeleted(string[])

このプロパティによって、文字列配列内の指定されたスキーマのユーザー/スキーマ・オブジェクトが削除されることが保証されます。

宣言

// C#
public static bool EnsureCreated (string[] schemas)

パラメータ

  • schemas – ユーザー生成オブジェクトを削除するスキーマのリスト。スキーマ名は大/小文字が区別されます。

戻り値

bool

備考

オブジェクトが存在する場合、Oracleデータ・ディクショナリ・オブジェクトを除いて、すべてのユーザー/スキーマ・オブジェクトが削除されます。EF Coreコンテキスト・モデル・オブジェクトが存在しない場合は、何も処理が実行されません。このメソッドに渡されたスキーマに、接続文字列に指定されたユーザー/スキーマが含まれない場合、そのスキーマは暗黙的にスキーマの配列に追加されます。

警告: 削除されたオブジェクトには、EF Coreコンテキスト・モデル以外のスキーマ・オブジェクトが含まれます(ユーザー/スキーマにこれらのオブジェクトを削除する権限がある場合)。

指定されたスキーマが存在しない場合は、何も処理が実行されません。

指定されたスキーマ内でユーザーが権限を持つユーザー作成オブジェクトをすべて削除しようとする場合、戻り値はtrueです。接続文字列に指定されたスキーマが存在しない場合は、falseです。

サンプル・コード

using (var db = DbContext())
{
    db.Database.EnsureDeleted(new string[]{"SCOTT", "HR", "EFUser"});
}

DbContextOptionsBuilderクラス

ODP.NET EF Coreには、追加の拡張メソッド、およびDbContextOptionsBuilderクラスのメソッドのデフォルト動作に対する変更が含まれています。

DbContextOptionsBuilder.UseOracle

この拡張メソッドは、Oracle Databaseに接続するためのプロバイダおよびデータベース接続構成を設定します。開発者は、ODP.NET Coreで使用可能なすべての接続文字列属性を設定できます。コールできる使用可能なメソッドのオーバーロードは、次のとおりです。

  • UseOracle(string connectionString)
  • UseOracle(string connectionString, Action<OracleDbContextOptionsBuilder> oracleOptionsAction = null)
  • UseOracle(DbConnection connection, Action<OracleDbContextOptionsBuilder> oracleOptionsAction = null)
  • DbContextOptionsBuilder<TContext> UseOracle<TContext>(string connectionString, Action<OracleDbContextOptionsBuilder> oracleOptionsAction = null)
  • DbContextOptionsBuilder<TContext> UseOracle<TContext>(DbConnection connection,Action<OracleDbContextOptionsBuilder> oracleOptionsAction = null)
  • UseOracle(DbContextOptionsBuilder, Action<OracleDbContextOptionsBuilder> oracleOptionsAction = null)

UseOracle(string connectionString)

この拡張メソッドは、プロバイダおよびデータベース接続構成を設定します。開発者は、ODP.NET Coreで使用可能なすべての接続文字列属性を設定できます。

宣言

// C#
optionsBuilder.UseOracle(@"User Id=blog;Password=<password>;Data Source=pdborcl;");

UseOracle(DbContextOptionsBuilder, Action<OracleDbContextOptionsBuilder> oracleOptionsAction = null)

次の拡張機能は、最初にDbConnectionや接続文字列を設定せずにOracleデータベースに接続するようにEFコア・コンテキストを構成します。DbConnectionまたは接続文字列は、DbContextがデータベースへの接続を試行する前に設定する必要があります。接続を設定するには、RelationalDatabaseFacadeExtensions.SetDbConnectionまたはRelationalDatabaseFacadeExtensions.SetConnectionStringを使用します。

宣言

// C#
public static DbContextOptionsBuilder UseOracle(this DbContextOptionsBuilder,  Action<OracleDbContextOptionsBuilder>)

パラメータ

  • DbContextOptionsBuilder - コンテキストの構成に使用されるビルダー

  • Action<OracleDbContextOptionsBuilder> - Oracle固有の追加構成を許可するオプションの処理

戻り値

オプション・ビルダーを使用して、さらに構成を連鎖できます。

サンプル・コード

// C# - Setting up the DB context
protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder) => optionsBuilder.UseOracle(); 
// Using the DB context
using (var context = new DbContext()) 
{ 
context.Database.SetDbConnection(new OracleConnection(<connection string>)); 
}

ノート:

  • optionsBuilderはDbContextOptionsBuilder型です。

  • Oracle組込みアカウントを使用してEntity Frameworkの移行を保存しないでください。

UseOracleSQLCompatibility(string version)

この拡張メソッドは、生成されたSQLおよび機能と互換性のあるデータベース・バージョンを指定します。

ノート:

このメソッドは非推奨です。Oracle EF Core 8では、メソッドUseOracleSQLCompatibility(enum version)を使用してOracle Databaseの互換性バージョンを設定します。

ODP.NET 21cは、引き続きEF Core 6および7にUseOracleSQLCompatibility(string version)を使用します。

このメソッドでは、値"12"がデフォルトとして使用されます。生成されたSQLは、データベース・バージョン12以降と互換性があります。他の値はメソッドの動作を変更しません。 

// C#
optionsBuilder.UseOracle("User Id=hr;Password=<password>;Data Source = inst1", b =>
b.UseOracleSQLCompatibility("12"));

ノート:

optionsBuilderはDbContextOptionsBuilder型です。

UseOracleSQLCompatibility(enum version)

OracleSQLCompatibilityの列挙は、生成されたSQLと互換性があるデータベース・バージョンを指定するために使用されます。また、.NETタイプのタイプ・マッピングを決定するためにも使用されます。

Oracle EF Core 23cを使用するEF Core 8以上のバージョンでは、UseOracleSQLCompatibility拡張メソッドでは、文字列値ではなく列挙型を引数として取るようになりました。

現在、UseOracleSQLCompatibility() APIを使用してアプリケーションに設定できるSQLCompatibilityには3つの値があります。

使用できる有効な列挙値を次に示します。

  • OracleSQLCompatibility.DatabaseVersion19

  • OracleSQLCompatibility.DatabaseVersion21

  • OracleSQLCompatibility.DatabaseVersion23

Oracle EF Core 8をOracleSQLCompatibility.DatabaseVersion21とともに使用する場合、JSONデータベース列がサポートされます。それ以外の場合、集計タイプはJSONではなくデータベースのNCLOB列にマップされます。

OracleSQLCompatibility.DatabaseVersion23を使用すると、.NETブール型はデフォルトでNUMBER(1)ではなくOracle BOOLEAN列型にマップされます。.NETブールをデフォルトでNUMBER(1)にマップするには、OracleSQLCompatibility.DatabaseVersion21以降を使用します。

デフォルトの列挙値は、ODP.NETバージョンと一致します。ODP.NET 23cの場合、デフォルトはOracleSQLCompatibility.DatabaseVersion23です。

次の例に、UseOracleSQLCompatibilityを設定する方法を示します。 

// C#
optionsBuilder.UseOracle("User Id=hr;Password=<password>;Data Source = inst1", b =>
b.UseOracleSQLCompatibility(OracleSQLCompatibility.DatabaseVersion19));

ノート:

optionsBuilderはDbContextOptionsBuilder型です。

IQueryingEnumerableインタフェース

この項の内容は次のとおりです。

IQueryingEnumerable.ToQueryString拡張メソッド

使用されるOracle SQL問合せの文字列表現。この拡張メソッドにより、Oracle DatabaseおよびOracle Autonomous Databaseで実行可能なSQLが生成されます。

生成されたSQLをプログラムで実行するために、開発者は特定の要件に対して次のC#疑似コードを適合させることができます。疑似コードは、サンプルLINQ問合せでToQueryString()を使用してスクリプトを生成する方法と、OracleCommandを使用してスクリプトを実行する方法を示しています。これはアプリケーションをバックアップするデータベース・バージョンによって異なります。 

using System.Data;
using Microsoft.EntityFrameworkCore;
using Oracle.ManagedDataAccess.Client;

class ToQueryStringPseudoCode
{
    static void Main(string[] args)
    {
        using (ModelContext db = new ModelContext())
        {
            //sample LINQ to convert query string from
            string name = "Name";
            var query = db.Set<Instructor>().Where(c => c.Name == name);
            string sqltext = query.ToQueryString();

            //’sqltext’ can be used directly with OracleCommand
            OracleConnection con = new OracleConnection("<Connection String>");
            con.Open();
            OracleCommand cmd = con.CreateCommand();
            cmd.CommandText = sqltext;
            OracleDataReader reader;
            reader = cmd.ExecuteReader();

            //verifying the result set
            while (reader.Read())
            {
                Console.WriteLine($"{reader[0]}, {reader[1]}, {reader[2]}, {reader[3]}");
            }
            con.Close();
        }
    }
}

MigrationBuilderクラス

MigrationBuilder.IsOracle拡張メソッド

MigrationBuilderオブジェクトがデータベース・プロバイダとしてODP.NETを使用する場合、trueを返します。

宣言

public static bool IsOracle(this MigrationBuilder)

パラメータ

  • MigrationBuilderオブジェクト

戻り値

bool。

サンプル・コード

var migrationBuilder = new MigrationBuilder("Oracle.EntityFrameworkCore"); 
bool b_oracle = migrationBuilder.IsOracle();  //returns true for ODP.NET

ModelBuilderクラス

ODP.NET EF Coreには、追加の拡張メソッド、およびModelBuilderクラスのメソッドのデフォルト動作に対する変更が含まれています。

ModelBuilder UseIdentityColumn()およびUseOracleIdentityColumn()

この拡張メソッドは、UseOracleSQLCompatibility()に渡される値に応じて、列がID列か、またはサーバー生成列値を保持するために順序とトリガーに関連付けられているかを指定します。デフォルトでは、この拡張メソッドは列で有効ではありません。 

// C #
protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.Entity<Blog>().Property(p => p.Id).UseIdentityColumn();
}

EF Core 3.1以降のバージョンの場合は、UseIdentityColumnを使用します。EF Core 3.1 Core以前のバージョンの場合は、UseOracleIdentityColumnを使用できます。EF Core 5以降、UseOracleIdentityColumnはOracle EF Coreでは使用できません。これら2つのメソッドには同じ機能があります。この項の残りの部分では、UseIdentityColumnという用語はUseOracleIdentityColumnと同義です。