Parâmetros declarativos (VB)

Artigo
06/25/2023

Neste tutorial, ilustraremos como usar um parâmetro definido como um valor embutido em código para selecionar os dados a serem exibidos em um controle DetailsView.

Introdução

No último tutorial , examinamos a exibição de dados com os controles GridView, DetailsView e FormView associados a um controle ObjectDataSource que invocou o GetProducts() método da ProductsBLL classe . O GetProducts() método retorna um DataTable fortemente tipado preenchido com todos os registros da tabela do Products banco de dados Northwind. A ProductsBLL classe contém métodos adicionais para retornar apenas subconjuntos dos produtos – GetProductByProductID(productID), GetProductsByCategoryID(categoryID)e GetProductsBySupplierID(supplierID). Esses três métodos esperam um parâmetro de entrada que indica como filtrar as informações retornadas do produto.

O ObjectDataSource pode ser usado para invocar métodos que esperam parâmetros de entrada, mas para fazer isso, devemos especificar de onde vêm os valores desses parâmetros. Os valores de parâmetro podem ser embutidos em código ou podem vir de uma variedade de fontes dinâmicas, incluindo: valores de querystring, variáveis de sessão, o valor da propriedade de um controle Web na página ou outros.

Para este tutorial, vamos começar ilustrando como usar um parâmetro definido como um valor embutido em código. Especificamente, veremos como adicionar um DetailsView à página que exibe informações sobre um produto específico, ou seja, o Gumbo Mix do Chef Anton, que tem um ProductID de 5. Em seguida, veremos como definir o valor do parâmetro com base em um controle da Web. Em particular, usaremos um TextBox para permitir que o usuário digite em um país/região, após o qual ele pode clicar em um Botão para ver a lista de fornecedores que residem nesse país/região.

Usando um valor de parâmetro Hard-Coded

Para o primeiro exemplo, comece adicionando um controle DetailsView à DeclarativeParams.aspx página na BasicReporting pasta . Na marca inteligente do DetailsView, selecione <Nova fonte> de dados na lista suspensa e escolha adicionar um ObjectDataSource.

Figura 1: Adicionar um ObjectDataSource à página (Clique para exibir a imagem em tamanho real)

Isso iniciará automaticamente o assistente Escolher Fonte de Dados do controle ObjectDataSource. Selecione a ProductsBLL classe na primeira tela do assistente.

Figura 2: Selecione a ProductsBLL Classe (Clique para exibir a imagem em tamanho real)

Como queremos exibir informações sobre um produto específico, queremos usar o GetProductByProductID(productID) método .

Figura 3: escolher o GetProductByProductID(productID) método (Clique para exibir a imagem em tamanho real)

Como o método selecionado inclui um parâmetro, há mais uma tela para o assistente, em que nos pedem para definir o valor a ser usado para o parâmetro . A lista à esquerda mostra todos os parâmetros para o método selecionado. Pois GetProductByProductID(productID) há apenas um productID. À direita, podemos especificar o valor para o parâmetro selecionado. A lista suspensa de origem do parâmetro enumera as várias fontes possíveis para o valor do parâmetro. Como queremos especificar um valor embutido em código de 5 para o productID parâmetro , deixe a fonte Parameter como None e insira 5 na caixa de texto DefaultValue.

Figura 4: Um valor de parâmetro Hard-Coded de 5 será usado para o productID parâmetro (clique para exibir a imagem em tamanho real)

Depois de concluir o assistente Configurar Fonte de Dados, a marcação declarativa do controle ObjectDataSource inclui um Parameter objeto na SelectParameters coleção para cada um dos parâmetros de entrada esperados pelo método definido na SelectMethod propriedade . Como o método que estamos usando neste exemplo espera apenas um único parâmetro de entrada, parameterID, há apenas uma entrada aqui. A SelectParameters coleção pode conter qualquer classe derivada da Parameter classe no System.Web.UI.WebControls namespace. Para valores de parâmetro embutidos em código, a classe base Parameter é usada, mas para as outras opções de origem de parâmetro uma classe derivada Parameter é usada; você também pode criar seus próprios tipos de parâmetro personalizados, se necessário.

