A Dictionary is an object that, like a List, contains a collection of values. The difference is that a Dictionary does not keep the values in any particular order. Instead, when you put a value in a Dictionary, you associate it with another value known as the key. When you want to retrieve a value, you present the key, and the Dictionary supplies the value associated with the key.

To understand the concept of a Dictionary, think about its real-life counterpart. A dictionary consists of a collection of words and definitions. In Dictionary terminology, we would refer to the words in a dictionary as the keys, and the definitions as the values. When you use a real dictionary, your goal is to find a definition (the value). To access a definition, you look up a word (the key), and when you find the word, you can read the definition (the value) associated with it.

Here's how you create a Dictionary:

Dictionary<string, string> phoneList = new Dictionary<string, string>();

Like a List, a Dictionary is a class that must be qualified with the type of data that will be stored in it. Since a Dictionary stores both keys and values, you must specify the data type of both. This Dictionary will use strings for both the keys and the values.

After you've created the Dictionary, you put values into the table using assignment statements:

phoneList["john"] = "523-1534";
phoneList["sue"] = "928-1699";
phoneList["fred"] = "991-2534";

The values in brackets are the keys; the values on the right-hand side of the assignment are the values to be placed into the Dictionary.

In general, to add a value to a Dictionary tbl, you write

tbl[key] = value

where key is usually a string literal or string variable, and value can be any kind of data.

The notation is similar to the code that you write when you change a value in a List. And, in fact, the same notation can be used to change a value in a Dictionary. For example, if after writing the statements above, you want to change the phone number associated with sue, you could write:

phoneList["sue"] = "528-1963";

This would replace the old phone number with the new one.

It helps to envision a Dictionary as a two-column table, with keys in the first column, and their associated values in the second column:

To retrieve a value from the Dictionary, you provide a key, and the Dictionary returns the associated value, like this:

string phoneNum = phoneList["john"];

What happens if you supply a key value that does not exist?

string phoneNum = phoneList["harold"]; // causes crash

A runtime exception is thrown. To prevent this, you can check to see if a key exists using the ContainsKey method:

if (phoneList.ContainsKey("harold")) {
  // harold is in the PhoneList
  string phoneNum = phoneList["harold"];
}

  foreach (string name in phoneList.Keys) {
    string phoneNum = phoneList[name];
    Console.WriteLine(name + ": " + phoneNum);
  }