Runnable C# Docs: Dictionary

Q: What is the difference between Dictionary.Add and the indexer in C#?

dict.Add(key, value) inserts a new entry and throws ArgumentException if the key already exists. dict[key] = value inserts the entry if the key is new and overwrites the value if it exists, and never throws for a duplicate. TryAdd(key, value) inserts only when the key is new and returns false otherwise.

Q: How does TryGetValue work in C#?

dict.TryGetValue(key, out var value) returns true and sets value when the key exists, and returns false and sets value to the default of its type when it does not. It does one lookup, where ContainsKey followed by dict[key] does two, and it never throws KeyNotFoundException.

Q: How do I iterate over a Dictionary in C#?

foreach (KeyValuePair pair in dict) gives each entry with pair.Key and pair.Value. To loop over only keys or only values, use dict.Keys or dict.Values. Do not add keys to the dictionary inside that loop: it throws InvalidOperationException.

Q: How do I make Dictionary keys case-insensitive?

Pass a comparer to the constructor: new Dictionary (StringComparer.OrdinalIgnoreCase). Then "Apple" and "apple" are the same key for lookups, Add and ContainsKey. The comparer is fixed when the dictionary is created.

Q: What is a KeyValuePair in C#?

KeyValuePair is the struct a dictionary hands you for each entry when you enumerate it. It has read-only Key and Value properties, so you cannot change an entry through it; write dict[pair.Key] = newValue instead (after the loop, or over a copy of the keys).

Dictionary<TKey, TValue> stores values under unique keys and finds a value by its key in roughly constant time, however many entries there are. It is the C# equivalent of a hash map: a phone book from name to number, a cache from ID to record, a count per word.

Creating a dictionary and reading values

using System;
using System.Collections.Generic;

class Program
{
    static void Main()
    {
        var stock = new Dictionary<string, int>();
        stock["apples"] = 12;
        stock["pears"] = 0;

        var prices = new Dictionary<string, decimal>
        {
            ["coffee"] = 3.20m,
            ["tea"] = 2.50m,
        };

        var capitals = new Dictionary<string, string>
        {
            { "France", "Paris" },
            { "Peru", "Lima" },
        };

        Console.WriteLine(stock["apples"]);
        Console.WriteLine(prices["tea"]);
        Console.WriteLine(capitals.Count);
        Console.WriteLine(capitals.ContainsKey("Peru"));
        Console.WriteLine(capitals.ContainsValue("Rome"));
    }
}

Output:

12
2.50
2
True
False

