KeyedCollection(Of TKey, TItem).GetKeyForItem Method (TItem)


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

When implemented in a derived class, extracts the key from the specified element.

Namespace:   System.Collections.ObjectModel
Assembly:  mscorlib (in mscorlib.dll)

Protected MustOverride Function GetKeyForItem (
	item As TItem
) As TKey


Type: TItem

The element from which to extract the key.

Return Value

Type: TKey

The key for the specified element.

If the key in the lookup dictionary is different from the key that is embedded in item, you cannot access item by using the key returned by GetKeyForItem.

You can implement this method to return null for a collection that contains items without keys, in which case the items can be accessed only by their index. This method is an O(1) operation.

You must override this method to provide the dictionary with a way to extract keys from items in the dictionary.

This method is called internally. It is not necessary for it to be public.

This code example shows the minimum code necessary to derive a collection class from KeyedCollection(Of TKey, TItem): overriding the GetKeyForItem method and providing a public constructor that delegates to a base class constructor. The code example also demonstrates many of the properties and methods inherited from KeyedCollection(Of TKey, TItem) and Collection(Of T) classes.

The SimpleOrder class is a very simple requisition list that contains OrderItem objects, each of which represents a line item in the order. The key of OrderItem is immutable, an important consideration for classes that derive from KeyedCollection(Of TKey, TItem). For a code example that uses mutable keys, see ChangeItemKey.

Imports System
Imports System.Collections.Generic
Imports System.Collections.ObjectModel

' This class represents a very simple keyed list of OrderItems,
' inheriting most of its behavior from the KeyedCollection and 
' Collection classes. The immediate base class is the constructed
' type KeyedCollection(Of Integer, OrderItem). When you inherit
' from KeyedCollection, the second generic type argument is the 
' type that you want to store in the collection -- in this case
' OrderItem. The first generic argument is the type that you want
' to use as a key. Its values must be calculated from OrderItem; 
' in this case it is the Integer field PartNumber, so SimpleOrder
' inherits KeyedCollection(Of Integer, OrderItem).
Public Class SimpleOrder
    Inherits KeyedCollection(Of Integer, OrderItem)

    ' This is the only method that absolutely must be overridden,
    ' because without it the KeyedCollection cannot extract the
    ' keys from the items. The input parameter type is the 
    ' second generic type argument, in this case OrderItem, and 
    ' the return value type is the first generic type argument,
    ' in this case Integer.
    Protected Overrides Function GetKeyForItem( _
        ByVal item As OrderItem) As Integer

        ' In this example, the key is the part number.
        Return item.PartNumber   
    End Function

End Class

