Dictionary<TKey,TValue> 类

定义

generic <typename TKey, typename TValue>
public ref class Dictionary : System::Collections::Generic::ICollection<System::Collections::Generic::KeyValuePair<TKey, TValue>>, System::Collections::Generic::IDictionary<TKey, TValue>, System::Collections::Generic::IEnumerable<System::Collections::Generic::KeyValuePair<TKey, TValue>>, System::Collections::Generic::IReadOnlyCollection<System::Collections::Generic::KeyValuePair<TKey, TValue>>, System::Collections::Generic::IReadOnlyDictionary<TKey, TValue>, System::Collections::IDictionary

generic <typename TKey, typename TValue>
public ref class Dictionary : System::Collections::Generic::ICollection<System::Collections::Generic::KeyValuePair<TKey, TValue>>, System::Collections::Generic::IDictionary<TKey, TValue>, System::Collections::Generic::IEnumerable<System::Collections::Generic::KeyValuePair<TKey, TValue>>, System::Collections::IDictionary, System::Runtime::Serialization::IDeserializationCallback, System::Runtime::Serialization::ISerializable

generic <typename TKey, typename TValue>
public ref class Dictionary : System::Collections::Generic::ICollection<System::Collections::Generic::KeyValuePair<TKey, TValue>>, System::Collections::Generic::IDictionary<TKey, TValue>, System::Collections::Generic::IEnumerable<System::Collections::Generic::KeyValuePair<TKey, TValue>>, System::Collections::Generic::IReadOnlyCollection<System::Collections::Generic::KeyValuePair<TKey, TValue>>, System::Collections::Generic::IReadOnlyDictionary<TKey, TValue>, System::Collections::IDictionary, System::Runtime::Serialization::IDeserializationCallback, System::Runtime::Serialization::ISerializable

public class Dictionary<TKey,TValue> : System.Collections.Generic.ICollection<System.Collections.Generic.KeyValuePair<TKey,TValue>>, System.Collections.Generic.IDictionary<TKey,TValue>, System.Collections.Generic.IEnumerable<System.Collections.Generic.KeyValuePair<TKey,TValue>>, System.Collections.Generic.IReadOnlyCollection<System.Collections.Generic.KeyValuePair<TKey,TValue>>, System.Collections.Generic.IReadOnlyDictionary<TKey,TValue>, System.Collections.IDictionary

[System.Runtime.InteropServices.ComVisible(false)]
[System.Serializable]
public class Dictionary<TKey,TValue> : System.Collections.Generic.ICollection<System.Collections.Generic.KeyValuePair<TKey,TValue>>, System.Collections.Generic.IDictionary<TKey,TValue>, System.Collections.Generic.IEnumerable<System.Collections.Generic.KeyValuePair<TKey,TValue>>, System.Collections.IDictionary, System.Runtime.Serialization.IDeserializationCallback, System.Runtime.Serialization.ISerializable

[System.Runtime.InteropServices.ComVisible(false)]
[System.Serializable]
public class Dictionary<TKey,TValue> : System.Collections.Generic.ICollection<System.Collections.Generic.KeyValuePair<TKey,TValue>>, System.Collections.Generic.IDictionary<TKey,TValue>, System.Collections.Generic.IEnumerable<System.Collections.Generic.KeyValuePair<TKey,TValue>>, System.Collections.Generic.IReadOnlyCollection<System.Collections.Generic.KeyValuePair<TKey,TValue>>, System.Collections.Generic.IReadOnlyDictionary<TKey,TValue>, System.Collections.IDictionary, System.Runtime.Serialization.IDeserializationCallback, System.Runtime.Serialization.ISerializable

public class Dictionary<TKey,TValue> : System.Collections.Generic.ICollection<System.Collections.Generic.KeyValuePair<TKey,TValue>>, System.Collections.Generic.IDictionary<TKey,TValue>, System.Collections.Generic.IEnumerable<System.Collections.Generic.KeyValuePair<TKey,TValue>>, System.Collections.Generic.IReadOnlyCollection<System.Collections.Generic.KeyValuePair<TKey,TValue>>, System.Collections.Generic.IReadOnlyDictionary<TKey,TValue>, System.Collections.IDictionary, System.Runtime.Serialization.IDeserializationCallback, System.Runtime.Serialization.ISerializable

