KeyedCollection<TKey, TItem>.ChangeItemKey Method

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

Changes the key associated with the specified element in the lookup dictionary.

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

Syntax

'Declaration
Protected Sub ChangeItemKey ( _
    item As TItem, _
    newKey As TKey _
)
protected void ChangeItemKey(
    TItem item,
    TKey newKey
)

Parameters

  • item
    Type: TItem
    The element to change the key of.
  • newKey
    Type: TKey
    The new key for item.

Exceptions

Exception Condition
ArgumentNullException

item is nulla null reference (Nothing in Visual Basic).

-or-

key is nulla null reference (Nothing in Visual Basic).

ArgumentException

item is not found.

-or-

key already exists in the KeyedCollection<TKey, TItem>.

Remarks

This method does not modify the key embedded in item; it simply replaces the key saved in the lookup dictionary. Therefore, if newKey is different from the key that is embedded in item, you cannot access item by using the key returned by GetKeyForItem.

This method does nothing if the KeyedCollection<TKey, TItem> does not have a lookup dictionary.

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

This method is an O(1) operation.

Notes for Implementers

After modifying the key embedded in an item, you must call this method to update the key in the lookup dictionary. If the dictionary creation threshold is –1, calling this method is not necessary.

Do not expose the ChangeItemKey method as a public method of a derived class. Misuse of this method puts the lookup dictionary out of sync with item keys. For example, setting the key to nulla null reference (Nothing in Visual Basic) and then setting it to another value adds multiple keys for an item to the lookup dictionary. Expose this method internally to allow mutable item keys: When the key for an item changes, this method is used to change the key in the lookup dictionary.

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.