Represents a collection of key/value pairs that are organized based on the hash code of the key.
Assembly: mscorlib (in mscorlib.dll)
Each element is a key/value pair stored in a DictionaryEntry object. A key cannot be a null reference (Nothing in Visual Basic), but a value can be.
The objects used as keys by a are required to override the Object.GetHashCode method (or the IHashCodeProvider interface) and the Object.Equals method (or the IComparer interface). The implementation of both methods and interfaces must handle case sensitivity the same way; otherwise, the might behave incorrectly. For example, when creating a , you must use the CaseInsensitiveHashCodeProvider class (or any case-insensitive IHashCodeProvider implementation) with the CaseInsensitiveComparer class (or any case-insensitive IComparer implementation).
Furthermore, these methods must produce the same results when called with the same parameters while the key exists in the . An alternative is to use a constructor with an IEqualityComparer parameter. If key equality were simply reference equality, the inherited implementation of Object.GetHashCode and Object.Equals would suffice.
Key objects must be immutable as long as they are used as keys in the .
When an element is added to the , the element is placed into a bucket based on the hash code of the key. Subsequent lookups of the key use the hash code of the key to search in only one particular bucket, thus substantially reducing the number of key comparisons required to find an element.
The load factor of a determines the maximum ratio of elements to buckets. Smaller load factors cause faster average lookup times at the cost of increased memory consumption. The default load factor of 1.0 generally provides the best balance between speed and size. A different load factor can also be specified when the is created.
As elements are added to a , the actual load factor of the increases. When the actual load factor reaches the specified load factor, the number of buckets in the is automatically increased to the smallest prime number that is larger than twice the current number of buckets.
Each key object in the must provide its own hash function, which can be accessed by calling GetHash. However, any object implementing IHashCodeProvider can be passed to a constructor, and that hash function is used for all objects in the table.
The capacity of a is the number of elements the can hold. As elements are added to a , the capacity is automatically increased as required through reallocation.
[Visual Basic, C#]
The foreach statement of the C# language (for each in Visual Basic) requires the type of each element in the collection. Since each element of the is a key/value pair, the element type is not the type of the key or the type of the value. Instead, the element type is DictionaryEntry. For example:
[Visual Basic, C#]
The foreach statement is a wrapper around the enumerator, which only allows reading from, not writing to, the collection.
Because serializing and deserializing an enumerator for a can cause the elements to become reordered, it is not possible to continue enumeration without calling the Reset method.
Because keys can be inherited and their behavior changed, their absolute uniqueness cannot be guaranteed by comparisons using the Equals method.
is thread safe for use by multiple reader threads and a single writing thread. It is thread safe for multi-thread use when only one of the threads perform write (update) operations, which allows for lock-free reads provided that the writers are serialized to the . To support multiple writers all operations on the must be done through the wrapper returned by the Synchronized method, provided that there are no threads reading the object.
Enumerating through a collection is intrinsically not a thread safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads.
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.