DataAdapter によるパラメータの使用

[アーティクル]
03/28/2008

DataAdapter は、データソースからデータを取得したりデータソースのデータを更新したりするために使用される 4 つのプロパティを持っています。SelectCommand プロパティは、データソースからデータを返します。InsertCommand、UpdateCommand、DeleteCommand の各プロパティは、データソースの変更を管理するために使用します。SelectCommand プロパティは DataAdapter の Fill メソッドを呼び出す前に設定する必要があります。InsertCommand、UpdateCommand、DeleteCommand の各プロパティは、DataAdapter の Update メソッドを呼び出す前に DataSet 内のデータに対して行われた変更に基づいて設定する必要があります。たとえば、行が追加された場合、InsertCommand は Update 呼び出しの前に設定されている必要があります。Update が挿入行、更新行、または削除行を処理しているとき、DataAdapter がそれぞれの Command プロパティを使用してそのアクションを処理します。変更された行についての現在の情報が Parameters コレクションを通じて Command オブジェクトに渡されます。

たとえば、データソースの行を更新するときは、一意識別子を使用してテーブル内の更新する列を識別する UPDATE ステートメントを呼び出します。一意識別子は、一般には主キーフィールドの値です。UPDATE ステートメントは、次の SQL ステートメントで示すように、一意識別子および更新する列および値の両方を含むパラメータを使用します。

UPDATE Customers SET CompanyName = @CompanyName WHERE CustomerID = @CustomerID

この例では、CompanyName フィールドは、CustomerID が @CustomerID パラメータの値と等しい列の @CompanyName パラメータの値で更新されます。これらのパラメータは Parameter オブジェクトの SourceColumn プロパティを使用して、変更された行から情報を取得します。前のサンプル UPDATE ステートメントのパラメータを次に示します。

custDA.Parameters.Add("@CompanyName", SqlDbType.NChar, 15, "CompanyName")
Dim myParm As SqlParameter = custDA.UpdateCommand.Parameters.Add("@CustomerID", _
                                              SqlDbType.NChar, 5, "CustomerID")
myParm.SourceVersion = DataRowVersion.Original

Parameters コレクションの Add メソッドは、パラメータ名、DataAdapter 固有の型、サイズ (その型に適用可能な場合)、および DataTable の SourceColumn の名前を受け取ります。@CustomerID パラメータの SourceVersion が Original に設定されていることに注意してください。この設定により、変更済みの DataRow の中で、識別を行う 1 つまたは複数の列の値が既に変更されている場合に、データソース内の既存の行を更新することを保証できます。識別列の値が既に変更されている場合は、Original 行の値はデータソースの現在の値と一致し、Current 行の値は更新済みの値を格納します。@CompanyName パラメータの SourceVersion は設定されていないため、既定の Current の行の値が使用されます。

SQL ステートメントを DataAdapter の SelectCommand、InsertCommand、UpdateCommand、DeleteCommand の各プロパティの CommandText として使用する例を次に示します。OleDbDataAdapter オブジェクトと OdbcDataAdapter オブジェクトの場合は、疑問符 (?) のプレースホルダを使用してパラメータを識別する必要があります。SqlDataAdapter オブジェクトの場合は、名前付きのパラメータを使用する必要があります。

SqlClient

Dim selectSQL As String = "SELECT CustomerID, CompanyName FROM Customers WHERE Country = @Country AND City = @City"
Dim insertSQL As String = "INSERT INTO Customers (CustomerID, CompanyName) " & _
                          "VALUES (@CustomerID, @CompanyName)"

Dim updateSQL As String = "UPDATE Customers SET CustomerID = @CustomerID, CompanyName = @CompanyName " & _
                          "WHERE CustomerID = @OldCustomerID"

