This documentation is archived and is not being maintained.

KeyedCollection(TKey, TItem) Class

Provides the abstract base class for a collection whose keys are embedded in the values.

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

JScript does not support generic types or methods.

Type Parameters


The type of keys in the collection.


The type of items in the collection.

The KeyedCollection(TKey, TItem) class provides both O(1) indexed retrieval and keyed retrieval that approaches O(1). It is an abstract type (MustInherit in Visual Basic), or more accurately an infinite set of abstract types, because each of its constructed generic types is an abstract base class. To use KeyedCollection(TKey, TItem), derive your collection type from the appropriate constructed type.

The KeyedCollection(TKey, TItem) class is a hybrid between a collection based on the IList(T) generic interface and a collection based on the IDictionary(TKey, TValue) generic interface. Like collections based on the IList(T) generic interface, KeyedCollection(TKey, TItem) is an indexed list of items. Like collections based on the IDictionary(TKey, TValue) generic interface, KeyedCollection(TKey, TItem) has a key associated with each element.

Unlike dictionaries, an element of KeyedCollection(TKey, TItem) is not a key/value pair; instead, the entire element is the value and the key is embedded within the value. For example, an element of a collection derived from KeyedCollection<String,String> (KeyedCollection(Of String, String) in Visual Basic) might be "John Doe Jr." where the value is "John Doe Jr." and the key is "Doe"; or a collection of employee records containing integer keys could be derived from KeyedCollection<int,Employee>. The abstract (MustOverride in Visual Basic) GetKeyForItem method extracts the key from the element.

By default, the KeyedCollection(TKey, TItem) includes a lookup dictionary. When an item is added to the KeyedCollection(TKey, TItem), the item's key is extracted once and saved in the lookup dictionary for faster searches. This behavior is overridden by specifying a dictionary creation threshold when you create the KeyedCollection(TKey, TItem). The lookup dictionary is created the first time the number of elements exceeds that threshold. If you specify –1 as the threshold, the lookup dictionary is never created.


When the internal lookup dictionary is used, it contains references to all the items in the collection if TItem is a reference type, or copies of all the items in the collection if TItem is a value type. Thus, using the lookup dictionary may not be appropriate if TItem is a value type.

Every key in a KeyedCollection(TKey, TItem) must be unique. A key cannot be a null reference (Nothing in Visual Basic).

This section contains two code examples. The first example shows the minimum code required to derive from KeyedCollection(TKey, TItem), and demonstrates many of the inherited methods. The second example shows how to override the protected methods of KeyedCollection(TKey, TItem) to provide custom behavior.

Example 1

This code example shows the minimum code necessary to derive a collection class from KeyedCollection(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(TKey, TItem) and Collection(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(TKey, TItem). For a code example that uses mutable keys, see ChangeItemKey.

No code example is currently available or this language may not be supported.

Example 2

The following code example shows how to override the protected InsertItem, RemoveItem, ClearItems, and SetItem methods, to provide custom behavior for the Add, Remove, and Clear methods, and for setting the default Item property (the indexer in C#). The custom behavior provided in this example is a notification event named Changed, which is raised at the end of each of the overridden methods.

The code example creates the SimpleOrder class, which derives from KeyedCollection(TKey, TItem) and represents a simple order form. The order form contains OrderItem objects representing items ordered. The code example also creates a SimpleOrderChangedEventArgs class to contain the event information, and an enumeration to identify the type of change.

The code example demonstrates the custom behavior by calling the properties and methods of the derived class, in the Main method of the Demo class.

This code example uses objects with immutable keys. For a code example that uses mutable keys, see ChangeItemKey.

No code example is currently available or this language may not be supported.

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

Windows 7, Windows Vista, Windows XP SP2, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP Starter Edition, Windows Server 2008 R2, Windows Server 2008, Windows Server 2003, Windows Server 2000 SP4, Windows Millennium Edition, Windows 98, Windows CE, Windows Mobile for Smartphone, Windows Mobile for Pocket PC, Xbox 360, Zune

The .NET Framework and .NET Compact Framework do not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

.NET Framework

Supported in: 3.5, 3.0, 2.0

.NET Compact Framework

Supported in: 3.5, 2.0

XNA Framework

Supported in: 3.0, 2.0, 1.0