Add security guidance for user-specified capacity in collections (#12415)

Author: Copilot

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 <xref:System.Collections.Generic.Dictionary%602> 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 @@
         <param name="capacity">The number of entries.</param>
         <summary>Ensures that the dictionary can hold up to a specified number of entries without any further expansion of its backing storage.</summary>
         <returns>The current capacity of the <see cref="T:System.Collections.Generic.Dictionary`2" />.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+> [!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.
+
+ ]]></format>
+        </remarks>
         <exception cref="T:System.ArgumentOutOfRangeException">
           <paramref name="capacity" /> is less than 0.</exception>
       </Docs>

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.
+
  ]]></format>
         </remarks>
       </Docs>
@@ -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.
+
  ]]></format>
         </remarks>
       </Docs>
@@ -1230,7 +1236,16 @@ The following example demonstrates how to merge two disparate sets. This example
         <param name="capacity">The minimum capacity to ensure.</param>
         <summary>Ensures that this hash set can hold the specified number of elements without any further expansion of its backing storage.</summary>
         <returns>The new capacity of this instance.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+> [!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.
+
+ ]]></format>
+        </remarks>
         <exception cref="T:System.ArgumentOutOfRangeException">
           <paramref name="capacity" /> is less than zero.</exception>
       </Docs>

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 <xref:System.Collections.Generic.List%601.%23ctor%28System.Int32%29> constructor. A <xref:System.Collections.Generic.List%601> 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 <xref:System.Collections.Generic.List%601.AsReadOnly%2A> method.
 
@@ -1476,7 +1479,16 @@
         <param name="capacity">The minimum capacity to ensure.</param>
         <summary>Ensures that the capacity of this list is at least the specified <paramref name="capacity" />. If the current capacity is less than <paramref name="capacity" />, it is increased to at least the specified <paramref name="capacity" />.</summary>
         <returns>The new capacity of this list.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+> [!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.
+
+ ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="Exists">

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.
+
  ]]></format>
         </remarks>
         <exception cref="T:System.ArgumentOutOfRangeException">
@@ -842,7 +845,16 @@
         <param name="capacity">The minimum capacity to ensure.</param>
         <summary>Ensures that the capacity of this queue is at least the specified <paramref name="capacity" />. If the current capacity is less than <paramref name="capacity" />, it is increased to at least the specified <paramref name="capacity" />.</summary>
         <returns>The new capacity of this queue.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+> [!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.
+
+ ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="GetEnumerator">

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.
+
  ]]></format>
         </remarks>
         <exception cref="T:System.ArgumentOutOfRangeException">