Comment un contrôle de source de données crée des paramètres pour des champs liés aux données

Lorsqu'un contrôle lié aux données demande une opération au contrôle de source de données, il passe une ou plusieurs collections IDictionary contenant des noms et des valeurs de paramètres pour l'opération de données demandée. La valeur des paires nom/valeur du dictionnaire est dérivée des contrôles enfants. Par exemple, dans le cas d'une opération de mise à jour, le contrôle lié aux données lit des valeurs de paramètre sur des contrôles TextBox ou CheckBox affichés en mode Édition. Le nom des paires nom/valeur est emprunté aux champs liés aux contrôles enfants et aux champs spécifiés dans la propriété DataKeyNames. Pour une opération de mise à jour ou de suppression, le contrôle lié aux données peut également passer un dictionnaire qui contient les valeurs d'origine de l'enregistrement de données.

Les paires nom/valeur sont passées à l'aide des collections IDictionary suivantes :

• Collection Values Passée pour une opération d'insertion. Contient les paires nom/valeur pour un nouvel enregistrement. Les noms et les valeurs des champs de la collection Values sont empruntés aux contrôles enfants dans un InsertItemTemplate ou aux champs liés dans un contrôle DetailsView dont la propriété InsertVisible a la valeur true.

• Collection Keys   Passée pour des opérations de mise à jour et de suppression. Contient la ou les clés primaires de l'enregistrement actuellement mis à jour ou supprimé. Si les champs clés peuvent être modifiés à la source de données, la collection Keys contient également leurs valeurs d'origine. Lorsqu'un contrôle lié aux données est rempli avec les données du contrôle de source de données, il conserve ces données dans l'état d'affichage. Lorsqu'une opération de mise à jour ou de suppression est demandée, la collection Keys est remplie avec les valeurs précédemment stockées dans l'état d'affichage. Si la propriété EnableViewState du contrôle lié aux données a la valeur false, la collection Keys n'est pas remplie pour l'opération de mise à jour ou de suppression.

• Collection NewValues   Passée pour une opération de mise à jour. Contient les paires nom/valeur contenant les nouvelles valeurs de l'élément mis à jour, y compris celles des champs clés actualisables. Les noms et les valeurs des champs de la collection NewValues sont empruntés aux contrôles enfants dans un EditItemTemplate ou aux champs liés dans un contrôle DetailsView dont la propriété ReadOnly a la valeur false.

• Collection OldValues   Passée pour des opérations de mise à jour ou de suppression. Contient les valeurs d'origine de l'enregistrement de données à utiliser pour le contrôle d'accès concurrentiel optimiste. (Pour plus d'informations sur le contrôle d'accès concurrentiel optimiste, consultez la propriété ConflictDetection du contrôle de source de données que vous utilisez). Les valeurs des champs clés identifiés par la propriété DataKeyNames ne sont pas comprises dans la collection OldValues. Les noms et les valeurs des champs clés ne sont compris que dans la collection Keys. Lorsqu'un contrôle lié aux données est rempli avec les données du contrôle de source de données, il conserve ces données dans l'état d'affichage. Lorsqu'une opération de mise à jour ou de suppression est demandée, la collection OldValues est remplie avec les valeurs précédemment stockées dans l'état d'affichage. Si la propriété EnableViewState du contrôle lié aux données a la valeur false, la collection OldValues n'est pas remplie pour l'opération de mise à jour ou de suppression.

Vous pouvez accéder à toutes ces collections à l'aide des arguments passés avec l'événement de contrôle lié aux données pour l'opération demandée. Par exemple, la classe GridViewUpdateEventArgs donne accès à la collection NewValues dans l'événement RowUpdating du contrôle GridView.

Le contrôle de source de données crée automatiquement des paramètres pour les valeurs passées dans les collections IDictionary. Pour une opération d'insertion, le contrôle de source de données remplit sa collection InsertParameters avec les valeurs des paires nom/valeur de la collection Values. Pour une opération de mise à jour, le contrôle de source de données remplit sa collection UpdateParameters avec les valeurs des paires nom/valeur des collections Keys, NewValues et OldValues. Pour une opération de suppression, le contrôle de source de données remplit sa collection DeleteParameters avec les valeurs des paires nom/valeur des collections Keys et OldValues.

La collection OldValues n'est pas remplie par défaut. Elle n'est remplie que lorsque la propriété ConflictDetection du contrôle de source de données a la valeur CompareAllValues.

Pour une opération de mise à jour ou de suppression, par défaut, seuls les paramètres des valeurs liées actuelles sont créés. Si vous devez accéder à la fois aux valeurs actuelles et d'origine liées, par exemple pour prendre en charge les contrôles d'accès concurrentiel optimiste, vous pouvez faire en sorte que le contrôle de source de données crée les paramètres des valeurs actuelles et des valeurs d'origine. À cette fin, vous devez établir une convention d'affectation de noms pour les paramètres qui contiendront les valeurs d'origine. Le format des paramètres des valeurs d'origine est déterminé par la propriété OldValuesParameterFormatString. Affectez à la propriété OldValuesParameterFormatString une chaîne qui inclut "{0}" comme espace réservé pour le nom du champ. Par exemple, si vous utilisez le contrôle SqlDataSource et affectez à la propriété OldValuesParameterFormatString la valeur "old_{0}", les noms des paramètres des valeurs d'origine seront résolus en noms de champs précédés du préfixe "@old_". (Le contrôle SqlDataSource ajoute le caractère "@" au début de tous les noms de paramètres.) Prenons l'exemple d'une opération de mise à jour sur un champ nommé LastModifiedDate. La valeur actuelle du champ est passée dans le dictionnaire Values et la valeur d'origine du champ est passée dans le dictionnaire OldValues. Un paramètre nommé @LastModifiedDate est créé pour passer la valeur actuelle et un paramètre nommé @old_LastModifiedDate est créé pour passer la valeur d'origine. Vous pouvez ensuite inclure les deux paramètres dans une instruction SQL pour distinguer les valeurs actuelle et d'origine du champ, comme illustré dans l'exemple suivant :

UPDATE Table1 SET LastModifiedDate = @LastModifiedDate
  WHERE Key = @Key AND LastModifiedDate = @old_LastModifiedDate

Vous n'avez pas besoin d'accéder directement aux collections nom/valeur IDictionary. Il vous suffit d'inclure les noms de paramètres générés automatiquement dans vos instructions SQL (si votre source de données prend en charge les paramètres nommés), ou de les inclure comme noms de paramètres des méthodes de données dans un objet métier auquel vous accédez à l'aide d'un contrôle ObjectDataSource.

Vous pouvez, si vous le souhaitez, définir des objets Parameter dans les collections UpdateParameters, InsertParameters ou DeleteParameters du contrôle de source de données pour personnaliser les valeurs passées par le contrôle lié aux données. Vous pouvez créer des objets Parameter pour typer fortement la valeur ou pour spécifier une valeur par défaut si null est passé.

L'exemple de code suivant montre un contrôle DetailsView lié à un contrôle SqlDataSource. Les propriétés InsertCommand, UpdateCommand et DeleteCommand du contrôle SqlDataSource utilisent les noms de paramètres automatiquement générés par le contrôle SqlDataSource. Les valeurs de paramètres sont remplies à partir des dictionnaires Keys et NewValues. Le dictionnaire OldValues n'est pas utilisé parce que la propriété ConflictDetection a la valeur ConflictOptions.OverwriteChanges, qui est la valeur par défaut.

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

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

  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 runat="server">
    <title>Northwind Employees</title>
</head>
<body>
    <form id="form1" runat="server">

      <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>

Concepts