サポートされる .NET オブジェクト
.NET オブジェクトの使用
ADO.NET 2.0 は、アプリケーションおよびデータ ソース間のより汎用的な追加インターフェイスを提供する新しい一連のクラスを導入ました。
ADO.NET 2.0 より以前に使われていたものは、アプリケーションが使用するデータ プロバイダーのそれぞれの特定のインスタンスに、データ プロバイダーをより密接な要因の 1 つとして含めることを選択しました。それとは対照的に、ADO.NET2.0 以降は、アプリケーションが異種のデータ ソースのセットを単一の API で処理できるようにする、基本クラスのセットを提供します。これは、今日の ODBC および JDBC で利用されるものとよく似ています。つまり、ADO.NET2.0 以降では、すべてのデータ クラスは基本クラスから派生し、特定の専用名前空間である System.Data.Common に存在します。
データ プロバイダーでは、以下が使用できます。
•
•
•
.NET の基本クラス
ADO.NET 1.0 および ADO.NET 1.1 データ プロバイダーのインターフェイスは、アプリケーションの互換性を維持するために構築されました。ADO.NET 2.0 以降の基本クラスは以下の追加機能を提供します。
•
•
•
•
•
•
•
•
•
•
日々のプログラミングという観点から、これらのクラスは抽象実装として提供されます。つまり、これらは直接インスタンス化できず、プロバイダー ファクトリで使用する必要があります。各データ プロバイダーは、DbFactory クラスから派生する一連の静的メソッドを含む PsqlFactory のような Factory クラスを提供する必要があります。これらの静的メソッドは、それぞれベース クラスのインスタンスを生成するファクトリ メソッドです。
これは、データ プロバイダーのインストール時に .NET Framework に登録されます。これにより、共通 .NET Framework DbFactory は、アプリケーションが必要とする登録済みデータ プロバイダーを見つけて、データ ソースへの接続を確立するための共通メカニズムを提供することができます。最終的に、.NET Framework は ADO.NET データ ソース用の完全に成熟した共通プログラミング API を提供します。
データ プロバイダー固有のクラス
ADO.NET データ プロバイダーは、すべての .NET パブリック オブジェクトをサポートしています。ADO.NET データ プロバイダーは、.NET のパブリック オブジェクトにプロバイダー固有のプレフィックス 「Psql 」を付けます(例:PsqlCommand)。
以下のオブジェクトについて説明します。
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
パブリック オブジェクトに関する詳細については、Microsoft .NET Framework Version 2.0 SDK のドキュメントを参照してください。
PsqlBulkCopy
PsqlBulkCopy オブジェクトは ADO.NET Bulk API に類似した API パターンを使用し、プロバイダー固有のプロパティやメソッドを持ちません。サポートされるプロパティおよびメソッドについては、データ プロバイダーのオンライン ヘルプおよび Microsoft .NET Framework SDK のドキュメントを参照してください。
PsqlBulkCopyColumnMapping
PsqlBulkCopyColumnMapping オブジェクトは ADO.NET Bulk API に類似した API パターンを使用し、プロバイダー固有のプロパティやメソッドを持ちません。サポートされるプロパティおよびメソッドについては、データ プロバイダーのオンライン ヘルプおよび Microsoft .NET Framework SDK のドキュメントを参照してください。
PsqlBulkCopyColumnMappingCollection
PsqlBulkCopyColumnMappingCollection オブジェクトは Microsoft SqlBulkCopyColumnMappingCollection クラスに類似した API パターンに従い、プロバイダー固有のプロパティやメソッドを持ちません。サポートされるプロパティおよびメソッドについては、データ プロバイダーのオンライン ヘルプおよび Microsoft .NET Framework SDK のドキュメントを参照してください。
PsqlCommand オブジェクト
表 28 では、PsqlCommand オブジェクトのパブリック プロパティについて説明します。
 
表 29 では、PsqlCommand オブジェクトのパブリック メソッドについて説明します。
 
メモ:Prepare メソッドは本リリースのデータ プロバイダーでは無効です。
PsqlCommandBuilder オブジェクト
PsqlCommandBuilder オブジェクトを使用すると、パフォーマンスに悪影響を及ぼす恐れがあります。同時実行が制限されるため、PsqlCommandBuilder では効率のよい SQL ステートメントを生成することができません。多くの場合、エンド ユーザーの方が、PsqlCommandBuilder オブジェクトで生成されるものより効率のよい Update ステートメントや Delete ステートメントを作成することができます。
表 30 では、PsqlCommandBuilder オブジェクトのパブリック プロパティについて説明します。
 
