| Oracle® Data Provider for .NET開発者ガイド 11g リリース2 (11.2.0.4) B66456-02 |
|
 前 |
 次 |
OracleCommandBuilderオブジェクトでは、データベースが更新される場合に、OracleDataAdapterに対して自動SQL生成が行われます。
クラスの継承
System.Object
System.MarshalByRefObject
System.ComponentModel.Component
System.Data.Common.DbCommandBuilder (ADO.NET 2.0専用)
OracleDataAccess.Client.OracleCommandBuilder
宣言
// ADO.NET 2.0: C# public sealed class OracleCommandBuilder : DbCommandBuilder
スレッド安全性
パブリック静的メソッドはスレッドセーフですが、インスタンス・メソッドではスレッド安全性は保証されません。
備考
OracleCommandBuilderでは、OracleDataAdapterのSelectCommandプロパティが設定されている場合、単一表の更新に対してSQL文が自動的に生成されます。DataSetに複数の表が含まれている場合、例外がスローされます。DataAdapterプロパティが設定されている場合は、OracleCommandBuilderがRowUpdatingイベントのリスナーとして自己登録します。一度に関連付けることができるのは、1つのOracleDataAdapterオブジェクトと1つのOracleCommandBuilderオブジェクトのみです。
INSERT、UPDATEまたはDELETE文を生成する場合、OracleCommandBuilderでは、必要なメタデータ・セットを取得するため、DataSet内のExtendedPropertiesが使用されます。メタデータの取得後にSelectCommandが変更された場合(最初の更新後など)、メタデータを更新するためRefreshSchemaメソッドがコールされる必要があります。
OracleCommandBuilderにより、最初にDataSetのExtendedPropertiesのメタデータが検索されます。メタデータがない場合、OracleCommandBuilderではOracleDataAdapterのSelectCommandプロパティによってメタデータが取得されます。
例
次の例では、EMP表の更新を実行しています。ここでは、OracleDataAdapter.Update()がコールされた場合のOracleDataAdapterオブジェクトに対するUpdateCommandを作成するために、OracleCommandBuilderオブジェクトが使用されています。
// C#
using System;
using System.Data;
using Oracle.DataAccess.Client;
class OracleCommandBuilderSample
{
static void Main()
{
string constr = "User Id=scott;Password=tiger;Data Source=oracle";
string cmdstr = "SELECT empno, sal from emp";
// Create the adapter with the selectCommand txt and the
// connection string
OracleDataAdapter adapter = new OracleDataAdapter(cmdstr, constr);
// Create the builder for the adapter to automatically generate
// the Command when needed
OracleCommandBuilder builder = new OracleCommandBuilder(adapter);
// Create and fill the DataSet using the EMP
DataSet dataset = new DataSet();
adapter.Fill(dataset, "EMP");
// Get the EMP table from the dataset
DataTable table = dataset.Tables["EMP"];
// Indicate DataColumn EMPNO is unique
// This is required by the OracleCommandBuilder to update the EMP table
table.Columns["EMPNO"].Unique = true;
// Get the first row from the EMP table
DataRow row = table.Rows[0];
// Update the salary
double sal = double.Parse(row["SAL"].ToString());
row["SAL"] = sal + .01;
// Now update the EMP using the adapter
// The OracleCommandBuilder will create the UpdateCommand for the
// adapter to update the EMP table
adapter.Update(dataset, "EMP");
Console.WriteLine("Row updated successfully");
}
}
要件
ネームスペース: Oracle.DataAccess.Client
アセンブリ: Oracle.DataAccess.dll
ODP.NETのバージョン: ODP.NET for .NET Framework 2.0またはODP.NET for .NET Framework 4
OracleCommandBuilderメンバーは次の表にリスト表示されています。
OracleCommandBuilderコンストラクタ
OracleCommandBuilderコンストラクタを、表5-8にリストします。
OracleCommandBuilder静的メソッド
OracleCommandBuilder静的メソッドを、表5-9にリストします。
表5-9 OracleCommandBuilder静的メソッド
| メソッド | 説明 |
|---|---|
|
|
指定した |
|
|
|
OracleCommandBuilderプロパティ
OracleCommandBuilderプロパティを、表5-10にリストします。
表5-10 OracleCommandBuilderプロパティ
| プロパティ | 説明 |
|---|---|
|
|
|
|
SQL文を生成するときにOracleオブジェクト名の前後に二重引用符を使用するかどうかを示します |
|
|
|
サポート対象外 |
|
|
サポート対象外 |
|
|
サポート対象外 |
|
SQL文が生成される |
|
|
|
開始文字、またはスペースや予約語などの特殊文字がその名前に含まれるデータベース・オブジェクトを指定するために使用する文字を指定します。 ADO.NET 2.0準拠のODP.NETでのみサポートされています。 |
|
|
終了文字、またはスペースや予約語などの特殊文字がその名前に含まれるデータベース・オブジェクトを指定するために使用する文字を指定します。 ADO.NET 2.0準拠のODP.NETでのみサポートされています。 |
|
|
スキーマ識別子と他の識別子の間のセパレータ用文字を指定します。 ADO.NET 2.0準拠のODP.NETでのみサポートされています。 |
|
|
|
OracleCommandBuilderパブリック・メソッド
OracleCommandBuilderパブリック・メソッドを、表5-11にリストします。
表5-11 OracleCommandBuilderパブリック・メソッド
| パブリック・メソッド | 説明 |
|---|---|
|
|
|
|
|
|
|
|
|
|
データベース上で削除を実行するSQL文( |
|
|
|
|
|
データベース上で挿入を実行するSQL文( |
|
|
|
|
|
|
|
|
データベース上で更新を実行するSQL文( |
|
|
|
|
|
|
適切にエスケープした識別子のすべての埋込み引用とともに、指定された非引用識別子の正しい引用形式を戻します。 ADO.NET 2.0準拠のODP.NETでのみサポートされています。 |
|
|
|
|
|
引用の目的で識別子に埋め込まれたエスケープ表記をいずれも削除し、指定された引用識別子の正しい非引用形式を戻します。 ADO.NET 2.0準拠のODP.NETでのみサポートされています。 |
|
|
|
OracleCommandBuilderイベント
OracleCommandBuilderイベントを、表5-12にリストします。
OracleCommandBuilderコンストラクタでは、OracleCommandBuilderクラスの新規インスタンスを作成します。
オーバーロード・リスト:
このコンストラクタでは、OracleCommandBuilderクラスのインスタンスを作成します。
OracleCommandBuilder(OracleDataAdapter)
このコンストラクタでは、OracleCommandBuilderクラスのインスタンスを作成し、DataAdapterプロパティを指定されたOracleDataAdapterオブジェクトに設定します。
このコンストラクタでは、OracleCommandBuilderクラスのインスタンスを作成します。
宣言
// C# public OracleCommandBuilder();
備考
デフォルトのコンストラクタ
OracleCommandBuilder静的メソッドを、表5-13にリストします。
表5-13 OracleCommandBuilder静的メソッド
| メソッド | 説明 |
|---|---|
|
|
指定した |
|
|
|
このメソッドは、指定したOracleCommandで表されるストアド・プロシージャまたは関数のパラメータに対する問合せを実行し、その戻り値をコマンドのOracleParameterCollectionに移入します。
宣言
// C#
public static void DeriveParameters(OracleCommand command);
パラメータ
command
パラメータが導出されるストアド・プロシージャまたは関数を表すコマンド
例外
InvalidOperationException - CommandTextがストアド・プロシージャまたは関数の有効な名前でないか、CommandTypeがCommandType.StoredProcedureでないか、Connection.StateがConnectionState.Openではありません。
備考
DeriveParametersを使用して、ストアド・ファンクションを表すOracleCommandオブジェクトのParameterコレクションを移入すると、このファンクションの戻り値が最初のパラメータ(OracleParameterCollectionの位置0)としてバインドされます。
DeriveParametersを使用できるのはストアド・プロシージャまたは関数に対してのみであり、無名PL/SQLブロックに対しては使用できません。
DeriveParametersを起動すると、コマンドのパラメータ・コレクション内の既存のパラメータがすべて削除されます。
DeriveParametersによりデータベース・ラウンドトリップが発生するため、このメソッドは設計時にのみ使用してください。本番環境での不必要なデータベース・ラウンドトリップを避けるには、設計時にDeriveParametersメソッドにより戻された明示的なパラメータ設定でDeriveParametersメソッド自体を置き換えるようにしてください。
DeriveParametersでストアド・プロシージャ名または関数名の大/小文字の区別が保持されるのは、名前が二重引用符で囲まれている場合のみです。たとえば、データベース内のストアド・プロシージャの名前が大/小文字の混在したGetEmployeesである場合、OracleCommandオブジェクトのCommandTextプロパティは、次の例のように適切に設定する必要があります。
cmd.CommandText = "\"GetEmployees\"";
パッケージ内のストアド・プロシージャおよび関数は、次の書式で指定する必要があります。
<package name>.<procedure or function name>
たとえば、EmpProcedures(大/小文字が混在)というパッケージ内のGetEmployees(大/小文字が混在)というストアド・プロシージャのパラメータを取得する場合、OracleCommandに指定する名前は次のとおりです。
"\"EmpProcedures\".\"GetEmployees\""
DeriveParameterをオブジェクト型のメソッドに使用することはできません。
導出されるパラメータには、ストアド・プロシージャを正しく実行するのに必要なすべてのメタデータ情報が含まれています。必要な場合は、アプリケーションで実行の前にパラメータの値を指定する必要があります。またアプリケーションでは、実行前にパラメータのメタデータ情報が変更される場合があります。たとえば、ストアド・プロシージャの実行を最適化するために、OracleParameterのSizeプロパティがPL/SQLのCHARおよびSTRING型に変更されます。
導出されるパラメータの出力値は、デフォルトでは.NETタイプとして戻されます。出力パラメータをプロバイダ・タイプとして取得するには、パラメータのOracleDbTypeプロパティをアプリケーションで明示的に設定して、このデフォルト動作をオーバーライドする必要があります。これを簡単に行う1つの方法として、プロバイダ・タイプとして戻す必要のある出力パラメータのすべてで、OracleDbTypeをそれ自体に設定するという方法があります。
指定したOracleCommandのBindByNameプロパティはそのまま残されますが、アプリケーションでその値を変更することができます。
指定したストアド・プロシージャまたは関数がオーバーロードの場合は、パラメータ・コレクションへの移入に最初のオーバーロードが使用されます。
// Database Setup
/*
connect scott/tiger@oracle
CREATE OR REPLACE PROCEDURE MyOracleStoredProc (arg_in IN VARCHAR2,
arg_out OUT VARCHAR2) IS
BEGIN
arg_out := arg_in;
END;
/
*/
// C#
using System;
using System.Data;
using Oracle.DataAccess.Client;
class DeriveParametersSample
{
static void Main()
{
// Create the PL/SQL Stored Procedure MyOracleStoredProc as indicated in
// the preceding Database Setup
string constr = "User Id=scott;Password=tiger;Data Source=oracle";
OracleConnection con = new OracleConnection(constr);
con.Open();
// Create an OracleCommand
OracleCommand cmd = new OracleCommand("MyOracleStoredProc", con);
cmd.CommandType = CommandType.StoredProcedure;
// Derive Parameters
OracleCommandBuilder.DeriveParameters(cmd);
Console.WriteLine("Parameters Derived");
// Prints "Number of Parameters for MyOracleStoredProc = 2"
Console.WriteLine("Number of Parameters for MyOracleStoredProc = {0}",
cmd.Parameters.Count);
// The PL/SQL stored procedure MyOracleStoredProc has one IN and
// one OUT parameter. Set the Value for the IN parameter.
cmd.Parameters[0].Value = "MyText";
// The application may modify the other OracleParameter properties also
// This sample uses the default Size for the IN parameter and modifies
// the Size for the OUT parameter
// The default size for OUT VARCHAR2 is 4000
// Prints "cmd.Parameters[1].Size = 4000"
Console.WriteLine("cmd.Parameters[1].Size = " + cmd.Parameters[1].Size);
// Set the Size for the OUT parameter
cmd.Parameters[1].Size = 6;
// Execute the command
cmd.ExecuteNonQuery();
// Prints "cmd.Parameters[1].Value = MyText"
Console.WriteLine("cmd.Parameters[1].Value = " + cmd.Parameters[1].Value);
con.Close();
con.Dispose();
}
}
例
OracleCommandBuilderプロパティを、表5-14にリストします。
表5-14 OracleCommandBuilderプロパティ
| プロパティ | 説明 |
|---|---|
|
|
|
|
SQL文を生成するときにOracleオブジェクト名の前後に二重引用符を使用するかどうかを示します |
|
|
|
サポート対象外 |
|
|
サポート対象外 |
|
|
サポート対象外 |
|
SQL文が生成される |
|
|
|
開始文字、またはスペースや予約語などの特殊文字がその名前に含まれるデータベース・オブジェクトを指定するために使用する文字を指定します。 ADO.NET 2.0準拠のODP.NETでのみサポートされています。 |
|
|
終了文字、またはスペースや予約語などの特殊文字がその名前に含まれるデータベース・オブジェクトを指定するために使用する文字を指定します。 ADO.NET 2.0準拠のODP.NETでのみサポートされています。 |
|
|
スキーマ識別子と他の識別子の間のセパレータ用文字を指定します。 ADO.NET 2.0準拠のODP.NETでのみサポートされています。 |
|
|
|
このプロパティでは、SQL文を生成する場合にOracleオブジェクト名(表または列など)の前後に二重引用符を使用するかどうかを指定します。
宣言
// C#
bool CaseSensitive {get; set;}
プロパティ値
二重引用符を使用するかどうかを示すbool
備考
デフォルト = false
このプロパティは、サポートされていません。
宣言
// ADO.NET 2.0: C#
public override CatalogLocation CatalogLocation {get; set;}
例外
NotSupportedException - このプロパティは、サポートされていません。
備考
このプロパティは、サポートされていません。
このプロパティは、サポートされていません。
宣言
// ADO.NET 2.0: C#
public override string CatalogSeparator {get; set;}
例外
NotSupportedException - このプロパティは、サポートされていません。
備考
このプロパティは、サポートされていません。
このプロパティは、サポートされていません。
宣言
// ADO.NET 2.0: C#
public override string ConflictOption {get; set;}
例外
NotSupportedException - このプロパティは、サポートされていません。
備考
このプロパティは、サポートされていません。
このプロパティでは、SQL文が生成されるOracleDataAdapterオブジェクトを示します。
宣言
// C#
OracleDataAdapter DataAdapter{get; set;}
プロパティ値
OracleDataAdapterオブジェクト。
備考
デフォルト = null
このプロパティでは、名前にスペースまたは予約語などの特殊文字が含まれるデータベース・オブジェクトの指定に使用される開始文字または文字を指定します。
宣言
// ADO.NET 2.0: C#
public override string QuotePrefix {get; set;}
プロパティ値
開始文字または使用する文字。デフォルト値は"\""です。
備考
このプロパティは、OracleConnectionまたはOracleCommandオブジェクトのいずれからも独立しています。
このプロパティでは、終了文字、またはスペースや予約語などの特殊文字がその名前に含まれているデータベース・オブジェクトを指定する文字を指定します。
宣言
// ADO.NET 2.0: C#
public override string QuoteSuffix {get; set;}
プロパティ値
終了文字または使用する文字。デフォルト値は"\""です。
備考
このプロパティは、OracleConnectionまたはOracleCommandオブジェクトのいずれからも独立しています。
このプロパティでは、スキーマ識別子と他の識別子の間のセパレータ用文字を指定します。
宣言
// ADO.NET 2.0: C#
public override string SchemaSeparator {get; set; }
プロパティ値
スキーマ・セパレータとして使用される文字。
例外
NotSupportedException - 入力値はピリオド(.)ではありません。
備考
デフォルトのスキーマ・セパレータはピリオド(.)です。このプロパティで受容可能な値はピリオド(.)のみです。
このプロパティは、OracleConnectionまたはOracleCommandオブジェクトのいずれからも独立しています。
例
// C#
using System;
using System.Data;
using System.Data.Common;
using Oracle.DataAccess.Client;
class SchemaSeperatorSample
{
static void Main(string[] args)
{
try
{
OracleCommandBuilder cmdBuilder = new OracleCommandBuilder();
//schemaSeparator is dot(.)
Console.WriteLine("schemaSeparator is {0}",
cmdBuilder.SchemaSeparator);
//set the schemaseparator, only '.' is allowed.
cmdBuilder.SchemaSeparator = ".";
// the only acceptable value for this property is a dot (.)
// Hence the following line will throw NotSupportedException
cmdBuilder.SchemaSeparator = "!";
}
catch (Exception ex)
{
Console.WriteLine(ex.Message);
Console.WriteLine(ex.StackTrace);
}
}
}
OracleCommandBuilderパブリック・メソッドを、表5-15にリストします。
表5-15 OracleCommandBuilderパブリック・メソッド
| パブリック・メソッド | 説明 |
|---|---|
|
|
|
|
|
|
|
|
|
|
データベース上で削除を実行するSQL文( |
|
|
|
|
|
データベース上で挿入を実行するSQL文( |
|
|
|
|
|
|
|
|
データベース上で更新を実行するSQL文( |
|
|
|
|
|
|
適切にエスケープした識別子のすべての埋込み引用とともに、指定された非引用識別子の正しい引用形式を戻します。 ADO.NET 2.0準拠のODP.NETでのみサポートされています。 |
|
|
|
|
|
引用の目的で識別子に埋め込まれたエスケープ表記をいずれも削除し、指定された引用識別子の正しい非引用形式を戻します。 ADO.NET 2.0準拠のODP.NETでのみサポートされています。 |
|
|
|
このメソッドでは、OracleDataAdapterでアプリケーションがUpdate()を呼び出すときにデータベース上で削除を実行するSQL文(CommandText)が含まれている、自動生成されたOracleCommandオブジェクトを取得します。
宣言
// C# public OracleCommand GetDeleteCommand();
戻り値
OracleCommand
例外
ObjectDisposedException - OracleCommandBuilderオブジェクトはすでに処理されています。
InvalidOperationException - SelectCommandまたはDataAdapterプロパティのいずれかがNULL、または主キーをOracleDataAdapterのSelectCommandプロパティから取得できない場合。
このメソッドでは、OracleDataAdapterでアプリケーションがUpdate()を呼び出すときにデータベース上で挿入を実行するSQL文(CommandText)を含んでいる、自動生成されたOracleCommandオブジェクトを取得します。
宣言
// C# public OracleCommand GetInsertCommand();
戻り値
OracleCommand
例外
ObjectDisposedException - OracleCommandBuilderオブジェクトはすでに処理されています。
InvalidOperationException - SelectCommandまたはDataAdapterプロパティのいずれかがNULL、または主キーをOracleDataAdapterのSelectCommandプロパティから取得できない場合。
このメソッドでは、OracleDataAdapterでアプリケーションがUpdate()を呼び出すときにデータベース上で更新を実行するSQL文(CommandText)を含んでいる、自動生成されたOracleCommandオブジェクトを取得します。
宣言
// C# public OracleCommand GetUpdateCommand();
戻り値
OracleCommand
例外
ObjectDisposedException - OracleCommandBuilderオブジェクトはすでに処理されています。
InvalidOperationException - SelectCommandまたはDataAdapterプロパティのいずれかがNULL、または主キーをOracleDataAdapterのSelectCommandプロパティから取得できない場合。
適切にエスケープされた識別子に引用を組み込んで、指定された非引用識別子の正しい引用形式を戻します。
宣言
// ADO.NET 2.0: C#
public override string QuoteIdentifier(string unquotedIdentifier);
パラメータ
UnquotedIdentifier
非引用識別子文字列。
戻り値
識別子の引用バージョン。識別子内の埋込み引用は適切にエスケープされています。
例外
ArgumentNullException - 入力パラメータはNullです。
備考
このメソッドは、OracleConnectionまたはOracleCommandオブジェクトのいずれからも独立しています。
例
// C#
using System;
using System.Data;
using System.Data.Common;
using Oracle.DataAccess.Client;
class QuoteIdentifierSample
{
static void Main(string[] args)
{
OracleCommandBuilder builder = new OracleCommandBuilder();
string quoteIdentifier = builder.QuoteIdentifier("US\"ER");
//quoteIdentifier for "US\"ER" is (\"US\"\"ER\")
Console.WriteLine("quoteIdentifier is {0}" , quoteIdentifier);
}
}
このメソッドでは、INSERT、UPDATEまたはDELETE文の生成に使用されるデータベース・スキーマ情報をリフレッシュします。
宣言
// ADO.NET 2.0: C# public override void RefreshSchema();
備考
OracleDataAdapterオブジェクトのSelectCommand値が変更されると、常にアプリケーションによってRefreshSchemaが呼び出されます。
このメソッドは、引用の目的で識別子に埋め込まれたエスケープ表記をいずれも削除し、指定された引用識別子の正しい非引用形式を戻します。
宣言
// ADO.NET 2.0: C#
public override string UnquoteIdentifier(string quotedIdentifier);
パラメータ
quotedIdentifier
引用されている文字列識別子。
戻り値
埋め込まれた引用エスケープ表記がいずれも削除済の非引用識別子。
例外
ArgumentNullException - 入力パラメータはNullです。
ArgumentException - 入力パラメータは空です。
備考
このメソッドは、OracleConnectionまたはOracleCommandオブジェクトのいずれからも独立しています。
例
// C#
using System;
using System.Data;
using System.Data.Common;
using Oracle.DataAccess.Client;
class UnQuoteIdentifierSample
{
static void Main(string[] args)
{
//create an OracleCommandBuilder object.
OracleCommandBuilder builder = new OracleCommandBuilder();
string identifier = "US\"ER";
Console.WriteLine("Identifier is {0}", identifier);
// quote the identifier
string quoteIdentifier = builder.QuoteIdentifier(identifier);
//quoteIdentifier of "US\"ER" is (\"US\"\"ER\")
Console.WriteLine("QuotedIdentifier is {0}" , quoteIdentifier);
string unquoteIdentifier = builder.UnquoteIdentifier(quoteIdentifier);
//And its unquoteIdentifier is US\"ER
Console.WriteLine("UnquotedIdentifier is {0}" , unquoteIdentifier);
}
}
