DataAdapter パラメーターDataAdapter Parameters

DbDataAdapter には 4 つのプロパティがあり、データ ソースからデータを取得したりデータ ソースのデータを更新したりするために使用されます。SelectCommand プロパティは、データ ソースのデータを返します。InsertCommandUpdateCommand、および DeleteCommand の各プロパティは、データ ソースの変更を管理するために使用されます。The DbDataAdapter has four properties that are used to retrieve data from and update data to the data source: the SelectCommand property returns data from the data source; and the InsertCommand , UpdateCommand, and DeleteCommand properties are used to manage changes at the data source. SelectCommand プロパティは、FillDataAdapter メソッドを呼び出す前に設定しておく必要があります。The SelectCommand property must be set before you call the Fill method of the DataAdapter. InsertCommandUpdateCommandDeleteCommand の各プロパティは、Update 内のデータに加えられた変更に応じて、DataAdapterDataTable メソッドを呼び出す前に設定する必要があります。The InsertCommand, UpdateCommand, or DeleteCommand properties must be set before the Update method of the DataAdapter is called, depending on what changes were made to the data in the DataTable. たとえば、行が追加された場合には、InsertCommand を呼び出す前に Update を設定する必要があります。For example, if rows have been added, the InsertCommand must be set before you call Update. Update によって挿入行、更新行、または削除行が処理されるとき、DataAdapter でそれぞれの Command プロパティが使用され、アクションが処理されます。When Update is processing an inserted, updated, or deleted row, the DataAdapter uses the respective Command property to process the action. 変更された行に関する現在の情報が Command コレクションを経由して Parameters オブジェクトに渡されます。Current information about the modified row is passed to the Command object through the Parameters collection.

データソースで行を更新する場合は、UPDATE ステートメントを呼び出します。このステートメントでは、一意の識別子を使用して、更新するテーブル内の行を識別します。When you update a row at the data source, you call the UPDATE statement, which uses a unique identifier to identify the row in the table to be updated. 一意識別子は、一般には主キー フィールドの値です。The unique identifier is typically the value of a primary key field. UPDATE ステートメントでは、次の Transact-SQL ステートメントに示すように、一意識別子と更新する列および値の両方を含むパラメーターを使用します。The UPDATE statement uses parameters that contain both the unique identifier and the columns and values to be updated, as shown in the following Transact-SQL statement.

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

注意

パラメーターのプレースホルダーの構文はデータ ソースに依存します。The syntax for parameter placeholders depends on the data source. 次に、SQL Server のデータ ソースのプレースホルダーの例を示します。This example shows placeholders for a SQL Server data source. System.Data.OleDb パラメーターおよび System.Data.Odbc パラメーターのプレースホルダーとして、疑問符 (?) を使用します。Use question mark (?) placeholders for System.Data.OleDb and System.Data.Odbc parameters.

この Visual Basic 例では、 CompanyNameフィールドは、が@CustomerIDパラメーターの値と@CompanyName CustomerID等しい行のパラメーターの値によって更新されます。In this Visual Basic example, the CompanyName field is updated with the value of the @CompanyName parameter for the row where CustomerID equals the value of the @CustomerID parameter. パラメーターは、 SourceColumn SqlParameterオブジェクトのプロパティを使用して、変更された行から情報を取得します。The parameters retrieve information from the modified row using the SourceColumn property of the SqlParameter object. 前のサンプル UPDATE ステートメントのパラメーターを次に示します。The following are the parameters for the previous sample UPDATE statement. このコードは、変数 adapter が有効な SqlDataAdapter オブジェクトを表すことを前提としています。The code assumes that the variable adapter represents a valid SqlDataAdapter object.

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 から受け取ります。The Add method of the Parameters collection takes the name of the parameter, the data type, the size (if applicable to the type), and the name of the SourceColumn from the DataTable. SourceVersion パラメーターの @CustomerIDOriginal に設定されることに注意してください。Notice that the SourceVersion of the @CustomerID parameter is set to Original. この設定により、変更された DataRow で 1 つまたは複数の識別列の値が変更されている場合に、データ ソース内の既存の行が確実に更新されます。This guarantees that the existing row in the data source is updated if the value of the identifying column or columns has been changed in the modified DataRow. 識別列の値が変更されている場合、Original 行の値がデータ ソースの現在の値と一致し、Current 行の値に更新済みの値が格納されます。In that case, the Original row value would match the current value at the data source, and the Current row value would contain the updated value. SourceVersion パラメーターの @CompanyName は設定されていないため、既定値である Current の行の値が使用されます。The SourceVersion for the @CompanyName parameter is not set and uses the default, Current row value.

注意

Fill操作DataAdapterGetのメソッドの両方について、.NETFramework型は.NETFrameworkデータプロバイダーから返された型から推論されます。DataReaderFor both the Fill operations of the DataAdapter and the Get methods of the DataReader, the .NET Framework type is inferred from the type returned from the .NET Framework data provider. Microsoft SQL Server、OLE DB、および ODBC データ型の推論された .NET Framework 型およびアクセサーメソッドについては、「 ADO.NET のデータ型のマッピング」を参照してください。The inferred .NET Framework types and accessor methods for Microsoft SQL Server, OLE DB, and ODBC data types are described in Data Type Mappings in ADO.NET.

Parameter.SourceColumn、Parameter.SourceVersionParameter.SourceColumn, Parameter.SourceVersion

