Parâmetros declarativos (C#)

por Scott Mitchell

Descarregar PDF

Neste tutorial, ilustraremos como usar um conjunto de parâmetros para um valor codificado 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 vinculados 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 Products tabela do 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 indicando como filtrar as informações do produto retornado.

O ObjectDataSource pode ser usado para invocar métodos que esperam parâmetros de entrada, mas, para isso, devemos especificar de onde vêm os valores para esses parâmetros. Os valores dos parâmetros podem ser definidos estaticamente 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 controlador Web na página ou outras fontes.

Para este tutorial, vamos começar ilustrando como usar um conjunto de parâmetros para um valor codificado. 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 etiqueta inteligente do DetailsView, selecione <Nova origem de dados> na lista suspensa e escolha adicionar um ObjectDataSource.

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

Isso iniciará automaticamente o assistente Choose Data Source do controle ObjectDataSource. Selecione a ProductsBLL classe na primeira tela do assistente.

Figura 2: Selecione a classe (ProductsBLL imagem em tamanho real)

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

Figura 3: Escolha o método (GetProductByProductID(productID) imagem em tamanho real)

Como o método selecionado inclui um parâmetro, há mais uma tela para o assistente, onde somos solicitados a 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 fontes de parâmetros enumera as várias fontes possíveis para o valor do parâmetro. Como queremos especificar um valor codificado de 5 para o productID parâmetro, deixe a origem do parâmetro como Nenhum e digite 5 na caixa de texto DefaultValue.

Figura 4: Um valor de parâmetro Hard-Coded de 5 será usado para o parâmetro (productID 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 coleção SelectParameters para cada um dos parâmetros de entrada esperados pelo método definido na propriedade SelectMethod. Como o método que estamos usando neste exemplo espera apenas um único parâmetro de entrada, parameterIDhá apenas uma entrada aqui. A SelectParameters coleção pode conter qualquer classe que derive da Parameter classe no System.Web.UI.WebControls namespace. Para valores de parâmetros codificados, a classe base Parameter é usada, mas para as outras opções de origem de parâmetros uma classe derivada Parameter é usada, você também pode criar seus próprios tipos de parâmetros 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 estiver a acompanhar no seu próprio computador, a marcação declarativa que vê neste momento pode incluir valores para as propriedades InsertMethod, UpdateMethod, DeleteMethod, bem como DeleteParameters. O assistente de escolha de fonte de dados do ObjectDataSource especifica automaticamente os métodos do ProductBLL a serem usados para inserir, atualizar e excluir. Portanto, a menos que tenha os apagado explicitamente, eles serão incluídos na marcação acima.

Ao visitar esta página, o controlo de dados Web invocará o método Select do ObjectDataSource, que chamará o método ProductsBLL da classe GetProductByProductID(productID) usando o valor fixo de 5 como parâmetro de entrada productID. 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 visualizar a imagem em tamanho real)

Configurando o valor do parâmetro para 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 da Web na página. Para ilustrar isso, vamos ter um GridView que lista todos os fornecedores que estão localizados em um país/região especificado pelo usuário. Para fazer isso, comece adicionando um TextBox à página na qual o usuário pode inserir um nome de país/país. Defina a propriedade deste ID controle TextBox como CountryName. Também adicione um botão de controlo web.

Figura 6: Adicionar uma TextBox à página com IDCountryName (Clique para visualizar a imagem em tamanho real)

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

Figura 7: Escolha o método (GetSuppliersByCountry(country) imagem em tamanho real)

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

Figura 8: Definir o valor do parâmetro para o valor de controle (CountryName imagem em tamanho real)

A marcação declarativa de ObjectDataSource difere ligeiramente do nosso primeiro exemplo, usando um ControlParameter em vez do objeto padrão Parameter . A 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 suficientemente inteligente para determinar que, para um TextBox, provavelmente desejaremos usar a propriedade Text para o valor do parâmetro. Se, no entanto, você quiser usar um valor de propriedade diferente do controle da Web, você pode 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 TextBox está vazia. O método Select de ObjectDataSource ainda é invocado pelo GridView, mas um valor de null é passado para o método GetSuppliersByCountry(country). O TableAdapter converte o null em um valor de banco de dados NULL (DBNull.Value), mas a consulta usada pelo GetSuppliersByCountry(country) método é escrita de forma que ele não retorna nenhum valor quando um NULL valor é especificado para o @CategoryID parâmetro. Em resumo, nenhum fornecedor é retornado.

Uma vez que o visitante entra num país, no entanto, e clica no botão Mostrar Fornecedores para provocar um postback, o método do ObjectDataSource é novamente consultado, passando o valor do controlo TextBox como o parâmetro.

Figura 9: Esses fornecedores do Canadá são mostrados (Clique para visualizar a imagem em tamanho real)

Mostrando todos os fornecedores por padrão

Em vez de mostrar nenhum dos fornecedores ao visualizar a página pela primeira vez, podemos querer mostrar todos os fornecedores em primeiro lugar, permitindo que o usuário pare a lista inserindo um nome de país/região na TextBox. Quando o TextBox está vazio, o SuppliersBLL método da GetSuppliersByCountry(country) classe é passado em um null valor para seu country parâmetro de entrada. Esse null valor é então transmitido para o método da GetSupplierByCountry(country) DAL, onde este é convertido para um valor no banco de dados NULL para o parâmetro @Country na consulta seguinte.

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 devolver todos os fornecedores quando o TextBox de país estiver vazio, podemos melhorar o método GetSuppliersByCountry(country) na BLL para invocar o método GetSuppliers() quando o seu parâmetro país for null e, caso contrário, chamar o método GetSuppliersByCountry(country) da DAL. Isso terá o efeito de devolver todos os fornecedores quando nenhum país for especificado e o subconjunto apropriado de fornecedores quando o parâmetro país for incluído.

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

public Northwind.SuppliersDataTable GetSuppliersByCountry(string country)
{
    if (string.IsNullOrEmpty(country))
        return GetSuppliers();
    else
        return Adapter.GetSuppliersByCountry(country);
}

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

Figura 10: Todos os fornecedores agora são mostrados por padrão (Clique para visualizar a 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 do 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 codificado, mas com a mesma facilidade (e sem uma linha de código) os valores de parâmetro podem ser obtidos da querystring, variáveis de sessão, cookies e até mesmo valores inseridos pelo usuário de controles da Web na página.

Os exemplos que analisamos neste tutorial ilustraram como usar valores de parâmetros 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 hora atuais ou, se nosso site estava usando associação, o 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.

Feliz Programação!

Sobre o Autor

Scott Mitchell, autor de sete livros sobre ASP/ASP.NET e fundador da 4GuysFromRolla.com, trabalha com tecnologias Web da Microsoft desde 1998. Scott trabalha como consultor, formador e escritor independente. Seu último livro é Sams Teach Yourself ASP.NET 2.0 in 24 Hours. Ele pode ser contatado em mitchell@4GuysFromRolla.com.

Um agradecimento especial a

Esta série de tutoriais foi revisada por muitos revisores úteis. O revisor principal deste tutorial foi Hilton Giesenow. Interessado em rever meus próximos artigos do MSDN? Se for o caso, envie-me uma mensagem para mitchell@4GuysFromRolla.com.

AnteriorPróximo