Parámetros de DataAdapterDataAdapter Parameters

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.The DbDataAdapter has four properties that are used to retrieve data from and update data to the data source: the SelectCommand property returns data from the data source; and the InsertCommand , UpdateCommand, and DeleteCommand properties are used to manage changes at the data source. La propiedad SelectCommand debe establecerse antes de llamar al método Fill de DataAdapter.The SelectCommand property must be set before you call the Fill method of the 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.The InsertCommand, UpdateCommand, or DeleteCommand properties must be set before the Update method of the DataAdapter is called, depending on what changes were made to the data in the DataTable. Por ejemplo, si se han agregado filas, se debe establecer InsertCommand antes de llamar a Update.For example, if rows have been added, the InsertCommand must be set before you call Update. Cuando Update procesa una fila insertada, actualizada o eliminada, DataAdapter utiliza la propiedad Command que corresponde a la acción en cuestión.When Update is processing an inserted, updated, or deleted row, the DataAdapter uses the respective Command property to process the action. La información actual relacionada con la fila modificada se pasa al objeto Command a través de la colección Parameters.Current information about the modified row is passed to the Command object through the Parameters collection.

Al actualizar una fila en el origen de datos, se llama a la instrucción UPDATE, que utiliza un identificador único para identificar la fila de la tabla que se va a actualizar.When you update a row at the data source, you call the UPDATE statement, which uses a unique identifier to identify the row in the table to be updated. El identificador único suele ser el valor del campo de clave principal.The unique identifier is typically the value of a primary key field. 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.The UPDATE statement uses parameters that contain both the unique identifier and the columns and values to be updated, as shown in the following Transact-SQL statement.

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.The syntax for parameter placeholders depends on the data source. En este ejemplo se muestran marcadores de posición para un origen de datos de SQL Server.This example shows placeholders for a SQL Server data source. Utilice signos de interrogación de cierre (?) como marcadores de posición de para los parámetros System.Data.OleDb y System.Data.Odbc.Use question mark (?) placeholders for System.Data.OleDb and System.Data.Odbc parameters.

En este Visual Basic ejemplo, el CompanyName campo se actualiza con el valor del @CompanyName parámetro de la fila donde CustomerID es igual al valor del @CustomerID parámetro.In this Visual Basic example, the CompanyName field is updated with the value of the @CompanyName parameter for the row where CustomerID equals the value of the @CustomerID parameter. Los parámetros recuperan información de la fila modificada mediante la SourceColumn propiedad del SqlParameter objeto.The parameters retrieve information from the modified row using the SourceColumn property of the SqlParameter object. A continuación se muestran los parámetros del ejemplo anterior de la instrucción UPDATE.The following are the parameters for the previous sample UPDATE statement. En el código se parte de que el adapter de la variable representa a un objeto SqlDataAdapter válido.The code assumes that the variable adapter represents a valid SqlDataAdapter object.

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.The Add method of the Parameters collection takes the name of the parameter, the data type, the size (if applicable to the type), and the name of the SourceColumn from the DataTable. Tenga en cuenta que SourceVersion del parámetro @CustomerID se establece en Original.Notice that the SourceVersion of the @CustomerID parameter is set to 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.This guarantees that the existing row in the data source is updated if the value of the identifying column or columns has been changed in the modified DataRow. 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.In that case, the Original row value would match the current value at the data source, and the Current row value would contain the updated value. 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.The SourceVersion for the @CompanyName parameter is not set and uses the default, Current row value.

Nota

Para las Fill operaciones de DataAdapter y los Get métodos de DataReader , el tipo de .NET Framework se deduce del tipo devuelto por el proveedor de datos de .NET Framework.For both the Fill operations of the DataAdapter and the Get methods of the DataReader, the .NET Framework type is inferred from the type returned from the .NET Framework data provider. Los tipos de .NET Framework inferidos y los métodos de descriptor de acceso para los tipos de datos Microsoft SQL Server, OLE DB y ODBC se describen en asignaciones de tipos de datos en ADO.net.The inferred .NET Framework types and accessor methods for Microsoft SQL Server, OLE DB, and ODBC data types are described in Data Type Mappings in ADO.NET.

Parameter.SourceColumn, Parameter.SourceVersionParameter.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.The SourceColumn and SourceVersion may be passed as arguments to the Parameter constructor, or set as properties of an existing Parameter. SourceColumn es el nombre de DataColumn de DataRow en la que se recupera el valor de Parameter.The SourceColumn is the name of the DataColumn from the DataRow where the value of the Parameter will be retrieved. SourceVersion especifica la versión de DataRow que utiliza DataAdapter para recuperar el valor.The SourceVersion specifies the DataRow version that the DataAdapter uses to retrieve the value.

En la tabla siguiente se muestran los valores de la enumeración DataRowVersion disponibles para su uso con SourceVersion.The following table shows the DataRowVersion enumeration values available for use with SourceVersion.

Enumeración DataRowVersionDataRowVersion Enumeration DescripciónDescription
Current El parámetro utiliza el valor actual de la columna.The parameter uses the current value of the column. Este es el valor predeterminado.This is the default.
Default El parámetro utiliza el DefaultValue de la columna.The parameter uses the DefaultValue of the column.
Original El parámetro utiliza el valor original de la columna.The parameter uses the original value of the column.
Proposed El parámetro utiliza un valor propuesto.The parameter uses a proposed value.

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).The SqlClient code example in the next section defines a parameter for an UpdateCommand in which the CustomerID column is used as a SourceColumn for two parameters: @CustomerID (SET CustomerID = @CustomerID), and @OldCustomerID (WHERE CustomerID = @OldCustomerID). El @CustomerID parámetro se utiliza para actualizar la columna CustomerID al valor actual de DataRow .The @CustomerID parameter is used to update the CustomerID column to the current value in the DataRow. Como resultado, CustomerID SourceColumn se utiliza con un SourceVersion de Current .As a result, the CustomerID SourceColumn with a SourceVersion of Current is used. El @OldCustomerID parámetro se utiliza para identificar la fila actual en el origen de datos.The @OldCustomerID parameter is used to identify the current row in the data source. 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.Because the matching column value is found in the Original version of the row, the same SourceColumn (CustomerID) with a SourceVersion of Original is used.

Trabajar con parámetros SqlClientWorking with SqlClient Parameters

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.The following example demonstrates how to create a SqlDataAdapter and set the MissingSchemaAction to AddWithKey in order to retrieve additional schema information from the database. Las propiedades SelectCommand, InsertCommand, UpdateCommand y DeleteCommand establecen sus correspondientes objetos SqlParameter agregados a la colección Parameters.The SelectCommand, InsertCommand, UpdateCommand, and DeleteCommand properties set and their corresponding SqlParameter objects added to the Parameters collection. El método devuelve un objeto SqlDataAdapter.The method returns a SqlDataAdapter object.

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;
}
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

Marcadores de posición de parámetros OleDbOleDb Parameter Placeholders

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.For the OleDbDataAdapter and OdbcDataAdapter objects, you must use question mark (?) placeholders to identify the parameters.

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.The parameterized query statements define which input and output parameters must be created. 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.To create a parameter, use the Parameters.Add method or the Parameter constructor to specify the column name, data type, and size. 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.For intrinsic data types, such as Integer, you do not have to include the size, or you can specify the default size.

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.The following code example creates the parameters for a SQL statement and then fills a DataSet.

Ejemplo de OleDbOleDb Example

' 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 OdbcOdbc Parameters

' 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 de parámetro para un parámetro, el parámetro recibe un nombre predeterminado incremental del parámetroN , comenzando por "parámetro1".If a parameter name is not supplied for a parameter, the parameter is given an incremental default name of ParameterN , starting with "Parameter1". Se recomienda evitar la Convención de nomenclatura del parámetroN cuando se proporciona un nombre de parámetro, porque el nombre proporcionado puede entrar en conflicto con un nombre de parámetro predeterminado existente en ParameterCollection .We recommend that you avoid the ParameterN naming convention when you supply a parameter name, because the name that you supply might conflict with an existing default parameter name in the ParameterCollection. Si el nombre proporcionado ya existe, se inicia una excepción.If the supplied name already exists, an exception is thrown.

Consulte tambiénSee also