Parâmetros DataAdapter

O DbDataAdapter tem quatro propriedades que são usadas para recuperar dados e atualizar dados para a fonte de dados: a SelectCommand propriedade retorna dados da fonte de dados e as propriedades , InsertCommande UpdateCommand e DeleteCommand são usadas para gerenciar alterações na fonte de dados. A SelectCommand propriedade deve ser definida antes de chamar o Fill método do DataAdapter. As InsertCommandpropriedades , UpdateCommand, ou DeleteCommand devem ser definidas antes que o UpdateDataAdapter método do seja chamado, dependendo de quais alterações foram feitas nos dados no DataTable. Por exemplo, se linhas foram adicionadas, o deve ser definido antes de InsertCommand chamar Update. Quando Update está processando uma linha inserida, atualizada ou excluída, o DataAdapter usa a respetiva Command propriedade para processar a ação. As informações atuais sobre a linha modificada são passadas para o Command objeto através da Parameters coleção.

Ao atualizar uma linha na fonte de dados, você chama a instrução UPDATE, que usa um identificador exclusivo para identificar a linha na tabela a ser atualizada. O identificador exclusivo é normalmente o valor de um campo de chave primária. A instrução UPDATE usa parâmetros que contêm o identificador exclusivo e as colunas e valores a serem atualizados, conforme mostrado na instrução Transact-SQL a seguir.

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

Neste exemplo do Visual Basic, o CompanyName campo é atualizado com o @CompanyName valor do parâmetro para a linha onde CustomerID é igual ao valor do @CustomerID parâmetro. Os parâmetros recuperam informações da linha modificada usando a SourceColumnSqlParameter propriedade do objeto. A seguir estão os parâmetros para a instrução UPDATE de exemplo anterior. O código pressupõe que a variável adapter representa um objeto válido 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

O Add método da coleção leva o nome do parâmetro, o tipo de Parameters dados, o tamanho (se aplicável ao tipo) e o nome do SourceColumnDataTable. Observe que o SourceVersion do parâmetro está @CustomerID definido como Original. Isso garante que a linha existente na fonte de dados seja atualizada se o valor da coluna ou colunas de identificação tiver sido alterado no arquivo DataRowmodificado. Nesse caso, o valor da Original linha corresponderia ao valor atual na fonte de dados e o valor da Current linha conteria o valor atualizado. O SourceVersion parâmetro for não @CompanyName está definido e usa o valor de linha padrão. Current

Parameter.SourceColumn (coluna de origem), Parameter.SourceVersion (versão de origem)

O SourceColumn e SourceVersion pode ser passado como argumentos para o Parameter construtor, ou definido como propriedades de um existente Parameter. O SourceColumn é o nome do DataColumn de onde o DataRow valor do será recuperado Parameter . O SourceVersion especifica a DataRow versão que o DataAdapter usa para recuperar o valor.

A tabela a seguir mostra os valores de enumeração disponíveis para uso com DataRowVersiono SourceVersion .

O SqlClient exemplo de código na próxima seção define um parâmetro para um UpdateCommand no qual a CustomerID coluna é usada como um SourceColumn para dois parâmetros: @CustomerID (SET CustomerID = @CustomerID), e @OldCustomerID (WHERE CustomerID = @OldCustomerID). O @CustomerID parâmetro é usado para atualizar a CustomerID coluna para o valor atual no DataRow. Como resultado, o CustomerIDSourceColumn com a SourceVersion de Current é usado. O @OldCustomerID parâmetro é usado para identificar a linha atual na fonte de dados. Como o valor da coluna correspondente é encontrado na Original versão da linha, o mesmo SourceColumn (CustomerID) com um SourceVersion de Original é usado.

Trabalhando com parâmetros SqlClient

O exemplo a seguir demonstra como criar um SqlDataAdapter e definir o MissingSchemaAction para AddWithKey recuperar informações adicionais de esquema do banco de dados. O SelectCommandconjunto de propriedades , InsertCommand, UpdateCommande DeleteCommand e seus objetos correspondentes SqlParameter adicionados à Parameters coleção. O método retorna um SqlDataAdapter objeto.

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

Espaços reservados para parâmetros OleDb

Para os OleDbDataAdapter objetos e OdbcDataAdapter , você deve usar espaços reservados de ponto de interrogação (?) para identificar os parâmetros.

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

As instruções de consulta parametrizadas definem quais parâmetros de entrada e saída devem ser criados. Para criar um parâmetro, use o Parameters.Add método ou o Parameter construtor para especificar o nome da coluna, o tipo de dados e o tamanho. Para tipos de dados intrínsecos, como Integer, não é necessário incluir o tamanho ou especificar o tamanho padrão.

O exemplo de código a seguir cria os parâmetros para uma instrução SQL e, em seguida, preenche um DataSetarquivo .

Exemplo de 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");

Parâmetros 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");

Consulte também

• DataAdapters e DataReaders
• Comandos e parâmetros
• Atualizando fontes de dados com DataAdapters
• Modificando dados com procedimentos armazenados
• Mapeamentos de tipo de dados no ADO.NET
• Visão geral ADO.NET