Both initializer forms do the same thing. The ["key"] = value form (C# 6) uses the indexer, so a repeated key overwrites; the { key, value } form calls Add, so a repeated key throws when the line runs.

ContainsKey is a hash lookup and is fast. ContainsValue has to scan every entry, because values are not indexed.

Add vs the indexer vs TryAdd

There are three ways to put an entry in, and they differ only in what happens when the key already exists:

using System;
using System.Collections.Generic;

class Program
{
    static void Main()
    {
        var ages = new Dictionary<string, int>();

        ages.Add("Ana", 31);
        ages["Ben"] = 25;     // new key: inserted
        ages["Ben"] = 26;     // existing key: overwritten
        Console.WriteLine(ages["Ben"]);

        try
        {
            ages.Add("Ana", 40); // duplicate key
        }
        catch (ArgumentException e)
        {
            Console.WriteLine("Caught " + e.GetType().Name);
        }

        Console.WriteLine(ages.TryAdd("Chloe", 22)); // new: added
        Console.WriteLine(ages.TryAdd("Ana", 99));   // exists: not added
        Console.WriteLine(ages["Ana"]);
    }
}

Output:

26
Caught ArgumentException
True
False
31

Add throwing on a duplicate is a feature: it surfaces data that should have been unique but was not. Use the indexer when "insert or update" is what you mean, and TryAdd (.NET Core 2.0 and later) when the first value should win.

Keys cannot be null. Add(null, ...) or dict[null] throws ArgumentNullException. Values can be null when the value type allows it.

KeyNotFoundException and TryGetValue

Reading a key that is not there with the indexer throws KeyNotFoundException. This is the most common dictionary error, and the fix is almost always TryGetValue.

using System;
using System.Collections.Generic;

class Program
{
    static void Main()
    {
        var emails = new Dictionary<int, string>
        {
            [101] = "ana@example.com",
            [102] = "ben@example.com",
        };

        try
        {
            Console.WriteLine(emails[999]);
        }
        catch (KeyNotFoundException e)
        {
            Console.WriteLine("Caught " + e.GetType().Name);
        }

        if (emails.TryGetValue(101, out string email))
        {
            Console.WriteLine("Found " + email);
        }

        if (!emails.TryGetValue(999, out string none))
        {
            Console.WriteLine("Missing, value is null: " + (none == null));
        }

        string fallback = emails.TryGetValue(103, out var e3) ? e3 : "no email";
        Console.WriteLine(fallback);
    }
}

Output:

Caught KeyNotFoundException
Found ana@example.com
Missing, value is null: True
no email

TryGetValue does one hash lookup and reports success as a bool. The pattern if (dict.ContainsKey(k)) { var v = dict[k]; } works but looks the key up twice. When the key is missing, the out variable gets the default value of the type (null, 0, false).

On .NET Core 2.0 and later there is also GetValueOrDefault(key, fallback), which returns the fallback when the key is missing: emails.GetValueOrDefault(103, "no email").

Updating and removing entries

using System;
using System.Collections.Generic;

class Program
{
    static void Main()
    {
        var cart = new Dictionary<string, int> { ["milk"] = 1, ["eggs"] = 6 };

        cart["milk"] += 1;                     // read, add, write back
        Console.WriteLine(cart["milk"]);

        Console.WriteLine(cart.Remove("eggs")); // true: removed
        Console.WriteLine(cart.Remove("rice")); // false: was not there
        Console.WriteLine(cart.Count);

        cart.Clear();
        Console.WriteLine(cart.Count);
    }
}

Output:

2
True
False
1
0

cart["milk"] += 1 throws KeyNotFoundException if milk is not in the dictionary yet, because it reads before it writes. Remove returns false instead of throwing for a missing key, so there is no need to check ContainsKey first.

Iterating: KeyValuePair, Keys and Values

A foreach over a dictionary produces KeyValuePair<TKey, TValue> items, each with a Key and a Value.

using System;
using System.Collections.Generic;

class Program
{
    static void Main()
    {
        var scores = new Dictionary<string, int>
        {
            ["Ana"] = 88,
            ["Ben"] = 72,
            ["Chloe"] = 95,
        };

        foreach (KeyValuePair<string, int> pair in scores)
        {
            Console.WriteLine(pair.Key + ": " + pair.Value);
        }

        foreach (string name in scores.Keys)
        {
            Console.Write(name + " ");
        }
        Console.WriteLine();

        int total = 0;
        foreach (int s in scores.Values) total += s;
        Console.WriteLine("Total " + total);

        // Change values: loop over a copy of the keys.
        foreach (string name in new List<string>(scores.Keys))
        {
            scores[name] += 5;
        }
        Console.WriteLine(scores["Ben"]);
    }
}

Output:

Ana: 88
Ben: 72
Chloe: 95
Ana Ben Chloe 
Total 255
77

pair.Value is read-only, so updating values means writing through the indexer. The last loop iterates over a List<string> copy of the keys, which is always safe; iterating scores.Keys directly while overwriting existing values is allowed on .NET Core 3.0 and later but throws InvalidOperationException on .NET Framework.

Adding a new key inside a foreach over the same dictionary throws InvalidOperationException on every version. Removing during enumeration throws on .NET Framework and is allowed from .NET Core 3.0. Code that must run everywhere collects the keys to remove first, then removes them after the loop.

With C# 7 and .NET Core 2.0 or later, KeyValuePair can be deconstructed in the loop header:

foreach (var (name, score) in scores)
{
    Console.WriteLine($"{name}: {score}");
}

Counting with a dictionary

Counting occurrences is the textbook use. Read the current count with TryGetValue (a missing key gives 0), then write back.

using System;
using System.Collections.Generic;

class Program
{
    static void Main()
    {
        string text = "the cat and the dog and the bird";
        var counts = new Dictionary<string, int>();

        foreach (string word in text.Split(' '))
        {
            counts.TryGetValue(word, out int n); // n is 0 when missing
            counts[word] = n + 1;
        }

        foreach (var pair in counts)
        {
            Console.WriteLine(pair.Key + " " + pair.Value);
        }
    }
}

Output:

the 3
cat 1
and 2
dog 1
bird 1

The same shape groups items: Dictionary<string, List<Order>>, where you fetch the list with TryGetValue, create and store one if missing, then Add to it. For one-off counting and grouping, LINQ does it in one expression: words.GroupBy(w => w).ToDictionary(g => g.Key, g => g.Count()). See LINQ.

Case-insensitive keys with a comparer

String keys compare exactly by default: "Apple" and "apple" are two keys. Pass an IEqualityComparer<string> to the constructor to change that.

using System;
using System.Collections.Generic;

class Program
{
    static void Main()
    {
        var exact = new Dictionary<string, int>();
        exact["Apple"] = 1;
        Console.WriteLine(exact.ContainsKey("apple"));

        var headers = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
        headers["Content-Type"] = "text/html";
        Console.WriteLine(headers["content-type"]);
        headers["CONTENT-TYPE"] = "application/json"; // same key: overwrites
        Console.WriteLine(headers.Count);
    }
}

Output:

False
text/html
1

StringComparer.OrdinalIgnoreCase is the right choice for identifiers such as HTTP headers, file extensions and usernames. Calling .ToLower() on every key before storing it also works, but it is easy to forget in one place.

For keys of your own class, the dictionary calls the key's GetHashCode and Equals. A class that does not override them compares by reference, so two separate objects with the same fields are different keys. See HashSet for how to write that pair.

Order, sorting and SortedDictionary

A Dictionary makes no promise about enumeration order. In practice a dictionary that has only had entries added enumerates in insertion order, but after a Remove, a later Add can reuse the freed slot and appear earlier. Code should never rely on it.

When you need an order, sort at the point of use or use a sorted collection:

using System;
using System.Collections.Generic;
using System.Linq;

class Program
{
    static void Main()
    {
        var sales = new Dictionary<string, int>
        {
            ["Lima"] = 340,
            ["Oslo"] = 520,
            ["Cairo"] = 210,
        };

        foreach (var pair in sales.OrderBy(p => p.Key))
            Console.WriteLine(pair.Key + " " + pair.Value);

        Console.WriteLine("By value, highest first:");
        foreach (var pair in sales.OrderByDescending(p => p.Value))
            Console.WriteLine(pair.Key + " " + pair.Value);

        var sorted = new SortedDictionary<string, int>(sales);
        sorted["Berlin"] = 90;
        Console.WriteLine(string.Join(", ", sorted.Keys));
    }
}

Output:

Cairo 210
Lima 340
Oslo 520
By value, highest first:
Oslo 520
Lima 340
Cairo 210
Berlin, Cairo, Lima, Oslo

SortedDictionary<TKey, TValue> keeps its keys sorted at all times (it is a balanced tree), so lookups and inserts are O(log n) instead of O(1). Use it when you enumerate in key order often; sort a normal dictionary with LINQ when you only need order once. SortedList<TKey, TValue> is a third option that uses less memory but is slow to insert into when large.

Quick reference

Task	Code
Create	`new Dictionary<string, int>()`
Insert or overwrite	`d[k] = v`
Insert, throw on duplicate	`d.Add(k, v)`
Insert only if new	`d.TryAdd(k, v)`
Read, throw if missing	`d[k]`
Read safely	`d.TryGetValue(k, out var v)`
Key exists	`d.ContainsKey(k)`
Remove	`d.Remove(k)` (returns `bool`)
Size	`d.Count`
Keys, values	`d.Keys`, `d.Values`
Sorted by key	`d.OrderBy(p => p.Key)` or `SortedDictionary`
Ignore case	`new Dictionary<string, T>(StringComparer.OrdinalIgnoreCase)`

Common mistakes

Reading a missing key with d[k]. Throws KeyNotFoundException; use TryGetValue.
Calling Add for a key that may exist. Throws ArgumentException; use the indexer or TryAdd.
Adding keys inside foreach over the dictionary. Throws InvalidOperationException; collect changes and apply them after.
Relying on enumeration order. Sort, or use SortedDictionary.
Changing a key object's fields after inserting it. Its hash code changes and the entry can no longer be found.
ContainsKey then indexer. Two lookups; TryGetValue does one.

Frequently Asked Questions

What is the difference between Dictionary.Add and the indexer in C#?

dict.Add(key, value) inserts a new entry and throws ArgumentException if the key already exists. dict[key] = value inserts the entry if the key is new and overwrites the value if it exists, and never throws for a duplicate. TryAdd(key, value) inserts only when the key is new and returns false otherwise.

How does TryGetValue work in C#?

dict.TryGetValue(key, out var value) returns true and sets value when the key exists, and returns false and sets value to the default of its type when it does not. It does one lookup, where ContainsKey followed by dict[key] does two, and it never throws KeyNotFoundException.

How do I iterate over a Dictionary in C#?

foreach (KeyValuePair<string, int> pair in dict) gives each entry with pair.Key and pair.Value. To loop over only keys or only values, use dict.Keys or dict.Values. Do not add keys to the dictionary inside that loop: it throws InvalidOperationException.

Is a C# Dictionary ordered?

No order is guaranteed. A dictionary that only ever had entries added usually enumerates in insertion order, but after a Remove new entries can fill the freed slot, so the order changes. Sort when you need an order: dict.OrderBy(p => p.Key), or use SortedDictionary<TKey, TValue>, which always enumerates by key.

How do I make Dictionary keys case-insensitive?

Pass a comparer to the constructor: new Dictionary<string, int>(StringComparer.OrdinalIgnoreCase). Then "Apple" and "apple" are the same key for lookups, Add and ContainsKey. The comparer is fixed when the dictionary is created.

What is a KeyValuePair in C#?

KeyValuePair<TKey, TValue> is the struct a dictionary hands you for each entry when you enumerate it. It has read-only Key and Value properties, so you cannot change an entry through it; write dict[pair.Key] = newValue instead (after the loop, or over a copy of the keys).

Related concepts