DataAdapter パラメータ (ADO.NET)

  • [アーティクル]

更新 : November 2007

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

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

UPDATE Customers SET CompanyName = @CompanyName 
  WHERE CustomerID = @CustomerID
bbw6zyha.alert_note(ja-jp,VS.90).gifメモ :

パラメータのプレースホルダの構文はデータ ソースに依存します。次に、SQL Server のデータ ソースのプレースホルダの例を示します。System.Data.OleDb パラメータおよび System.Data.Odbc パラメータのプレースホルダとして、疑問符 (?) を使用します。

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

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

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

bbw6zyha.alert_note(ja-jp,VS.90).gifメモ :

DataAdapter の Fill 操作と DataReader の Get メソッドのどちらの場合も、.NET Framework の型は .NET Framework データ プロバイダから返された型から推論されます。Microsoft SQL Server、OLE DB、および ODBC のデータ型から推論される .NET Framework の型およびアクセサ メソッドについては、「ADO.NET でのデータ型のマッピング」を参照してください。

Parameter.SourceColumn、Parameter.SourceVersion

SourceColumn および SourceVersion が、引数として Parameter コンストラクタに渡されるか、既存の Parameter のプロパティとして設定されます。SourceColumn は、Parameter の値の取得先である DataRow の DataColumn の名前です。SourceVersion により、DataAdapter で値の取得に使用される DataRow のバージョンを指定します。

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

DataRowVersion 列挙型

説明

Current

このパラメータは列の現在の値を使用します。これは、既定の設定です。

Default

このパラメータには列の DefaultValue を使用します。

Original

このパラメータは列の元の値を使用します。

Proposed

このパラメータは提示された値を使用します。

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

SqlClient パラメータの使用

次のコード サンプルでは、データベースから追加のスキーマ情報を取得するために SqlDataAdapter を作成し、MissingSchemaAction を AddWithKey に設定する方法を示します。SelectCommand プロパティ、InsertCommand プロパティ、UpdateCommand プロパティ、および DeleteCommand プロパティが設定され、各プロパティに対応する SqlParameter オブジェクトが Parameters コレクションに追加されます。このメソッドは SqlDataAdapter オブジェクトを返します。

Public Function CreateSqlDataAdapter( _
    ByVal connection As SqlConnection) As SqlDataAdapter

    Dim adapter As SqlDataAdapter = New SqlDataAdapter
    adapter.MissingSchemaAction = MissingSchemaAction.AddWithKey

    ' Create the commands.
    adapter.SelectCommand = New SqlCommand( _
        "SELECT CustomerID, CompanyName FROM CUSTOMERS", connection)
    adapter.InsertCommand = New SqlCommand( _
        "INSERT INTO Customers (CustomerID, CompanyName) " & _
         "VALUES (@CustomerID, @CompanyName)", connection)
    adapter.UpdateCommand = New SqlCommand( _
        "UPDATE Customers SET CustomerID = @CustomerID, CompanyName = " & _
        "@CompanyName WHERE CustomerID = @oldCustomerID", connection)
    adapter.DeleteCommand = New SqlCommand( _
        "DELETE FROM Customers WHERE CustomerID = @CustomerID", connection)

    ' Create the parameters.
    adapter.InsertCommand.Parameters.Add("@CustomerID", _
        SqlDbType.Char, 5, "CustomerID")
    adapter.InsertCommand.Parameters.Add("@CompanyName", _
        SqlDbType.VarChar, 40, "CompanyName")

    adapter.UpdateCommand.Parameters.Add("@CustomerID", _
        SqlDbType.Char, 5, "CustomerID")
    adapter.UpdateCommand.Parameters.Add("@CompanyName", _
        SqlDbType.VarChar, 40, "CompanyName")
    adapter.UpdateCommand.Parameters.Add("@oldCustomerID", _
        SqlDbType.Char, 5, "CustomerID").SourceVersion = _
        DataRowVersion.Original

    adapter.DeleteCommand.Parameters.Add("@CustomerID", _
        SqlDbType.Char, 5, "CustomerID").SourceVersion = _
        DataRowVersion.Original

    Return adapter
End Function

