Как Dictionary в C# сигнализирует, что ключ уже существует?

Класс Dictionary<TKey, TValue> предоставляет несколько способов реакции на попытку добавления дубликата ключа. Выбор зависит от используемого метода.

1. Метод Add — строгая проверка

При вызове dict.Add(key, value) с ключом, который уже присутствует в словаре, будет выброшено исключение ArgumentException с сообщением: "An item with the same key has already been added."

var dictionary = new Dictionary<string, int>();
dictionary.Add("apple", 10);

try
{
    dictionary.Add("apple", 20); // Вызовет исключение!
}
catch (ArgumentException ex)
{
    Console.WriteLine(ex.Message); // "An item with the same key has already been added."
}

2. Индексатор dict[key] — перезапись

Использование индексатора для присваивания значения не вызывает исключения. Если ключ существует, его значение будет перезаписано. Если ключа нет — пара будет добавлена.

dictionary["banana"] = 5; // Добавляет "banana"
dictionary["banana"] = 7; // Перезаписывает значение на 7

3. Метод TryAdd (начиная с .NET Core 2.0 / .NET 5+) — безопасная попытка

Этот метод возвращает bool, указывая на успешность добавления (true — добавлен, false — ключ уже существует). Исключение не генерируется.

bool isAdded1 = dictionary.TryAdd("orange", 30); // Возвращает true
bool isAdded2 = dictionary.TryAdd("orange", 40); // Возвращает false, значение не изменилось

4. Проверка перед добавлением

Часто используется идиома с проверкой через свойство ContainsKey.

if (!dictionary.ContainsKey("apple"))
{
    dictionary.Add("apple", 50);
}
// Или короче с индексатором:
if (!dictionary.ContainsKey("apple")) dictionary["apple"] = 50;

Рекомендация: Для безопасности и ясности кода используйте TryAdd в новых проектах. Метод Add подходит, когда дублирование ключа считается критической ошибкой в логике программы.