Windows apps
Collapse the table of content
Expand the table of content
Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

KeyedCollection<TKey, TItem>::ChangeItemKey Method (TItem, TKey)

 

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

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

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.

Exception Condition
ArgumentNullException

item is null.

-or-

key is null.

ArgumentException

item is not found.

-or-

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

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

This method is an O(1) operation.

Before 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 null 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.

The following code example shows how to override the protected ChangeItemKey method to support mutable keys, and how to override the protected InsertItem, RemoveItem, ClearItems, and SetItem methods to maintain the integrity of the keys and the collection.

The code example creates the MutableKeys collection, which derives from KeyedCollection<TKey, TItem>, and the MutableKey class. The MutableKey class has a settable Key property. When a new key is assigned to the property, the property setter calls the internal (Friend in Visual Basic) ChangeKey method of the collection to test whether the new key would conflict with an existing key. If so, an exception is thrown and the property value is not changed.

In order to maintain the connection between a MutableKey object and the MutableKeys collection and to prevent an object from being inserted into two collections, the MutableKey class has an internal (Friend in Visual Basic) Collection field. This field is maintained by the protected methods that provide custom behavior for adding and removing items from the collection, such as the InsertItem method. The field is set when the item is added to a collection and cleared when the item is removed.

No code example is currently available or this language may not be supported.

Universal Windows Platform
Available since 8
.NET Framework
Available since 2.0
Portable Class Library
Supported in: portable .NET platforms
Silverlight
Available since 2.0
Windows Phone Silverlight
Available since 7.0
Windows Phone
Available since 8.1
Return to top
Show:
© 2017 Microsoft