Parâmetros DataAdapter

  • Artigo

O DbDataAdapter tem quatro propriedades que são usadas para recuperar dados da fonte de dados e atualizá-los nela: a propriedade SelectCommand retorna dados da fonte de dados; e as propriedades InsertCommand, UpdateCommand e DeleteCommand são usadas para gerenciar alterações na fonte de dados. A propriedade SelectCommand deve ser definida antes que você chame o método Fill do DataAdapter. A propriedade InsertCommand, UpdateCommand ou DeleteCommand deve ser definida antes que o método Update do DataAdapter seja chamado, dependendo de quais alterações foram feitas nos dados da DataTable. Por exemplo, se as linhas tiverem sido adicionadas, o InsertCommand deve ser definido antes de chamar Update. Quando Update estiver processando uma linha inserida, atualizada ou excluída, o DataAdapter usará a respectiva propriedade Command para processar a ação. As informações atuais sobre a linha modificada são passadas para o objeto Command através da coleção Parameters.

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

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

Observação

A sintaxe para espaços reservados de parâmetro depende da fonte de dados. Este exemplo mostra os espaços reservados de uma fonte de dados do SQL Server. Use espaços reservados de ponto de interrogação (?) para os parâmetros System.Data.OleDb e System.Data.Odbc.

Neste exemplo do Visual Basic, o campo CompanyName é atualizado com o valor do parâmetro @CompanyName para a linha em que CustomerID é igual ao valor do parâmetro @CustomerID. Os parâmetros recuperam informações da linha modificada usando a propriedade SourceColumn do objeto SqlParameter. Estes são os parâmetros da instrução UPDATE de exemplo anterior. O código assume que a variável adapter representa um objeto SqlDataAdapter válido.

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 método Add da coleção Parameters adota o nome do parâmetro, o tipo de dados, o tamanho (se aplicável ao tipo) e o nome da SourceColumn da DataTable. Observe que SourceVersion do parâmetro @CustomerID é definido como Original. Isso garante que a linha existente na fonte de dados será atualizada se o valor da(s) coluna(s) de identificação tiverem sido alteradas na DataRow modificada. Nesse caso, o valor de linha Original corresponderia ao valor atual na fonte de dados, e o valor de linha Current conteria o valor atualizado. A SourceVersion do parâmetro @CompanyName não está definida e usa o padrão, o valor de linha Current.

Observação

Para as operações Fill do DataAdapter e os métodos Get do DataReader, o tipo .NET Framework é inferido do tipo retornado do provedor de dados .NET Framework. Os tipos do .NET Framework inferidos e os métodos de acesso aos tipos de dados ODBC, OLE DB e do Microsoft SQL Server são descritos em Mapeamentos de tipos de dados no ADO.NET.

Parameter.SourceColumn, Parameter.SourceVersion

A SourceColumn e a SourceVersion podem ser passadas como argumentos para o construtor Parameter ou definidas como propriedades de um Parameter existente. A SourceColumn é o nome da DataColumn da DataRow, em que o valor do Parameter será recuperado. A SourceVersion especifica a versão da DataRow que o DataAdapter usa para recuperar o valor.

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

Enumeração DataRowVersion Descrição
Current O parâmetro usa o valor atual da coluna. Este é o padrão.
Default O parâmetro usa o DefaultValue da coluna.
Original O parâmetro usa o valor original da coluna.
Proposed O parâmetro usa um valor proposto.

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

Trabalhando com parâmetros SqlClient

O exemplo a seguir demonstra como criar um SqlDataAdapter e definir MissingSchemaAction para AddWithKey a fim de recuperar informações adicionais do esquema no banco de dados. O conjunto de propriedades SelectCommand, InsertCommand, UpdateCommand e DeleteCommand e os objetos SqlParameter correspondentes adicionados à coleção Parameters. O método retorna um objeto 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

Espaços reservados do parâmetro OleDb

Para os objetos OleDbDataAdapter e OdbcDataAdapter, você deve usar os 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 de saída devem ser criados. Para criar um parâmetro, use o método Parameters.Add ou o construtor Parameter para especificar o nome da coluna, o tipo de dados e o tamanho. Para tipos de dados intrínsecos, como Integer, você não precisa incluir o tamanho ou pode especificar o tamanho padrão.

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

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

Observação

Se um nome de parâmetro não for fornecido para um parâmetro, o parâmetro receberá um nome padrão incremental de ParameterN, começando com "Parameter1". É recomendável evitar o uso da convenção de nomenclatura ParameterN ao fornecer um nome de parâmetro porque o nome fornecido poderá entrar em conflito com um nome de parâmetro padrão existente no ParameterCollection. Se o nome fornecido já existir, será gerada uma exceção.

Confira também