表 31 では、PsqlCommandBuilder オブジェクトのパブリック メソッドについて説明します。
 
PsqlConnection オブジェクト
表 32 では、PsqlConnection オブジェクトのパブリック コンストラクターについて説明します。
表 33 では、PsqlConnection オブジェクトのパブリック プロパティについて説明します。いくつかのプロパティでは、対応する接続文字列オプションに指定された値を返します。接続文字列オプションとは異なり、PsqlConnection のプロパティ名にはスペースが含まれません。
 
表 34 では、PsqlConnection オブジェクトのパブリック メソッドについて説明します。
 
PsqlConnection オブジェクトの InfoMessage イベントを使用すると、データベースから警告や情報メッセージを取得することができます。データベースからエラーが返される場合は、例外が発生します。データベース サーバーから送られる警告や情報メッセージを処理したいクライアントは、PsqlInfoMessageEventHandler デリゲートを作成してこのイベントに登録してください。
InfoMessage イベントでは、このイベントに関するデータを含む PsqlInfoMessageEventArgs の引数を受け取ります。
PsqlConnectionStringBuilder オブジェクト
PsqlConnectionStringBuilder プロパティ名は、PsqlConnection.ConnectionString プロパティの接続文字列オプション名と同じです。ただし、接続文字列オプション名は単語の間にスペースを入れることができます。たとえば、接続文字列オプション Min Pool Size はプロパティ名 MinPoolSize に相当します。
接続文字列の基本形式は、セミコロンで区切られた一連の「キーワード/値」のペアを含んでいます。次に、ADO.NET データ プロバイダー用の単純な接続文字列のキーワードと値の例を示します。
"Server DSN=SERVERDEMO;Host=localhost"
表 35 では、Zen データ プロバイダーでサポートされる接続文字列オプションに対応するプロパティを挙げ、各プロパティについて説明します。
 
"Host=ホスト値;Port=ポート値[, ...]"
メモ:このオプションは、Connection Retry Count 接続文字列オプションを 0 に設定している場合は作用しません。
メモ:1 つの接続文字列に Database Name と Server DSN 接続文字列オプションを混在させることはできません。
メモ:このオプションは、Zen ADO.NET Entity Framework Core データ プロバイダーでのみサポートされます。
IPv6 形式の詳細については、『Getting Started with Zen』の 「IPv6」 を参照してください。
メモ:このオプションは、データの暗号化と復号で必要となる追加オーバーヘッド(主に CPU 使用)のため、パフォーマンスに悪影響を与えることがあります。
メモ:Zen は分散トランザクションをサポートしないため、スレッドの現在のトランザクション コンテキストでの接続への参加試行は失敗します。
接続する Zen データベース サーバーの名前または IP アドレスを指定します。たとえば、Accountingserver などのサーバー名を指定できます。あるいは、199.226.22.34(IPv4)または 1234:5678:0000:0000:0000:0000:9abc:def0(IPv6)などの IP アドレスを指定できます。
メモ:CommandTimeout オプションの初期値は、サーバーのデッドロック検出およびタイムアウトの最大値より大きい値に設定します。これによって、アプリケーションはタイムアウトした場合により意味のある応答を受け取ることができます。
メモ:何らかの理由でステートメントが失敗した場合、Zen サーバーへの接続は失敗します。データ プロバイダーは、サーバーから返されたエラーを含む例外をスローします。
メモ:このオプションは、Alternate Servers 接続文字列オプションで代替サーバーが指定されていなければ作用しません。
メモ:このオプションは、Zen ADO.NET Entity Framework データ プロバイダーではサポートされません。
メモ:この接続文字列オプションはパフォーマンスに悪影響を与えることがあります。詳細については、お使いのデータ プロバイダーのパフォーマンスに関する考慮点のドキュメントを参照してください。
メモ:1 つの接続文字列に Database Name と Server DSN 接続文字列オプションを混在させることはできません。
メモ:このオプションは、Zen ADO.NET Entity Framework データ プロバイダーではサポートされません。
表 36 に、データ プロバイダーが、返すデータから除外する列コレクションの名前と 16 進値を挙げます。複数の値を指定するには、名前をカンマ区切りのリストで指定するか、返したい列コレクションの 16 進値の合計を指定します。
 