type Dictionary<'Key, 'Value> = class
    interface ICollection<KeyValuePair<'Key, 'Value>>
    interface seq<KeyValuePair<'Key, 'Value>>
    interface IEnumerable
    interface IDictionary<'Key, 'Value>
    interface IReadOnlyCollection<KeyValuePair<'Key, 'Value>>
    interface IReadOnlyDictionary<'Key, 'Value>
    interface ICollection
    interface IDictionary

[<System.Runtime.InteropServices.ComVisible(false)>]
[<System.Serializable>]
type Dictionary<'Key, 'Value> = class
    interface IDictionary<'Key, 'Value>
    interface ICollection<KeyValuePair<'Key, 'Value>>
    interface seq<KeyValuePair<'Key, 'Value>>
    interface IDictionary
    interface ICollection
    interface IEnumerable
    interface ISerializable
    interface IDeserializationCallback

[<System.Runtime.InteropServices.ComVisible(false)>]
[<System.Serializable>]
type Dictionary<'Key, 'Value> = class
    interface IDictionary<'Key, 'Value>
    interface ICollection<KeyValuePair<'Key, 'Value>>
    interface IDictionary
    interface ICollection
    interface IReadOnlyDictionary<'Key, 'Value>
    interface IReadOnlyCollection<KeyValuePair<'Key, 'Value>>
    interface seq<KeyValuePair<'Key, 'Value>>
    interface IEnumerable
    interface ISerializable
    interface IDeserializationCallback

[<System.Runtime.InteropServices.ComVisible(false)>]
[<System.Serializable>]
type Dictionary<'Key, 'Value> = class
    interface IDictionary<'Key, 'Value>
    interface ICollection<KeyValuePair<'Key, 'Value>>
    interface seq<KeyValuePair<'Key, 'Value>>
    interface IEnumerable
    interface IDictionary
    interface ICollection
    interface IReadOnlyDictionary<'Key, 'Value>
    interface IReadOnlyCollection<KeyValuePair<'Key, 'Value>>
    interface ISerializable
    interface IDeserializationCallback

type Dictionary<'Key, 'Value> = class
    interface IDictionary<'Key, 'Value>
    interface ICollection<KeyValuePair<'Key, 'Value>>
    interface IReadOnlyDictionary<'Key, 'Value>
    interface IReadOnlyCollection<KeyValuePair<'Key, 'Value>>
    interface seq<KeyValuePair<'Key, 'Value>>
    interface IDictionary
    interface ICollection
    interface IEnumerable

type Dictionary<'Key, 'Value> = class
    interface ICollection<KeyValuePair<'Key, 'Value>>
    interface seq<KeyValuePair<'Key, 'Value>>
    interface IEnumerable
    interface IDictionary<'Key, 'Value>
    interface IReadOnlyCollection<KeyValuePair<'Key, 'Value>>
    interface IReadOnlyDictionary<'Key, 'Value>
    interface ICollection
    interface IDictionary
    interface IDeserializationCallback
    interface ISerializable

Public Class Dictionary(Of TKey, TValue)
Implements ICollection(Of KeyValuePair(Of TKey, TValue)), IDictionary, IDictionary(Of TKey, TValue), IEnumerable(Of KeyValuePair(Of TKey, TValue)), IReadOnlyCollection(Of KeyValuePair(Of TKey, TValue)), IReadOnlyDictionary(Of TKey, TValue)

Public Class Dictionary(Of TKey, TValue)
Implements ICollection(Of KeyValuePair(Of TKey, TValue)), IDeserializationCallback, IDictionary, IDictionary(Of TKey, TValue), IEnumerable(Of KeyValuePair(Of TKey, TValue)), ISerializable

Public Class Dictionary(Of TKey, TValue)
Implements ICollection(Of KeyValuePair(Of TKey, TValue)), IDeserializationCallback, IDictionary, IDictionary(Of TKey, TValue), IEnumerable(Of KeyValuePair(Of TKey, TValue)), IReadOnlyCollection(Of KeyValuePair(Of TKey, TValue)), IReadOnlyDictionary(Of TKey, TValue), ISerializable

类型参数

继承

Object

Dictionary<TKey,TValue>

派生

System.ServiceModel.MessageQuerySet

属性

ComVisibleAttribute SerializableAttribute

实现

ICollection<KeyValuePair<TKey,TValue>> IDictionary<TKey,TValue> IEnumerable<KeyValuePair<TKey,TValue>> IEnumerable<T> IReadOnlyCollection<KeyValuePair<TKey,TValue>> IReadOnlyDictionary<TKey,TValue> ICollection IDictionary IEnumerable IDeserializationCallback ISerializable

示例

下面的代码示例创建包含字符串键的字符串的空 Dictionary<TKey,TValue> ，并使用 Add 该方法添加一些元素。 该示例演示该方法在 Add 尝试添加重复键时引发 ArgumentException 。

该示例使用 Item[] 属性（C# 中的索引器）检索值，演示如何在请求的键不存在时引发值 KeyNotFoundException ，并显示可以替换与键关联的值。

该示例演示如何将TryGetValue该方法用作检索值的更高效方法（如果程序经常必须尝试不在字典中的键值），并演示如何在调用ContainsKey该方法之前使用Add该方法测试键是否存在。

该示例演示如何枚举字典中的键和值，以及如何单独使用 Keys 属性和属性枚举键和 Values 值。

最后，该示例演示了该方法 Remove 。

// Create a new dictionary of strings, with string keys.
//
Dictionary<string, string> openWith =
    new Dictionary<string, string>();

// Add some elements to the dictionary. There are no
// duplicate keys, but some of the values are duplicates.
openWith.Add("txt", "notepad.exe");
openWith.Add("bmp", "paint.exe");
openWith.Add("dib", "paint.exe");
openWith.Add("rtf", "wordpad.exe");

// The Add method throws an exception if the new key is
// already in the dictionary.
try
{
    openWith.Add("txt", "winword.exe");
}
catch (ArgumentException)
{
    Console.WriteLine("An element with Key = \"txt\" already exists.");
}

// The Item property is another name for the indexer, so you
// can omit its name when accessing elements.
Console.WriteLine("For key = \"rtf\", value = {0}.",
    openWith["rtf"]);

// The indexer can be used to change the value associated
// with a key.
openWith["rtf"] = "winword.exe";
Console.WriteLine("For key = \"rtf\", value = {0}.",
    openWith["rtf"]);

// If a key does not exist, setting the indexer for that key
// adds a new key/value pair.
openWith["doc"] = "winword.exe";

// The indexer throws an exception if the requested key is
// not in the dictionary.
try
{
    Console.WriteLine("For key = \"tif\", value = {0}.",
        openWith["tif"]);
}
catch (KeyNotFoundException)
{
    Console.WriteLine("Key = \"tif\" is not found.");
}

// When a program often has to try keys that turn out not to
// be in the dictionary, TryGetValue can be a more efficient
// way to retrieve values.
string value = "";
if (openWith.TryGetValue("tif", out value))
{
    Console.WriteLine("For key = \"tif\", value = {0}.", value);
}
else
{
    Console.WriteLine("Key = \"tif\" is not found.");
}

// ContainsKey can be used to test keys before inserting
// them.
if (!openWith.ContainsKey("ht"))
{
    openWith.Add("ht", "hypertrm.exe");
    Console.WriteLine("Value added for key = \"ht\": {0}",
        openWith["ht"]);
}

// When you use foreach to enumerate dictionary elements,
// the elements are retrieved as KeyValuePair objects.
Console.WriteLine();
foreach( KeyValuePair<string, string> kvp in openWith )
{
    Console.WriteLine("Key = {0}, Value = {1}",
        kvp.Key, kvp.Value);
}

// To get the values alone, use the Values property.
Dictionary<string, string>.ValueCollection valueColl =
    openWith.Values;

// The elements of the ValueCollection are strongly typed
// with the type that was specified for dictionary values.
Console.WriteLine();
foreach( string s in valueColl )
{
    Console.WriteLine("Value = {0}", s);
}

// To get the keys alone, use the Keys property.
Dictionary<string, string>.KeyCollection keyColl =
    openWith.Keys;

// The elements of the KeyCollection are strongly typed
// with the type that was specified for dictionary keys.
Console.WriteLine();
foreach( string s in keyColl )
{
    Console.WriteLine("Key = {0}", s);
}

// Use the Remove method to remove a key/value pair.
Console.WriteLine("\nRemove(\"doc\")");
openWith.Remove("doc");

if (!openWith.ContainsKey("doc"))
{
    Console.WriteLine("Key \"doc\" is not found.");
}

/* This code example produces the following output:

An element with Key = "txt" already exists.
For key = "rtf", value = wordpad.exe.
For key = "rtf", value = winword.exe.
Key = "tif" is not found.
Key = "tif" is not found.
Value added for key = "ht": hypertrm.exe

Key = txt, Value = notepad.exe
Key = bmp, Value = paint.exe
Key = dib, Value = paint.exe
Key = rtf, Value = winword.exe
Key = doc, Value = winword.exe
Key = ht, Value = hypertrm.exe

Value = notepad.exe
Value = paint.exe
Value = paint.exe
Value = winword.exe
Value = winword.exe
Value = hypertrm.exe

Key = txt
Key = bmp
Key = dib
Key = rtf
Key = doc
Key = ht

Remove("doc")
Key "doc" is not found.
*/

// Create a new dictionary of strings, with string keys.
let openWith = Dictionary<string, string>()

// Add some elements to the dictionary. There are no
// duplicate keys, but some of the values are duplicates.
openWith.Add("txt", "notepad.exe")
openWith.Add("bmp", "paint.exe")
openWith.Add("dib", "paint.exe")
openWith.Add("rtf", "wordpad.exe")

// The Add method throws an exception if the new key is
// already in the dictionary.
try
    openWith.Add("txt", "winword.exe")
with :? ArgumentException ->
    printfn "An element with Key = \"txt\" already exists."

// The Item property is another name for the indexer, so you
// can omit its name when accessing elements.
printfn $"""For key = "rtf", value = {openWith["rtf"]}"""

// The indexer can be used to change the value associated
// with a key.
openWith["rtf"] <- "winword.exe"
printfn $"""For key = "rtf", value = {openWith["rtf"]}"""

// If a key does not exist, setting the indexer for that key
// adds a new key/value pair.
openWith["doc"] <- "winword.exe"

// The indexer throws an exception if the requested key is
// not in the dictionary.
try
    printfn $"""For key = "tif", value = {openWith["tif"]}"""
with :? KeyNotFoundException ->
    printfn "Key = \"tif\" is not found."

// When a program often has to try keys that turn out not to
// be in the dictionary, TryGetValue can be a more efficient
// way to retrieve values.
match openWith.TryGetValue "tif" with
| true, value -> printfn $"For key = \"tif\", value = {value}."
| _ -> printfn "Key = \"tif\" is not found."

// ContainsKey can be used to test keys before inserting
// them.
if openWith.ContainsKey "ht" |> not then
    openWith.Add("ht", "hypertrm.exe")
    printfn $"""Value added for key = "ht": {openWith["ht"]}"""

// When you use foreach to enumerate dictionary elements,
// the elements are retrieved as KeyValuePair objects.
printfn ""

for kvp in openWith do
    printfn $"Key = {kvp.Key}, Value = {kvp.Value}"

// To get the values alone, use the Values property.
let valueColl = openWith.Values

// The elements of the ValueCollection are strongly typed
// with the type that was specified for dictionary values.
printfn ""

for s in valueColl do
    printfn $"Value = {s}"

// To get the keys alone, use the Keys property.
let keyColl = openWith.Keys

// The elements of the KeyCollection are strongly typed
// with the type that was specified for dictionary keys.
printfn ""

for s in keyColl do
    printfn $"Key = {s}"

// Use the Remove method to remove a key/value pair.
printfn "\nRemove(\"doc\")"
openWith.Remove "doc" |> ignore

if openWith.ContainsKey "doc" |> not then
    printfn "Key \"doc\" is not found."
