Add security guidance for user-specified capacity in collections

[Copilot]

Passing untrusted user input directly as capacity to collection constructors or EnsureCapacity can enable denial-of-service via excessive memory allocation. Adds [!CAUTION] remarks to the affected APIs recommending safer patterns.

Affected APIs

Constructors (int capacity overload):

• List<T>, Dictionary<TKey,TValue>, HashSet<T>, Queue<T>, ArrayList

EnsureCapacity(int capacity) methods:

• List<T>, Dictionary<TKey,TValue>, HashSet<T>, Queue<T>

Guidance added

Each caution note recommends:

1. Prefer the parameterless constructor — let the collection resize naturally as elements are added.
2. If a user-supplied value must be used, clamp it to a safe ceiling:

   new List<T>(Math.Clamp(untrustedValue, 0, 20))

3. Alternatively, verify that the actual element count matches the claimed capacity before passing it.

EnsureCapacity methods that previously had To be added. remarks now include a full ## Remarks section with the caution.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Handling user specified capacity in collections</issue_title>
<issue_description>### Describe the issue or suggestion

The documentation for collections accepting a capacity value should contain some remarks about user specified values.

If the capacity is user specified, prefer to let the collection to resize itself when adding elements instead of specifying a capacity in the constructor or EnsureCapacity. If this is not possible, then it is good practice to validate the value before passing it to the constructor or EnsureCapacity. Two options are:

• Clamp the capacity to a small safe value and allow the list to dynamically grow as items are added. For example, use Math.Clamp(untrustedValue, 0, 20) to limit the initial creation to no more than 20 entries. The list will naturally expand if more than 20 entries are added.
• Verify that the number of list elements really does match the claimed capacity. Use caution not to introduce vulnerable backtracking logic when doing so.

The collections that have an EnsureCapacity:

• List<T>
• Dictionary<TKey, TValue>
• HashSet<T>
• Queue<T>
• ArrayList

---

Associated WorkItem - 558455</issue_description>

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

• Fixes Handling user specified capacity in collections #12272

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[dotnet-policy-service]

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

[gewarren]

@copilot Please only use a single space after the > character in a note block.

[Copilot]

Fixed in dbbe727 — all 9 CAUTION content lines now use a single space after >.

[Copilot]

Pull request overview

Adds security-focused documentation guidance warning against passing untrusted user input as capacity to collection constructors or EnsureCapacity, helping reduce potential denial-of-service risks from excessive allocation.

Changes:

• Add [!CAUTION] callouts to capacity-accepting constructors for several collections.
• Replace placeholder To be added. remarks on EnsureCapacity(int) with a full markdown remarks section including the caution guidance.
• Keep the guidance consistent across affected APIs (prefer natural growth, clamp, or validate claimed size).

Reviewed changes

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

Show a summary per file

File	Description
xml/System.Collections/ArrayList.xml	Adds CAUTION guidance to the ArrayList(int capacity) constructor remarks.
xml/System.Collections.Generic/Queue`1.xml	Adds CAUTION guidance to Queue(int capacity) and documents EnsureCapacity(int) remarks.
xml/System.Collections.Generic/List`1.xml	Adds CAUTION guidance to List(int capacity) and documents EnsureCapacity(int) remarks.
xml/System.Collections.Generic/HashSet`1.xml	Adds CAUTION guidance to HashSet(int capacity) and documents EnsureCapacity(int) remarks.
xml/System.Collections.Generic/Dictionary`2.xml	Adds CAUTION guidance to Dictionary(int capacity) and documents EnsureCapacity(int) remarks.

---

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