Questa documentazione è stata archiviata e non viene gestita.

Classe Dictionary<TKey, TValue>

Aggiornamento: novembre 2007

Rappresenta un insieme di chiavi e valori.

Spazio dei nomi:  System.Collections.Generic
Assembly:  mscorlib (in mscorlib.dll)

[SerializableAttribute]
[ComVisibleAttribute(false)]
public class Dictionary<TKey, TValue> : IDictionary<TKey, TValue>, 
	ICollection<KeyValuePair<TKey, TValue>>, IEnumerable<KeyValuePair<TKey, TValue>>, 
	IDictionary, ICollection, IEnumerable, ISerializable, IDeserializationCallback

J# supporta l'utilizzo di API generiche ma non la dichiarazione di nuove.
JScript non supporta i tipi o i metodi generici.

Parametri di tipo

TKey

Tipo di chiavi nel dizionario.

TValue

Tipo di valori nel dizionario.

La classe generica Dictionary<TKey, TValue> fornisce un mapping da un gruppo di chiavi a un gruppo di valori. Ogni aggiunta al dizionario è costituita da un valore e dalla relativa chiave. Il recupero di un valore tramite la relativa chiave è un'operazione molto veloce, prossima a O(1), perché la classe Dictionary<TKey, TValue> viene implementata come tabella hash.

xfhwa508.alert_note(it-it,VS.90).gifNota:

La velocità di recupero dipende dalla qualità dell'algoritmo di hash del tipo specificato per il parametro TKey.

Se un oggetto viene utilizzato come chiave nella classe Dictionary<TKey, TValue>, non deve venire modificato in alcun modo che possa comportare una modifica del relativo valore hash. Ogni chiave in una classe Dictionary<TKey, TValue> deve essere univoca in base all'operatore di confronto di uguaglianza del dizionario. Una chiave non può essere null, a differenza di un valore, se il tipo di valore TValue è un tipo di riferimento.

Dictionary<TKey, TValue> richiede un'implementazione di uguaglianza per determinare se le chiavi sono uguali. È possibile specificare un'implementazione dell'interfaccia generica IEqualityComparer<T> utilizzando un costruttore che accetta un parametro comparer. Se non si specifica un'implementazione, viene utilizzato l'operatore di confronto di uguaglianza EqualityComparer<T>.Default. Se il tipo TKey implementa l'interfaccia generica System.IEquatable<T>, l'operatore di confronto di uguaglianza predefinito utilizza tale implementazione.

xfhwa508.alert_note(it-it,VS.90).gifNota:

Ad esempio, è possibile utilizzare gli operatori di confronto tra stringhe senza distinzione tra maiuscole e minuscole forniti dalla classe StringComparer per creare dizionari con chiavi di stringhe senza distinzione tra maiuscole e minuscole.

La capacità di una classe Dictionary<TKey, TValue> è il numero di elementi che tale classe Dictionary<TKey, TValue> può contenere. Ogni volta che si aggiungono elementi a una classe Dictionary<TKey, TValue>, la capacità viene automaticamente aumentata nel modo appropriato riallocando la matrice interna.

Ai fini dell'enumerazione, ogni elemento del dizionario viene trattato come struttura KeyValuePair<TKey, TValue> che rappresenta un valore e la relativa chiave. L'ordine in cui gli elementi vengono restituiti non è definito.

L'istruzione foreach del linguaggio C# ( for each in C++, For Each in Visual Basic) richiede il tipo di ogni elemento dell'insieme. Poiché la classe Dictionary<TKey, TValue> è un insieme di chiavi e valori, il tipo di elemento non è il tipo della chiave né il tipo del valore. Il tipo di elemento è, infatti, un KeyValuePair<TKey, TValue> del tipo della chiave e del tipo del valore. Ad esempio:

foreach (KeyValuePair<int, string> kvp in myDictionary) {...}

L'istruzione foreach è un wrapper per l'enumeratore che consente solo di leggere dall'insieme, non di scrivere in esso.

xfhwa508.alert_note(it-it,VS.90).gifNota:

Poiché le chiavi possono essere ereditate ed è possibile modificarne il comportamento, non è possibile garantirne l'univocità assoluta mediante confronti eseguiti utilizzando il metodo Equals.

Nell'esempio di codice riportato di seguito viene creata una classe Dictionary<TKey, TValue> vuota di stringhe con chiavi stringa e viene utilizzato il metodo Add per aggiungere alcuni elementi. L'esempio dimostra che il metodo Add genera una classe ArgumentException durante il tentativo di aggiunta di una chiave duplicata.

Nell'esempio viene utilizzata la proprietà Item (ovvero l'indicizzatore in C#) per il recupero dei valori. Viene mostrato inoltre che se una chiave richiesta non è presente nell'insieme, viene generata un'eccezione KeyNotFoundException e che è possibile sostituire un valore associato alla chiave.

L'esempio mostra come utilizzare il metodo TryGetValue come modo più efficace per il recupero di valori se un programma deve provare valori di chiave non presenti nel dizionario e illustra come utilizzare il metodo ContainsKey per verificare l'esistenza di una chiave prima di chiamare il metodo Add.

L'esempio mostra come enumerare le chiavi e i valori nel dizionario e come enumerare le chiavi e i valori da soli utilizzando la proprietà Keys e la proprietà Values.

Infine viene illustrato il metodo Remove.

using System;
using System.Collections.Generic;

public class Example
{
    public static void Main()
    {
        // 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.
 */


System.Object
  System.Collections.Generic.Dictionary<TKey, TValue>

I membri statici pubblici (Shared in Visual Basic) di questo tipo sono thread-safe. Qualsiasi membro di istanza non ha garanzia di essere thread-safe.

Un oggetto Dictionary<TKey, TValue> può supportare più lettori simultaneamente, purché l'insieme non venga modificato. Tuttavia, l'enumerazione di un insieme non è di per sé una procedura thread-safe. Nel raro caso in cui l'enumerazione condivida accessi in scrittura, è necessario bloccare l'insieme durante l'intero processo di enumerazione. Per consentire l'accesso all'insieme in lettura e scrittura da parte di più thread, è necessario implementare una sincronizzazione personalizzata.

Windows Vista, Windows XP SP2, Windows XP Media Center Edition, Windows XP Professional x64 Edition , Windows XP Starter Edition, Windows Server 2003, Windows Server 2000 SP4, Windows Millennium Edition, Windows 98, Windows CE, Windows Mobile per Smartphone, Windows Mobile per Pocket PC, Xbox 360

.NET Framework e .NET Compact Framework non supportano tutte le versioni di ciascuna piattaforma. Per un elenco delle versioni supportate, vedere Requisiti di sistema di .NET Framework.

.NET Framework

Supportato in: 3.5, 3.0, 2.0

.NET Compact Framework

Supportato in: 3.5, 2.0

XNA Framework

Supportato in: 2.0, 1.0
Mostra: