Java Map equivalent in C#

csharp

key-value-pair

custom-key-types

dictionary-integrity

byAlex Kataev·Feb 26, 2025

The C# equivalent of a Java Map<K, V> would be the Dictionary<TKey, TValue>. Take a look at this short example below:

var dictionary = new Dictionary<int, string> { { 1, "one" }, { 2, "two" } };
string value = dictionary[2]; // Returns "two", not an actual tutu.

The Dictionary<TKey, TValue> class in C# is your best bet for efficient key-value mapping, much similar to how your buddy Java's HashMap rolls.

Safe value retrieval

No keys? No problem! Use TryGetValue to attempt fetching a value for a given key. No exceptions thrown if the key's playing hide and seek:

if (dictionary.TryGetValue(2, out string result))
{
    Console.WriteLine(result); // Prints "two", because two > one, right?
}

This feature means no more ducking behind try-catch blocks or pre-checking for your sought-after keys.

The beauty of custom key types

C# isn't picky about the types you use as keys, letting you roll out your own custom key types. Just make sure they:

Are remodeled statues (aka immutable); tampering with keys after they're part of the dictionary can lead to shady business.
Go well with the IEquatable<T> interface, Equals(object) method, and GetHashCode(), ensuring your key comparisons are as exact as your coffee order.

Here's a custom key type sample:

public class CustomKey : IEquatable<CustomKey>
{
    public readonly int Id;
    public readonly string Name;

    public CustomKey(int id, string name)
    {
        Id = id;
        Name = name;
    }
    
    public bool Equals(CustomKey other)
    {
        return other != null && Id == other.Id && Name == other.Name;
    }
    
    public override int GetHashCode()
    {
        return HashCode.Combine(Id, Name);
    }
}

Bring on the power of personalized uniqueness and equality with these custom key types.

Ease of adding and retrieving elements

Who says you need magic to conjure elements? Not here, thanks to the Add method:

dictionary.Add(3, "three");

Accessing elements is also a snap:

string three = dictionary[3]; // Serves "three" on a platter, just don't ask for a "third".

Note that direct access could result in a KeyNotFoundException. It's like opening a door that doesn't exist. Eek! Our old pal TryGetValue proves safer in such situations.

Key immutability and dictionary integrity

Key change post-insertion is a big NO-NO. It's a fast-track ticket to dictionary turmoil for these reasons:

Dictionaries rely on the key's hash code for storing pairs. It's like their version of a home address.
If this "address" changes (ahem, mutable keys!), dictionaries might get lost trying to find the key-value pair. Such misadventures can corrupt the dictionary.
Keep keys immutable or ensure their mutable parts don't meddle with the hash code. Remember: Happy keys, happy dictionary.

Handling non-existent keys

TryGetValue also shines when you've got keys that might not map to a value. It prevents unpleasant surprises by gently declining to retrieve non-existent keys, instead of imploding with a KeyNotFoundException.

Here's a common use case:

if (dictionary.TryGetValue(searchKey, out var value))
{
    // Key exists, and 'value' wraps up your treasure.
}
else
{
    // Key's AWOL, and 'value' is a consolation prize: the type's default.
}