Usando parâmetros com controles de fonte de dados

Artigo
10/15/2014

Controles de fonte de dados no ASP.NET podem aceitar parâmetros de entrada para que você possa passar valores para eles em tempo de execução.Você pode utilizar parâmetros para fornecer critérios de pesquisa para a recuperação de dados; para fornecer valores a serem inseridos, atualizados, ou excluídos em um armazenamento de dados; e para fornecer valores para classificação, paginação, e filtragem.Usar parâmetros possibilita a filtragem de dados e a criação de aplicativos detalhes mestre com pouco ou nenhum código personalizado.

Você também pode usar parâmetros para personalizar os valores passados para uma fonte de dados por uma controle associado a dados, tal como um controle GridView ou FormView, que oferece suporte a operações de atualização automática, inserção e exclusão.Por exemplo, você pode utilizar parâmetros nos objetos para valores fortemente tipados ou para recuperar valores na saída da fonte de dados.Além disso, consultas parametrizadas podem tornar um aplicativo mais seguro, o protegendo contra ataques de injeção SQL.

Os valores dos parâmetros podem ser obtidos em uma variedade de fontes.Parameter objetos permitem que você forneça valores para operações de dados parametrizadas nas propriedades do controle de servidor Web, cookies, estado de sessão, QueryString campos, propriedades de analisar do usuário e outras fontes.

Tipos de parâmetro

Você pode especificar vários tipos de parâmetros para os objetos em seu aplicativo da Web.O tipo do parâmetro do objeto determina de onde o valor do parâmetro vêm.A classe Parameter é a classe base para todos os objetos de parâmetros e inclui propriedades Name, Type, Direction e DefaultValue que são comuns a todos os tipos de parâmetros.Você normalmente usa a classe base Parameter para especificar como uma fonte de dados deve tratar valores de parâmetros obtidos de um controle associado a dados, tais como os valores passados por um controle GridView para uma operação de Update parâmetro ou Delete.

Você pode usar os tipos de parâmetros que derivam da classe Parameter para obter valores de outras fontes, conforme descrito na tabela a seguir.

Tipo de parâmetro	Descrição
ControlParameter	Define um parâmetro para o valor da propriedade de um Control em uma página da Web ASP.NET.Você especifica o Control usando a propriedade ControlID.Você especifica o nome da propriedade que fornece o valor do parâmetro usando a propriedade PropertyName do objeto ControlParameter. Alguns controles que derivam de Control definem uma ControlValuePropertyAttribute, que determina a propriedade padrão a partir da qual recupera o valor do controle.A propriedade padrão é usada sempre que a propriedade PropertyName não está definida explicitamente.O ControlValuePropertyAttribute é aplicado às seguintes propriedades de controle: Calendar.SelectedDate CheckBox.Checked DetailsView.SelectedValue FileUpload.FileBytes GridView.SelectedValue Label.Text TextBox.Text TreeView.SelectedValue
CookieParameter	Define um parâmetro para o valor de um objeto HttpCookie.Você especifica o nome do objeto HttpCookie usando a propriedade CookieName.Se o objeto HttpCookie especificado não existir, então, o valor da propriedade DefaultValue é usado como valor do parâmetro. Observação: Somente são suportados cookies de valor único.
FormParameter	Define um parâmetro para o valor de um campo de formulário HTML.Você especifica o nome do campo de formulário HTML que usa a propriedade FormField.Se o valor do campo de formulário HTML especificado não existir, então o valor da propriedade DefaultValue é usado como valor do parâmetro.
ProfileParameter	Define um parâmetro para o valor de uma propriedade do perfil de usuário atual (Profile).Você especifica o nome da propriedade de perfil usando a propriedade PropertyName.Se a propriedade de perfil especificada não existir, então o valor da propriedade DefaultValue é usado como valor do parâmetro. Para mais informações sobre perfis, consulte Visão geral sobre propriedades de perfil do ASP.NET.
QueryStringParameter	Define um parâmetro para o valor de um campo QueryString.Você especifica o nome do objeto QueryString usando a propriedade QueryStringField.Se o objeto QueryString especificado não existir, então, o valor da propriedade DefaultValue é usado como valor do parâmetro.
SessionParameter	Define um parâmetro para o valor de um objeto Session.Você especifica o nome do objeto Session usando a propriedade SessionField.Se o objeto Session especificado não existir, então, o valor da propriedade DefaultValue é usado como valor do parâmetro.

Valores de parâmetros fortemente tipados