// This code example produces the following output:
//     An element with Key = "txt" already exists.
//     For key = "rtf", value = wordpad.exe.
//     For key = "rtf", value = winword.exe.
//     Key = "tif" is not found.
//     Key = "tif" is not found.
//     Value added for key = "ht": hypertrm.exe
//
//     Key = txt, Value = notepad.exe
//     Key = bmp, Value = paint.exe
//     Key = dib, Value = paint.exe
//     Key = rtf, Value = winword.exe
//     Key = doc, Value = winword.exe
//     Key = ht, Value = hypertrm.exe
//
//     Value = notepad.exe
//     Value = paint.exe
//     Value = paint.exe
//     Value = winword.exe
//     Value = winword.exe
//     Value = hypertrm.exe
//
//     Key = txt
//     Key = bmp
//     Key = dib
//     Key = rtf
//     Key = doc
//     Key = ht
//
//     Remove("doc")
//     Key "doc" is not found.

Imports System.Collections.Generic

Public Class Example
    
    Public Shared Sub Main() 

        ' Create a new dictionary of strings, with string keys.
        '
        Dim openWith As New Dictionary(Of String, String)
        
        ' Add some elements to the dictionary. There are no 
        ' duplicate keys, but some of the values are duplicates.
        openWith.Add("txt", "notepad.exe")
        openWith.Add("bmp", "paint.exe")
        openWith.Add("dib", "paint.exe")
        openWith.Add("rtf", "wordpad.exe")
        
        ' The Add method throws an exception if the new key is 
        ' already in the dictionary.
        Try
            openWith.Add("txt", "winword.exe")
        Catch 
            Console.WriteLine("An element with Key = ""txt"" already exists.")
        End Try

        ' The Item property is the default property, so you 
        ' can omit its name when accessing elements. 
        Console.WriteLine("For key = ""rtf"", value = {0}.", _
            openWith("rtf"))
        
        ' The default Item property can be used to change the value
        ' associated with a key.
        openWith("rtf") = "winword.exe"
        Console.WriteLine("For key = ""rtf"", value = {0}.", _
            openWith("rtf"))
        
        ' If a key does not exist, setting the default Item property
        ' for that key adds a new key/value pair.
        openWith("doc") = "winword.exe"

        ' The default Item property throws an exception if the requested
        ' key is not in the dictionary.
        Try
            Console.WriteLine("For key = ""tif"", value = {0}.", _
                openWith("tif"))
        Catch 
            Console.WriteLine("Key = ""tif"" is not found.")
        End Try

        ' When a program often has to try keys that turn out not to
        ' be in the dictionary, TryGetValue can be a more efficient 
        ' way to retrieve values.
        Dim value As String = ""
        If openWith.TryGetValue("tif", value) Then
            Console.WriteLine("For key = ""tif"", value = {0}.", value)
        Else
            Console.WriteLine("Key = ""tif"" is not found.")
        End If

        ' ContainsKey can be used to test keys before inserting 
        ' them.
        If Not openWith.ContainsKey("ht") Then
            openWith.Add("ht", "hypertrm.exe")
            Console.WriteLine("Value added for key = ""ht"": {0}", _
                openWith("ht"))
        End If

        ' When you use foreach to enumerate dictionary elements,
        ' the elements are retrieved as KeyValuePair objects.
        Console.WriteLine()
        For Each kvp As KeyValuePair(Of String, String) In openWith
            Console.WriteLine("Key = {0}, Value = {1}", _
                kvp.Key, kvp.Value)
        Next kvp

        ' To get the values alone, use the Values property.
        Dim valueColl As _
            Dictionary(Of String, String).ValueCollection = _
            openWith.Values
        
        ' The elements of the ValueCollection are strongly typed
        ' with the type that was specified for dictionary values.
        Console.WriteLine()
        For Each s As String In  valueColl
            Console.WriteLine("Value = {0}", s)
        Next s

        ' To get the keys alone, use the Keys property.
        Dim keyColl As _
            Dictionary(Of String, String).KeyCollection = _
            openWith.Keys
        
        ' The elements of the KeyCollection are strongly typed
        ' with the type that was specified for dictionary keys.
        Console.WriteLine()
        For Each s As String In  keyColl
            Console.WriteLine("Key = {0}", s)
        Next s

        ' Use the Remove method to remove a key/value pair.
        Console.WriteLine(vbLf + "Remove(""doc"")")
        openWith.Remove("doc")
        
        If Not openWith.ContainsKey("doc") Then
            Console.WriteLine("Key ""doc"" is not found.")
        End If

    End Sub

