Oracle® Data Provider for .NET開発者ガイド ODAC 12c リリース4 (12.1.0.2) for Microsoft Windows E72575-01 |
|
前 |
次 |
OracleBulkCopy
オブジェクトは別のデータ・ソースからOracle表にデータを効率的に一括ロードまたはコピーします。
クラスの継承
System.Object
System.OracleBulkCopy
宣言
// C# public sealed class OracleBulkCopy : IDisposable
要件
プロバイダ | ODP.NET管理対象外ドライバ |
アセンブリ | Oracle.DataAccess.dll |
ネームスペース | Oracle.DataAccess.Client |
.NET Framework | 3.5, 4.0, 4.5, 4.6 |
スレッド安全性
パブリック静的メソッドはスレッドセーフですが、インスタンス・メソッドではスレッド安全性は保証されません。
備考
OracleBulkCopy
クラスは、Oracle Database表にのみデータを書き込む際に使用できます。ただし、データ・ソースに制限はありません。データがDataTable
インスタンスにロードされるか、IDataReader
インスタンスで読込み可能であるかぎりデータ・ソースは使用されます。
コピー先番号列への文字列データの一括コピーは、現在サポートされていません。
OracleBulkCopy
メンバーは次の表にリストされています。
OracleBulkCopyコンストラクタ
OracleBulkCopy
コンストラクタを、表17-1にリストします。
OracleBulkCopyプロパティ
OracleBulkCopy
プロパティを、表17-2にリストします。
表17-2 OracleBulkCopyプロパティ
プロパティ | 説明 |
---|---|
|
バッチとしてデータベースに送信される行数を指定します |
|
一括コピー操作の動作を識別する |
|
中断される前に一括コピー操作が完了するまでの秒数を指定します |
|
データ・ソースと保存先表間の列マッピングを指定します |
|
Oracle Databaseが一括コピー操作の実行に使用する |
|
データがロードされるデータベース・パーティションを指定します |
|
データがロードされるデータベース表を指定します |
|
通知イベントが生成される前に処理された行数を定義します |
OracleBulkCopyパブリック・メソッド
OracleBulkCopy
パブリック・メソッドを、表17-3にリストします。
表17-3 OracleBulkCopyパブリック・メソッド
メソッド | 説明 |
---|---|
|
|
|
オブジェクトにより割り当てられたリソースまたはメモリーを解除します |
|
保存先表に行をコピーします |
OracleBulkCopyイベント
OracleBulkCopy
イベントを、表17-4にリストします。
OracleBulkCopy
コンストラクタでは、OracleBulkCopy
クラスの新規インスタンスを作成します。
オーバーロード・リスト:
OracleBulkCopy(OracleConnection)
このコンストラクタでは、指定された接続とOracleBulkCopyOptions
のデフォルト値を使用してOracleBulkCopy
クラスの新規インスタンスがインスタンス化されます。
このコンストラクタでは、指定されたconnectionString
およびOracleBulkCopyOptions
のデフォルト値に基づいてOracleBulkCopy
の新規インスタンスがインスタンス化されます。
OracleBulkCopy(OracleConnection, OracleBulkCopyOptions)
このコンストラクタでは、指定された接続オブジェクトとOracleBulkCopyOptions
の値を使用してOracleBulkCopy
の新規インスタンスがインスタンス化されます。
OracleBulkCopy(string, OracleBulkCopyOptions)
このコンストラクタでは、指定されたconnectionString
およびOracleBulkCopyOptions
の値に基づいてOracleConnection
の新規インスタンスがインスタンス化されます。
このコンストラクタでは、指定された接続とデフォルトのOracleBulkCopyOptions
の列挙値を使用してOracleBulkCopy
クラスの新規インスタンスがインスタンス化されます。
宣言
// C#
public OracleBulkCopy(OracleConnection connection);
パラメータ
connection
一括コピー操作を実行するOracleConnection
のオープン・インスタンス。
例外
ArgumentNullException
- connectionパラメータがNULLです。
InvalidOperationException
- 接続がオープン状態ではありません。
備考
このコンストラクタに渡される接続オブジェクトはオープンされている必要があります。OracleBulkCopy
インスタンスがクローズされると、オープンのままとなります。
このコンストラクタでは、デフォルトの列挙値OracleBulkCopyOptions.Default
が使用されます。
Connection
プロパティは指定した接続に設定されます。
このコンストラクタでは、指定されたconnectionString
に基づいて最初にOracleConnection
オブジェクトを作成し、次にOracleConnection
オブジェクトおよびOracleBulkCopyOptions
デフォルト値を使用して新規のOracleBulkCopy
を初期化して、OracleBulkCopy
クラスの新規インスタンスがインスタンス化されます。
宣言
// C#
public OracleBulkCopy(string connectionString);
パラメータ
connectionString
Oracle Databaseへの接続および一括コピー操作の実行に使用される接続情報。
例外
ArgumentNullException
- connectionString
パラメータがNullです。
ArgumentException
- connectionString
パラメータが空です。
備考
WriteToServer
メソッドは、接続がまだオープンでない場合に接続を開きます。OracleBulkCopy
インスタンスがクローズされると、接続も自動的にクローズされます。
このコンストラクタでは、デフォルトの列挙値OracleBulkCopyOptions.Default
が使用されます。
Connection
プロパティは、指定したconnectionString
を使用して初期化されるOracleConnection
オブジェクトに設定されます。
このコンストラクタでは、指定された接続オブジェクトとOracleBulkCopyOptions
の値を使用してOracleBulkCopy
の新規インスタンスがインスタンス化されます。
宣言
// C# public OracleBulkCopy(OracleConnection connection, OracleBulkCopyOptions copyOptions);
パラメータ
connection
一括コピー操作を実行するOracleConnection
オブジェクトのオープン・インスタンス。
copyOptions
OracleBulkCopy
オブジェクトの動作を識別するOracleBulkCopyOptions
の列挙値の組合せ。
例外
ArgumentNullException
- connection
パラメータがNULLです。
InvalidOperationException
- 接続がオープン状態ではありません。
備考
このコンストラクタに渡される接続はオープンされている必要があります。OracleBulkCopy
インスタンスがクローズされると、オープンのままとなります。
Connection
プロパティは指定した接続に設定されます。
このコンストラクタでは、指定されたconnectionString
に基づいて最初にOracleConnection
オブジェクトを作成し、次にOracleConnection
オブジェクトおよび指定されたOracleBulkCopyOptions
の列挙値を使用して新規のOracleBulkCopy
オブジェクトを初期化して、OracleBulkCopy
クラスの新規インスタンスがインスタンス化されます。
宣言
// C# public OracleBulkCopy(string connectionString, OracleBulkCopyOptions copyOptions);
パラメータ
connectionString
一括コピー操作を実行するためにOracle Databaseに接続する際に使用される接続情報。
copyOptions
一括コピー操作の動作を識別するOracleBulkCopyOptions
の列挙値の組合せ。
例外
ArgumentNullException
- connectionString
はNullです。
ArgumentException
- connectionString
パラメータが空です。
備考
このコンストラクタでは、OracleConnection
クラスの新規インスタンスを使用してOracleBulkCopy
クラスの新規インスタンスを初期化します。OracleBulkCopy
インスタンスはcopyOptions
パラメータで指定されたオプションに従って動作します。
OracleBulkCopy
インスタンスがクローズされると、接続も自動的にクローズされます。
Connection
プロパティは、指定したconnectionString
を使用して初期化されるOracleConnection
オブジェクトに設定されます。
OracleBulkCopy
プロパティを、表17-5にリストします。
表17-5 OracleBulkCopyプロパティ
プロパティ | 説明 |
---|---|
|
バッチとしてデータベースに送信される行数を指定します |
|
一括コピー操作の動作を識別する |
|
中断される前に一括コピー操作が完了するまでの秒数を指定します |
|
データ・ソースと保存先表間の列マッピングを指定します |
|
Oracle Databaseが一括コピー操作の実行に使用する |
|
データがロードされるデータベース・パーティションを指定します |
|
データがロードされるデータベース表を指定します |
|
通知イベントが生成される前に処理された行数を定義します |
このプロパティは、バッチとしてデータベースに送信される行数を指定します。
宣言
// C# public int BatchSize {get; set;}
プロパティ値
バッチとしてデータベースに送信される行数の整数値。
例外
ArgumentOutOfRangeException
- バッチ・サイズがゼロ未満です。
備考
デフォルト値はゼロで、複数のバッチでは行はデータベースに送信されないことを示します。行セット全体が1回のバッチで送信されます。
バッチ・サイズを大きくすると、データベース・ラウンドトリップは減少しますが、クライアント側のメモリーの消費量も大きくなります。メモリーを消費しすぎると、マシン全体のパフォーマンスが低下し、アクセス可能なメモリーが処理中に不足してエラーになる場合もあります。クライアント側のメモリーを過剰に消費しないように注意してください。これはバッチ・サイズを小さくして回避できます。
バッチは、BatchSize
の行数が処理されるか、データベースに送信する行がなくなると完了します。
BatchSize
>
0
で、UseInternalTransaction
一括コピー・オプションが指定されていると、各一括コピー操作のバッチがトランザクション内に発生します。一括コピー操作の実行に使用される接続がすでにトランザクションの一部である場合、InvalidOperationException
例外が発生します。
BatchSize
>
0
でUseInternalTransaction
オプションが指定されていない場合は、行はサイズBatchSize
の複数のバッチではデータベースに送信されませんが、トランザクション関連のアクションは実行されません。
BatchSize
プロパティの設定はいつでも可能です。一括コピーがすでに実行中である場合、現在のバッチ・サイズは前のバッチ・サイズによって決定されます。後続のバッチには新規のバッチ・サイズが使用されます。
BatchSize
プロパティが最初はゼロで、WriteToServer
操作の実行中に変更された場合、その操作は単一バッチとしてデータにロードされます。同じOracleBulkCopy
インスタンス上で実行される次回以降のWriteToServer
操作では、新規のBatchSize
が使用されます。
このプロパティはOracleBulkCopyOptions
の列挙値を指定し、一括コピー操作の動作を決定します。
宣言
// C# public OracleBulkCopyOptions BulkCopyOptions {get; set;}
プロパティ値
一括コピー操作の動作を定義するOracleBulkCopyOptions
の列挙オブジェクト。
例外
ArgumentNullException
- 一括コピー・オプション・セットはNULLです。
備考
このプロパティのデフォルト値はOracleBulkCopyOptions.Default
の値です。このプロパティは、一括コピー操作のバッチ間の一括コピー・オプションの変更に使用できます。
このプロパティは、中断される前に一括コピー操作が完了するまでの秒数を指定します。
宣言
// C# public int BulkCopyTimeout {get; set;}
プロパティ値
一括コピー操作がタイムアウトした後の秒数の整数値。
例外
ArgumentOutOfRangeException
- タイムアウト値はゼロ未満に設定されています。
備考
デフォルト値は30秒です。
BatchSize
>0
の場合、前のバッチでデータベースに送信された行はコミットされたままです。現在のバッチで処理される行はデータベースに送信されません。BatchSize=0
である場合データベースに送信される行はありません。
このプロパティは、データ・ソースと保存先表間の列マッピングを指定します。
宣言
// C# public OracleBulkCopyColumnMappingCollection ColumnMappings {get;}
プロパティ値
ソースと保存先表間の列マッピングを定義するOracleBulkCopyColumnMappingCollection
オブジェクト。
備考
ColumnMappings
コレクションは、データ・ソースおよび保存先表がそれぞれ同じ列数で、各ソース列の順序位置が対応する保存先列の順序位置に一致する場合は必要ありません。しかし、列の数が違ったり順序位置が一致しない場合は、データが正しい列にコピーされるか確認するためにColumnMappings
コレクションを使用する必要があります。
一括コピー操作の実行中は、このコレクションにアクセスはできますが変更はできません。
デフォルトでは、このプロパティは列マッピングの空のコレクションを指定します。
このプロパティは、Oracle Databaseが一括コピー操作の実行に使用するOracleConnection
オブジェクトを指定します。
宣言
// C# public OracleConnection Connection {get; }
プロパティ値
一括コピー操作に使用されるOracleConnection
オブジェクト。
備考
OracleBulkCopy
オブジェクトが接続文字列を使用して初期化されると、このプロパティによってOracleBulkCopy
で構成される接続が取得されます。
このプロパティは、データがロードされるデータベース・パーティションを指定します。
宣言
// C# public string DestinationPartitionName {get; set;}
プロパティ値
保存先パーティション名を識別する文字列値。
備考
DestinationPartitionName
がWriteToServer
操作が実行中に変更されると、その変更は現在の操作には影響しません。新規のDestinationPartitionName
値は次回のWriteToServer
メソッドのコール時に使用されます。
このプロパティは、データがロードされるデータベース表を指定します。
宣言
// C# public string DestinationTableName {get; set;}
プロパティ値
保存先表名を識別する文字列値。
例外
ArgumentNullException
- 保存先表名のセットがNullです。
ArgumentException
- 保存先表名が空です。
備考
DestinationTableName
がWriteToServer
操作が実行中に変更されると、その変更は現在の操作には影響しません。新規のDestinationTableName
値は次回のWriteToServer
メソッドのコール時に使用されます。
このプロパティは通知イベントが生成される前に処理された行数を定義します。
宣言
// C# public int NotifyAfter {get; set;}
プロパティ値
通知イベントが発生するまでに処理対象として指定された行数の整数値。
例外
ArgumentOutOfRangeException
- プロパティ値がゼロ未満の数値に設定されています。
備考
このプロパティのデフォルト値はゼロで、通知イベントが生成されないことを示します。
このプロパティは、一括コピー操作の進行を表示するユーザー・インタフェース・コンポネントで取得されます。NotifyAfter
プロパティの設定は一括コピー操作中であってもいつでも可能です。変更は、同じインスタンスでの次回の通知および次回の操作から有効となります。
OracleBulkCopy
メソッドを、表17-6にリストします。
表17-6 OracleBulkCopyパブリック・メソッド
メソッド | 説明 |
---|---|
|
|
|
オブジェクトにより割り当てられたリソースまたはメモリーを解除します |
|
保存先表に行をコピーします |
このメソッドは、OracleBulkCopy
インスタンスをクローズします。
宣言
// C# public void Close();
例外
InvalidOperationException
- Close
メソッドはOracleRowsCopied
イベントからコールされました。
備考
Close
メソッドがOracleBulkCopy
オブジェクトでコールされると、後続の操作は行われません。WriteToServer
メソッドをコールしてInvalidOperationException
をスローします。接続がOracleBulkCopy
オブジェクトによってオープンされている、つまり、接続文字列を取得するコンストラクタによってOracleBulkCopy
オブジェクトが作成された場合は、Close
メソッドによって接続がクローズされます。
このメソッドでは、オブジェクトにより割り当てられたリソースまたはメモリーを解除します。
宣言
// C# public void Dispose();
実装
IDisposable
備考
Dispose
メソッドがOracleBulkCopy
オブジェクトでコールされると、次の操作は行われません。接続がOracleBulkCopy
オブジェクトによってオープンされている、つまり、接続文字列を取得するコンストラクタによってOracleBulkCopy
オブジェクトが作成された場合は、接続がクローズされます。
WriteToServer
は保存先表に行をコピーします。
オーバーロード・リスト:
このメソッドでは、指定されたDataRow
配列から、OracleBulkCopy
オブジェクトのDestinationTableName
プロパティによって指定された保存先表にすべての行がコピーされます。
このメソッドでは、指定されたDataTable
のすべての行が、OracleBulkCopy
オブジェクトのDestinationTableName
プロパティによって指定された保存先表にコピーされます。
このメソッドでは、指定されたIDataReader
のすべての行が、OracleBulkCopy
オブジェクトのDestinationTableName
プロパティによって指定された保存先表にコピーされます。
WriteToServer(DataTable, DataRowState)
このメソッドでは、指定されたDataTable
の指定された行の状態に一致する行が、OracleBulkCopy
オブジェクトのDestinationTableName
プロパティによって指定された保存先表にコピーされます。
WriteToServer(OracleRefCursor)
このメソッドでは、指定されたOracleRefCursor
から、OracleBulkCopy
オブジェクトのDestinationTableName
プロパティによって指定された保存先表にすべての行がコピーされます。
このメソッドでは、指定されたDataRow
配列から、OracleBulkCopy
オブジェクトのDestinationTableName
プロパティによって指定された保存先表にすべての行がコピーされます。
宣言
// C#
public void WriteToServer(DataRow[] rows);
パラメータ
rows
保存先表にコピーするDataRow
オブジェクトの配列。
例外
ArgumentNullException
- rows
パラメータがNullです。
InvalidOperationException
- 接続がオープン状態ではありません。
備考
ColumnMappings
コレクションはDataRow
列から保存先データベース表にマップされます。
このメソッドでは、指定されたDataTable
のすべての行が、OracleBulkCopy
オブジェクトのDestinationTableName
プロパティによって指定された保存先表にコピーされます。
宣言
// C#
public void WriteToServer(DataTable table);
パラメータ
table
保存先表にコピーする行を含むソースのDataTable
。
例外
ArgumentNullException
- table
パラメータがNullです。
InvalidOperationException
- 接続がオープン状態ではありません。
備考
DataTable
内の行は、削除されたものを除いてすべて保存先表にコピーされます。
ColumnMappings
コレクションはDataTable
列から保存先データベース表にマップされます。
このメソッドでは、指定されたIDataReader
のすべての行が、OracleBulkCopy
オブジェクトのDestinationTableName
プロパティによって指定された保存先表にコピーされます。
宣言
// C#
public void WriteToServer(IDataReader reader);
パラメータ
reader
保存先表にコピーする行を含むIDataReader
インスタンス。
例外
ArgumentNullException
- reader
パラメータがNullです。
InvalidOperationException
- 接続がオープン状態ではありません。
備考
一括コピー操作はデータ・リーダーの次に使用可能な行で開始します。通常、ExecuteReader
メソッドへのコールによって戻されるreader
は、次の行が最初の行になるようにWriteToServer
メソッドに渡されます。複数の結果セットをコピーするには、アプリケーションはreader
でNextResult
をコールし、WriteToServer
メソッドを再コールする必要があります。
このWriteToServer
メソッドは、reader.Read
を内部でコールしてソース行を取得するように、リーダーの状態を変更します。このため、WriteToServer
操作が完了すると、結果セットの最後はreader
となります。
ColumnMappings
コレクションはデータ・リーダー列から保存先データベース表にマップされます。
このメソッドでは、指定されたDataTable
の指定された行の状態に一致する行が、OracleBulkCopy
オブジェクトのDestinationTableName
プロパティによって指定された保存先表にコピーされます。
宣言
// C# public void WriteToServer(DataTable table, DataRowState rowState);
パラメータ
table
保存先表にコピーする行を含むDataTable
。
rowState
DataRowState
の列挙値。行の状態に一致する行のみ保存先にコピーされます。
例外
ArgumentNullException
- table
またはrowState
パラメータがNullです。
InvalidOperationException
- 接続がオープン状態ではありません。
備考
DataTable
内の行がrowState
引数に示されている状態で、削除されていない場合のみ、保存先表にコピーされます。
ColumnMappings
コレクションはDataTable
列から保存先データベース表にマップされます。
DataRowState.Deleted
はサポートされず、削除した行以外のすべての行がコピーされるという動作になります。
このメソッドでは、指定されたOracleRefCursor
から、OracleBulkCopy
オブジェクトのDestinationTableName
プロパティによって指定された保存先表にすべての行がコピーされます。
宣言
// C#
public void WriteToServer(OracleRefCursor refCursor);
パラメータ
refCursor
保存先表にコピーする行を含むOracleRefCursor
オブジェクト。
例外
ArgumentNullException
- refCursor
パラメータがNullです
InvalidOperationException
- 接続がオープン状態ではありません。
備考
ColumnMappings
コレクションはOracleRefCursor
列から保存先データベース表にマップされます。
OracleBulkCopy
イベントを、表17-7にリストします。
このイベントは、OracleBulkCopy.NotifyAfter
プロパティで指定された行数が処理されるたびにトリガーされます。
宣言
// C# public event OracleRowsCopiedEventHandler OracleRowsCopied;
例外
InvalidOperationException
- Close
メソッドはこのイベントでコールされます。
備考
このイベントはNotifyAfter
プロパティで指定された行数が処理されると発生します。これは、行がデータベースに送信されるかコミットされることを示すものではありません。
このイベントからの操作を取り消すには、OracleRowsCopiedEventArgs
クラスのAbort
プロパティを使用します。