Application Program Interface

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

• DatabaseFacadeクラス

• DbContextOptionsBuilderクラス

• IQueryingEnumerableインタフェース

• MigrationBuilderクラス

• ModelBuilderクラス

• OracleSQLCompatibilityの列挙

• ベクトル用のデータベース関数(EF.Functions)

DatabaseFacadeクラス

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

• DatabaseFacade.IsOracle

• DatabaseFacade.EnsureCreated

• DatabaseFacade.EnsureCreated(string[])

• DatabaseFacade.EnsureDeleted

• DatabaseFacade.EnsureDeleted(string[])

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

• UseOracle(string connectionString)

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

• UseOracleSQLCompatibility(enum version)

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(enum version)

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

Oracle EF Core 21.12.1以降、UseOracleSQLCompatibility拡張メソッドで文字列値ではなく列挙型を引数として取るようになりました。

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

• OracleSQLCompatibility.DatabaseVersion19

• OracleSQLCompatibility.DatabaseVersion21

• OracleSQLCompatibility.DatabaseVersion23

デフォルトでは、SQL互換性の値はOracleSQLCompatibility.DatabaseVersion21です。そのため、生成されたSQLはデータベース・バージョン21と互換性があります。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 21cの場合、デフォルトはOracleSQLCompatibility.DatabaseVersion21です。

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

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

ノート:

• optionsBuilderはDbContextOptionsBuilder型です。

• この拡張メソッドは、EF Core 8の場合にのみ存在します。

IQueryingEnumerableインタフェース

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

• IQueryingEnumerable.ToQueryString拡張メソッド

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()

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と同義です。

OracleSQLCompatibilityの列挙

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

現在、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 21cの場合、デフォルトはOracleSQLCompatibility.DatabaseVersion21です。

ベクトル用のデータベース関数(EF.Functions)

EF Coreのプロバイダには、データベース関数を呼び出すカスタムC#メソッドを設定できます。これらのメソッドは、LINQでEF.Functionsの拡張メソッドとして使用できます。ODP.NETでは、ベクトル・データの管理用にこれらが多数提供されています。これらのベクトル・メソッドは、Oracle EF Coreバージョン23.6以上でEF Core 9以上の場合に使用できます。ベクトル機能では、Oracle Database 23ai以上に接続し、OracleSQLCompatibilityをDatabaseVersion23以上に設定する必要があります。

• VectorDistance

• VectorEmbedding

• ToVector

VectorDistance

このメソッドは、指定した2つのベクトル間の距離を計算します。

宣言

// C# - 2 overloaded methods
public static double VectorDistance(object expression1, object expression2)
public static double VectorDistance(object expression1, object expression2, string metric)

パラメータ

expression1およびexpression2は、距離を計算する2つのベクトルを表します。

metricは、距離の計算に使用するメトリックを示す文字列です。

戻り値

メトリック形式の2つのベクトル間の距離を示すSystem.Double

例外

• いずれかの引数値がnullの場合、ArgumentNullExceptionがスローされます。

• いずれかの引数値が空の文字列の場合、ArgumentExceptionがスローされます。

• 無効な引数値が渡されると、OracleExceptionがデータベース・エラー・メッセージとともにスローされます。

備考

このメソッドでは、Oracle VECTOR_DISTANCEデータベース関数を使用します。

両方のベクトル・パラメータで、ディメンションの数およびベクトル形式が同じである必要があります。これは、VECTOR_DISTANCE関数の要件です。列式、変数またはインライン文字列を指定できます。

指定可能な距離メトリック値:

• Cosine (Default)

• Dot

• Euclidean

• Euclidean_Squared

• Hamming

• Jaccard

• Manhattan

メトリック・パラメータを変数として使用する場合は、VECTOR_DISTANCEデータベース関数のメトリック引数は文字列ではなくメトリック式であるため、メトリック・パラメータをEF.Constant()メソッドに入れる必要があります。

サンプル・コード

var query1 = (from t in ctx.AIData
              where t.Id == 10
              select EF.Functions.VectorDistance(t.V, vector, "Cosine")).ToList();
 
 
var distanceType= "Cosine";
var query2 = (from t in ctx.AIData
              where t.Id == 10
              select EF.Functions.VectorDistance(t.V, vector, EF.Constant(distanceType))).ToList();

関連項目:

Oracle SQL VECTOR_DISTANCEデータベース関数

VectorEmbedding

このメソッドは、指定したモデルを使用して入力文字列のベクトル埋込みを返します。

宣言

// C#
public static object VectorEmbedding(string modelName, object expression)

パラメータ

modelNameは、ベクトル埋込みを生成するための、埋込みのインポート元のモデルです。

expressionは、埋込みを生成するための元の値です。

戻り値

指定した式のベクトル形式の埋込みを示すSystem.Object。

例外

• いずれかの引数値がnullの場合、ArgumentNullExceptionがスローされます。

• いずれかの引数値が空の文字列の場合、ArgumentExceptionがスローされます。

• 無効な引数値が渡されると、OracleExceptionがデータベース・エラー・メッセージとともにスローされます。

備考

このメソッドでは、Oracle VECTOR_EMBEDDINGデータベース関数を使用します。

modelNameは、データベース内のものと同じにしてください。EF Coreのこのメソッドを使用する前に、モデルをデータベースにロードしておく必要があります。

modelNameには、インライン文字列または変数を指定できます。変数の場合は、パラメータ化を防ぐためにEF.Constant()メソッドに入れてください。modelNameは式であり、VECTOR_EMBEDDINGデータベース関数の文字列ではありません。

式の引数には、列、変数またはインライン文字列を指定できます。

サンプル・コード

string keyword = “cars”;
var query1 = (from t in ctx.AIData
                  select EF.Functions.VectorEmbedding("doc_model", keyword)).Take(1).ToList();
  
var modelName = "doc_model"
var query2 = (from t in ctx.AIData
                     select EF.Functions.VectorEmbedding(EF.Constant(modelName), keyword)).Take(1).ToList();

関連項目:

Oracle SQL VECTOR_EMBEDDINGデータベース関数

ToVector

このメソッドは、1つの形式から別の形式にベクトルを変換します。

宣言

// C# - 3 overloaded methods
public static object ToVector(object expression)
public static object ToVector(object expression, long dimensions)
public static object ToVector(object expression, long dimensions, string format)

パラメータ

expressionは、別のベクトル形式に変換するベクトルです。

dimensionsは、新しいベクトルのディメンション数を表す数値です。

formatは、ベクトルの変換先のベクトル数値形式です。

戻り値

指定したベクトル数値形式のSystem.Object。

例外

• いずれかの引数値がnullの場合、ArgumentNullExceptionがスローされます。

• いずれかの引数値が空の文字列の場合、ArgumentExceptionがスローされます。

• 無効な引数値が渡されると、OracleExceptionがデータベース・エラー・メッセージとともにスローされます。

備考

このメソッドでは、Oracle TO_VECTORデータベース関数を使用します。

expressionには、列、変数またはベクトル形式のインライン文字列を指定できます。

ディメンションの数は、zero (0)と指定することもできます。この場合、ディメンション番号は式によって決まります。

指定可能なベクトル形式の値:

• Binary

• Int8

• Float32

• Float64

• *

これはベクトルの変換先のターゲット・ベクトル数値形式です。形式値が指定されていないかアスタリスク(*)の場合は、FLOAT32形式が使用されます。

ディメンションまたは形式を変数として使用するには、EF.Constant()メソッドにそれらを入れます。

関連項目:

Oracle SQL TO_VECTORデータベース関数