SourceColumn および SourceVersion が、引数として Parameter コンストラクターに渡されるか、既存の Parameter のプロパティとして設定されます。The SourceColumn and SourceVersion may be passed as arguments to the Parameter constructor, or set as properties of an existing Parameter. SourceColumn は、DataColumn の値の取得先である DataRowParameter の名前です。The SourceColumn is the name of the DataColumn from the DataRow where the value of the Parameter will be retrieved. SourceVersion により、DataRow で値の取得に使用される DataAdapter のバージョンを指定します。The SourceVersion specifies the DataRow version that the DataAdapter uses to retrieve the value.

DataRowVersion で使用できる SourceVersion 列挙型の値を次の表に示します。The following table shows the DataRowVersion enumeration values available for use with SourceVersion.

DataRowVersion 列挙定数DataRowVersion Enumeration 説明Description
Current このパラメーターは列の現在の値を使用します。The parameter uses the current value of the column. 既定値です。This is the default.
Default このパラメーターには列の DefaultValue を使用します。The parameter uses the DefaultValue of the column.
Original このパラメーターは列の元の値を使用します。The parameter uses the original value of the column.
Proposed このパラメーターは提示された値を使用します。The parameter uses a proposed value.

次のセクションの SqlClient コード サンプルでは、UpdateCommand 列を 2 つのパラメーター CustomerID (SourceColumn) および @CustomerID (SET CustomerID = @CustomerID) の @OldCustomerID として使用する WHERE CustomerID = @OldCustomerID のパラメーターを定義します。The SqlClient code example in the next section defines a parameter for an UpdateCommand in which the CustomerID column is used as a SourceColumn for two parameters: @CustomerID (SET CustomerID = @CustomerID), and @OldCustomerID (WHERE CustomerID = @OldCustomerID). パラメーターを使用して、 CustomerID列をのDataRow現在の値に更新します。 @CustomerIDThe @CustomerID parameter is used to update the CustomerID column to the current value in the DataRow. その結果CustomerID SourceVersion 、がCurrentであるが使用されます。 SourceColumnAs a result, the CustomerID SourceColumn with a SourceVersion of Current is used. @OldCustomerIDパラメーターは、データソースの現在の行を識別するために使用されます。The @OldCustomerID parameter is used to identify the current row in the data source. 一致する列の値がその行の Original バージョンで見つかったため、SourceColumnCustomerID である同じ SourceVersion (Original) が使用されます。Because the matching column value is found in the Original version of the row, the same SourceColumn (CustomerID) with a SourceVersion of Original is used.

SqlClient パラメーターの使用Working with SqlClient Parameters

次のコード サンプルでは、データベースから追加のスキーマ情報を取得するために SqlDataAdapter を作成し、MissingSchemaActionAddWithKey に設定する方法を示します。The following example demonstrates how to create a SqlDataAdapter and set the MissingSchemaAction to AddWithKey in order to retrieve additional schema information from the database. SelectCommand プロパティ、InsertCommand プロパティ、UpdateCommand プロパティ、および DeleteCommand プロパティが設定され、各プロパティに対応する SqlParameter オブジェクトが Parameters コレクションに追加されます。The SelectCommand, InsertCommand, UpdateCommand, and DeleteCommand properties set and their corresponding SqlParameter objects added to the Parameters collection. このメソッドは SqlDataAdapter オブジェクトを返します。The method returns a SqlDataAdapter object.

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;
}
Public Function CreateSqlDataAdapter( _
    ByVal connection As SqlConnection) As SqlDataAdapter

    Dim adapter As 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

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

OleDbDataAdapter オブジェクトと OdbcDataAdapter オブジェクトの場合は、疑問符 (?) のプレースホルダーを使用してパラメーターを特定する必要があります。For the OleDbDataAdapter and OdbcDataAdapter objects, you must use question mark (?) placeholders to identify the parameters.

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 = ?";  

パラメーターとして使用されるクエリ ステートメントは、作成する必要のある入力パラメーターおよび出力パラメーターを定義します。The parameterized query statements define which input and output parameters must be created. パラメーターを作成するには、Parameters.Add メソッドまたは Parameter コンストラクターを使用して、列名、データ型、およびサイズを指定します。To create a parameter, use the Parameters.Add method or the Parameter constructor to specify the column name, data type, and size. Integer などの組み込みのデータ型の場合は、サイズを指定する必要はありません。サイズを指定する場合、既定のサイズを指定することになります。For intrinsic data types, such as Integer, you do not have to include the size, or you can specify the default size.

次のコード サンプルでは、SQL ステートメントのパラメーターを作成した後、DataSet にデータを格納します。The following code example creates the parameters for a SQL statement and then fills a DataSet.

OleDb の例OleDb Example

' 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 パラメーターOdbc Parameters

' 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");  

注意

パラメーター名がパラメーターに指定されていない場合、パラメーターには、"Parameter1"から始まるパラメーター Nの増分既定名が指定されます。If a parameter name is not supplied for a parameter, the parameter is given an incremental default name of ParameterN , starting with "Parameter1". パラメーター名を指定するときは、パラメーター名の名前付け規則を使用しないことをお勧めします。これは、 ParameterCollection指定した名前が内の既存の既定のパラメーター名と競合する可能性があるためです。We recommend that you avoid the ParameterN naming convention when you supply a parameter name, because the name that you supply might conflict with an existing default parameter name in the ParameterCollection. 指定した名前が既に存在する場合は、例外がスローされます。If the supplied name already exists, an exception is thrown.

関連項目See also