End Class

' This code example produces the following output:
'
'An element with Key = "txt" already exists.
'For key = "rtf", value = wordpad.exe.
'For key = "rtf", value = winword.exe.
'Key = "tif" is not found.
'Key = "tif" is not found.
'Value added for key = "ht": hypertrm.exe
'
'Key = txt, Value = notepad.exe
'Key = bmp, Value = paint.exe
'Key = dib, Value = paint.exe
'Key = rtf, Value = winword.exe
'Key = doc, Value = winword.exe
'Key = ht, Value = hypertrm.exe
'
'Value = notepad.exe
'Value = paint.exe
'Value = paint.exe
'Value = winword.exe
'Value = winword.exe
'Value = hypertrm.exe
'
'Key = txt
'Key = bmp
'Key = dib
'Key = rtf
'Key = doc
'Key = ht
'
'Remove("doc")
'Key "doc" is not found.
'

注解

泛 Dictionary<TKey,TValue> 型类提供从一组键到一组值的映射。 字典的每个添加都包含一个值及其关联的键。 通过使用其键检索值的速度非常快，接近 O（1），因为该 Dictionary<TKey,TValue> 类作为哈希表实现。

只要对象用作键， Dictionary<TKey,TValue>它就不能以任何方式更改影响其哈希值。 每个键 Dictionary<TKey,TValue> 都必须根据字典的相等比较器是唯一的。 如果键的类型null是引用类型，则键不能TValue，但值可以是。

Dictionary<TKey,TValue> 需要相等实现来确定键是否相等。 可以使用接受参数的IEqualityComparer<T>构造函数指定泛型接口的实现;如果未指定实现，则使用默认泛型相等比较器comparer。EqualityComparer<T>.Default 如果类型 TKey 实现 System.IEquatable<T> 泛型接口，则默认相等比较器使用该实现。

一个 Dictionary<TKey,TValue> 元素的容量是可以保留的元素 Dictionary<TKey,TValue> 数。 随着元素添加到 a Dictionary<TKey,TValue>，重新分配内部数组，容量会自动增加。

仅限 .NET Framework：对于非常大Dictionary<TKey,TValue>的对象，可以通过将配置元素的属性enabled设置为<gcAllowVeryLargeObjects>true在运行时环境中，将 64 位系统上的最大容量增加到 20 亿个元素。

为了进行枚举，字典中的每个项都被视为表示 KeyValuePair<TKey,TValue> 值及其键的结构。 返回项的顺序未定义。

foreach C# 语言（For Each在 Visual Basic 中）的语句返回集合中元素类型的对象。 Dictionary<TKey,TValue>由于是键和值的集合，因此元素类型不是键的类型或值的类型。 相反，元素类型是 KeyValuePair<TKey,TValue> 键类型和值类型。 例如：

foreach( KeyValuePair<string, string> kvp in myDictionary )
{
    Console.WriteLine("Key = {0}, Value = {1}", kvp.Key, kvp.Value);
}

for kvp in myDictionary do
    printfn $"Key = {kvp.Key}, Value = {kvp.Value}"

For Each kvp As KeyValuePair(Of String, String) In myDictionary
    Console.WriteLine("Key = {0}, Value = {1}", kvp.Key, kvp.Value)
Next kvp

该 foreach 语句是枚举器周围的包装器，它只允许从集合中读取，而不是写入集合。

线程安全性

只要集合未修改，A Dictionary<TKey,TValue> 就可以同时支持多个读取器。 即便如此，通过集合进行枚举本质上不是线程安全的过程。 在枚举与写入访问竞争的极少数情况下，必须在整个枚举期间锁定集合。 若要允许多个线程访问集合进行读取和写入，必须实现自己的同步。

有关线程安全的替代方法，请参阅 ConcurrentDictionary<TKey,TValue> 类或 ImmutableDictionary<TKey,TValue> 类。

此类型的公共静态（Shared 在 Visual Basic 中）成员是线程安全的。

另请参阅

• IDictionary<TKey,TValue>
• SortedList<TKey,TValue>
• KeyValuePair<TKey,TValue>
• IEqualityComparer<T>