Parámetros de los comandos de adaptadores de datos

Artículo
10/07/2008

Actualización: noviembre 2007

Los comandos de un adaptador de datos (los definidos en la propiedad CommandText de los objetos SelectCommand,InsertCommand, UpdateCommand y DeleteCommand) normalmente utilizan parámetros. En tiempo de ejecución, los parámetros se utilizan para pasar valores a las instrucciones SQL o los procedimientos almacenados representados por los comandos.

Nota:
En la versión anterior de Visual Studio, los adaptadores de datos se usaban para la comunicación entre una aplicación con una base de datos. Aunque los adaptadores de datos siguen siendo un componente fundamental de los .Proveedores de datos de .NET Framework (ADO.NET), los TableAdapters son componentes generados por el diseñador que simplifican el proceso de mover datos entre su aplicación y una base de datos. Para obtener más información sobre cómo trabajar con TableAdapters, vea Información general sobre TableAdapter.

En la versión anterior de Visual Studio, los adaptadores de datos se usaban para la comunicación entre una aplicación con una base de datos. Aunque los adaptadores de datos siguen siendo un componente fundamental de los .Proveedores de datos de .NET Framework (ADO.NET), los TableAdapters son componentes generados por el diseñador que simplifican el proceso de mover datos entre su aplicación y una base de datos. Para obtener más información sobre cómo trabajar con TableAdapters, vea Información general sobre TableAdapter.

Los parámetros se utilizan en dos contextos:

Parámetros de selección - en las aplicaciones de producción, a menudo se extrae sólo un subconjunto de los datos de una base de datos. Para hacerlo así, se utiliza una instrucción SQL o un procedimiento almacenado que incluye una cláusula WHERE con un parámetro de criterios de selección que se obtiene en tiempo de ejecución. Además, cuando se actualizan o se eliminan registros, se utiliza una cláusula WHERE que señala el o los registro que se van a modificar. Los valores que se utilizan en la cláusula WHERE suelen derivarse en tiempo de ejecución.

Parámetros de actualización - cuando se actualiza un registro existente o se inserta uno nuevo, los valores de las columnas del registro nuevo o modificado se establecen en tiempo de ejecución. Además, los valores que se utilizan durante la comprobación de concurrencia optimista se establecen por medio de parámetros.

Nota:
Para Oracle, al utilizar los parámetros con nombre en una instrucción SQL o procedimiento almacenado, debe incluir dos puntos (:) delante del nombre del parámetro. Sin embargo, cuando haga referencia a un parámetro con nombre en otra parte del código (por ejemplo, al llamar a Add), no tiene que incluir los dos puntos (:) delante del parámetro con nombre. El proveedor de datos incluye los dos puntos automáticamente. Para obtener más información, vea OracleParameter (Clase).

Para Oracle, al utilizar los parámetros con nombre en una instrucción SQL o procedimiento almacenado, debe incluir dos puntos (:) delante del nombre del parámetro. Sin embargo, cuando haga referencia a un parámetro con nombre en otra parte del código (por ejemplo, al llamar a Add), no tiene que incluir los dos puntos (:) delante del parámetro con nombre. El proveedor de datos incluye los dos puntos automáticamente. Para obtener más información, vea OracleParameter (Clase).

Parámetros de selección

Cuando seleccione registros para llenar un conjunto de datos, a menudo incluirá uno o más parámetros en la cláusula WHERE, de modo que pueda especificar en tiempo de ejecución los registros que se van a extraer. Por ejemplo, los usuarios podrían buscar, en una base de datos de libros, una palabra clave específica del título que escribirán en una página Web. Para permitir esta posibilidad, podría especificar la siguiente instrucción SQL como propiedad CommandText de un SelectCommand. Los parámetros se indican con un marcador de posición (un signo de interrogación) o con una variable de parámetro con nombre. Los parámetros de consultas que implican objetos OleDbCommand y OdbcCommand utilizan signos de interrogación; las consultas que utilizan objetos SqlCommand usan parámetros con nombre que comienzan con un símbolo @, mientras que los objetos OracleCommand utilizan parámetros con nombre que comienzan con dos puntos (:).

Una consulta que utilizara marcadores de posición podría tener el siguiente aspecto:

SELECT BookId, Title, Author, Price from BOOKS
WHERE (Title LIKE ?)

Una consulta que utilizara parámetros con nombre SqlCommand podría tener el siguiente aspecto:

SELECT BookId, Title, Author, Price from BOOKS
WHERE (Title LIKE @title)

Una consulta que utilizara parámetros con nombre OracleCommand podría tener el siguiente aspecto:

SELECT BookId, Title, Author, Price from BOOKS
WHERE (Title LIKE :title)

En la aplicación, se pide al usuario una palabra clave del título. A continuación se establece el valor del parámetro y se ejecuta el comando.

Nota:
En ocasiones, quizá desee obtener todo el contenido de una tabla de base de datos (por ejemplo, si configura una tabla de búsqueda) pero generalmente deseará extraer sólo los datos necesarios para que la aplicación resulte eficiente.

En Visual Studio puede utilizar el Generador de consultas para generar instrucciones SQL con parámetros. Si arrastra elementos desde el Explorador de servidores, Visual Studio podrá configurar los parámetros en algunos casos, pero no en todos, por lo que tendrá que completar manualmente la configuración.

Parámetros de actualización

Independientemente de si el objeto SelectCommand contiene o no un comando parametrizado, los comandos para las propiedades UpdateCommand, InsertCommand y DeleteCommand siempre lo contienen.

Los comandos para las propiedades UpdateCommand y InsertCommand necesitan que se actualicen los parámetros de todas las columnas de la base de datos. Además, las instrucciones UpdateCommand y DeleteCommand requieren una cláusula WHERE parametrizada que identifica el registro que se va a actualizar, de manera similar al modo en que se suele configurar el objeto SelectCommand.

Imagine una aplicación en la que los usuarios pueden comprar libros. Mientras compran, los usuarios mantienen una cesta de la compra, que se implementa como una tabla de datos. En la tabla ShoppingCart, los usuarios mantienen un registro para cada libro que desean comprar, donde el identificador del libro y el identificador del cliente actúan como clave del registro de la cesta de la compra.

Cuando los usuarios agregan un libro a su cesta de la compra, la aplicación puede invocar una instrucción SQL INSERT. En el adaptador, la sintaxis de la instrucción podría tener el siguiente aspecto:

INSERT INTO ShoppingCart
   (BookId, CustId, Quantity)
Values (?, ?, ?)

Los tres signos de interrogación representan marcadores de posición de parámetros que se completarán en tiempo de ejecución con valores para el identificador de usuario, el identificador de libro y la cantidad. Si está utilizando parámetros con nombre, la misma consulta tendría este aspecto:

INSERT INTO ShoppingCart
   (BookId, CustId, Quantity)
Values (@bookid, @custid, @quantity)

Si el usuario decide cambiar algo de un artículo de la cesta de la compra, por ejemplo la cantidad, la aplicación podría invocar una instrucción SQL UPDATE. La sintaxis de la instrucción podría ser la siguiente:

UPDATE ShoppingCart
   SET (BookId = ?, CustId = ?, Quantity = ?)
WHERE (BookId = ? AND CustId = ?)

O bien, si está utilizando parámetros con nombre, podría ser así:

UPDATE ShoppingCart
   SET (BookId = @bookid, CustId = @custid, Quantity = @quantity)
WHERE (BookId = @bookid AND CustId = @custid)

En esta instrucción, los parámetros de la cláusula SET se llenan con valores actualizados para el registro modificado. Los parámetros de la cláusula WHERE identifican el registro que se va a actualizar y se llenan con los valores originales del registro.

Un usuario podría también quitar un artículo de la cesta de la compra. En este caso, la aplicación podría invocar una instrucción SQL DELETE con una sintaxis como la siguiente, si se estuviera utilizando marcadores de posición de parámetros:

DELETE FROM ShoppingCart
WHERE (BookId = ? AND CustId = ?)

O bien la siguiente, si se utilizaran parámetros con nombre:

DELETE FROM ShoppingCart
WHERE (BookId = @bookid AND CustId = @custid)

La colección Parameters y los objetos Parameter

Para permitir que se pasen valores de parámetro en tiempo de ejecución, cada uno de los cuatro objetos de comando de un adaptador de datos admite una propiedad Parameters. La propiedad contiene una colección de objetos Parameter individuales que se corresponden, uno a uno, con los marcadores de posición de la instrucción.

La tabla siguiente muestra la colección de parámetros correspondiente a cada adaptador:

Adaptador de datos	Colección de parámetros
SqlDataAdapter	SqlParameterCollection
OleDbDataAdapter	OleDbParameterCollection
OdbcDataAdapter	OdbcParameterCollection
OracleDataAdapter	OracleParameterCollection

Nota:
Para Oracle, al utilizar los parámetros con nombre en una instrucción SQL o procedimiento almacenado, debe incluir dos puntos (:) delante del nombre del parámetro. Sin embargo, cuando haga referencia a un parámetro con nombre en otra parte del código (por ejemplo, al llamar a Add), no tiene que incluir los dos puntos (:) delante del parámetro con nombre. El proveedor de datos de .NET Framework para Oracle proporciona los dos puntos automáticamente.

Para Oracle, al utilizar los parámetros con nombre en una instrucción SQL o procedimiento almacenado, debe incluir dos puntos (:) delante del nombre del parámetro. Sin embargo, cuando haga referencia a un parámetro con nombre en otra parte del código (por ejemplo, al llamar a Add), no tiene que incluir los dos puntos (:) delante del parámetro con nombre. El proveedor de datos de .NET Framework para Oracle proporciona los dos puntos automáticamente.

Si utiliza la colección de parámetros, se ahorrará el problema de generar manualmente un comando SQL en forma de cadena con valores en tiempo de ejecución; además, aprovechará las ventajas de la comprobación de tipos en los parámetros.

Si utiliza el Asistente para la configuración del adaptador de datos para configurar el adaptador, la colección de parámetros se instalará y configurará automáticamente para los cuatro comandos del adaptador. Si arrastra elementos desde el Explorador de servidores al formulario o componente, Visual Studio puede ejecutar las configuraciones siguientes:

Si arrastra una tabla o algunas columnas al diseñador, Visual Studio generará un objeto SelectCommand (específicamente, una instrucción SQL SELECT) sin parámetros y objetos UpdateCommand, InsertCommand y DeleteCommand parametrizados. Si desea que la instrucción del objeto SelectCommand tenga parámetros, deberá configurarlos manualmente.
Si arrastra un procedimiento almacenado hasta el diseñador, Visual Studio generará un objeto SelectCommand, con los parámetros que necesite el procedimiento almacenado. Sin embargo, si los necesita, deberá configurar los objetos UpdateCommand, InsertCommand y DeleteCommand manualmente junto con sus parámetros.

En general, si desea crear consultas parametrizadas para el adaptador, es recomendable que utilice el Asistente para la configuración del adaptador de datos. Sin embargo, si es necesario, puede configurar manualmente los parámetros por medio de la ventana Propiedades.

Estructura de la colección Parameters

Los elementos de la colección Parameters de un comando se corresponden, uno a uno, con los parámetros necesarios para el correspondiente objeto Command. Si el objeto de comando es una instrucción SQL, los elementos de la colección corresponden a los marcadores de posición (signos de interrogación) de la instrucción. La siguiente instrucción UPDATE requiere una colección de cinco elementos de parámetro:

UPDATE ShoppingCart
   SET (BookId = ?, CustId = ?, Quantity = ?)
WHERE (BookId = ? AND CustId = ?)

Ésta es la misma instrucción con parámetros con nombre:

UPDATE ShoppingCart
   SET (BookId = @bookid, CustId = @custid, Quantity = @quantity)
WHERE (BookId = @bookid AND CustId = @custid)

Si el objeto de comando hace referencia a un procedimiento almacenado, el número de elementos de parámetro de la colección lo determina el propio procedimiento. Los parámetros pueden no corresponderse exactamente con los marcadores de posición de una instrucción SQL.

En los procedimientos almacenados, los parámetros pueden también tener nombre. En este caso, la posición de un parámetro en la colección no es importante. En su lugar, cada elemento de parámetro de la colección tiene una propiedad ParameterName que se utiliza para hacerlo coincidir con el parámetro correspondiente del procedimiento almacenado.

Si está configurando manualmente la colección de parámetros, deberá comprender exactamente cuántos parámetros requiere el procedimiento almacenado. Muchos procedimientos almacenados devuelven un valor; si es así, el valor se pasa de nuevo a la aplicación en la colección de parámetros, así que deberá contar con ello. Además, algunos procedimientos almacenados incluyen múltiples instrucciones SQL y deberá asegurarse de que la colección de parámetros refleja todos los valores que se pasan a todas las instrucciones del procedimiento.

Si los parámetros no tienen nombre (como en los procedimientos almacenados), los elementos de la colección se asignan por posición a los parámetros que requiere el comando. Si el comando es un procedimiento almacenado y devuelve un valor, el primer elemento de la colección (elemento cero) se reserva para este valor devuelto.