1 COLUMN_HAS_DEFAULT は常にヌル値を返します。
PsqlConnectionStringBuilder オブジェクトにはプロバイダー固有のメソッドはありません。サポートされるメソッドの情報については、データ プロバイダーのオンライン ヘルプおよび Microsoft .NET Framework SDK ドキュメントを参照してください。
PsqlCredential オブジェクト
PsqlCredential オブジェクトは、Zen サーバー認証を使用して安全にログインする方法を提供します。PsqlCredential は、Zen サーバーによって認識されるユーザー ID とパスワードで構成されます。
PsqlCredential オブジェクトのパスワードは、接続文字列とは違って SecureString 型です。接続文字列のパスワードは、プロバイダーが読み取って SecureString に変換しない限り、セキュリティで保護されていません。パスワードは、メモリに書き込まずに安全な方法で処理されます。パスワードに格納する文字列は、使用後に消去されます。
メモ:PsqlCredential は、ユーザー ID とパスワードが必要な認証方法の場合にのみ使用してください。また、Kerberos 認証またはクライアント認証を使用している場合は、PsqlCredential を使用しないでください。最後に、PsqlCredential オブジェクトを使用する場合は、接続文字列にユーザー ID とパスワードを含めないでください。
次のコード スニペットは、PsqlCredential クラスを使用する方法を示しています。この例で文字列から SecureString への変換に使用されている方法は、考えられる多くの方法のうちの 1 つです。
PsqlConnection con = null;
PsqlCredential lobjCredential = null;
string userId = "ABCD";
SecureString password = ConvertToSecureString("XYXYX");
private static SecureString ConvertToSecureString(string value)
{
   var securePassword = new SecureString();
   foreach (char c in value.ToCharArray())
   securePassword.AppendChar(c);
   securePassword.MakeReadOnly();
   return securePassword;
}
try
{
   lobjCredential = new PsqlCredential(userId, password);
   con = new PsqlConnection("Host=nc-xxx;Port=xxxx;Database Name=xxxx"",
      lobjCredential);
   con.Open();
   Console.WriteLine("Connection Successfully Opened...");
   con.Close();
}
catch (Exception e)
{
   Console.Write(e.Message)
}
finally
{
   if (null != con)
   {
      con.Close();
      con = null;
   }
   if (null != lobjCredential)
   {
      lobjCredential = null;
   }
}
次の表では、PsqlCredential オブジェクトのプロバイダー固有のパブリック プロパティの実装について説明します。
接続が開いているときに PsqlCredential オブジェクトを使用して、プールされている同じ接続を使用したい場合は、使用可能な接続プールから同じ接続が取得されるよう、同じ PsqlCredential オブジェクトを参照する必要があります。
接続ごとに新しい資格情報オブジェクトを作成する場合、ドライバーはオブジェクトを個別に扱い、同じユーザー ID とパスワードが使用されている場合でも、それらを異なる接続プールに入れます。
PsqlDataAdapter オブジェクト
PsqlDataAdapter オブジェクトは PsqlCommand オブジェクトを使って Zen データベースに対して SQL コマンドを実行し、取得したデータを DataSet に読み込んだり、DataSet で変更されたデータをデータベースと照合したりします。
表 38 では、PsqlDataAdapter オブジェクトのパブリック プロパティについて説明します。
 
PsqlDataReader オブジェクト
PsqlDataReader オブジェクトは、データベースから読み取り専用のレコードを取得する前方スクロール カーソルです。PsqlDataAdapter を使用するよりもパフォーマンスは高くなりますが、結果セットは変更できません。
表 39 では、PsqlDataReader オブジェクトのパブリック プロパティについて説明します。
 
表 40 では、PsqlDataReader オブジェクトのパブリック メソッドの一部について説明します。
 
PsqlError オブジェクト
PsqlError オブジェクトは、Zen サーバーで生成されたエラーや警告に関する情報を収集します。
表 41 では、PsqlError オブジェクトのパブリック プロパティについて説明します。
 