Public Class Demo

    Public Shared Sub Main() 
        Dim weekly As New SimpleOrder()

        ' The Add method, inherited from Collection, takes OrderItem.
        weekly.Add(New OrderItem(110072674, "Widget", 400, 45.17))
        weekly.Add(New OrderItem(110072675, "Sprocket", 27, 5.3))
        weekly.Add(New OrderItem(101030411, "Motor", 10, 237.5))
        weekly.Add(New OrderItem(110072684, "Gear", 175, 5.17))


        ' The Contains method of KeyedCollection takes TKey.
        Console.WriteLine(vbLf & "Contains(101030411): {0}", _

        ' The default Item property of KeyedCollection takes the key
        ' type, Integer.
        Console.WriteLine(vbLf & "weekly(101030411).Description: {0}", _

        ' The Remove method of KeyedCollection takes a key.
        Console.WriteLine(vbLf & "Remove(101030411)")

        ' The Insert method, inherited from Collection, takes an 
        ' index and an OrderItem.
        Console.WriteLine(vbLf & "Insert(2, New OrderItem(...))")
        weekly.Insert(2, New OrderItem(111033401, "Nut", 10, .5))

        ' The default Item property is overloaded. One overload comes
        ' from KeyedCollection(Of Integer, OrderItem); that overload
        ' is read-only, and takes Integer because it retrieves by key. 
        ' The other overload comes from Collection(Of OrderItem), the 
        ' base class of KeyedCollection(Of Integer, OrderItem); it 
        ' retrieves by index, so it also takes an Integer. The compiler
        ' uses the most-derived overload, from KeyedCollection, so the
        ' only way to access SimpleOrder by index is to cast it to
        ' Collection(Of OrderItem). Otherwise the index is interpreted
        ' as a key, and KeyNotFoundException is thrown.
        Dim coweekly As Collection(Of OrderItem) = weekly
        Console.WriteLine(vbLf & "coweekly(2).Description: {0}", _

        Console.WriteLine(vbLf & "coweekly(2) = New OrderItem(...)")
        coweekly(2) = New OrderItem(127700026, "Crank", 27, 5.98)

        Dim temp As OrderItem = coweekly(2)

        ' The IndexOf method, inherited from Collection(Of OrderItem), 
        ' takes an OrderItem instead of a key.
        Console.WriteLine(vbLf & "IndexOf(temp): {0}", _

        ' The inherited Remove method also takes an OrderItem.
        Console.WriteLine(vbLf & "Remove(temp)")

        Console.WriteLine(vbLf & "RemoveAt(0)")

    End Sub

    Private Shared Sub Display(ByVal order As SimpleOrder) 
        For Each item As OrderItem In  order
        Next item
    End Sub
End Class

' This class represents a simple line item in an order. All the 
' values are immutable except quantity.
Public Class OrderItem
    Public ReadOnly PartNumber As Integer
    Public ReadOnly Description As String
    Public ReadOnly UnitPrice As Double

    Private _quantity As Integer = 0

    Public Sub New(ByVal partNumber As Integer, _
                   ByVal description As String, _
                   ByVal quantity As Integer, _
                   ByVal unitPrice As Double) 
        Me.PartNumber = partNumber
        Me.Description = description
        Me.Quantity = quantity
        Me.UnitPrice = unitPrice
    End Sub 'NewNew

    Public Property Quantity() As Integer 
            Return _quantity
        End Get
            If value < 0 Then
                Throw New ArgumentException("Quantity cannot be negative.")
            End If
            _quantity = value
        End Set
    End Property

    Public Overrides Function ToString() As String 
        Return String.Format( _
            "{0,9} {1,6} {2,-12} at {3,8:#,###.00} = {4,10:###,###.00}", _
            PartNumber, _quantity, Description, UnitPrice, _
            UnitPrice * _quantity)
    End Function
End Class

' This code example produces the following output:
'110072674    400 Widget       at    45.17 =  18,068.00
'110072675     27 Sprocket     at     5.30 =     143.10
'101030411     10 Motor        at   237.50 =   2,375.00
'110072684    175 Gear         at     5.17 =     904.75
'Contains(101030411): True
'weekly(101030411).Description: Motor
'110072674    400 Widget       at    45.17 =  18,068.00
'110072675     27 Sprocket     at     5.30 =     143.10
'110072684    175 Gear         at     5.17 =     904.75
'Insert(2, New OrderItem(...))
'110072674    400 Widget       at    45.17 =  18,068.00
'110072675     27 Sprocket     at     5.30 =     143.10
'111033401     10 Nut          at      .50 =       5.00
'110072684    175 Gear         at     5.17 =     904.75
'coweekly(2).Description: Nut
'coweekly(2) = New OrderItem(...)
'IndexOf(temp): 2
'110072674    400 Widget       at    45.17 =  18,068.00
'110072675     27 Sprocket     at     5.30 =     143.10
'110072684    175 Gear         at     5.17 =     904.75
'110072675     27 Sprocket     at     5.30 =     143.10
'110072684    175 Gear         at     5.17 =     904.75

Universal Windows Platform
Available since 8
.NET Framework
Available since 2.0
Portable Class Library
Supported in: portable .NET platforms
Available since 2.0
Windows Phone Silverlight
Available since 7.0
Windows Phone
Available since 8.1
Return to top