Parámetros DataAdapter (ADO.NET)

Artículo
10/07/2008

Actualización: November 2007

DbDataAdapter tiene cuatro propiedades que se utilizan para recuperar y actualizar datos en el origen de datos: la propiedad SelectCommand devuelve datos del origen de datos y las propiedades InsertCommand , UpdateCommand y DeleteCommand se utilizan para administrar los cambios en el origen de datos. La propiedad SelectCommand debe establecerse antes de llamar al método Fill de DataAdapter. Las propiedades InsertCommand, UpdateCommand o DeleteCommand se deben establecer antes llamar al método Update de DataAdapter, en función de las modificaciones realizadas en los datos en DataTable. Por ejemplo, si se han agregado filas, se debe establecer InsertCommand antes de llamar a Update. Cuando Update procesa una fila insertada, actualizada o eliminada, DataAdapter utiliza la propiedad Command que corresponde a la acción en cuestión. La información actual relacionada con la fila modificada se pasa al objeto Command a través de la colección Parameters.

Cuando actualice una fila en el origen de datos, llame a la instrucción UPDATE que utiliza un identificador único para identificar la fila de la tabla que debe actualizarse. El identificador único suele ser el valor del campo de clave principal. La instrucción UPDATE utiliza parámetros que contienen el identificador único y las columnas y valores que se van a actualizar, como muestra la siguiente instrucción Transact-SQL.

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

Nota:
La sintaxis de los marcadores de posición de parámetros depende del origen de datos. En este ejemplo se muestran marcadores de posición para un origen de datos de SQL Server. Utilice signos de interrogación de cierre (?) como marcadores de posición de para los parámetros System.Data.OleDb y System.Data.Odbc.

En este ejemplo de Visual Basic, el campo CompanyName se actualiza con el valor del parámetro @CompanyName para la fila cuyo CustomerID coincida con el valor del parámetro @CustomerID. Los parámetros recuperan información de la fila modificada mediante la propiedad SourceColumn del objeto SqlParameter. A continuación se muestran los parámetros del ejemplo anterior de la instrucción UPDATE. En el código se parte de que el adapter de la variable representa a un 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

El método Add de la colección Parameters toma el nombre del parámetro, el tipo de datos, el tamaño (si corresponde al tipo) y el nombre de la propiedad SourceColumn de DataTable. Tenga en cuenta que SourceVersion del parámetro @CustomerID se establece en Original. De esta forma se garantiza que la fila existente en el origen de datos se actualice cuando el valor de la columna o columnas identificadas haya cambiado en la fila DataRow modificada. En ese caso, el valor de la fila Original coincidiría con el valor actual en el origen de datos y el valor de la fila Current contendría el valor actualizado. No se asigna ningún valor a SourceVersion para el parámetro @CompanyName, por lo que se utiliza el valor predeterminado, el de la fila Current.

Nota:
En las operaciones Fill de DataAdapter y los métodos Get de DataReader, el tipo .NET Framework se deduce del tipo devuelto desde el proveedor de datos de .NET Framework. Los métodos de descriptor de acceso y los tipos de .NET Framework deducidos para tipos de datos de Microsoft SQL Server, OLE DB y ODBC se describen en Asignar tipos de datos en ADO.NET.

Parameter.SourceColumn, Parameter.SourceVersion

SourceColumn y SourceVersion se pueden pasar como argumentos al constructor Parameter, o también se pueden establecer como propiedades de un Parameter existente. SourceColumn es el nombre de DataColumn de DataRow en la que se recupera el valor de Parameter . SourceVersion especifica la versión de DataRow que utiliza DataAdapter para recuperar el valor.

En la tabla siguiente se muestran los valores de la enumeración DataRowVersion disponibles para su uso con SourceVersion.

Enumeración DataRowVersion	Descripción
Current	El parámetro utiliza el valor actual de la columna. Éste es el valor predeterminado.
Default	El parámetro utiliza el DefaultValue de la columna.
Original	El parámetro utiliza el valor original de la columna.
Proposed	El parámetro utiliza un valor propuesto.

En el ejemplo de código de SqlClient de la siguiente sección se define un parámetro para UpdateCommand donde la columna CustomerID se utiliza como SourceColumn para dos parámetros: @CustomerID (SET CustomerID = @CustomerID) y @OldCustomerID (WHERE CustomerID = @OldCustomerID). El parámetro @CustomerID se utiliza para actualizar la columna CustomerID de forma que tenga el valor actual de DataRow. Como resultado, se usa CustomerID SourceColumn con SourceVersion de Current. El parámetro @OldCustomerID se utiliza para identificar la fila actual en el origen de datos. Dado que el valor de la columna coincidente se encuentra en la versión Original de la fila, también se usa el mismo objeto SourceColumn (CustomerID) con SourceVersion de Original.

Trabajar con parámetros SqlClient

En el ejemplo siguiente se muestra cómo crear SqlDataAdapter y establecer MissingSchemaAction en AddWithKey para recuperar información de esquema adicional de la base de datos. Las propiedades SelectCommand, InsertCommand, UpdateCommand y DeleteCommand establecen sus correspondientes objetos SqlParameter agregados a la colección Parameters . El método devuelve un objeto 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;
}

Marcadores de posición de parámetros OleDb

En el caso de los objetos OleDbDataAdapter y OdbcDataAdapter, debe utilizar signos de interrogación de cierre (?) como marcadores de posición para identificar los 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 = ?";

Las instrucciones de consulta con parámetros definen qué parámetros de entrada y de salida se deben crear. Para crear un parámetro, se utiliza el método Parameters.Add o el constructor Parameter con el fin de especificar el nombre de columna, tipo de datos y tamaño. En el caso de tipos de datos intrínsecos, como Integer, no es necesario incluir el tamaño, aunque se puede especificar el tamaño predeterminado.

En el ejemplo de código siguiente se crean los parámetros para una instrucción SQL y, a continuación, se llena un DataSet.

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

Nota:
Si no se proporciona un nombre para un parámetro, éste toma un nombre predeterminado incremental del tipo ParameterN, que comienza por "Parameter1". Se recomienda evitar la convención de nomenclatura del tipo "ParameterN" al asignar un nombre de parámetro, ya que dicho nombre podría entrar en conflicto con un nombre de parámetro predeterminado existente en ParameterCollection. Si el nombre proporcionado ya existe, se inicia una excepción.

Si no se proporciona un nombre para un parámetro, éste toma un nombre predeterminado incremental del tipo ParameterN, que comienza por "Parameter1". Se recomienda evitar la convención de nomenclatura del tipo "ParameterN" al asignar un nombre de parámetro, ya que dicho nombre podría entrar en conflicto con un nombre de parámetro predeterminado existente en ParameterCollection. Si el nombre proporcionado ya existe, se inicia una excepción.