Document CA2208 paramName requirement and provide guidance for non-parameter exceptions

docs/fundamentals/code-analysis/quality-rules/ca2208.md

@@ -1,7 +1,7 @@
 ---
 title: "CA2208: Instantiate argument exceptions correctly (code analysis)"
 description: "Learn about code analysis rule CA2208: Instantiate argument exceptions correctly"
-ms.date: 05/18/2020
+ms.date: 10/24/2025
 f1_keywords:
 - CA2208
 - InstantiateArgumentExceptionsCorrectly
@@ -29,8 +29,8 @@ dev_langs:
 When a method has a parameter, and it throws an exception type that is, or derives from, <xref:System.ArgumentException>, it is expected to call a constructor accepting a `paramName` parameter correctly. Possible causes include the following situations:
 
 - A call is made to the default (parameterless) constructor of an exception type that is, or derives from, <xref:System.ArgumentException> that also has a constructor that accepts a `paramName` parameter.
-- An incorrect string argument is passed to a parameterized constructor of an exception type that is, or derives from, <xref:System.ArgumentException>.
-- One of the parameters' names is passed for the `message` argument of the constructor of exception type that is, or derives from, <xref:System.ArgumentException>.
+- An incorrect string argument is passed to a parameterized constructor of an exception type that is, or derives from, <xref:System.ArgumentException>. For example, the `paramName` argument doesn't match the name of one of the method's parameters.
+- A parameter name is passed for the `message` argument of the constructor of an exception type that is, or derives from, <xref:System.ArgumentException>.
 
 ## Rule description
 
@@ -109,6 +109,16 @@ The following code fixes the previous violation by switching the constructor arg
 
 :::code language="vb" source="snippets/vb/all-rules/ca2208-instantiate-argument-exceptions-correctly_1.vb" id="snippet2":::
 
+The following code shows a method that incorrectly throws <xref:System.ArgumentNullException> with a `paramName` that doesn't match any of the method's parameters. The rule fires because `description` is a local variable, not a method parameter.
+
+:::code language="csharp" source="snippets/csharp/all-rules/ca2208.cs" id="snippet3":::
+:::code language="vb" source="snippets/vb/all-rules/ca2208-instantiate-argument-exceptions-correctly_1.vb" id="snippet3":::
+
+The following code fixes the previous violation by using <xref:System.InvalidOperationException> instead, which is appropriate when an object's state is invalid.
+
+:::code language="csharp" source="snippets/csharp/all-rules/ca2208.cs" id="snippet4":::
+:::code language="vb" source="snippets/vb/all-rules/ca2208-instantiate-argument-exceptions-correctly_1.vb" id="snippet4":::
+
 ## Related rules
 
 - [CA1507: Use nameof in place of string](ca1507.md)

docs/fundamentals/code-analysis/quality-rules/snippets/csharp/all-rules/ca2208.cs

@@ -33,3 +33,55 @@ public Book(string title)
     }
     //</snippet2>
 }
+
+namespace ca2208_3
+{
+#pragma warning disable CA2208 // Instantiate argument exceptions correctly
+    //<snippet3>
+    public class Product
+    {
+        public string? Description { get; set; }
+        public string Name { get; set; } = string.Empty;
+    }
+
+    public class Example
+    {
+        // Violates CA2208: 'description' is not a parameter of this method.
+        public void ProcessProduct(Product product)
+        {
+            string? description = product.Description;
+            if (description is null)
+            {
+                throw new ArgumentNullException(nameof(description), $"Product named {product.Name} had no description!");
+            }
+            // Process description...
+        }
+    }
+    //</snippet3>
+#pragma warning restore CA2208 // Instantiate argument exceptions correctly
+}
+
+namespace ca2208_4
+{
+    //<snippet4>
+    public class Product
+    {
+        public string? Description { get; set; }
+        public string Name { get; set; } = string.Empty;
+    }
+
+    public class Example
+    {
+        // Fixed: Use InvalidOperationException for invalid object state.
+        public void ProcessProduct(Product product)
+        {
+            string? description = product.Description;
+            if (description is null)
+            {
+                throw new InvalidOperationException($"Product named {product.Name} had no description!");
+            }
+            // Process description...
+        }
+    }
+    //</snippet4>
+}

docs/fundamentals/code-analysis/quality-rules/snippets/vb/all-rules/ca2208-instantiate-argument-exceptions-correctly_1.vb

@@ -51,3 +51,47 @@ Namespace ca2208_2
     '</snippet2>
 
 End Namespace
+
+Namespace ca2208_3
+#Disable Warning CA2208 ' Instantiate argument exceptions correctly
+    '<snippet3>
+    Public Class Product
+        Public Property Description As String
+        Public Property Name As String = String.Empty
+    End Class
+
+    Public Class Example
+        ' Violates CA2208: 'description' is not a parameter of this method.
+        Public Sub ProcessProduct(ByVal product As Product)
+            Dim description As String = product.Description
+            If description Is Nothing Then
+                Throw New ArgumentNullException(NameOf(description), $"Product named {product.Name} had no description!")
+            End If
+            ' Process description...
+        End Sub
+    End Class
+    '</snippet3>
+#Enable Warning CA2208 ' Instantiate argument exceptions correctly
+
+End Namespace
+
+Namespace ca2208_4
+    '<snippet4>
+    Public Class Product
+        Public Property Description As String
+        Public Property Name As String = String.Empty
+    End Class
+
+    Public Class Example
+        ' Fixed: Use InvalidOperationException for invalid object state.
+        Public Sub ProcessProduct(ByVal product As Product)
+            Dim description As String = product.Description
+            If description Is Nothing Then
+                Throw New InvalidOperationException($"Product named {product.Name} had no description!")
+            End If
+            ' Process description...
+        End Sub
+    End Class
+    '</snippet4>
+
+End Namespace