Parámetros declarativos (C#)
por Scott Mitchell
En este tutorial se muestra cómo usar un conjunto de parámetros en un valor codificado de forma rígida para seleccionar los datos que se van a mostrar en un control DetailsView.
Introducción
En el último tutorial hemos examinado la visualización de datos con los controles GridView, DetailsView y FormView enlazados a un control ObjectDataSource que invocó el método GetProducts() de la clase de ProductsBLL. El método GetProducts() devuelve una DataTable fuertemente tipada y rellenada con todos los registros de la tabla Products la base de datos Northwind. La clase de ProductsBLL contiene métodos adicionales para devolver solo subconjuntos de los productos: GetProductByProductID(productID), GetProductsByCategoryID(categoryID) y GetProductsBySupplierID(supplierID). Estos tres métodos esperan un parámetro de entrada que indica cómo filtrar la información del producto que se devuelve.
ObjectDataSource se puede usar para invocar métodos que esperan parámetros de entrada, pero para ello debemos especificar de dónde proceden los valores de estos parámetros. Los valores de parámetro se pueden codificar de forma rígida o pueden provenir de una gran variedad de orígenes dinámicos, como valores de cadena de consulta, variables de sesión, el valor de propiedad de un control web en la página u otros.
En este tutorial, vamos a comenzar ilustrando cómo usar un parámetro establecido en un valor codificado de forma rígida. En concreto, veremos cómo agregar una DetailsView a la página que muestra información sobre un producto específico, es decir, Chef Anton's Gumbo Mix, que tiene un ProductID de 5. A continuación, veremos cómo establecer el valor del parámetro en función de un control web. En concreto, usaremos un TextBox para permitir que el usuario escriba en un país o región, después de lo cual puede hacer clic en un botón para ver la lista de proveedores que residen en ese país o región.
Uso de un valor de parámetro codificado de forma rígida
En el primer ejemplo, empiece agregando un control DetailsView a la página DeclarativeParams.aspx de la carpeta BasicReporting. En la etiqueta inteligente de DetailsView, seleccione <Nuevo origen de datos> de la lista desplegable y elija agregar un ObjectDataSource.
Figura 1: Agregue un ObjectDataSource a la página (haga clic para ver la imagen de tamaño completo)
Esto iniciará automáticamente el asistente para elegir origen de datos del control de ObjectDataSource. Seleccione la clase de ProductsBLL en la primera pantalla del asistente.
Figura 2: Seleccione la clase de ProductsBLL (haga clic para ver la imagen en tamaño completo)
Puesto que queremos mostrar información sobre un producto determinado, queremos usar el método GetProductByProductID(productID).
Figura 3: Seleccione el método GetProductByProductID(productID) (haga clic para ver la imagen en tamaño completo)
Dado que el método seleccionado incluye un parámetro, el asistente muestra una pantalla más, en la que se nos pide que definamos el valor que se va a usar para el parámetro. La lista de la izquierda muestra todos los parámetros del método seleccionado. Para GetProductByProductID(productID) solo hay un productID. A la derecha, podemos especificar el valor del parámetro seleccionado. La lista desplegable de orígenes de parámetros enumera los distintos orígenes posibles para el valor del parámetro. Puesto que queremos especificar un valor codificado de forma rígida de 5 para el parámetro productID, deje el origen Parámetro como Ninguno y escriba 5 en el cuadro de texto DefaultValue.
Figura 4: Se usará un valor de parámetro codificado de forma rígida de 5 para el parámetro productID (haga clic para ver la imagen en tamaño completo)
Después de completar el asistente para configurar orígenes de datos, el marcado declarativo del control ObjectDataSource incluye un objeto Parameter en la colección SelectParameters para cada uno de los parámetros de entrada que espera el método definido en la propiedad SelectMethod. Dado que el método que se usa en este ejemplo espera un único parámetro de entrada, parameterID, solo hay una entrada aquí. La colección SelectParameters puede contener cualquier clase que derive de la clase de Parameter en el espacio de nombres de System.Web.UI.WebControls. En el caso de los valores de parámetro codificados de forma rígida, se usa la clase base de Parameter, pero en el caso de las otras opciones de orígenes de parámetros se usa una clase derivada de Parameter. También puede crear sus propios tipos de parámetros personalizados, si es necesario.
<asp:ObjectDataSource ID="ObjectDataSource1" runat="server"
SelectMethod="GetProductByProductID" TypeName="ProductsBLL">
<SelectParameters>
<asp:Parameter DefaultValue="5" Name="productID"
Type="Int32" />
</SelectParameters>
</asp:ObjectDataSource>
Nota:
Si sigue en su propio equipo, el marcado declarativo que ve en este momento puede incluir valores para las propiedades InsertMethod, UpdateMethod y DeleteMethod, así como DeleteParameters. El asistente para elegir orígenes de datos de ObjectDataSource especifica automáticamente los métodos del ProductBLL que se van a usar para insertar, actualizar y eliminar, por lo que, a menos que los borre explícitamente, se incluirán en el marcado anterior.
Al visitar esta página, el control web de datos invocará el método Select de ObjectDataSource, que llamará al método GetProductByProductID(productID) de la clase de ProductsBLL mediante el valor codificado de forma rígida de 5 para el parámetro de entrada productID. El método devolverá un objeto ProductDataTable fuertemente tipado que contiene una sola fila con información sobre Chef Anton's Gumbo Mix (el producto con ProductID 5).
Figura 5: Se muestra información sobre Chef Anton's Gumbo Mix (haga clic para ver la imagen en tamaño completo)
Configuración del valor del parámetro en el valor de propiedad de un control web
Los valores de parámetro de ObjectDataSource también se pueden configurar en función del valor de un control web en la página. Para ilustrarlo, vamos a crear un GridView con todos los proveedores que se encuentran en el país o región que especifique el usuario. Para ello, agregue un TextBox a la página en la que el usuario pueda escribir el nombre de un país. Establezca la propiedad ID de este control de TextBox en CountryName. Agregue también un control web Botón.
Figura 6: Agregar un TextBox a la página con CountryName de ID (haga clic para ver la imagen en tamaño completo)
A continuación, agregue un GridView a la página y, desde la etiqueta inteligente, elija agregar un nuevo ObjectDataSource. Dado que queremos mostrar la información del proveedor, seleccione la clase de SuppliersBLL en la primera pantalla del asistente. En la segunda pantalla, seleccione el método GetSuppliersByCountry(country).
Figura 7: Seleccione el método GetSuppliersByCountry(country) (haga clic para ver la imagen en tamaño completo)
Dado que el método GetSuppliersByCountry(country) tiene un parámetro de entrada, el asistente incluye una vez más una pantalla final para elegir el valor del parámetro. Esta vez establezca el origen del parámetro en Control. Esto rellenará la lista desplegable ControlID con los nombres de los controles de la página. Seleccione el control CountryName de la lista. Cuando la página se visita por primera vez, el TextBox de CountryName estará en blanco, por lo que no se devuelve ningún resultado y no se muestra nada. Si desea mostrar algunos resultados de forma predeterminada, establezca el cuadro de texto DefaultValue en consecuencia.
Figura 8: Establezca el valor del parámetro en el valor de control CountryName (haga clic para ver la imagen en tamaño completo)
El marcado declarativo de ObjectDataSource difiere ligeramente del primer ejemplo, usando un ControlParameter en lugar del objeto estándar Parameter. Un ControlParameter tiene propiedades adicionales para especificar el ID del control web y el valor de propiedad que se va a usar para el parámetro (PropertyName). El asistente para configurar orígenes de datos era lo suficientemente inteligente para determinar que, para un TextBox, es probable que deseemos usar la propiedad Text del valor del parámetro. Sin embargo, si desea usar un valor de propiedad diferente del control web, puede cambiar el valor de PropertyName aquí o haciendo clic en el vínculo "Mostrar propiedades avanzadas" del asistente.
<asp:ObjectDataSource ID="ObjectDataSource2" runat="server"
SelectMethod="GetSuppliersByCountry" TypeName="SuppliersBLL">
<SelectParameters>
<asp:ControlParameter ControlID="CountryName"
Name="country" PropertyName="Text"
Type="String" />
</SelectParameters>
</asp:ObjectDataSource>
Al visitar la página por primera vez, el TextBox de CountryName está vacío. GridView sigue invocando el método Select de ObjectDataSource, pero un valor de null se pasa al método GetSuppliersByCountry(country). TableAdapter convierte el null en un valor de base de datos NULL (DBNull.Value), pero la consulta que utiliza el método GetSuppliersByCountry(country) se escribe de modo que no devuelve ningún valor cuando se especifica un valor de NULL para el parámetro @CategoryID. En resumen, no se devuelve ningún proveedor.
Sin embargo, una vez que el visitante entra en un país y hace clic en el botón Mostrar proveedores para provocar un postback, se necesita el método Select de ObjectDataSource, que pasa el valor de Text del control TextBox como el parámetro country.
Figura 9: Se muestran los proveedores de Canadá (haga clic para ver la imagen en tamaño completo)
Visualización de todos los proveedores de forma predeterminada
En lugar de que no se muestre ningún proveedor al ver por primera vez la página, es posible que deseemos mostrar todos los proveedores al principio, de modo que el usuario pueda reducir la lista escribiendo un nombre de país o región en el TextBox. Cuando TextBox está vacío, el método GetSuppliersByCountry(country) de la clase de SuppliersBLL se pasa en un valor de null para su parámetro de entrada country. A continuación, este valor de null se transmite al método GetSupplierByCountry(country) de DAL, donde se traduce a un valor NULL de base de datos para el parámetro @Country en la consulta siguiente:
SELECT SupplierID, CompanyName, Address, City, Country, Phone
FROM Suppliers
WHERE Country = @Country
La expresión Country = NULL siempre devuelve False, incluso para los registros cuya columna Country tiene un valor de NULL. Por lo tanto, no se devuelve ningún registro.
Para devolver todos los proveedores cuando el TextBox de país está vacío, podemos aumentar el método GetSuppliersByCountry(country) en el BLL para invocar el método GetSuppliers() cuando su parámetro de país es null y, en caso contrario, llamar al método GetSuppliersByCountry(country) de DAL. Esto tendrá el efecto de devolver todos los proveedores cuando no se especifica ningún país y el subconjunto adecuado de proveedores cuando se incluye el parámetro país.
Cambie el método GetSuppliersByCountry(country) de la clase SuppliersBLL por lo siguiente:
public Northwind.SuppliersDataTable GetSuppliersByCountry(string country)
{
if (string.IsNullOrEmpty(country))
return GetSuppliers();
else
return Adapter.GetSuppliersByCountry(country);
}
Con este cambio, la página DeclarativeParams.aspx muestra todos los proveedores cuando se visita por primera vez (o cada vez que el TextBox de CountryName está vacío).
Figura 10: Todos los proveedores se muestran ahora de forma predeterminada (haga clic para ver la imagen en tamaño completo)
Resumen
Para usar métodos con parámetros de entrada, es necesario especificar los valores de los parámetros de la colección SelectParameters de ObjectDataSource. Los distintos tipos de parámetros permiten obtener el valor del parámetro de orígenes diferentes. El tipo de parámetro predeterminado usa un valor codificado de forma rígida, pero con igual facilidad (y sin una línea de código) los valores de parámetro se pueden obtener de los valores QueryString, las variables de sesión, las cookies e incluso los valores especificados por el usuario de los controles web de la página.
En los ejemplos que hemos examinado en este tutorial, se muestra cómo usar valores de parámetro declarativos. Sin embargo, puede que haya ocasiones en las que necesitemos usar un origen de parámetros que no esté disponible, como la fecha y hora actuales o, si nuestro sitio estaba usando pertenencia, el id. de usuario del visitante. En estos escenarios, podemos establecer los valores de parámetro mediante programación antes de que ObjectDataSource invoque el método del objeto subyacente. Veremos cómo hacerlo en el siguiente tutorial.
¡Feliz programación!
Acerca del autor
Scott Mitchell, autor de siete libros de ASP/ASP.NET y fundador de 4GuysFromRolla.com, ha trabajado con tecnologías web de Microsoft desde 1998. Scott trabaja como consultor independiente, entrenador y escritor. Su último libro es Sams Teach Yourself ASP.NET 2.0 in 24 Hours. Puede ponerse en contacto con él a través de mitchell@4GuysFromRolla.com. o de su blog, que se puede encontrar en http://ScottOnWriting.NET.
Agradecimientos especiales a
Esta serie de tutoriales fue revisada por muchos revisores de gran ayuda. El revisor principal de este tutorial fue Hilton Giesenow. ¿Le interesaría revisar mis próximos artículos de MSDN? Si es así, escríbame a mitchell@4GuysFromRolla.com.