From dfa3a78ae877c4ff362bf9fdee344faf4cf7c9a5 Mon Sep 17 00:00:00 2001 From: Copilot <198982749+Copilot@users.noreply.github.com> Date: Fri, 20 Mar 2026 18:41:24 +0000 Subject: [PATCH] Add security guidance for user-specified capacity in collections (#12415) --- xml/System.Collections.Generic/Dictionary`2.xml | 17 +++++++++++++++-- xml/System.Collections.Generic/HashSet`1.xml | 17 ++++++++++++++++- xml/System.Collections.Generic/List`1.xml | 14 +++++++++++++- xml/System.Collections.Generic/Queue`1.xml | 14 +++++++++++++- xml/System.Collections/ArrayList.xml | 3 +++ 5 files changed, 60 insertions(+), 5 deletions(-) diff --git a/xml/System.Collections.Generic/Dictionary`2.xml b/xml/System.Collections.Generic/Dictionary`2.xml index 92079ccc4c8..47e46d41bfc 100644 --- a/xml/System.Collections.Generic/Dictionary`2.xml +++ b/xml/System.Collections.Generic/Dictionary`2.xml @@ -458,6 +458,9 @@ +> [!CAUTION] +> If `capacity` comes from user input, prefer using a constructor without a capacity parameter and letting the collection resize as elements are added. If you must use a user-specified value, either clamp it to a reasonable limit (for example, `Math.Clamp(untrustedValue, 0, 20)`) or verify that the element count matches the specified value. + ## Examples The following code example creates a with a case-insensitive equality comparer for the current culture. The example adds four elements, some with lower-case keys and some with upper-case keys. The example then attempts to add an element with a key that differs from an existing key only by case, catches the resulting exception, and displays an error message. Finally, the example displays the elements in the dictionary. @@ -526,7 +529,8 @@ This constructor is an O(1) operation. - +> [!CAUTION] +> If `capacity` comes from user input, prefer using a constructor without a capacity parameter and letting the collection resize as elements are added. If you must use a user-specified value, either clamp it to a reasonable limit (for example, `Math.Clamp(untrustedValue, 0, 20)`) or verify that the element count matches the specified value. ## Examples The following code example creates a dictionary with an initial capacity of 4 and populates it with 4 entries. @@ -1292,7 +1296,16 @@ The number of entries. Ensures that the dictionary can hold up to a specified number of entries without any further expansion of its backing storage. The current capacity of the . - To be added. + + [!CAUTION] +> If `capacity` comes from user input, prefer letting the collection resize itself as elements are added instead of calling this method. If you must use a user-specified value, either clamp it to a reasonable limit (for example, `Math.Clamp(untrustedValue, 0, 20)`) or verify that the element count matches the specified value. + + ]]> + is less than 0. diff --git a/xml/System.Collections.Generic/HashSet`1.xml b/xml/System.Collections.Generic/HashSet`1.xml index f5f89aba673..34064c69e9c 100644 --- a/xml/System.Collections.Generic/HashSet`1.xml +++ b/xml/System.Collections.Generic/HashSet`1.xml @@ -376,6 +376,9 @@ The following example demonstrates how to merge two disparate sets. This example ## Remarks Since resizes are relatively expensive (require rehashing), this attempts to minimize the need to resize by setting the initial capacity based on the value of the `capacity`. +> [!CAUTION] +> If `capacity` comes from user input, prefer using a constructor overload without a `capacity` parameter, and let the collection resize as elements are added. If you must use a user-specified value, either clamp it to a reasonable limit (for example, `Math.Clamp(untrustedValue, 0, 20)`), or verify that the element count matches the specified value. + ]]> @@ -506,6 +509,9 @@ The following example demonstrates how to merge two disparate sets. This example ## Remarks Since resizes are relatively expensive (require rehashing), this attempts to minimize the need to resize by setting the initial capacity based on the value of the `capacity`. +> [!CAUTION] +> If `capacity` comes from user input, prefer using a constructor overload without a `capacity` parameter, and let the collection resize as elements are added. If you must use a user-specified value, either clamp it to a reasonable limit (for example, `Math.Clamp(untrustedValue, 0, 20)`), or verify that the element count matches the specified value. + ]]> @@ -1230,7 +1236,16 @@ The following example demonstrates how to merge two disparate sets. This example The minimum capacity to ensure. Ensures that this hash set can hold the specified number of elements without any further expansion of its backing storage. The new capacity of this instance. - To be added. + + [!CAUTION] +> If `capacity` comes from user input, prefer letting the collection resize itself as elements are added instead of calling this method. If you must use a user-specified value, either clamp it to a reasonable limit (for example, `Math.Clamp(untrustedValue, 0, 20)`) or verify that the element count matches the specified value. + + ]]> + is less than zero. diff --git a/xml/System.Collections.Generic/List`1.xml b/xml/System.Collections.Generic/List`1.xml index b8f07b41918..8a1dee2ca71 100644 --- a/xml/System.Collections.Generic/List`1.xml +++ b/xml/System.Collections.Generic/List`1.xml @@ -320,6 +320,9 @@ This constructor is an O(1) operation. +> [!CAUTION] +> If `capacity` comes from user input, prefer using the parameterless constructor and letting the collection resize as elements are added. If you must use a user-specified value, either clamp it to a reasonable limit (for example, `Math.Clamp(untrustedValue, 0, 20)`) or verify that the element count matches the specified value. + ## Examples The following example demonstrates the constructor. A of strings with a capacity of 4 is created, because the ultimate size of the list is known to be exactly 4. The list is populated with four strings, and a read-only copy is created by using the method. @@ -1476,7 +1479,16 @@ The minimum capacity to ensure. Ensures that the capacity of this list is at least the specified . If the current capacity is less than , it is increased to at least the specified . The new capacity of this list. - To be added. + + [!CAUTION] +> If `capacity` comes from user input, prefer letting the collection resize itself as elements are added instead of calling this method. If you must use a user-specified value, either clamp it to a reasonable limit (for example, `Math.Clamp(untrustedValue, 0, 20)`) or verify that the element count matches the specified value. + + ]]> + diff --git a/xml/System.Collections.Generic/Queue`1.xml b/xml/System.Collections.Generic/Queue`1.xml index 5793bea03ed..adddf34e1dc 100644 --- a/xml/System.Collections.Generic/Queue`1.xml +++ b/xml/System.Collections.Generic/Queue`1.xml @@ -335,6 +335,9 @@ This constructor is an O(`n`) operation, where `n` is `capacity`. +> [!CAUTION] +> If `capacity` comes from user input, prefer using the parameterless constructor and letting the collection resize as elements are added. If you must use a user-specified value, either clamp it to a reasonable limit (for example, `Math.Clamp(untrustedValue, 0, 20)`) or verify that the element count matches the specified value. + ]]> @@ -842,7 +845,16 @@ The minimum capacity to ensure. Ensures that the capacity of this queue is at least the specified . If the current capacity is less than , it is increased to at least the specified . The new capacity of this queue. - To be added. + + [!CAUTION] +> If `capacity` comes from user input, prefer letting the collection resize itself as elements are added instead of calling this method. If you must use a user-specified value, either clamp it to a reasonable limit (for example, `Math.Clamp(untrustedValue, 0, 20)`) or verify that the element count matches the specified value. + + ]]> + diff --git a/xml/System.Collections/ArrayList.xml b/xml/System.Collections/ArrayList.xml index 72057f97854..00351d7bbb2 100644 --- a/xml/System.Collections/ArrayList.xml +++ b/xml/System.Collections/ArrayList.xml @@ -354,6 +354,9 @@ This constructor is an `O(n)` operation, where `n` is `capacity`. +> [!CAUTION] +> If `capacity` comes from user input, prefer using the parameterless constructor and letting the collection resize as elements are added. If you must use a user-specified value, either clamp it to a reasonable limit (for example, `Math.Clamp(untrustedValue, 0, 20)`) or verify that the element count matches the specified value. + ]]>