<asp:ObjectDataSource ID="ObjectDataSource1" runat="server"
    SelectMethod="GetProductByProductID" TypeName="ProductsBLL">
    <SelectParameters>
        <asp:Parameter DefaultValue="5"
           Name="productID" Type="Int32" />
    </SelectParameters>
</asp:ObjectDataSource>

Observação

Se você estiver acompanhando em seu próprio computador, a marcação declarativa que você vê neste ponto poderá incluir valores para as InsertMethodpropriedades , UpdateMethode DeleteMethod , bem como DeleteParameters. O assistente Escolher Fonte de Dados do ObjectDataSource especifica automaticamente os métodos do ProductBLL a ser usado para inserção, atualização e exclusão, portanto, a menos que você os desmarque explicitamente, eles serão incluídos na marcação acima.

Ao visitar esta página, o controle web de dados invocará o método objectDataSource Select , que chamará o ProductsBLL método da GetProductByProductID(productID) classe usando o valor embutido em código 5 para o productID parâmetro de entrada. O método retornará um objeto fortemente tipado ProductDataTable que contém uma única linha com informações sobre o Gumbo Mix do Chef Anton (o produto com ProductID 5).

Figura 5: Informações sobre o Gumbo Mix do Chef Anton são exibidas (clique para exibir imagem em tamanho real)

Definindo o valor do parâmetro como o valor da propriedade de um controle Web

Os valores de parâmetro do ObjectDataSource também podem ser definidos com base no valor de um controle web na página. Para ilustrar isso, vamos ter um GridView que lista todos os fornecedores localizados em um país especificado pelo usuário. Para realizar esse início, adicione uma TextBox à página na qual o usuário pode inserir um nome de país. Defina a propriedade do ID controle TextBox como CountryName. Adicione também um controle Web button.

Figura 6: Adicionar uma Caixa de Texto à Página com IDCountryName (Clique para exibir a imagem em tamanho real)

Em seguida, adicione um GridView à página e, na marca inteligente, escolha adicionar um novo ObjectDataSource. Como queremos exibir informações do fornecedor, selecione a SuppliersBLL classe na primeira tela do assistente. Na segunda tela, escolha o GetSuppliersByCountry(country) método .

Figura 7: Escolher o GetSuppliersByCountry(country) Método (Clique para exibir a imagem em tamanho real)

Como o GetSuppliersByCountry(country) método tem um parâmetro de entrada, o assistente inclui mais uma vez uma tela final para escolher o valor do parâmetro. Desta vez, defina a origem do parâmetro como Control. Isso preencherá a lista suspensa ControlID com os nomes dos controles na página; selecione o CountryName controle na lista. Quando a página for visitada pela primeira vez, a CountryName Caixa de Texto ficará em branco, portanto, nenhum resultado será retornado e nada será exibido. Se você quiser exibir alguns resultados por padrão, defina a caixa de texto DefaultValue adequadamente.

Figura 8: definir o valor do parâmetro para o valor de CountryName controle (clique para exibir a imagem em tamanho real)

A marcação declarativa do ObjectDataSource difere ligeiramente do nosso primeiro exemplo, usando um ControlParameter em vez do objeto padrão Parameter . Um ControlParameter tem propriedades adicionais para especificar o ID do controle Web e o valor da propriedade a ser usado para o parâmetro (PropertyName). O assistente Configurar Fonte de Dados foi inteligente o suficiente para determinar que, para um TextBox, provavelmente queremos usar a Text propriedade para o valor do parâmetro. Se, no entanto, você quiser usar um valor de propriedade diferente do controle Web, poderá alterar o PropertyName valor aqui ou clicando no link "Mostrar propriedades avançadas" no assistente.

<asp:ObjectDataSource ID="ObjectDataSource2" runat="server"
    SelectMethod="GetSuppliersByCountry" TypeName="SuppliersBLL">
    <SelectParameters>
        <asp:ControlParameter ControlID="CountryName"
            Name="country" PropertyName="Text"
            Type="String" />
    </SelectParameters>
</asp:ObjectDataSource>

Ao visitar a página pela primeira vez, a CountryName Caixa de Texto está vazia. O método objectDataSource Select ainda é invocado pelo GridView, mas um valor de Nothing é passado para o GetSuppliersByCountry(country) método . O TableAdapter converte o Nothing em um valor de banco de dados NULL (DBNull.Value), mas a consulta usada pelo GetSuppliersByCountry(country) método é escrita de modo que não retorna nenhum valor quando um NULL valor é especificado para o @CategoryID parâmetro . Em suma, nenhum fornecedor é retornado.

No entanto, quando o visitante entra em um país/região e clica no botão Mostrar Fornecedores para causar um postback, o método objectDataSource Select é requerido, passando o valor do Text controle TextBox como o country parâmetro .

Figura 9: Os fornecedores do Canadá são mostrados (clique para exibir a imagem em tamanho real)

Mostrando todos os fornecedores por padrão

Em vez de mostrar nenhum dos fornecedores ao exibir pela primeira vez a página, talvez queiramos mostrar todos os fornecedores no início, permitindo que o usuário pare a lista inserindo um nome de país no TextBox. Quando o TextBox está vazio, o SuppliersBLL método da GetSuppliersByCountry(country) classe é passado Nothing para seu country parâmetro de entrada. Esse Nothing valor é então passado para baixo no método do GetSupplierByCountry(country) DAL, em que ele é convertido em um valor de banco de dados NULL para o @Country parâmetro na seguinte consulta:

SELECT     SupplierID, CompanyName, Address, City, Country, Phone
FROM         Suppliers
WHERE Country = @Country

A expressão Country = NULL sempre retorna False, mesmo para registros cuja Country coluna tem um NULL valor; portanto, nenhum registro é retornado.

Para retornar todos os fornecedores quando o país TextBox estiver vazio, podemos aumentar o GetSuppliersByCountry(country) método na BLL para invocar o método quando o GetSuppliers() parâmetro de país for Nothing e chamar o método do DAL de GetSuppliersByCountry(country) outra forma. Isso terá o efeito de retornar todos os fornecedores quando nenhum país for especificado e o subconjunto apropriado de fornecedores quando o parâmetro country for incluído.

Altere o GetSuppliersByCountry(country) método na SuppliersBLL classe para o seguinte:

Public Function GetSuppliersByCountry(country As String) _
    As Northwind.SuppliersDataTable
    If String.IsNullOrEmpty(country) Then
        Return GetSuppliers()
    Else
        Return Adapter.GetSuppliersByCountry(country)
    End If
End Function

Com essa alteração, a DeclarativeParams.aspx página mostra todos os fornecedores quando visitados pela primeira vez (ou sempre que a CountryName Caixa de Texto está vazia).

Figura 10: Todos os fornecedores agora são mostrados por padrão (clique para exibir imagem em tamanho real)

Resumo

Para usar métodos com parâmetros de entrada, precisamos especificar os valores para os parâmetros na coleção objectDataSource SelectParameters . Diferentes tipos de parâmetros permitem que o valor do parâmetro seja obtido de diferentes fontes. O tipo de parâmetro padrão usa um valor embutido em código, mas os valores de parâmetro facilmente (e sem uma linha de código) podem ser obtidos da querystring, das variáveis de sessão, dos cookies e até mesmo dos valores inseridos pelo usuário dos controles da Web na página.

Os exemplos que examinamos neste tutorial ilustraram como usar valores de parâmetro declarativos. No entanto, pode haver momentos em que precisamos usar uma fonte de parâmetro que não está disponível, como a data e a hora atuais, ou, se nosso site estava usando Associação, a ID de Usuário do visitante. Para esses cenários, podemos definir os valores de parâmetro programaticamente antes de ObjectDataSource invocar o método do objeto subjacente. Veremos como fazer isso no próximo tutorial.

Programação feliz!

Sobre o autor

Scott Mitchell, autor de sete livros do ASP/ASP.NET e fundador da 4GuysFromRolla.com, trabalha com tecnologias da Microsoft Web desde 1998. Scott trabalha como consultor independente, treinador e escritor. Seu último livro é Sams Teach Yourself ASP.NET 2.0 em 24 Horas. Ele pode ser contatado em mitchell@4GuysFromRolla.com. ou através de seu blog, que pode ser encontrado em http://ScottOnWriting.NET.

Agradecimentos Especiais

Esta série de tutoriais foi revisada por muitos revisores úteis. O revisor principal deste tutorial foi Hilton Giesenow. Interessado em revisar meus próximos artigos do MSDN? Nesse caso, solte-me uma linha em mitchell@4GuysFromRolla.com.

Anterior Avançar