[Serializable] |
This implementation does not provide a synchronized (thread-safe) wrapper for a DictionaryBase, but derived classes can create their own synchronized versions of the DictionaryBase using the DictionaryBase.System.Collections.ICollection.SyncRoot property.
Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads could 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.
The foreach statement of the C# language requires the type of each element in the collection. Since each element of the DictionaryBase is a key-and-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:
foreach (DictionaryEntry myEntry in myDictionaryBase) {...}
This base class is provided to make it easier for implementers to create a strongly typed custom collection. Implementers should extend this base class instead of creating their own.
Members of this base class are protected and are intended to be used through a derived class only.
| Count | Read-only Gets the number of elements contained in the DictionaryBase instance. |
| Clear | Clears the contents of the DictionaryBase instance. |
| CopyTo | Copies the DictionaryBase elements to a one-dimensional Array at the specified index. |
| Equals (inherited from System.Object) |
See base class member description: System.Object.Equals Derived from System.Object, the primary base class for all objects. |
| GetEnumerator | Returns an IDictionaryEnumerator that can iterate through the DictionaryBase instance. |
| GetHashCode (inherited from System.Object) |
See base class member description: System.Object.GetHashCode Derived from System.Object, the primary base class for all objects. |
| GetType (inherited from System.Object) |
See base class member description: System.Object.GetType Derived from System.Object, the primary base class for all objects. |
| ToString (inherited from System.Object) |
See base class member description: System.Object.ToString Derived from System.Object, the primary base class for all objects. |
| ctor #1 | Default constructor. This constructor is called by derived class constructors to initialize state in this type. |
| Dictionary | Read-only Gets the list of elements contained in the DictionaryBase instance. |
| InnerHashtable | Read-only Gets the list of elements contained in the DictionaryBase instance. |
| Finalize (inherited from System.Object) |
See base class member description: System.Object.Finalize Derived from System.Object, the primary base class for all objects. |
| MemberwiseClone (inherited from System.Object) |
See base class member description: System.Object.MemberwiseClone Derived from System.Object, the primary base class for all objects. |
| OnClear | Performs additional custom processes before clearing the contents of the DictionaryBase instance. |
| OnClearComplete | Performs additional custom processes after clearing the contents of the DictionaryBase instance. |
| OnGet | Gets the element with the specified key and value in the DictionaryBase instance. |
| OnInsert | Performs additional custom processes before inserting a new element into the DictionaryBase instance. |
| OnInsertComplete | Performs additional custom processes after inserting a new element into the DictionaryBase instance. |
| OnRemove | Performs additional custom processes before removing an element from the DictionaryBase instance. |
| OnRemoveComplete | Performs additional custom processes after removing an element from the DictionaryBase instance. |
| OnSet | Performs additional custom processes before setting a value in the DictionaryBase instance. |
| OnSetComplete | Performs additional custom processes after setting a value in the DictionaryBase instance. |
| OnValidate | Performs additional custom processes when validating the element with the specified key and value. |
| IDictionary.Add | Adds an element with the specified key and value into the DictionaryBase. |
| IDictionary.Contains | Determines whether the DictionaryBase contains a specific key. |
| IDictionary.Remove | Removes the element with the specified key from the DictionaryBase. |
| IEnumerable.GetEnumerator | Returns an IEnumerator that can iterate through the DictionaryBase. |
Hierarchy:
protected DictionaryBase(); |
public int Count {get;}
|
protected IDictionary Dictionary {get;}
|
protected Hashtable InnerHashtable {get;}
|
public void Clear(); |
array
index
| Exception Type | Condition |
|---|---|
| ArgumentNullException | array is null. |
| ArgumentOutOfRangeException | index is less than zero. |
| ArgumentException | array is multidimensional. -or- index is equal to or greater than the length of array. -or- The number of elements in the source DictionaryBase is greater than the available space from index to the end of the destination array. |
| InvalidCastException | The type of the source DictionaryBase cannot be cast automatically to the type of the destination array. |
~DictionaryBase(); |
public IDictionaryEnumerator GetEnumerator(); |
Initially, the enumerator is positioned before the first element in the collection. IEnumerator.Reset also brings the enumerator back to this position. At this position, calling IEnumerator.Current throws an exception. Therefore, you must call IEnumerator.MoveNext to advance the enumerator to the first element of the collection before reading the value of IEnumerator.Current.
IEnumerator.Current returns the same object until either IEnumerator.MoveNext or IEnumerator.Reset is called. IEnumerator.MoveNext sets IEnumerator.Current to the next element.
After the end of the collection is passed, the enumerator is positioned after the last element in the collection, and calling IEnumerator.MoveNext returns false. If the last call to IEnumerator.MoveNext returned false, calling IEnumerator.Current throws an exception. To set IEnumerator.Current to the first element of the collection again, you can call IEnumerator.Reset followed by IEnumerator.MoveNext.
An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying or deleting elements, the enumerator is irrecoverably invalidated and the next call to IEnumerator.MoveNext or IEnumerator.Reset throws an InvalidOperationException. If the collection is modified between IEnumerator.MoveNext and IEnumerator.Current, IEnumerator.Current will return the element that it is set to, even if the enumerator is already invalidated.
The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads could 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.
public virtual int GetHashCode(); |
public Type GetType(); |
protected object MemberwiseClone(); |
protected virtual void OnClear(); |
The On* methods are invoked only on the instance returned by the DictionaryBase.Dictionary property, but not on the instance returned by the DictionaryBase.InnerHashtable property.
This method allows implementers to define processes that must be performed before deleting all the elements from the underlying Hashtable. By defining this method, implementers can add functionality to inherited methods without having to override all other methods.
DictionaryBase.OnClear is invoked before the standard Clear behavior, whereas DictionaryBase.OnClearComplete is invoked after the standard Clear behavior.
For example, implementers can exempt certain elements from deletion by a global Clear.
protected virtual void OnClearComplete(); |
The On* methods are invoked only on the instance returned by the DictionaryBase.Dictionary property, but not on the instance returned by the DictionaryBase.InnerHashtable property.
This method allows implementers to define processes that must be performed after deleting all the elements from the underlying Hashtable. By defining this method, implementers can add functionality to inherited methods without having to override all other methods.
DictionaryBase.OnClear is invoked before the standard Clear behavior, whereas DictionaryBase.OnClearComplete is invoked after the standard Clear behavior.
key
currentValue
The On* methods are invoked only on the instance returned by the DictionaryBase.Dictionary property, but not on the instance returned by the DictionaryBase.InnerHashtable property.
This method allows implementers to define processes that must be performed when executing the standard Get behavior of the underlying Hashtable. By defining this method, implementers can add functionality to inherited methods without having to override all other methods.
DictionaryBase.OnGet can be used to specify processes to perform before returning the value retrieved from the underlying Hashtable. For example, implementers can cast the value into another type before returning it.
key
value
The On* methods are invoked only on the instance returned by the DictionaryBase.Dictionary property, but not on the instance returned by the DictionaryBase.InnerHashtable property.
This method allows implementers to define processes that must be performed before inserting the element into the underlying Hashtable. By defining this method, implementers can add functionality to inherited methods without having to override all other methods.
DictionaryBase.OnInsert is invoked before the standard Insert behavior, whereas DictionaryBase.OnInsertComplete is invoked after the standard Insert behavior.
For example, implementers can restrict which types of objects can be inserted into the Hashtable.
key
value
The On* methods are invoked only on the instance returned by the DictionaryBase.Dictionary property, but not on the instance returned by the DictionaryBase.InnerHashtable property.
This method allows implementers to define processes that must be performed after inserting the element into the underlying Hashtable. By defining this method, implementers can add functionality to inherited methods without having to override all other methods.
DictionaryBase.OnInsert is invoked before the standard Insert behavior, whereas DictionaryBase.OnInsertComplete is invoked after the standard Insert behavior.
key
value
The On* methods are invoked only on the instance returned by the DictionaryBase.Dictionary property, but not on the instance returned by the DictionaryBase.InnerHashtable property.
This method allows implementers to define processes that must be performed before removing the element from the underlying Hashtable. By defining this method, implementers can add functionality to inherited methods without having to override all other methods.
DictionaryBase.OnRemove is invoked before the standard Remove behavior, whereas DictionaryBase.OnRemoveComplete is invoked after the standard Remove behavior.
For example, implementers can prevent removal of elements by always throwing an exception in DictionaryBase.OnRemove.
key
value
The On* methods are invoked only on the instance returned by the DictionaryBase.Dictionary property, but not on the instance returned by the DictionaryBase.InnerHashtable property.
This method allows implementers to define processes that must be performed after removing the element from the underlying Hashtable. By defining this method, implementers can add functionality to inherited methods without having to override all other methods.
DictionaryBase.OnRemove is invoked before the standard Remove behavior, whereas DictionaryBase.OnRemoveComplete is invoked after the standard Remove behavior.
key
oldValue
newValue
The On* methods are invoked only on the instance returned by the DictionaryBase.Dictionary property, but not on the instance returned by the DictionaryBase.InnerHashtable property.
This method allows implementers to define processes that must be performed before setting the specified element in the underlying Hashtable. By defining this method, implementers can add functionality to inherited methods without having to override all other methods.
DictionaryBase.OnSet is invoked before the standard Set behavior, whereas DictionaryBase.OnSetComplete is invoked after the standard Set behavior.
For example, implementers can restrict which values can be overwritten by performing a check inside DictionaryBase.OnSet.
key
oldValue
newValue
The On* methods are invoked only on the instance returned by the DictionaryBase.Dictionary property, but not on the instance returned by the DictionaryBase.InnerHashtable property.
This method allows implementers to define processes that must be performed after setting the specified element in the underlying Hashtable. By defining this method, implementers can add functionality to inherited methods without having to override all other methods.
DictionaryBase.OnSet is invoked before the standard Set behavior, whereas DictionaryBase.OnSetComplete is invoked after the standard Set behavior.
key
value
The On* methods are invoked only on the instance returned by the DictionaryBase.Dictionary property, but not on the instance returned by the DictionaryBase.InnerHashtable property.
This method allows implementers to define processes that must be performed when executing the standard behavior of the underlying Hashtable. By defining this method, implementers can add functionality to inherited methods without having to override all other methods.
DictionaryBase.OnValidate can be used to impose restrictions on the type of objects that are accepted into the collection. The default implementation prevents null from being added to or removed from the underlying Hashtable.
key
value
| Exception Type | Condition |
|---|---|
| ArgumentNullException | key is null. |
| ArgumentException | An element with the same key already exists in the DictionaryBase. |
| NotSupportedException | The DictionaryBase is read-only. -or- The DictionaryBase has a fixed size. |
The DictionaryBase.System.Collections.IDictionary.Item property can also be used to add new elements by setting the value of a key that does not exist in the DictionaryBase. For example:
myCollection["myNonexistentKey"] = myValue
. However, if the specified key already exists in the DictionaryBase, setting the DictionaryBase.System.Collections.IDictionary.this property overwrites the old value. In contrast, the DictionaryBase.System.Collections.IDictionary.Add method does not modify existing elements.
key
| Exception Type | Condition |
|---|---|
| ArgumentNullException | key is null. |
void IDictionary.Remove( |
key
| Exception Type | Condition |
|---|---|
| ArgumentNullException | key is null. |
| NotSupportedException | The DictionaryBase is read-only. -or- The DictionaryBase has a fixed size. |
IEnumerator IEnumerable.GetEnumerator(); |
Initially, the enumerator is positioned before the first element in the collection. IEnumerator.Reset also brings the enumerator back to this position. At this position, calling IEnumerator.Current throws an exception. Therefore, you must call IEnumerator.MoveNext to advance the enumerator to the first element of the collection before reading the value of IEnumerator.Current.
IEnumerator.Current returns the same object until either IEnumerator.MoveNext or IEnumerator.Reset is called. IEnumerator.MoveNext sets IEnumerator.Current to the next element.
After the end of the collection is passed, the enumerator is positioned after the last element in the collection, and calling IEnumerator.MoveNext returns false. If the last call to IEnumerator.MoveNext returned false, calling IEnumerator.Current throws an exception. To set IEnumerator.Current to the first element of the collection again, you can call IEnumerator.Reset followed by IEnumerator.MoveNext.
An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying or deleting elements, the enumerator is irrecoverably invalidated and the next call to IEnumerator.MoveNext or IEnumerator.Reset throws an InvalidOperationException. If the collection is modified between IEnumerator.MoveNext and IEnumerator.Current, IEnumerator.Current will return the element that it is set to, even if the enumerator is already invalidated.
The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads could 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.
public virtual string ToString(); |