Dim deleteSQL As String = "DELETE FROM Customers WHERE CustomerID = @CustomerID"
[C#]
string selectSQL = "SELECT CustomerID, CompanyName FROM Customers WHERE Country = @Country AND City = @City";
string insertSQL = "INSERT INTO Customers (CustomerID, CompanyName) " +
                   "VALUES (@CustomerID, @CompanyName)";

string updateSQL = "UPDATE Customers SET CustomerID = @CustomerID, CompanyName = @CompanyName " +
                   "WHERE CustomerID = @OldCustomerID";

string deleteSQL = "DELETE FROM Customers WHERE CustomerID = @CustomerID";

OleDb または Odbc

Dim selectSQL As String = "SELECT CustomerID, CompanyName FROM Customers WHERE Country = ? AND City = ?"
Dim insertSQL AS String = "INSERT INTO Customers (CustomerID, CompanyName) VALUES (?, ?)"

Dim updateSQL AS String = "UPDATE Customers SET CustomerID = ?, CompanyName = ? WHERE CustomerID = ?"

Dim deleteSQL As String = "DELETE FROM Customers WHERE CustomerID = ?"
[C#]
string selectSQL = "SELECT CustomerID, CompanyName FROM Customers WHERE Country = ? AND City = ?";
string insertSQL = "INSERT INTO Customers (CustomerID, CompanyName) " +
                   "VALUES (?, ?)";

string updateSQL = "UPDATE Customers SET CustomerID = ?, CompanyName = ? " +
                   "WHERE CustomerID = ? ";

string deleteSQL = "DELETE FROM Customers WHERE CustomerID = ?";

パラメータとして使用されるクエリステートメントは、作成する必要のある入力パラメータおよび出力パラメータを定義します。パラメータを作成するには、Parameters.Add メソッドまたは Parameter コンストラクタを使用して列名、データ型、およびサイズを指定します。Integer など組み込みのデータ型の場合は、サイズを含める必要はありませんし、その場合は自動的に既定のサイズを指定することになります。

前の例の SQL ステートメントのパラメータを作成し、DataSet にデータを格納するサンプルコードを次に示します。

SqlClient

Dim nwindConn As SqlConnection = New SqlConnection("Data Source=localhost;Integrated Security=SSPI;Initial Catalog=northwind")
Dim custDA As SqlDataAdapter = New SqlDataAdapter

Dim selectCMD AS SqlCommand = New SqlCommand(selectSQL, nwindConn)
custDA.SelectCommand = selectCMD

' Add parameters and set values.
selectCMD.Parameters.Add("@Country", SqlDbType.NVarChar, 15).Value = "UK"
selectCMD.Parameters.Add("@City", SqlDbType.NVarChar, 15).Value = "London"

Dim custDS As DataSet = New DataSet
custDA.Fill(custDS, "Customers")
[C#]
SqlConnection nwindConn = new SqlConnection("Data Source=localhost;Integrated Security=SSPI;Initial Catalog=northwind");
SqlDataAdapter custDA = new SqlDataAdapter();         

SqlCommand selectCMD = new SqlCommand(selectSQL, nwindConn);
custDA.SelectCommand = selectCMD;

// Add parameters and set values.
selectCMD.Parameters.Add("@Country", SqlDbType.NVarChar, 15).Value = "UK";
selectCMD.Parameters.Add("@City", SqlDbType.NVarChar, 15).Value = "London";

DataSet custDS = new DataSet();
custDA.Fill(custDS, "Customers");

OleDb

Dim nwindConn As OleDbConnection = New OleDbConnection("Provider=SQLOLEDB;Data Source=localhost;" & _
                                                       "Integrated Security=SSPI;Initial Catalog=northwind")
Dim custDA As OleDbDataAdapter = New OleDbDataAdapter 

Dim selectCMD AS OleDbCommand = New OleDbCommand(selectSQL, nwindConn)
custDA.SelectCommand = selectCMD

' Add parameters and set values.
selectCMD.Parameters.Add("@Country", OleDbType.VarChar, 15).Value = "UK"
selectCMD.Parameters.Add("@City", OleDbType.VarChar, 15).Value = "London"

Dim custDS As DataSet = New DataSet
custDA.Fill(custDS, "Customers")
[C#]
OleDbConnection nwindConn = new OleDbConnection("Provider=SQLOLEDB;Data Source=localhost;" +
                                                "Integrated Security=SSPI;Initial Catalog=northwind;");
OleDbDataAdapter custDA = new OleDbDataAdapter();

OleDbCommand selectCMD = new OleDbCommand(selectSQL, nwindConn);
custDA.SelectCommand = selectCMD;

// Add parameters and set values.
selectCMD.Parameters.Add("@Country", OleDbType.VarChar, 15).Value = "UK";
selectCMD.Parameters.Add("@City", OleDbType.VarChar, 15).Value = "London";

DataSet custDS = new DataSet();
custDA.Fill(custDS, "Customers");

Odbc

Dim nwindConn As OdbcConnection = New OdbcConnection("Driver={SQL Server};Server=localhost;" & _
                                                     "Trusted_Connection=yes;Database=northwind")
Dim custDA As OdbcDataAdapter = New OdbcDataAdapter

Dim selectCMD AS OdbcCommand = New OdbcCommand(selectSQL, nwindConn)
custDA.SelectCommand = selectCMD

' Add Parameters and set values.
selectCMD.Parameters.Add("@Country", OdbcType.VarChar, 15).Value = "UK"
selectCMD.Parameters.Add("@City", OdbcType.VarChar, 15).Value = "London"

Dim custDS As DataSet = New DataSet
custDA.Fill(custDS, "Customers")
[C#]
OdbcConnection nwindConn = new OdbcConnection("Driver={SQL Server};Server=localhost;" +
                                              "Trusted_Connection=yes;Database=northwind;");
OdbcDataAdapter custDA = new OdbcDataAdapter();

OdbcCommand selectCMD = new OdbcCommand(selectSQL, nwindConn);
custDA.SelectCommand = selectCMD;

//Add Parameters and set values.
selectCMD.Parameters.Add("@Country", OdbcType.VarChar, 15).Value = "UK";
selectCMD.Parameters.Add("@City", OdbcType.VarChar, 15).Value = "London";

DataSet custDS = new DataSet();
custDA.Fill(custDS, "Customers");

メモあるパラメータに対してパラメータ名がサポートされていない場合は、"Parameter1" から増分していく既定名 ParameterN が割り当てられます。パラメータ名を指定するときには、"ParameterN" の名前付けルールを使用しないことをお勧めします。これは、指定した名前が ParameterCollection 内の既存のパラメータ名と競合しないようにするためです。指定した名前が既に存在する場合は、例外がスローされます。

Parameter.DbType

パラメータの型は .NET Framework データプロバイダに固有の属性です。型が指定されている場合は、その値がデータソースに渡される前に Parameter の値が .NET Framework データプロバイダ型に変換されます。型が指定されていない場合は、ADO.NET は Parameter オブジェクトの Value の .NET Framework 型の中から Parameter の NET Framework データプロバイダ型を推論します。

Parameter オブジェクトの DbType プロパティを特定の System.Data.DbType に設定する一般的な方法で Parameter の型を指定することもできます。また、ADO.NET は Parameter オブジェクトの DbType の中から Parameter の .NET Framework データプロバイダ型を推論します。

Parameter オブジェクトの .NET Framework データプロバイダ型は、Parameter オブジェクトの Value の .NET Framework 型か、または Parameter オブジェクトの DbType から推論されます。Parameter 値として渡されるオブジェクトまたは指定された DbType に基づいて推論される Parameter 型を、次の表に示します。

.NET Framework 型	System.Data.DbType	SqlDbType	OleDbType	OdbcType	OracleType
bool	Boolean	Bit	Boolean	Bit	Byte
byte	Byte	TinyInt	UnsignedTinyInt	TinyInt	Byte
byte[]	Binary	VarBinary。バイト配列が VarBinary の最大サイズ (8000 バイト) より大きい場合は、この暗黙の変換はエラーになります。8000 バイトを超えるバイト配列の場合は、明示的に SqlDbType を設定してください。	VarBinary	Binary	Raw
char		char からの SqlDbType の推論はサポートされていません。	Char	Char	Byte
DateTime	DateTime	DateTime	DBTimeStamp	DateTime	DateTime
Decimal	Decimal	Decimal	Decimal	Numeric	Number
double	Double	Float	Double	Double	Double
float	Single	Real	Single	Real	Float
Guid	Guid	UniqueIdentifier	Guid	UniqueIdentifier	Raw
Int16	Int16	SmallInt	SmallInt	SmallInt	Int16
Int32	Int32	Int	Int	Int	Int32
Int64	Int64	BitInt	BigInt	BigInt	Number
object	Object	Variant	Variant	Object からの OdbcType の推論はサポートされていません。	Blob
string	String	NVarChar。文字列が NVarChar の最大サイズ (4000 文字) より大きい場合、この暗黙の変換はエラーになります。4000 文字を超える文字列の場合は、明示的に SqlDbType を設定してください。	VarWChar	NVarChar	NVarChar
TimeSpan	Time	TimeSpan からの SqlDbType の推論はサポートされていません。	DBTime	Time	DateTime
UInt16	UInt16	UInt16 からの SqlDbType の推論はサポートされていません。	UnsignedSmallInt	Int	UInt16
UInt32	UInt32	UInt32 からの SqlDbType の推論はサポートされていません。	UnsignedInt	BigInt	UInt32
UInt64	UInt64	UInt64 からの SqlDbType の推論はサポートされていません。	UnsignedBigInt	Numeric	Number
	AnsiString	VarChar	VarChar	VarChar	VarChar
	AnsiStringFixedLength	Char	Char	Char	Char
	Currency	Money	Currency	Currency からの OdbcType の推論はサポートされていません。	Number
	Date	Date からの SqlType の推論はサポートされていません。	DBDate	Date	DateTime
	SByte	SByte からの SqlType の推論はサポートされていません。	TinyInt	SByte からの OdbcType の推論はサポートされていません。	SByte
	StringFixedLength	NChar	WChar	NChar	NChar
	Time	Time からの SqlType の推論はサポートされていません。	DBTime	Time	DateTime
	VarNumeric	VarNumeric からの SqlDbType の推論はサポートされていません。	VarNumeric	VarNumeric からの OdbcType の推論はサポートされていません。	Number

メモ .NET Framework Version 1.0 に同梱されている .NET Framework データプロバイダは、Decimal パラメータ値の Precision と Scale を確認しないため、切り捨てられたデータがデータソースに挿入されることがあります。.NET Framework Version 1.0 を使用している場合は、Decimal 値の Precision と Scale を検証してからパラメータ値を設定してください。

.NET Framework Version 1.1 以降では、Decimal パラメータ値で無効な Precision が設定されている場合、例外がスローされます。Decimal パラメータスケールを超える Scale 値は、切り捨てられます。

Parameter.Direction

Parameter の Direction を設定するために ParameterDirection 列挙型で使用できる値を次の表に示します。

メンバ名	説明
Input	このパラメータは入力パラメータです。これは、既定の設定です。
InputOutput	このパラメータは入力と出力の両方の機能を持っています。
Output	このパラメータは出力パラメータです。
ReturnValue	このパラメータは戻り値を表します。

Parameter の Direction を設定する方法を次のサンプルコードに示します。

myParm.Direction = ParameterDirection.Output

Parameter.SourceColumn、Parameter.SourceVersion

SourceColumn および SourceVersion は、Parameter コンストラクタに記述子として渡したり、既存の Parameter のプロパティとして設定することもできます。SourceColumn は、Parameter の値の取得元である DataRow の DataColumn の名前です。SourceVersion は、DataAdapter が値を取得するために使用する DataRow バージョンを指定します。

SourceVersion で使用できる DataRowVersion 列挙型の値を次の表に示します。

メンバ名	説明
Current	このパラメータは列の現在の値を使用します。これは、既定の設定です。
Default	このパラメータは列の DefaultValue を使用します。
Original	このパラメータは列の元の値を使用します。
Proposed	このパラメータは提示された値を使用します。

CustomerID 列を 2 つのパラメータ @CustomerID (SET CustomerID = @CustomerID) および @OldCustomerID (WHERE CustomerID = @OldCustomerID) の SourceColumn として使用する UPDATE ステートメントを定義するサンプルコードを次に示します。@CustomerID パラメータは CustomerID 列を DataRow の現在の値に更新するために使用されています。そのため、SourceVersion を Current に設定した CustomerID SourceColumn が使用されています。@OldCustomerID パラメータは、データソースの現在の行を識別するために使用されています。その行の Original バージョンで一致する列の値が見つかったため、SourceVersion を Original に設定した同じ SourceColumn (CustomerID) が使用されています。

SqlClient

custDA.UpdateCommand.Parameters.Add("@CustomerID", SqlDbType.NChar, 5, "CustomerID")

custDA.UpdateCommand.Parameters.Add("@CompanyName", SqlDbType.NVarChar, 40, "CompanyName")

Dim myParm As SqlParameter = custDA.UpdateCommand.Parameters.Add("@OldCustomerID", _
                               SqlDbType.NChar, 5, "CustomerID")
myParm.SourceVersion = DataRowVersion.Original
[C#]
custDA.UpdateCommand.Parameters.Add("@CustomerID", SqlDbType.NChar, 5, "CustomerID");

custDA.UpdateCommand.Parameters.Add("@CompanyName", SqlDbType.NVarChar, 40, "CompanyName");

SqlParameter myParm = custDA.UpdateCommand.Parameters.Add("@OldCustomerID", SqlDbType.NChar, 5, "CustomerID");
myParm.SourceVersion = DataRowVersion.Original;

OleDb

custDA.UpdateCommand.Parameters.Add("@CustomerID", OleDbType.Char, 5,"CustomerID")

custDA.UpdateCommand.Parameters.Add("@CompanyName", OleDbType.VarChar, 40, "CompanyName")

Dim myParm As OleDbParameter = custDA.UpdateCommand.Parameters.Add("@OldCustomerID", _
                                 OleDbType.Char, 5, "CustomerID")
myParm.SourceVersion = DataRowVersion.Original
[C#]
custDA.UpdateCommand.Parameters.Add("@CustomerID", OleDbType.Char, 5, "CustomerID");

custDA.UpdateCommand.Parameters.Add("@CompanyName", OleDbType.VarChar, 40, "CompanyName");

OleDbParameter myParm = custDA.UpdateCommand.Parameters.Add("@OldCustomerID", OleDbType.Char, 5, "CustomerID");
myParm.SourceVersion = DataRowVersion.Original;

Odbc

custDA.UpdateCommand.Parameters.Add("@CustomerID", OdbcType.Char, 5, "CustomerID")

custDA.UpdateCommand.Parameters.Add("@CompanyName", OdbcType.VarChar, 40, "CompanyName")

Dim myParm As OdbcParameter = custDA.UpdateCommand.Parameters.Add("@oldCustomerID", _
                              OdbcType.Char, 5, "CustomerID")
myParm.SourceVersion = DataRowVersion.Original
[C#]
custDA.UpdateCommand.Parameters.Add("@CustomerID", OdbcType.Char, 5, "CustomerID");

custDA.UpdateCommand.Parameters.Add("@CompanyName", OdbcType.VarChar, 40, "CompanyName");

OdbcParameter myParm = custDA.UpdateCommand.Parameters.Add("@oldCustomerID", OdbcType.Char, 5, "CustomerID");
myParm.SourceVersion = DataRowVersion.Original;

UpdatedRowSource

Command オブジェクトの UpdatedRowSource プロパティを使用すると、データソースから返された値を DataSet に割り当てる方法を制御できます。UpdatedRowSource プロパティを UpdateRowSource 列挙型の値の 1 つに設定することで、DataAdapter コマンドが返したパラメータを無視するか、DataSet 内の変更行に適用するかを制御できます。最初に返された行 (存在する場合) を、DataSet 内の変更行に適用するかどうかを指定することもできます。

UpdateRowSource 列挙型のさまざまの値と、それらの値が DataAdapter で使用されるコマンドの動作にどのように影響するかを次の表で説明します。

UpdateRowSource	説明
Both	出力パラメータと返された結果セットの最初の行を DataSet 内の変更行に割り当てます。
FirstReturnedRecord	返された結果セットの最初の行のデータだけを DataSet 内の変更行に割り当てます。
None	出力パラメータまたは返された結果セットの行が無視されます。
OutputParameters	出力パラメータだけを DataSet 内の変更行に割り当てます。

参照

次の方法で共有

DataAdapter によるパラメータの使用

SqlClient

OleDb または Odbc

SqlClient

OleDb

Odbc

Parameter.DbType

Parameter.Direction

Parameter.SourceColumn、Parameter.SourceVersion

SqlClient

OleDb

Odbc

UpdatedRowSource

参照

その他のリソース