public static SqlDataAdapter CreateSqlDataAdapter(SqlConnection connection)
{
    SqlDataAdapter adapter = new SqlDataAdapter();
    adapter.MissingSchemaAction = MissingSchemaAction.AddWithKey;

    // Create the commands.
    adapter.SelectCommand = new SqlCommand(
        "SELECT CustomerID, CompanyName FROM CUSTOMERS", connection);
    adapter.InsertCommand = new SqlCommand(
        "INSERT INTO Customers (CustomerID, CompanyName) " +
        "VALUES (@CustomerID, @CompanyName)", connection);
    adapter.UpdateCommand = new SqlCommand(
        "UPDATE Customers SET CustomerID = @CustomerID, CompanyName = @CompanyName " +
        "WHERE CustomerID = @oldCustomerID", connection);
    adapter.DeleteCommand = new SqlCommand(
        "DELETE FROM Customers WHERE CustomerID = @CustomerID", connection);

    // Create the parameters.
    adapter.InsertCommand.Parameters.Add("@CustomerID", 
        SqlDbType.Char, 5, "CustomerID");
    adapter.InsertCommand.Parameters.Add("@CompanyName", 
        SqlDbType.VarChar, 40, "CompanyName");

    adapter.UpdateCommand.Parameters.Add("@CustomerID", 
        SqlDbType.Char, 5, "CustomerID");
    adapter.UpdateCommand.Parameters.Add("@CompanyName", 
        SqlDbType.VarChar, 40, "CompanyName");
    adapter.UpdateCommand.Parameters.Add("@oldCustomerID", 
        SqlDbType.Char, 5, "CustomerID").SourceVersion = 
        DataRowVersion.Original;

    adapter.DeleteCommand.Parameters.Add("@CustomerID", 
        SqlDbType.Char, 5, "CustomerID").SourceVersion = 
        DataRowVersion.Original;

    return adapter;
}

OleDb パラメータのプレースホルダ

OleDbDataAdapter オブジェクトと OdbcDataAdapter オブジェクトの場合は、疑問符 (?) のプレースホルダを使用してパラメータを識別する必要があります。

Dim selectSQL As String = _
  "SELECT CustomerID, CompanyName FROM Customers " & _
  "WHERE CountryRegion = ? 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 = ?"

string selectSQL = 
  "SELECT CustomerID, CompanyName FROM Customers " +
  "WHERE CountryRegion = ? 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 にデータを格納します。

OleDb の例

' Assumes that connection is a valid OleDbConnection object.
Dim adapter As OleDbDataAdapter = New OleDbDataAdapter 

Dim selectCMD AS OleDbCommand = New OleDbCommand(selectSQL, connection)
adapter.SelectCommand = selectCMD

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

Dim customers As DataSet = New DataSet
adapter.Fill(customers, "Customers")

// Assumes that connection is a valid OleDbConnection object.
OleDbDataAdapter adapter = new OleDbDataAdapter();

OleDbCommand selectCMD = new OleDbCommand(selectSQL, connection);
adapter.SelectCommand = selectCMD;

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

DataSet customers = new DataSet();
adapter.Fill(customers, "Customers");

Odbc パラメータ

' Assumes that connection is a valid OdbcConnection object.
Dim adapter As OdbcDataAdapter = New OdbcDataAdapter

Dim selectCMD AS OdbcCommand = New OdbcCommand(selectSQL, connection)
adapter.SelectCommand = selectCMD

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

Dim customers As DataSet = New DataSet
adapter.Fill(customers, "Customers")

// Assumes that connection is a valid OdbcConnection object.
OdbcDataAdapter adapter = new OdbcDataAdapter();

OdbcCommand selectCMD = new OdbcCommand(selectSQL, connection);
adapter.SelectCommand = selectCMD;

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

DataSet customers = new DataSet();
adapter.Fill(customers, "Customers");
bbw6zyha.alert_note(ja-jp,VS.90).gifメモ :

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

参照

概念

DataAdapter によるデータ ソースの更新 (ADO.NET)

ストアド プロシージャでのデータの変更 (ADO.NET)

その他の技術情報

DataAdapter と DataReader (ADO.NET)

コマンドとパラメータ (ADO.NET)

ADO.NET でのデータ型のマッピング