Параметры DataAdapterDataAdapter Parameters

Класс DbDataAdapter имеет четыре свойства, которые служат для получения данных из источника данных и обновления данных в нем: свойство SelectCommand возвращает данные из источника данных, а свойства InsertCommand, UpdateCommand и 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 должно быть установлено до вызова метода Fill объекта DataAdapter.The SelectCommand property must be set before you call the Fill method of the DataAdapter. Свойства InsertCommand, UpdateCommand или DeleteCommand должны быть установлены до вызова метода Update объекта DataAdapter в зависимости от того, какие изменения были сделаны в данных в DataTable.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.

CompanyName В этом Visual Basic примере поле обновляется значением @CompanyName параметра для строки, где CustomerID равно значению @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  

Метод Add коллекции Parameters принимает имя параметра, тип данных, размер (если он применим к типу) и имя 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 параметра @CustomerID установлена в Original.Notice that the SourceVersion of the @CustomerID parameter is set to Original. Это гарантирует, что существующая строка в источнике данных обновляется, если значение идентифицирующих столбцов изменилось в измененном DataRow.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 операций DataAdapter , Get такDataReaderи для методов, тип .NET Framework выводится из типа, возвращаемого поставщиком данных .NET Framework.For 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. Выводимые типы .NET Framework и методы доступа для типов данных Microsoft SQL Server, OLE DB и ODBC описаны в разделе сопоставления типов данных в 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 из DataRow, где значение Parameter будет получено.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.

Перечисление DataRowVersionDataRowVersion 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, в котором столбец 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 В результате используется элемент SourceColumn WITH SourceVersion сCurrent .As 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 строки найдено значение, совпадающее со значением столбца, используется тот же SourceColumn (CustomerID) с 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.

Работа с параметрами SqlClientWorking with SqlClient Parameters

Следующий пример демонстрирует, как создать SqlDataAdapter и установить MissingSchemaAction в AddWithKey, чтобы получить из базы данных дополнительные сведения о схеме.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

Местозаполнители параметров OleDbOleDb 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.

Пример OleDbOleDb 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");  

Параметры OdbcOdbc 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");  

Примечание

Если для параметра не указано имя параметра, то параметру присваивается добавочное имя по умолчанию параметраN , начиная с "параметр1".If a parameter name is not supplied for a parameter, the parameter is given an incremental default name of ParameterN , starting with "Parameter1". Рекомендуется избегать использования параметраN в соглашении об именовании при указании имени параметра, так как указываемое имя может конфликтовать с существующим именем параметра по умолчанию в 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