DataKey Class

 
System_CAPS_noteNote

The .NET API Reference documentation has a new home. Visit the .NET API Browser on docs.microsoft.com to see the new experience.

Represents the primary key field or fields of a record in a data-bound control.

Namespace:   System.Web.UI.WebControls
Assembly:  System.Web (in System.Web.dll)

System.Object
  System.Web.UI.WebControls.DataKey

public class DataKey : IStateManager, IEquatable<DataKey>

NameDescription
System_CAPS_pubmethodDataKey(IOrderedDictionary)

Initializes a new instance of the DataKey class using the specified dictionary of key field values.

System_CAPS_pubmethodDataKey(IOrderedDictionary, String[])

Initializes a new instance of the DataKey class using the specified dictionary of key field values and array of field names.

NameDescription
System_CAPS_protpropertyIsTrackingViewState

Gets a value indicating whether the DataKey object is tracking its view-state changes.

System_CAPS_pubpropertyItem[Int32]

Gets the value of the key field at the specified index from a DataKey object.

System_CAPS_pubpropertyItem[String]

Gets the value of the key field with the specified field name from a DataKey object.

System_CAPS_pubpropertyValue

Gets the value of the key field at index 0 in the DataKey object.

System_CAPS_pubpropertyValues

Gets an IOrderedDictionary object that contains every key field in the DataKey object.

NameDescription
System_CAPS_pubmethodEquals(DataKey)

Determines whether the specified DataKey array is equal to the current data key.

System_CAPS_pubmethodEquals(Object)

Determines whether the specified object is equal to the current object.(Inherited from Object.)

System_CAPS_protmethodFinalize()

Allows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection.(Inherited from Object.)

System_CAPS_pubmethodGetHashCode()

Serves as the default hash function. (Inherited from Object.)

System_CAPS_pubmethodGetType()

Gets the Type of the current instance.(Inherited from Object.)

System_CAPS_protmethodLoadViewState(Object)

Loads the previously saved view state of the DataKey object.

System_CAPS_protmethodMemberwiseClone()

Creates a shallow copy of the current Object.(Inherited from Object.)

System_CAPS_protmethodSaveViewState()

Saves the current view state of the DataKey object.

System_CAPS_pubmethodToString()

Returns a string that represents the current object.(Inherited from Object.)

System_CAPS_protmethodTrackViewState()

Marks the starting point at which to begin tracking and saving view-state changes to the DataKey object.

NameDescription
System_CAPS_pubinterfaceSystem_CAPS_privmethodIStateManager.LoadViewState(Object)

This API supports the product infrastructure and is not intended to be used directly from your code. Loads the previously saved view state of the DataKey object.

System_CAPS_pubinterfaceSystem_CAPS_privmethodIStateManager.SaveViewState()

This API supports the product infrastructure and is not intended to be used directly from your code. Saves the current view state of the DataKey object.

System_CAPS_pubinterfaceSystem_CAPS_privmethodIStateManager.TrackViewState()

This API supports the product infrastructure and is not intended to be used directly from your code. Marks the starting point at which to begin tracking and saving view-state changes to the DataKey object.

System_CAPS_pubinterfaceSystem_CAPS_privpropertyIStateManager.IsTrackingViewState

Gets a value indicating whether the DataKey object is tracking its view-state changes.

The DataKey class is used to represent the primary key for a record in a data-bound control. The primary key for a record can be composed of one of more fields from the data source. Although the DataKey class is not a collection, it can store multiple key field values. The key field values are populated when one of the constructors for the DataKey class is called. You can retrieve a key field value from a DataKey object in the following ways:

  • Use the DataKey.Item[Int32] property to retrieve a key field value at a specific index in the DataKey object.

  • Use the DataKey.Item[String] property to retrieve a key field value of a specific field.

  • Use the Value property to retrieve the value of the key field at index 0 in the DataKey object. This property is often used as a shortcut to retrieve the key value of a record when the primary key contains only one field.

  • Use the Values property to create an IOrderedDictionary object that can be used to iterate through the key field values.

In general, DataKey objects are automatically generated by data-bound controls when the control's DataKeyNames property is set. The DataKey objects contain the values of the key field or fields specified in the DataKeyNames property. Data-bound controls that display a single record at a time (such as DetailsView or FormView) generally store the DataKey object for the current record displayed in the DataKey property of the control. Data-bound controls that display multiple records at a time (such as GridView) generally store the DataKey objects for each record in the control in a DataKeyArray collection. The DataKeyArray collection is then stored in the DataKeys property of the control.

The following code example demonstrates how to determine the primary key value of a record in a DetailsView control using the Value property of a DataKey object.


<%@ 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 CustomerDetailsView_DataBound(Object sender, EventArgs e)
  {
    // Get the DataKey object for the current record.
    DataKey key = CustomerDetailsView.DataKey;

    // Display the the value of the key field.
    MessageLabel.Text = "The key field value for the displayed record is " + 
      key.Value.ToString() + ".";
  }

</script>

<html xmlns="http://www.w3.org/1999/xhtml" >

  <head runat="server">
    <title>DataKey Example</title>
</head>
<body>
    <form id="form1" runat="server">

      <h3>DataKey Example</h3>

        <asp:detailsview id="CustomerDetailsView"
          datasourceid="DetailsViewSource"
          autogeneraterows="true"
          datakeynames="CustomerID"  
          allowpaging="true"
          ondatabound="CustomerDetailsView_DataBound" 
          runat="server">

        </asp:detailsview>

        <br/>

        <asp:label id="MessageLabel"
          forecolor="Red"
          runat="server"/>

        <!-- This example uses Microsoft SQL Server and connects  -->
        <!-- to the Northwind sample database. Use an ASP.NET     -->
        <!-- expression to retrieve the connection string value   -->
        <!-- from the Web.config file.                            -->
        <asp:sqldatasource id="DetailsViewSource"
          selectcommand="Select [CustomerID], [CompanyName], [Address], [City], [PostalCode], [Country] From [Customers]"
          connectionstring="<%$ ConnectionStrings:NorthWindConnectionString%>" 
          runat="server"/>

      </form>
  </body>
</html>

.NET Framework
Available since 2.0

Any public static ( Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Return to top
Show: