KeyedCollection<TKey, TItem> Class

Microsoft Silverlight will reach end of support after October 2021. Learn more.

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

Inheritance Hierarchy

System.Object
  System.Collections.ObjectModel.Collection<TItem>
    System.Collections.ObjectModel.KeyedCollection<TKey, TItem>
      System.Collections.Generic.KeyedByTypeCollection<TItem>
      System.ServiceModel.Description.MessagePartDescriptionCollection

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

Syntax

'Declaration
<DebuggerDisplayAttribute("Count = {Count}")> _
<DefaultMemberAttribute("Item")> _
<ComVisibleAttribute(False)> _
Public MustInherit Class KeyedCollection(Of TKey, TItem) _
    Inherits Collection(Of TItem)

[DebuggerDisplayAttribute("Count = {Count}")]
[DefaultMemberAttribute("Item")]
[ComVisibleAttribute(false)]
public abstract class KeyedCollection<TKey, TItem> : Collection<TItem>

Type Parameters

• TKey
  The type of keys in the collection.

• TItem
  The type of items in the collection.

The KeyedCollection<TKey, TItem> type exposes the following members.

Constructors

	Name	Description
	KeyedCollection<TKey, TItem>()	Initializes a new instance of the KeyedCollection<TKey, TItem> class that uses the default equality comparer.
	KeyedCollection<TKey, TItem>(IEqualityComparer<TKey>)	Initializes a new instance of the KeyedCollection<TKey, TItem> class that uses the specified equality comparer.
	KeyedCollection<TKey, TItem>(IEqualityComparer<TKey>, Int32)	Initializes a new instance of the KeyedCollection<TKey, TItem> class that uses the specified equality comparer and creates a lookup dictionary when the specified threshold is exceeded.

Top

Properties

	Name	Description
	Comparer	Gets the generic equality comparer that is used to determine equality of keys in the collection.
	Count	Gets the number of elements actually contained in the Collection<T>. (Inherited from Collection<T>.)
	Dictionary	Gets the lookup dictionary of the KeyedCollection<TKey, TItem>.
	Item[TKey]	Gets the element with the specified key.
	Item[Int32]	Gets or sets the element at the specified index. (Inherited from Collection<T>.)
	Items	Gets a IList<T> wrapper around the Collection<T>. (Inherited from Collection<T>.)

Top

Methods

	Name	Description
	Add	Adds an object to the end of the Collection<T>. (Inherited from Collection<T>.)
	ChangeItemKey	Changes the key associated with the specified element in the lookup dictionary.
	Clear	Removes all elements from the Collection<T>. (Inherited from Collection<T>.)
	ClearItems	Removes all elements from the KeyedCollection<TKey, TItem>. (Overrides Collection<T>.ClearItems().)
	Contains(T)	Determines whether an element is in the Collection<T>. (Inherited from Collection<T>.)
	Contains(TKey)	Determines whether the collection contains an element with the specified key.
	CopyTo	Copies the entire Collection<T> to a compatible one-dimensional Array, starting at the specified index of the target array. (Inherited from Collection<T>.)
	Equals(Object)	Determines whether the specified Object is equal to the current Object. (Inherited from Object.)
	Finalize	Allows an object to try to free resources and perform other cleanup operations before the Object is reclaimed by garbage collection. (Inherited from Object.)
	GetEnumerator	Returns an enumerator that iterates through the Collection<T>. (Inherited from Collection<T>.)
	GetHashCode	Serves as a hash function for a particular type. (Inherited from Object.)
	GetKeyForItem	When implemented in a derived class, extracts the key from the specified element.
	GetType	Gets the Type of the current instance. (Inherited from Object.)
	IndexOf	Searches for the specified object and returns the zero-based index of the first occurrence within the entire Collection<T>. (Inherited from Collection<T>.)
	Insert	Inserts an element into the Collection<T> at the specified index. (Inherited from Collection<T>.)
	InsertItem	Inserts an element into the KeyedCollection<TKey, TItem> at the specified index. (Overrides Collection<T>.InsertItem(Int32, T).)
	MemberwiseClone	Creates a shallow copy of the current Object. (Inherited from Object.)
	Remove(T)	Removes the first occurrence of a specific object from the Collection<T>. (Inherited from Collection<T>.)
	Remove(TKey)	Removes the element with the specified key from the KeyedCollection<TKey, TItem>.
	RemoveAt	Removes the element at the specified index of the Collection<T>. (Inherited from Collection<T>.)
	RemoveItem	Removes the element at the specified index of the KeyedCollection<TKey, TItem>. (Overrides Collection<T>.RemoveItem(Int32).)
	SetItem	Replaces the item at the specified index with the specified item. (Overrides Collection<T>.SetItem(Int32, T).)
	ToString	Returns a string that represents the current object. (Inherited from Object.)

Top

Explicit Interface Implementations

	Name	Description
	ICollection.CopyTo	Copies the elements of the ICollection to an Array, starting at a particular Array index. (Inherited from Collection<T>.)
	ICollection<T>.IsReadOnly	Gets a value indicating whether the ICollection<T> is read-only. (Inherited from Collection<T>.)
	ICollection.IsSynchronized	Gets a value indicating whether access to the ICollection is synchronized (thread safe). (Inherited from Collection<T>.)
	ICollection.SyncRoot	Gets an object that can be used to synchronize access to the ICollection. (Inherited from Collection<T>.)
	IEnumerable.GetEnumerator	Returns an enumerator that iterates through a collection. (Inherited from Collection<T>.)
	IList.Add	Adds an item to the IList. (Inherited from Collection<T>.)
	IList.Contains	Determines whether the IList contains a specific value. (Inherited from Collection<T>.)
	IList.IndexOf	Determines the index of a specific item in the IList. (Inherited from Collection<T>.)
	IList.Insert	Inserts an item into the IList at the specified index. (Inherited from Collection<T>.)
	IList.IsFixedSize	Gets a value indicating whether the IList has a fixed size. (Inherited from Collection<T>.)
	IList.IsReadOnly	Gets a value indicating whether the IList is read-only. (Inherited from Collection<T>.)
	IList.Item	Gets or sets the element at the specified index. (Inherited from Collection<T>.)
	IList.Remove	Removes the first occurrence of a specific object from the IList. (Inherited from Collection<T>.)

Top

Remarks

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.

Note:
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 nulla null reference (Nothing in Visual Basic).

Version Information

Silverlight

Supported in: 5, 4, 3

Silverlight for Windows Phone

Supported in: Windows Phone OS 7.1, Windows Phone OS 7.0

XNA Framework

Supported in: Xbox 360, Windows Phone OS 7.0

Platforms

For a list of the operating systems and browsers that are supported by Silverlight, see Supported Operating Systems and Browsers.

Thread Safety

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

See Also

Reference

System.Collections.ObjectModel Namespace