En consecuencia, puede hacer referencia a los objetos de parámetro individuales por su posición de índice en la colección. Sin embargo, los objetos de parámetro admiten también una propiedad ParameterName que proporciona un medio para hacer referencia a los parámetros independientemente de su orden. Por ejemplo, las dos instrucciones siguientes podrían ser equivalentes (asumiendo que el segundo parámetro de la colección se denomine Title_Keyword):

' Encloses the keyword in SQL wildcard characters.
titleKeyword = "%" & txtTitleKeyword.Text & "%"
OleDbDataAdapter1.SelectCommand.Parameters(1).Value = titleKeyword
OleDbDataAdapter1.SelectCommand.Parameters("Title_Keyword").Value = titleKeyword

// Encloses the keyword in SQL wildcard characters.
string titleKeyword = "%" + txtTitleKeyword.Text + "%";
this.OleDbDataAdapter1.SelectCommand.Parameters[1].Value = titleKeyword;
this.OleDbDataAdapter1.SelectCommand.Parameters["Title_Keyword"].Value = titleKeyword;

El uso de un nombre de parámetro es, habitualmente, un hábito de programación mucho mejor que hacer referencia a los parámetros por su valor de índice, porque reduce las necesidades de mantenimiento si cambia el número de parámetros y evita tener que recordar si un procedimiento almacenado devuelve un valor. Hacer referencia a un parámetro por nombre en lugar de hacerlo por valor de índice implica una ligera sobrecarga adicional, compensada por la facilidad de programación y la mantenibilidad de la aplicación.

Establecer valores de parámetro

Hay dos formas de establecer el valor de un parámetro:

Estableciendo explícitamente la propiedad Value del parámetro.
Asignando parámetros a columnas de una tabla del conjunto de datos, de modo que, cuando sea necesario, se pueda extraer los valores de las filas de datos.

El valor del parámetro se establece explícitamente cuando se llena un conjunto de datos o se llama a un comando, es decir, para los parámetros de selección. Por ejemplo, en el ejemplo anterior de la búsqueda de libros, la aplicación podría ofrecer a los usuarios un cuadro de texto para escribir una palabra clave del título. A continuación, antes de llamar al método Fill del adaptador, debería establecer explícitamente el valor del parámetro en el texto del cuadro de texto. El código que hiciera esto sería similar al siguiente, que establece como parámetro el contenido de un cuadro de texto antes de llenar un conjunto de datos.

' Encloses the keyword in SQL wildcard characters.
titleKeyword = "%" & txtTitleKeyword.Text & "%"
OleDbDataAdapter1.SelectCommand.Parameters("Title_Keyword").Value = titleKeyword
OleDbDataAdapter1.Fill(dsAuthors1)

// Encloses the keyword in SQL wildcard characters.
titleKeyword = "%" + txtTitleKeyword.Text + "%";
this.OleDbDataAdapter1.SelectCommand.Parameters["Title_Keyword"].Value = titleKeyword;
this.OleDbDataAdapter1.Fill(dsAuthors1);

Los valores de parámetros asignados se utilizan durante las actualizaciones. Cuando se llama al método Update de un adaptador, el método recorre los registros de una tabla de un conjunto de datos y realiza de forma individual la actualización adecuada para el registro (actualizar, insertar, eliminar). En este caso, los valores de los parámetros ya están disponibles como columnas en los registros del conjunto de datos. Por ejemplo, cuando el proceso de actualización llega a un nuevo registro de la tabla del conjunto de datos, un registro para el que debe llamar a una instrucción INSERT en la base de datos, los valores de la cláusula VALUE de la instrucción INSERT pueden leerse directamente del registro.

Estos escenarios son habituales, pero no son los únicos. A veces, los procedimientos almacenados devuelven datos mediante parámetros o mediante el valor devuelto por el procedimiento. Si es así, los valores devueltos deben asignarse a columnas de una tabla del conjunto de datos.

También es posible establecer parámetros de actualización de forma explícita. El adaptador admite un evento RowUpdating, al que se llama cada vez que se actualiza una fila. Puede crear un controlador para este evento y establecer aquí los valores de los parámetros. Esto permite un control muy preciso sobre los valores de parámetros y permite ejecutar procesos tales como la creación dinámica de valores de parámetro antes de escribirlos en un registro de la base de datos.