Параметры DataAdapter (ADO.NET)

Статья
11/04/2008

Обновлен: November 2007

Класс DbDataAdapter имеет четыре свойства, которые используются для получения данных из источника данных и обновления данных в нем: свойство SelectCommand возвращает данные из источника данных, а свойства InsertCommand, UpdateCommand и DeleteCommand используются для управления изменениями в источнике данных. Свойство SelectCommand должно быть установлено до вызова метода Fill объекта DataAdapter. Свойства InsertCommand, UpdateCommand или DeleteCommand должны быть установлены до вызова метода Update объекта DataAdapter в зависимости от того, какие изменения были сделаны в данных в DataTable. Например, если добавлены строки, свойство InsertCommand должно быть установлено перед вызовом метода Update. Если метод Update обрабатывает вставленную, обновленную или удаленную строку, DataAdapter использует соответствующее свойство Command для обработки действия. Текущие данные об измененной строке передаются в объект Command через коллекцию Parameters.

При обновлении строки в источнике данных вызывается инструкция UPDATE, которая использует уникальный идентификатор для идентификации строки обновляемой таблицы. Уникальным идентификатором обычно является значение поля первичного ключа. Инструкция UPDATE использует параметры, содержащие и уникальный идентификатор, и столбцы и обновляемые значения, как показано в следующей инструкции Transact-SQL.

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

Примечание.
Синтаксис местозаполнителей параметров зависит от источника данных. В этом примере показаны местозаполнители для источника данных SQL Server. Для параметров System.Data.OleDb и System.Data.Odbc в качестве местозаполнителей используйте вопросительный знак (?).

Синтаксис местозаполнителей параметров зависит от источника данных. В этом примере показаны местозаполнители для источника данных SQL Server. Для параметров System.Data.OleDb и System.Data.Odbc в качестве местозаполнителей используйте вопросительный знак (?).

В этом примере на Visual Basic поле CompanyName обновляется значением параметра @CompanyName для строки, в которой CustomerID равен значению параметра @CustomerID. Параметры получают данные из измененной строки, используя свойство SourceColumn объекта SqlParameter. Далее представлены параметры для предыдущего образца инструкции 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

Метод Add коллекции Parameters принимает имя параметра, тип данных, размер (если он применим к типу) и имя SourceColumn из DataTable. Обратите внимание, что SourceVersion параметра @CustomerID установлена в Original. Это гарантирует, что существующая строка в источнике данных обновляется, если значение идентифицирующих столбцов изменилось в измененном DataRow. В этом случае значение строки Original будет соответствовать текущему значению в источнике данных и значение строки Current будет содержать обновленное значение. SourceVersion для параметра @CompanyName не установлена и использует значение по умолчанию строки Current.

Примечание.
Как для операций Fill объекта DataAdapter, так и для методов Get объекта DataReader тип .NET Framework выводится из типа, возвращаемого поставщиком данных .NET Framework. Выводимые типы .NET Framework и методы доступа для типов данных Microsoft SQL Server, OLE DB и ODBC описываются в разделе Сопоставления типов данных в ADO.NET.

Как для операций Fill объекта DataAdapter, так и для методов Get объекта DataReader тип .NET Framework выводится из типа, возвращаемого поставщиком данных .NET Framework. Выводимые типы .NET Framework и методы доступа для типов данных Microsoft SQL Server, OLE DB и ODBC описываются в разделе Сопоставления типов данных в ADO.NET.

Parameter.SourceColumn, Parameter.SourceVersion

SourceColumn и SourceVersion могут быть посланы как аргументы в конструктор Parameter или установлены как свойства существующих Parameter. SourceColumn является именем DataColumn из DataRow, где значение Parameter будет получено. SourceVersion задает версию DataRow, которую DataAdapter использует для получения значения.

В следующей таблице показаны значения перечисления DataRowVersion, доступные для использования с SourceVersion.

Перечисление DataRowVersion	Описание
Current	Параметр использует текущее значение столбца. Это настройка по умолчанию.
Default	Параметр использует DefaultValue столбца.
Original	Параметр использует исходное значение столбца.
Proposed	Параметр использует предложенное значение.

В примере кода следующего раздела определяется параметр SqlClient для UpdateCommand, в которой столбец CustomerID используется как SourceColumn для двух параметров: @CustomerID (SET CustomerID = @CustomerID) и @OldCustomerID (WHERE CustomerID = @OldCustomerID). Параметр @CustomerID используется для обновления столбца CustomerID текущим значением в DataRow. В результате используется CustomerID SourceColumn с SourceVersion для Current. Параметр @OldCustomerID используется для идентификации текущей строки в источнике данных. Так как в версии Original строки найдено значение, совпадающее со значением столбца, используется тот же SourceColumn (CustomerID) с SourceVersion для Original.

Работа с параметрами 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");

Примечание.
Если для параметра не указано имя, ему присваивается имя по умолчанию ParameterN с увеличивающимся целочисленным суффиксом N, начиная с имени «Parameter1». Рекомендуется избегать практики именования в виде ParameterN при указании имени параметра, т. к. такое имя может конфликтовать с именем существующего параметра по умолчанию в ParameterCollection. Если указанное имя уже существует, возникает исключение.

Если для параметра не указано имя, ему присваивается имя по умолчанию ParameterN с увеличивающимся целочисленным суффиксом N, начиная с имени «Parameter1». Рекомендуется избегать практики именования в виде ParameterN при указании имени параметра, т. к. такое имя может конфликтовать с именем существующего параметра по умолчанию в ParameterCollection. Если указанное имя уже существует, возникает исключение.