Dictionary in C#

In this article, we are going to talk about the Dictionary in C#. We will learn how to create a dictionary, add, retrieve, update, and delete elements. Among that, we will see the usage of its common properties and methods.

Let’s begin.

What Is Dictionary in C#?

Dictionary<TKey,TValue> is a generic collection that stores the data in key-value pairs. It implements IDictionary<TKey,TValue> interface.

In C# we don’t have a built-in Map type. But we can use Dictionary<TKey,TValue> to map objects. It is a useful tool that allows us to map value to a key.

A dictionary cannot have null or duplicate keys, whereas it can have null and duplicate values.

Now, let’s look at its implementation.

Create a Dictionary in C#

Let’s take a look at three ways to create a dictionary.

Initializing an Empty Dictionary

Let’s start by creating an empty dictionary:

var dict1 = new Dictionary<int, string>();

We create the dict1 dictionary with an empty constructor, and it doesn’t have any data. We do it this way if we want to create an empty dictionary.

Initializing With the Number of Elements

Another way we can initialize a dictionary is by setting the number of elements: 

var dict2 = new Dictionary<int, string>(10);

We can use this implementation if we want to define the initial capacity of our dictionary. If we know the number of elements we are going to store in our dictionary, it is always great for performance to define an initial capacity.

Initializing With Data

In addition, we can also populate the dictionary with some data:

var dict3 = new Dictionary<int, string>()
{
    {1, "Red"},
    {2, "Yellow"},
    {3, "Green"},
};

We have seen how to create a dictionary.

Now, let’s dive in deeper and create a Dictionary<int, Product> that maps a Product value to a key. We will use this for the rest of our application.

That said, let’s inspect our Product class:

public class Product
{
    public int ProductId { get; set; }
    public string? ProductName { get; set; }
}

We will first create an empty productsDict dictionary:

var productsDict = new Dictionary<int, Product>();

Let’s carry on and look at how to add elements, fetch, update, and delete its elements.

Add Elements to a Dictionary in C#

We can add elements to productsDict by using the built-in Add(TKey,TValue) method:

productsDict.Add(0, new Product() { ProductId = 111, ProductName = "Table" });
productsDict.Add(1, new Product() { ProductId = 112, ProductName = "Chair" });
productsDict.Add(2, new Product() { ProductId = 113, ProductName = "TV" });

After we execute the code, productsDict now has 3 <int, Product> key-value pairs as its elements.

Remember, we said a dictionary cannot have duplicate keys. Then, what happens if we add an element with a key that already exists? Yes, it will throw an exception.

So, we should always check whether the key we are trying to add is already added.

Let’s see a demonstration of facing this exception:

try
{
    productsDict.Add(2, new Product() { ProductId = 113, ProductName = "Wardrobe" });
}
catch (ArgumentException ex)
{
    Console.WriteLine(ex.Message);
}

In our productDict dictionary, we already have a key with a value of 2. Therefore, it is not possible to add a Product as a value with the same key – we will come across an exception. 

In order to handle the exception, we wrap the Add(TKey,TValue) method with a try/catch block.

After we run our app, we can inspect the error message in the console window:

An item with the same key has already been added. Key: 2

To prevent this, without needing to use try/catch blocks, we can use the TryAdd(TKey,TValue) method:

if (productsDict.TryAdd(3, new Product() { ProductId = 114, ProductName = "Lamp" }))
{
    Console.WriteLine($"Product is added.");
}

This method attempts to add the element to the dictionary. It returns true if it can successfully add the element, or it returns false and skips the if statement without raising an exception.

When we add a new key value such as 3, the method returns true and then successfully adds the new Product to productsDict.

As a result, we see the console output:

Product is added.

Retrieve Elements From a Dictionary in C#

To retrieve elements from a dictionary in C#, we iterate through the dictionary and get them as KeyValuePair objects.

Here’s how we do it with a foreach loop:

foreach (KeyValuePair<int, Product> product in productsDict)
{
    Console.WriteLine($"Key = {product.Key}, Value = {product.Value.ProductId}, {product.Value.ProductName}");
}

We iterate through each KeyValuePair in productsDict to fetch the mapped value. As a result, we obtain Product object with its ProductId and ProductName properties:

Key = 0, Value = 111, Table
Key = 1, Value = 112, Chair
Key = 2, Value = 113, TV
Key = 3, Value = 114, Lamp

There are also other ways to iterate through a dictionary. If you want to learn about them, please check our article on Different Ways to Iterate Through a Dictionary in C#.

Thread Safety With Dictionary

There is something worthwhile to mention here. The dictionary supports multiple reads at the same time during the enumeration. However, it doesn’t give access to writing during the enumeration. This means it doesn’t allow multiple threads to operate reading and writing at the same time. Therefore, this is not a thread-safe procedure. To find out more information about thread safety, please take a look at the documentation on Thread Safety.