Porpadrão, parâmetros são classificados como Object.Se um valor do parâmetro é de outro tipo, tal como DateTime ou Int32, você pode criar objetos Parameter explicitamente e definir a propriedade Type do parâmetro para um valor TypeCode.

Direção do parâmetro

Parâmetros são parâmetros de entrada por padrão.Em alguns casos, como quando você usa procedimentos armazenados, você precisará ler um valor retornado da fonte de dados.Em caso afirmativo, você pode definir a propriedade Direction do objeto Parameter para garantir que você capture as informações que a fonte de dados retorna para seu aplicativo da Web.As configurações de direção dos parâmetros suportados são Input, InputOutput, Output e ReturnValue.Você normalmente irá manipular um evento de controle da fonte de dados, tal como um evento Inserted ou Updated, para obter o valor de retorno do parâmetro depois que a operação de dados é concluída.

Controles de fonte de dados e parâmetros

Os controles de fonte de dados suportam operações parametrizadas de maneiras diferentes.Por exemplo, o controle LinqDataSource permite que você substitua os valores de tempo de execução em uma cláusula em uma consulta LINQ.Os controles SqlDataSource e AccessDataSource permitem que você especifique os espaços reservados de parâmetros em uma Instrução SQL, tal como SelectCommand.O controle ObjectDataSource usa parâmetros para determinar a assinatura do método apropriada para a chamada de uma operação de dados específica, como o SelectMethod.Para obter mais informações, consulte Usando parâmetros com o controle SqlDataSource e Usando Parâmetros com o Controle ObjectDataSource.

Os controles de fonte de dados normalmente incluem uma coleção de parâmetros para cada operação dados.Ao selecionar os dados, você pode especificar uma coleção SelectParameters, ao atualizar um item de dados ,você pode especificar uma coleção UpdateParameters, e assim por diante.O conteúdo da coleção parâmetros para uma determinada ação é usada para fornecer valores para a fonte de dados subjacente.Quando inserimos, atualizamos, ou excluímos dados, o controle da fonte de dados cria parâmetros de limitam os campos, os combina com a coleção parâmetros explicitamente especificada (se houver), e então passa a coleção resultante para a fonte de dados.Para obter informações sobre os nomes e valores dos parâmetros que um controle da fonte de dados cria baseado em dados de um controle acoplado, consulte Como um Controle da Fonte de Dados Cria Parâmetros para Campos Ligados a Dados.

O exemplo a seguir mostra um controle SqlDataSource que recupera informações com base em um valor de um campo QueryString.

<asp:SqlDataSource id="Employees1" 
  ConnectionString="<%$ ConnectionStrings:Northwind %>"
  SelectCommand="SELECT EmployeeID, LastName, FirstName FROM Employees
                 WHERE EmployeeID = @empId">
  <SelectParameters>
    <asp:QueryStringParameter Name="empId" QueryStringField="empId" />
  </SelectParameters>
</asp:SqlDataSource>

O exemplo a seguir mostra um controle SqlDataSource que recupera informações com base em um valor de outro controle na página.

<asp:DropDownList id="DropDownList1"  
    autopostback="True">
  <asp:listitem selected>Sales Representative</asp:listitem>
  <asp:listitem>Sales Manager</asp:listitem>
  <asp:listitem>Vice President, Sales</asp:listitem>
</asp:DropDownList></p>

<asp:SqlDataSource id="Employees" 
  ConnectionString="<%$ ConnectionStrings:Northwind%>"
  SelectCommand="SELECT LastName FROM Employees WHERE Title = @Title">
  <SelectParameters>
    <asp:ControlParameter Name="Title" 
      ControlID="DropDownList1"
      PropertyName="SelectedValue"/>
  </SelectParameters>
</asp:sqldatasource>

O exemplo a seguir mostra um controle LinqDataSource que cria a cláusula WHERE com base em um valor de um campo QueryString.

<asp:LinqDataSource 
      ContextTypeName="NorthwindDataContext" 
      TableName="Employees" 
      Where="EmployeeID = @empID" 
      ID="LinqDataSource1" 
      >
  <WhereParameters>
    <asp:QueryStringParameter Type="Int32" DefaultValue="1" 
        Name="empID" QueryStringField="empID" />
  </WhereParameters>
</asp:LinqDataSource>

O exemplo a seguir mostra um controle LinqDataSource que cria a cláusula ORDER BY com base em uma seleção pelo usuário.A propriedade AutoGenerateOrderByClause é definida como true.Portanto, o controle LinqDataSource cria a cláusula ORDER BY com os parâmetros na coleção OrderByParameters.

<asp:DropDownList AutoPostBack="true" ID="DropDownList1" >
    <asp:ListItem Value="Category"></asp:ListItem>
    <asp:ListItem Value="Price"></asp:ListItem>
</asp:DropDownList>
<asp:LinqDataSource 
    ContextTypeName="ExampleDataContext" 
    TableName="Products" 
    AutoGenerateOrderByClause="true"
    ID="LinqDataSource1" 
    >
    <OrderByParameters>
      <asp:ControlParameter
         ControlID="DropDownList1" 
         Type="String" />
    </OrderByParameters>
</asp:LinqDataSource>

O exemplo a seguir mostra um controle SqlDataSource que usa comandos parametrizados para consultar e modificar dados de um controle associado a dados.Os parâmetros são explicitamente especificados, para valores de parâmetro fortemente tipados e para especificar os parâmetros de saída.

<%@ Page language="VB" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<script >

  Sub EmployeesDropDownList_OnSelectedIndexChanged(sender As Object, e As EventArgs)
    EmployeeDetailsView.DataBind()
  End Sub

  Sub EmployeeDetailsView_ItemUpdated(sender As Object, e As DetailsViewUpdatedEventArgs)
    EmployeesDropDownList.DataBind()
    EmployeesDropDownList.SelectedValue = e.Keys("EmployeeID").ToString()
    EmployeeDetailsView.DataBind()
  End Sub

  Sub EmployeeDetailsView_ItemDeleted(sender As Object, e As DetailsViewDeletedEventArgs)
    EmployeesDropDownList.DataBind()
  End Sub

  Sub EmployeeDetailsSqlDataSource_OnInserted(sender As Object, e As SqlDataSourceStatusEventArgs)
    Dim command As System.Data.Common.DbCommand = e.Command  
    EmployeesDropDownList.DataBind()
    EmployeesDropDownList.SelectedValue = _
      command.Parameters("@EmpID").Value.ToString()
    EmployeeDetailsView.DataBind()
  End Sub

</script>

<html xmlns="http://www.w3.org/1999/xhtml" >
  <head >
    <title>Northwind Employees</title>
</head>
<body>
    <form id="form1" >

      <h3>Northwind Employees</h3>

        <table cellspacing="10">

          <tr>
            <td valign="top">
              <asp:DropDownList ID="EmployeesDropDownList" 
                DataSourceID="EmployeesSqlDataSource" 
                DataValueField="EmployeeID" 
                DataTextField="FullName"
                AutoPostBack="True"
                OnSelectedIndexChanged="EmployeesDropDownList_OnSelectedIndexChanged"
                RunAt="Server" />            
            </td>

            <td valign="top">                
              <asp:DetailsView ID="EmployeeDetailsView"
                DataSourceID="EmployeeDetailsSqlDataSource"
                AutoGenerateRows="false"
                AutoGenerateInsertbutton="true"
                AutoGenerateEditbutton="true"
                AutoGenerateDeletebutton="true"
                DataKeyNames="EmployeeID"     
                Gridlines="Both"
                OnItemUpdated="EmployeeDetailsView_ItemUpdated"
                OnItemDeleted="EmployeeDetailsView_ItemDeleted"      
                RunAt="server">

                <HeaderStyle backcolor="Navy"
                  forecolor="White"/>

                <RowStyle backcolor="White"/>

                <AlternatingRowStyle backcolor="LightGray"/>

                <EditRowStyle backcolor="LightCyan"/>

                <Fields>                  
                  <asp:BoundField DataField="EmployeeID" HeaderText="Employee ID" InsertVisible="False" ReadOnly="true"/>                    
                  <asp:BoundField DataField="FirstName"  HeaderText="First Name"/>
                  <asp:BoundField DataField="LastName"   HeaderText="Last Name"/>                    
                  <asp:BoundField DataField="Address"    HeaderText="Address"/>                    
                  <asp:BoundField DataField="City"       HeaderText="City"/>                        
                  <asp:BoundField DataField="Region"     HeaderText="Region"/>
                  <asp:BoundField DataField="PostalCode" HeaderText="Postal Code"/>                    
                </Fields>                    
              </asp:DetailsView>
            </td>                
          </tr>            
        </table>

        <asp:SqlDataSource ID="EmployeesSqlDataSource"  
          SelectCommand="SELECT EmployeeID, LastName + ', ' + FirstName AS FullName FROM Employees" 
          Connectionstring="<%$ ConnectionStrings:NorthwindConnection %>" 
          RunAt="server">
        </asp:SqlDataSource>


        <asp:SqlDataSource ID="EmployeeDetailsSqlDataSource" 
          SelectCommand="SELECT EmployeeID, LastName, FirstName, Address, City, Region, PostalCode
                         FROM Employees WHERE EmployeeID = @EmpID"

          InsertCommand="INSERT INTO Employees(LastName, FirstName, Address, City, Region, PostalCode)
                         VALUES (@LastName, @FirstName, @Address, @City, @Region, @PostalCode); 
                         SELECT @EmpID = SCOPE_IDENTITY()"

          UpdateCommand="UPDATE Employees SET LastName=@LastName, FirstName=@FirstName, Address=@Address,
                           City=@City, Region=@Region, PostalCode=@PostalCode
                         WHERE EmployeeID=@EmployeeID"

          DeleteCommand="DELETE Employees WHERE EmployeeID=@EmployeeID"

          ConnectionString="<%$ ConnectionStrings:NorthwindConnection %>"
          OnInserted="EmployeeDetailsSqlDataSource_OnInserted"
          RunAt="server">

          <SelectParameters>
            <asp:ControlParameter ControlID="EmployeesDropDownList" PropertyName="SelectedValue"
                                  Name="EmpID" Type="Int32" DefaultValue="0" />
          </SelectParameters>

          <InsertParameters>
            <asp:Parameter Name="LastName"   Type="String" />
            <asp:Parameter Name="FirstName"  Type="String" />
            <asp:Parameter Name="Address"    Type="String" />
            <asp:Parameter Name="City"       Type="String" />
            <asp:Parameter Name="Region"     Type="String" />
            <asp:Parameter Name="PostalCode" Type="String" />
            <asp:Parameter Name="EmpID" Direction="Output" Type="Int32" DefaultValue="0" />
          </InsertParameters>

          <UpdateParameters>
            <asp:Parameter Name="LastName"   Type="String" />
            <asp:Parameter Name="FirstName"  Type="String" />
            <asp:Parameter Name="Address"    Type="String" />
            <asp:Parameter Name="City"       Type="String" />
            <asp:Parameter Name="Region"     Type="String" />
            <asp:Parameter Name="PostalCode" Type="String" />
            <asp:Parameter Name="EmployeeID" Type="Int32" DefaultValue="0" />
          </UpdateParameters>

          <DeleteParameters>
            <asp:Parameter Name="EmployeeID" Type="Int32" DefaultValue="0" />
          </DeleteParameters>

        </asp:SqlDataSource>
      </form>
  </body>
</html>

<%@ Page language="C#" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<script >

  void EmployeesDropDownList_OnSelectedIndexChanged(Object sender, EventArgs e)
  {
    EmployeeDetailsView.DataBind();
  }

  void EmployeeDetailsView_ItemUpdated(Object sender, DetailsViewUpdatedEventArgs e)
  {
    EmployeesDropDownList.DataBind();
    EmployeesDropDownList.SelectedValue = e.Keys["EmployeeID"].ToString();
    EmployeeDetailsView.DataBind();
  }

  void EmployeeDetailsView_ItemDeleted(Object sender, DetailsViewDeletedEventArgs e)
  {
    EmployeesDropDownList.DataBind();
  }

  void EmployeeDetailsSqlDataSource_OnInserted(Object sender, SqlDataSourceStatusEventArgs e)
  {
    System.Data.Common.DbCommand command = e.Command;   
    EmployeesDropDownList.DataBind();
    EmployeesDropDownList.SelectedValue = 
      command.Parameters["@EmpID"].Value.ToString();
    EmployeeDetailsView.DataBind();
  }

</script>

<html xmlns="http://www.w3.org/1999/xhtml" >
  <head >
    <title>Northwind Employees</title>
