Export (0) Print
Expand All
This topic has not yet been rated - Rate this topic

DictionaryBase Class

Provides the abstract base class for a strongly typed collection of key/value pairs.

Namespace:  System.Collections
Assembly:  mscorlib (in mscorlib.dll)
'Declaration
<SerializableAttribute> _
<ComVisibleAttribute(True)> _
Public MustInherit Class DictionaryBase _
	Implements IDictionary, ICollection, IEnumerable

The DictionaryBase type exposes the following members.

  NameDescription
Protected methodDictionaryBaseInitializes a new instance of the DictionaryBase class.
Top
  NameDescription
Public propertyCountGets the number of elements contained in the DictionaryBase instance.
Protected propertyDictionaryGets the list of elements contained in the DictionaryBase instance.
Protected propertyInnerHashtableGets the list of elements contained in the DictionaryBase instance.
Top
  NameDescription
Public methodClearClears the contents of the DictionaryBase instance.
Public methodCopyToCopies the DictionaryBase elements to a one-dimensional Array at the specified index.
Public methodEquals(Object)Determines whether the specified Object is equal to the current Object. (Inherited from Object.)
Protected methodFinalizeAllows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from Object.)
Public methodGetEnumeratorReturns an IDictionaryEnumerator that iterates through the DictionaryBase instance.
Public methodGetHashCodeServes as a hash function for a particular type. (Inherited from Object.)
Public methodGetTypeGets the Type of the current instance. (Inherited from Object.)
Protected methodMemberwiseCloneCreates a shallow copy of the current Object. (Inherited from Object.)
Protected methodOnClearPerforms additional custom processes before clearing the contents of the DictionaryBase instance.
Protected methodOnClearCompletePerforms additional custom processes after clearing the contents of the DictionaryBase instance.
Protected methodOnGetGets the element with the specified key and value in the DictionaryBase instance.
Protected methodOnInsertPerforms additional custom processes before inserting a new element into the DictionaryBase instance.
Protected methodOnInsertCompletePerforms additional custom processes after inserting a new element into the DictionaryBase instance.
Protected methodOnRemovePerforms additional custom processes before removing an element from the DictionaryBase instance.
Protected methodOnRemoveCompletePerforms additional custom processes after removing an element from the DictionaryBase instance.
Protected methodOnSetPerforms additional custom processes before setting a value in the DictionaryBase instance.
Protected methodOnSetCompletePerforms additional custom processes after setting a value in the DictionaryBase instance.
Protected methodOnValidatePerforms additional custom processes when validating the element with the specified key and value.
Public methodToStringReturns a string that represents the current object. (Inherited from Object.)
Top
  NameDescription
Public Extension MethodAsParallelEnables parallelization of a query. (Defined by ParallelEnumerable.)
Public Extension MethodAsQueryableConverts an IEnumerable to an IQueryable. (Defined by Queryable.)
Public Extension MethodCast(Of TResult)Casts the elements of an IEnumerable to the specified type. (Defined by Enumerable.)
Public Extension MethodOfType(Of TResult)Filters the elements of an IEnumerable based on a specified type. (Defined by Enumerable.)
Top
  NameDescription
Explicit interface implemetationPrivate propertyICollection.IsSynchronizedGets a value indicating whether access to a DictionaryBase object is synchronized (thread safe).
Explicit interface implemetationPrivate propertyICollection.SyncRootGets an object that can be used to synchronize access to a DictionaryBase object.
Explicit interface implemetationPrivate methodIDictionary.AddAdds an element with the specified key and value into the DictionaryBase.
Explicit interface implemetationPrivate methodIDictionary.ContainsDetermines whether the DictionaryBase contains a specific key.
Explicit interface implemetationPrivate propertyIDictionary.IsFixedSizeGets a value indicating whether a DictionaryBase object has a fixed size.
Explicit interface implemetationPrivate propertyIDictionary.IsReadOnlyGets a value indicating whether a DictionaryBase object is read-only.
Explicit interface implemetationPrivate propertyIDictionary.ItemGets or sets the value associated with the specified key.
Explicit interface implemetationPrivate propertyIDictionary.KeysGets an ICollection object containing the keys in the DictionaryBase object.
Explicit interface implemetationPrivate methodIDictionary.RemoveRemoves the element with the specified key from the DictionaryBase.
Explicit interface implemetationPrivate propertyIDictionary.ValuesGets an ICollection object containing the values in the DictionaryBase object.
Explicit interface implemetationPrivate methodIEnumerable.GetEnumeratorReturns an IEnumerator that iterates through the DictionaryBase.
Top

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 DictionaryBase 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.

The foreach statement is a wrapper around the enumerator, which only allows reading from, not writing to, the collection.

NoteNote

Because keys can be inherited and their behavior changed, their absolute uniqueness cannot be guaranteed by comparisons using the Equals method.

Notes to Implementers

This base class is provided to make it easier for implementers to create a strongly typed custom collection. Implementers are encouraged to 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.

The following code example implements the DictionaryBase class and uses that implementation to create a dictionary of String keys and values that have a Length of 5 characters or less.


Imports System
Imports System.Collections

Public Class ShortStringDictionary
   Inherits DictionaryBase

   Default Public Property Item(key As String) As String
      Get
         Return CType(Dictionary(key), String)
      End Get
      Set
         Dictionary(key) = value
      End Set
   End Property

   Public ReadOnly Property Keys() As ICollection
      Get
         Return Dictionary.Keys
      End Get
   End Property

   Public ReadOnly Property Values() As ICollection
      Get
         Return Dictionary.Values
      End Get
   End Property

   Public Sub Add(key As String, value As String)
      Dictionary.Add(key, value)
   End Sub 'Add

   Public Function Contains(key As String) As Boolean
      Return Dictionary.Contains(key)
   End Function 'Contains

   Public Sub Remove(key As String)
      Dictionary.Remove(key)
   End Sub 'Remove

   Protected Overrides Sub OnInsert(key As Object, value As Object)
      If Not GetType(System.String).IsAssignableFrom(key.GetType()) Then
         Throw New ArgumentException("key must be of type String.", "key")
      Else
         Dim strKey As String = CType(key, String)
         If strKey.Length > 5 Then
            Throw New ArgumentException("key must be no more than 5 characters in length.", "key")
         End If
      End If 
      If Not GetType(System.String).IsAssignableFrom(value.GetType()) Then
         Throw New ArgumentException("value must be of type String.", "value")
      Else
         Dim strValue As String = CType(value, String)
         If strValue.Length > 5 Then
            Throw New ArgumentException("value must be no more than 5 characters in length.", "value")
         End If
      End If
   End Sub 'OnInsert

   Protected Overrides Sub OnRemove(key As Object, value As Object)
      If Not GetType(System.String).IsAssignableFrom(key.GetType()) Then
         Throw New ArgumentException("key must be of type String.", "key")
      Else
         Dim strKey As String = CType(key, String)
         If strKey.Length > 5 Then
            Throw New ArgumentException("key must be no more than 5 characters in length.", "key")
         End If
      End If
   End Sub 'OnRemove

   Protected Overrides Sub OnSet(key As Object, oldValue As Object, newValue As Object)
      If Not GetType(System.String).IsAssignableFrom(key.GetType()) Then
         Throw New ArgumentException("key must be of type String.", "key")
      Else
         Dim strKey As String = CType(key, String)
         If strKey.Length > 5 Then
            Throw New ArgumentException("key must be no more than 5 characters in length.", "key")
         End If
      End If 
      If Not GetType(System.String).IsAssignableFrom(newValue.GetType()) Then
         Throw New ArgumentException("newValue must be of type String.", "newValue")
      Else
         Dim strValue As String = CType(newValue, String)
         If strValue.Length > 5 Then
            Throw New ArgumentException("newValue must be no more than 5 characters in length.", "newValue")
         End If
      End If
   End Sub 'OnSet

   Protected Overrides Sub OnValidate(key As Object, value As Object)
      If Not GetType(System.String).IsAssignableFrom(key.GetType()) Then
         Throw New ArgumentException("key must be of type String.", "key")
      Else
         Dim strKey As String = CType(key, String)
         If strKey.Length > 5 Then
            Throw New ArgumentException("key must be no more than 5 characters in length.", "key")
         End If
      End If 
      If Not GetType(System.String).IsAssignableFrom(value.GetType()) Then
         Throw New ArgumentException("value must be of type String.", "value")
      Else
         Dim strValue As String = CType(value, String)
         If strValue.Length > 5 Then
            Throw New ArgumentException("value must be no more than 5 characters in length.", "value")
         End If
      End If
   End Sub 'OnValidate 

End Class 'ShortStringDictionary


Public Class SamplesDictionaryBase

   Public Shared Sub Main()

      ' Creates and initializes a new DictionaryBase.
      Dim mySSC As New ShortStringDictionary()

      ' Adds elements to the collection.
      mySSC.Add("One", "a")
      mySSC.Add("Two", "ab")
      mySSC.Add("Three", "abc")
      mySSC.Add("Four", "abcd")
      mySSC.Add("Five", "abcde")

      ' Display the contents of the collection using For Each. This is the preferred method.
      Console.WriteLine("Contents of the collection (using For Each):")
      PrintKeysAndValues1(mySSC)

      ' Display the contents of the collection using the enumerator.
      Console.WriteLine("Contents of the collection (using enumerator):")
      PrintKeysAndValues2(mySSC)

      ' Display the contents of the collection using the Keys property and the Item property.
      Console.WriteLine("Initial contents of the collection (using Keys and Item):")
      PrintKeysAndValues3(mySSC)

      ' Tries to add a value that is too long.
      Try
          mySSC.Add("Ten", "abcdefghij")
      Catch e As ArgumentException
          Console.WriteLine(e.ToString())
      End Try

      ' Tries to add a key that is too long.
      Try
          mySSC.Add("Eleven", "ijk")
      Catch e As ArgumentException
          Console.WriteLine(e.ToString())
      End Try

      Console.WriteLine()

      ' Searches the collection with Contains.
      Console.WriteLine("Contains ""Three"": {0}", mySSC.Contains("Three"))
      Console.WriteLine("Contains ""Twelve"": {0}", mySSC.Contains("Twelve"))
      Console.WriteLine()

      ' Removes an element from the collection.
      mySSC.Remove("Two")

      ' Displays the contents of the collection.
      Console.WriteLine("After removing ""Two"":")
      PrintKeysAndValues1(mySSC)

    End Sub 'Main


    ' Uses the For Each statement which hides the complexity of the enumerator.
    ' NOTE: The For Each statement is the preferred way of enumerating the contents of a collection.
    Public Shared Sub PrintKeysAndValues1(myCol As ShortStringDictionary)
      Dim myDE As DictionaryEntry
      For Each myDE In  myCol
          Console.WriteLine("   {0,-5} : {1}", myDE.Key, myDE.Value)
      Next myDE
      Console.WriteLine()
    End Sub 'PrintKeysAndValues1


    ' Uses the enumerator. 
    ' NOTE: The For Each statement is the preferred way of enumerating the contents of a collection.
    Public Shared Sub PrintKeysAndValues2(myCol As ShortStringDictionary)
      Dim myDE As DictionaryEntry
      Dim myEnumerator As System.Collections.IEnumerator = myCol.GetEnumerator()
      While myEnumerator.MoveNext()
          If Not (myEnumerator.Current Is Nothing) Then
            myDE = CType(myEnumerator.Current, DictionaryEntry)
            Console.WriteLine("   {0,-5} : {1}", myDE.Key, myDE.Value)
          End If
      End While
      Console.WriteLine()
    End Sub 'PrintKeysAndValues2


    ' Uses the Keys property and the Item property.
    Public Shared Sub PrintKeysAndValues3(myCol As ShortStringDictionary)
      Dim myKeys As ICollection = myCol.Keys
      Dim k As String
      For Each k In  myKeys
          Console.WriteLine("   {0,-5} : {1}", k, myCol(k))
      Next k
      Console.WriteLine()
    End Sub 'PrintKeysAndValues3

End Class 'SamplesDictionaryBase 


'This code produces the following output.
'
'Contents of the collection (using For Each):
'   Three : abc
'   Five  : abcde
'   Two   : ab
'   One   : a
'   Four  : abcd
'
'Contents of the collection (using enumerator):
'   Three : abc
'   Five  : abcde
'   Two   : ab
'   One   : a
'   Four  : abcd
'
'Initial contents of the collection (using Keys and Item):
'   Three : abc
'   Five  : abcde
'   Two   : ab
'   One   : a
'   Four  : abcd
'
'System.ArgumentException: value must be no more than 5 characters in length.
'Parameter name: value
'   at ShortStringDictionary.OnValidate(Object key, Object value)
'   at System.Collections.DictionaryBase.System.Collections.IDictionary.Add(Object key, Object value)
'   at SamplesDictionaryBase.Main()
'System.ArgumentException: key must be no more than 5 characters in length.
'Parameter name: key
'   at ShortStringDictionary.OnValidate(Object key, Object value)
'   at System.Collections.DictionaryBase.System.Collections.IDictionary.Add(Object key, Object value)
'   at SamplesDictionaryBase.Main()
'
'Contains "Three": True
'Contains "Twelve": False
'
'After removing "Two":
'   Three : abc
'   Five  : abcde
'   One   : a
'   Four  : abcd



.NET Framework

Supported in: 4, 3.5, 3.0, 2.0, 1.1, 1.0

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Windows 7, Windows Vista SP1 or later, Windows XP SP3, Windows XP SP2 x64 Edition, Windows Server 2008 (Server Core not supported), Windows Server 2008 R2 (Server Core supported with SP1 or later), Windows Server 2003 SP2

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

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

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 SyncRoot property.

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.

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.