Retrieve an Element With a Given Key 

When we want to fetch a value of a specific key, we first need to check if the key exists in the dictionary. We can use several ways to do this.

ContainsKey(TKey) –  this method returns true or false depending on whether the key exists in the dictionary.

Also, there is another built-in method – TryGetValue(Tkey, TValue):

if (productsDict.TryGetValue(2, out Product? product1) && product1 != null)
{
    Console.WriteLine($"Key = {2} exists, Value = {product1.ProductId}, {product1.ProductName}");
}

This method safely returns the value if the given key exists without throwing an exception. It returns false if the key doesn’t exist. If the method finds a key, it sets the assigned value to the product1 variable by using the out keyword.

The console output as a result:

Key = 2 exists, Value = 113, TV

Check our article on How to Detect if a Dictionary Key Exists in C# that explains these methods in more detail. Also, we have an article on How to Get an Item by Index from Dictionary in C# that we recommend reading.

Retrieve an Element by Using an Extension Method

In addition to the previous methods, we are going to inspect one more method – GetValueOrDefault<TKey,TValue>. This is an extension method that comes with IDictionary<TKey,TValue>. As we mentioned before, Dictionary<TKey,TValue> inherits from the IDictionary<TKey,TValue> interface. Therefore, we can use the extension methods the interface provides.

GetValueOrDefault<TKey,TValue> takes the key and returns its value. In this case, we don’t need to use the out keyword. It returns the value automatically if it exists. Otherwise, it returns the default value:

var productValue = (productsDict.GetValueOrDefault(1));

if (productValue != null)
{
    Console.WriteLine($"Key = {1} exists, Value = {productValue.ProductId}, {productValue.ProductName}");
}

We take 1 as the value of the key parameter we want to fetch from the dictionary. When we execute the code, because a key with a value of 1 exists, it returns the Product value that is mapped to it. 

We can see the output in the console window:

Key = 1 exists, Value = 112, Chair

Take a notice that we perform a null check. Especially when using reference types in the dictionary, we have to watch out for the possibility of obtaining null values. If the GrtValueOrDefault method can’t find the key in the dictionary, it would return null. As a result, we would face NullReferenceException. 

So, what is so special about this method, and why would we want to use it instead of the other methods such as TryGetValue<TKey,TValue>?

Well, with this method, we can set a default value that we want to return if the key we request doesn’t exist:

Dictionary<int, string> dict3 = new Dictionary<int, string>()
{
    {1, "Red"},
    {2, "Yellow"},
    {3, "Green"},
};

var color = (dict3.GetValueOrDefault(4, "Color not found."));
Console.WriteLine(color);

We set a default value of "Color not found.". To emphasize, the type of the default value has to match TValue type we declared in the dictionary, which is a string in this case.

As the key with a value of 4 does not exist, we can see the default value as our result.

You can explore the List of Extension Methods we can use for different scenarios.

Update Dictionary in C#

Let’s carry on with our productsDict and see how to update its elements.

We can simply update the value of an element using the Item[Key]:

productsDict[0] = new Product() { ProductId = 110, ProductName = "Desk" };

With it, we can get or set the value of the element of the given key. Accordingly, the value of the key parameter 0 changes:

Key = 0, Value = 110, Desk
Key = 1, Value = 112, Chair
Key = 2, Value = 113, TV
Key = 3, Value = 114, Lamp

As a rule of thumb, we cannot retrieve, or update a value that doesn’t exist. As well as, we cannot add an element with a key that we already added. Therefore, we should also check if the key we want to update exists using the methods we discussed. 

Remove Dictionary Elements

There is another commonly used built-in method – Remove(TKey). We use this method to remove a certain existing element:

productsDict.Remove(2);

After executing the method, the element with the key parameter value of 2 is not in the productDict anymore:

Key = 0, Value = 110, Desk
Key = 1, Value = 112, Chair
Key = 3, Value = 114, Lamp

If we want to remove all the elements from a dictionary in C#, we also have a built-in Clear() method for that:

productsDict.Clear();

Let’s check if we successfully cleared the dictionary elements. In order to check this, we will use the property – Count:

var numberOfElements = productsDict.Count;

Console.WriteLine($"Number of dictionary elements: {numberOfElements}");

This property shows us the number of elements in the dictionary.

In this case, we expect the number of elements to be 0:

Number of dictionary elements: 0

Conclusion

In this article, we have learned about Dictionary in C#.

We looked at creating and adding to a dictionary and how to retrieve, update, and remove its elements. We implemented commonly used methods and properties. We also covered some edge cases and ways to deal with exceptions.