Параметры DataAdapter

Статья
04/11/2023

Класс 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 в качестве местозаполнителей используйте вопросительный знак (?).

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

Parameter.SourceColumn, Parameter.SourceVersion

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

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

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

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

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

Следующий пример демонстрирует, как создать SqlDataAdapter и установить MissingSchemaAction в AddWithKey, чтобы получить из базы данных дополнительные сведения о схеме. Устанавливаются свойства SelectCommand, InsertCommand, UpdateCommand и DeleteCommand, и соответствующие им объекты SqlParameter добавляются в коллекцию Parameters. Метод возвращает объект SqlDataAdapter.

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

        // Create the commands.
        SelectCommand = new SqlCommand(
        "SELECT CustomerID, CompanyName FROM CUSTOMERS", connection),
        InsertCommand = new SqlCommand(
        "INSERT INTO Customers (CustomerID, CompanyName) " +
        "VALUES (@CustomerID, @CompanyName)", connection),
        UpdateCommand = new SqlCommand(
        "UPDATE Customers SET CustomerID = @CustomerID, CompanyName = @CompanyName " +
        "WHERE CustomerID = @oldCustomerID", connection),
        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

Для объектов 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");

Примечание.

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

Параметры DataAdapter

Parameter.SourceColumn, Parameter.SourceVersion

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

Местозаполнители параметров OleDb

Пример OleDb

Параметры Odbc

См. также

Дополнительные ресурсы