メモ:SQLstate 情報が何もない ADO.NET クライアントのエラー メッセージについては、S1000 がデフォルトの SQLState として使用されます。
PsqlErrorCollection オブジェクト
PsqlErrorCollection オブジェクトは、PsqlException によって作成され、Zen サーバーによって生成されたすべてのエラーを格納します。
表 42 では、PsqlErrorCollection オブジェクトでサポートされるプロバイダー固有のパブリック プロパティについて説明します。サポートされるその他のプロパティおよびメソッドの情報については、データ プロバイダーのオンライン ヘルプおよび Microsoft .NET Framework SDK ドキュメントを参照してください。
 
表 43 では、PsqlErrorCollection オブジェクトのパブリック メソッドについて説明します。
 
PsqlException オブジェクト
プロバイダー固有の例外は System.Data interface インターフェイスから直接派生します。System.Exception オブジェクト全般で直接使用できるのは、Message プロパティなどのパブリック プロパティおよびメソッドのみです。SQLState および Number プロパティは、プロバイダー固有のコードを介して、または参照を使用してのみアクセスできます。
ADO.NET 2.0 は、DbException クラスに新しいプロパティ Data を導入しました。このプロパティは、例外に関する追加のユーザー定義情報を提供する、キーと値の組のコレクションを返します。ADO.NET データ プロバイダーは、SQLState、Number、および ErrorPosition などのキー/値ペアのコレクションを取得します。
Psql.Data.SqlClient プレフィックスは各キーに適用されます。たとえば、次のようになります。
Psql.Data.SqlClient.Data["SQLState"] = 28000;
複数のエラーが存在する場合、表 44 で説明しているプロパティは最後に生成されたエラーに対して適用されます。複数のエラーが発生したかどうかを判断するには、このオブジェクトの Errors プロパティで返される PsqlErrorCollection の Count プロパティをチェックします。詳細については、PsqlErrorCollection オブジェクトを参照してください。
 
PsqlFactory オブジェクト
プロバイダー ファクトリ クラスを使用すると、ユーザーは汎用オブジェクトのプログラムを作成できます。DbProviderFactory からインスタンス化すれば、ファクトリが正しいタイプの具体的なクラスを生成します。
表 45 は、ADO.NET データ プロバイダーの選択や DbProviderFactory のインスタンス化を調整するために使用される静的メソッドを示しています。
 
PsqlInfoMessageEventArgs オブジェクト
PsqlInfoMessageEventArgs オブジェクトは、PsqlInfoMessageEventHandler に入力として渡され、Zen サーバーで生成される警告に関する情報を格納します。
表 46 では、PsqlInfoMessageEventArgs オブジェクトのパブリック プロパティについて説明します。
 
PsqlParameter オブジェクト
PsqlParameter オブジェクトは PsqlCommand オブジェクトのパラメーターを表します。
表 47 では、PsqlParameter オブジェクトのパブリック プロパティについて説明します。
 
メモ:配列バインドが有効な場合(PsqlCommand オブジェクトの ArrayBindCount プロパティを参照してください)、このプロパティは値の配列として指定されます。各配列の長さは ArrayBindCount プロパティの値と一致させる必要があります。バイナリ型の列に配列の値を指定する場合、そのデータは実質的には byte[] として指定されます。これはバイトの配列の配列です。データ プロバイダーは複数のパラメーターにバインドするパラメーター配列を使用するような場合には、「ジャグ(Jagged)」配列を予測します。
PsqlParameterCollection オブジェクト
PsqlParameterCollection オブジェクトは PsqlCommand に関するパラメーターのコレクションです。また、DataSet の列へのマッピングも含まれています。
表 48 では、PsqlParameterCollection オブジェクトのパブリック プロパティについて説明します。
 
表 49 では、PsqlParameterCollection オブジェクトのパブリック メソッドについて説明します。
 
PsqlTrace オブジェクト
PsqlTrace オブジェクトは、開発時に問題をデバッグするためアプリケーションによって作成されます。PsqlTrace オブジェクトのプロパティを設定すると、その値を優先し環境変数の設定を無効にします。アプリケーションが最終的なものになったら、PsqlTrace オブジェクトへの参照を必ず削除してください。
次のコードでは MyTrace.txt という名前の Trace オブジェクトを作成しています。その結果、データ プロバイダーへの呼び出しはすべてそのファイルへトレースされます。
PsqlTrace  MyTraceObject = new PsqlTrace();
     MyTraceObject.TraceFile="C:\\MyTrace.txt";
     MyTraceObject.RecreateTrace = 1;
     MyTraceObject.EnableTrace = 1;
表 50 では、PsqlTrace オブジェクトのパブリック プロパティについて説明します。
 
メモ:EnableTrace でトレースを有効にするよう設定するとトレース処理が開始します。したがって、EnableTrace を設定する前にトレース ファイル用のプロパティ値を定義しておく必要があります。いったんトレース処理が開始されたら、TraceFile および RecreateTrace プロパティの値を変更することはできません。
表 51 では、PsqlTrace オブジェクトのパブリック メソッドについて説明します。
 
PsqlTransaction オブジェクト
表 52 では、PsqlTransaction オブジェクトのパブリック プロパティについて説明します。
 
表 53 では、PsqlTransaction オブジェクトのパブリック メソッドについて説明します。
 
Zen Common Assembly
Zen ADO.NET データ プロバイダーでは、バルク ロードなどの拡張機能を提供する追加クラスを使用できます。すべてのクラスはマネージ コードのみで作成されています。以下のクラスが Pervasive.Data.Common.dll アセンブリで提供されます。
•
•
•
•
•
バルク ロードに使用されるクラスは、汎用プログラミング モデルを実装します。これらは、Zen Bulk Load をサポートする任意の DataDirect Technologies ADO.NET データ プロバイダーまたは ODBC ドライバー、およびサポートされる任意のデータベースと共に使用することができます。
CsvDataReader
CsvDataReader クラスは、Zen Bulk Load が定義した CSV ファイル形式用の DataReader 構文を提供します。
表 54 は、CsvDataWriter オブジェクトのパブリック プロパティの一覧です。
 
メモ:このプロパティは Open() 呼び出しの前および Close() 呼び出しの後にのみ設定できます。それ以外の場合、InvalidOperationException がスローされます。
メモ:このプロパティは Open() 呼び出しの前および Close() 呼び出しの後にのみ設定できます。それ以外の場合、InvalidOperationException がスローされます。
メモ:このプロパティは Open() 呼び出しの前および Close() 呼び出しの後にのみ設定できます。それ以外の場合、InvalidOperationException がスローされます。
メモ:このプロパティは Open() 呼び出しの前および Close() 呼び出しの後にのみ設定できます。それ以外の場合、InvalidOperationException がスローされます。
表 55 は CsvDataReader オブジェクトのパブリック メソッドの一覧です。
 
CsvDataWriter
CsvDataWriter クラスは、Zen Bulk Load によって書き出される CSV ファイル形式の Pervasive DataWriter 構文を提供します。
詳細については、データ プロバイダーのオンライン ヘルプを参照してください。
表 56 は、CsvDataWriter オブジェクトのパブリック プロパティの一覧です。
 
表 57 は CsvDataWriter オブジェクトのパブリック メソッドの一覧です。
 
DbBulkCopy
DbBulkCopy クラスは 1 つのデータ ソースから別のデータ ソースへ行をコピーするのを容易にします。
DbBulkCopy オブジェクトは、事実上の業界標準である Microsoft SqlBulkCopy クラスの定義に従っており、プロバイダー固有のプロパティやメソッドを持ちません。サポートされるプロパティおよびメソッドについては、データ プロバイダーのオンライン ヘルプおよび Microsoft .NET Framework SDK のドキュメントを参照してください。
DbBulkCopyColumnMapping
DbBulkCopyColumnMapping クラスは、データ ソース テーブルから宛先テーブルへの列のマップを表します。
DbBulkCopyColumnMapping オブジェクトは、事実上の業界標準である Microsoft SqlBulkCopyColumnMapping クラスの定義に従っており、プロバイダー固有のプロパティやメソッドを持ちません。サポートされるプロパティおよびメソッドについては、データ プロバイダーのオンライン ヘルプおよび Microsoft .NET Framework SDK のドキュメントを参照してください。
DbBulkCopyColumnMappingCollection
DbBulkCopyColumnMappingCollection クラスは DbBulkCopyColumnMapping オブジェクトのコレクションです。
DbBulkCopyColumnMappingCollection オブジェクトは、事実上の業界標準である Microsoft SqlBulkCopyColumnMappingCollection クラスの定義に従っており、プロバイダー固有のプロパティやメソッドを持ちません。サポートされるプロパティおよびメソッドについては、データ プロバイダーのオンライン ヘルプおよび Microsoft .NET Framework SDK のドキュメントを参照してください。