</head>
<body>
    <form id="form1" >

      <h3>Northwind Employees</h3>

        <table cellspacing="10">

          <tr>
            <td valign="top">
              <asp:DropDownList ID="EmployeesDropDownList" 
                DataSourceID="EmployeesSqlDataSource" 
                DataValueField="EmployeeID" 
                DataTextField="FullName"
                AutoPostBack="True"
                OnSelectedIndexChanged="EmployeesDropDownList_OnSelectedIndexChanged"
                RunAt="Server" />            
            </td>

            <td valign="top">                
              <asp:DetailsView ID="EmployeeDetailsView"
                DataSourceID="EmployeeDetailsSqlDataSource"
                AutoGenerateRows="false"
                AutoGenerateInsertbutton="true"
                AutoGenerateEditbutton="true"
                AutoGenerateDeletebutton="true"
                DataKeyNames="EmployeeID"     
                Gridlines="Both"
                OnItemUpdated="EmployeeDetailsView_ItemUpdated"
                OnItemDeleted="EmployeeDetailsView_ItemDeleted"      
                RunAt="server">

                <HeaderStyle backcolor="Navy"
                  forecolor="White"/>

                <RowStyle backcolor="White"/>

                <AlternatingRowStyle backcolor="LightGray"/>

                <EditRowStyle backcolor="LightCyan"/>

                <Fields>                  
                  <asp:BoundField DataField="EmployeeID" HeaderText="Employee ID" InsertVisible="False" ReadOnly="true"/>                    
                  <asp:BoundField DataField="FirstName"  HeaderText="First Name"/>
                  <asp:BoundField DataField="LastName"   HeaderText="Last Name"/>                    
                  <asp:BoundField DataField="Address"    HeaderText="Address"/>                    
                  <asp:BoundField DataField="City"       HeaderText="City"/>                        
                  <asp:BoundField DataField="Region"     HeaderText="Region"/>
                  <asp:BoundField DataField="PostalCode" HeaderText="Postal Code"/>                    
                </Fields>                    
              </asp:DetailsView>
            </td>                
          </tr>            
        </table>

        <asp:SqlDataSource ID="EmployeesSqlDataSource"  
          SelectCommand="SELECT EmployeeID, LastName + ', ' + FirstName AS FullName FROM Employees" 
          Connectionstring="<%$ ConnectionStrings:NorthwindConnection %>" 
          RunAt="server">
        </asp:SqlDataSource>


        <asp:SqlDataSource ID="EmployeeDetailsSqlDataSource" 
          SelectCommand="SELECT EmployeeID, LastName, FirstName, Address, City, Region, PostalCode
                         FROM Employees WHERE EmployeeID = @EmpID"

          InsertCommand="INSERT INTO Employees(LastName, FirstName, Address, City, Region, PostalCode)
                         VALUES (@LastName, @FirstName, @Address, @City, @Region, @PostalCode); 
                         SELECT @EmpID = SCOPE_IDENTITY()"

          UpdateCommand="UPDATE Employees SET LastName=@LastName, FirstName=@FirstName, Address=@Address,
                           City=@City, Region=@Region, PostalCode=@PostalCode
                         WHERE EmployeeID=@EmployeeID"

          DeleteCommand="DELETE Employees WHERE EmployeeID=@EmployeeID"

          ConnectionString="<%$ ConnectionStrings:NorthwindConnection %>"
          OnInserted="EmployeeDetailsSqlDataSource_OnInserted"
          RunAt="server">

          <SelectParameters>
            <asp:ControlParameter ControlID="EmployeesDropDownList" PropertyName="SelectedValue"
                                  Name="EmpID" Type="Int32" DefaultValue="0" />
          </SelectParameters>

          <InsertParameters>
            <asp:Parameter Name="LastName"   Type="String" />
            <asp:Parameter Name="FirstName"  Type="String" />
            <asp:Parameter Name="Address"    Type="String" />
            <asp:Parameter Name="City"       Type="String" />
            <asp:Parameter Name="Region"     Type="String" />
            <asp:Parameter Name="PostalCode" Type="String" />
            <asp:Parameter Name="EmpID" Direction="Output" Type="Int32" DefaultValue="0" />
          </InsertParameters>

          <UpdateParameters>
            <asp:Parameter Name="LastName"   Type="String" />
            <asp:Parameter Name="FirstName"  Type="String" />
            <asp:Parameter Name="Address"    Type="String" />
            <asp:Parameter Name="City"       Type="String" />
            <asp:Parameter Name="Region"     Type="String" />
            <asp:Parameter Name="PostalCode" Type="String" />
            <asp:Parameter Name="EmployeeID" Type="Int32" DefaultValue="0" />
          </UpdateParameters>

          <DeleteParameters>
            <asp:Parameter Name="EmployeeID" Type="Int32" DefaultValue="0" />
          </DeleteParameters>

        </asp:SqlDataSource>
      </form>
  </body>
</html>

Consulte também

Partilhar via

Usando parâmetros com controles de fonte de dados

Tipos de parâmetro

Valores de parâmetros fortemente tipados

Direção do parâmetro

Controles de fonte de dados e parâmetros

Consulte também

Tarefas

Conceitos

Referência

Recursos adicionais