Fix ImmutableDictionary ArgumentException docs: clarify duplicate-key-same-value is a no-op

[Copilot]

ImmutableDictionary uses KeyCollisionBehavior.ThrowIfValueDifferent, meaning adding a duplicate key with an equal value is silently ignored — but the existing ArgumentException docs implied an exception is thrown for any duplicate key.

Changes

• **ImmutableDictionary2.xml** — Fixed IDictionary<TKey,TValue>.Addexplicit interface impl:"same key already exists"→"same key but a different value already exists"`
• **ImmutableDictionary2+Builder.xml** — Same fix for Builder.Add`
• ImmutableDictionary.xml — Added missing ArgumentException docs to all 8 ToImmutableDictionary enumerable-source overloads (key/value selector variants included); the Builder-based overload is excluded since a builder can't hold duplicate keys

The public ImmutableDictionary<TKey,TValue>.Add already had the correct wording ("but has a different value") and was left unchanged.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>ImmutableDictionary.Add ArgumentException doc should clarify duplicate-key-with-same-value behavior</issue_title>
<issue_description>### Description

The XML doc for ImmutableDictionary<TKey, TValue>.Add, ImmutableDictionary<TKey, TValue>.Builder.Add, and ToImmutableDictionary states:

<exception cref="T:System.ArgumentException">An element with the same key already exists in the dictionary.</exception>

This implies the exception is thrown whenever a duplicate key is added, regardless of value. However, the actual behavior (by design) is that the exception is only thrown when the key exists with a different value. Adding a duplicate key with an equal value is silently treated as a no-op.

This was confirmed by inspecting the source code: the implementation uses KeyCollisionBehavior.ThrowIfValueDifferent (not ThrowAlways). See dotnet/runtime#125652 for the full analysis.

Affected APIs

• ImmutableDictionary<TKey,TValue>.Add(TKey, TValue)
• ImmutableDictionary<TKey,TValue>.Builder.Add(TKey, TValue)
• ImmutableDictionary.ToImmutableDictionary extension methods

Suggested fix

Update the ArgumentException doc to something like:

An element with the same key but a different value already exists in the dictionary.

Or add a Remarks note clarifying that adding a key-value pair where both the key and value match an existing entry is treated as a no-op and does not throw.</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes ImmutableDictionary.Add ArgumentException doc should clarify duplicate-key-with-same-value behavior #12411

---

📱 Kick off Copilot coding agent tasks wherever you are with GitHub Mobile, available on iOS and Android.

[dotnet-policy-service]

Tagging subscribers to this area: @dotnet/area-system-collections

[Copilot]

Pull request overview

This PR updates the API reference XML docs for System.Collections.Immutable.ImmutableDictionary to accurately describe when an ArgumentException is thrown on duplicate keys, aligning the documentation with the implemented “throw only if the existing value differs” behavior.

Changes:

• Updated ArgumentException text for IDictionary<TKey,TValue>.Add (explicit impl) and ImmutableDictionary<TKey,TValue>.Builder.Add to clarify it throws only when the existing value is different.
• Added missing ArgumentException documentation to the enumerable-source ToImmutableDictionary overloads to match the same “different value” collision behavior.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
xml/System.Collections.Immutable/ImmutableDictionary`2+Builder.xml	Clarifies duplicate-key exception wording for Builder.Add.
xml/System.Collections.Immutable/ImmutableDictionary`2.xml	Clarifies duplicate-key exception wording for the explicit IDictionary<TKey,TValue>.Add implementation.
xml/System.Collections.Immutable/ImmutableDictionary.xml	Adds consistent ArgumentException docs to enumerable-source ToImmutableDictionary overloads.

---

You can also share your feedback on Copilot code review. Take the survey.