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

[Copilot]

Update CA2208 documentation to clarify paramName requirement

• Review existing CA2208 documentation and code examples
• Understand the issue: CA2208 requires paramName to match actual method parameters
• Update documentation to explain the paramName matching requirement
  • Added fourth bullet point in "Cause" section about paramName requirement
  • Added IMPORTANT callout in "Rule description" explaining the requirement
• Add example showing violation when using non-parameter variable names
  • Added snippet3 showing incorrect usage with local variable
  • Added snippet4 showing correct fix using InvalidOperationException
• Add guidance on when to use ArgumentNullException vs other exceptions
  • Explained to use InvalidOperationException for invalid object state
• Build and validate code snippets to ensure they compile
  • Both C# and VB snippets compile without errors
• Review changes to ensure they follow writing style guidelines
  • Markdown linting passes with no errors
  • Updated ms.date to current date
• Address reviewer feedback
  • Replaced Foo/Bar with Product/Description in code examples

Original prompt

---

This section details on the original issue you should resolve

<issue_title>CA2208 - Undocumented check: ArgumentNullException paramName argument should match an actual method parameter</issue_title>
<issue_description>### Type of issue

Missing information

Description

The following compiler warning is not reflected in the documentation.

warning CA2208: Method Foo passes 'bar' as the paramName argument to a ArgumentNullException constructor. Replace this argument with one of the method's parameter names. Note that the provided parameter name should have the exact casing as declared on the method. (https://learn.microsoft.com/dotnet/fundamentals/code-analysis/quality-rules/ca2208)

Example:

public void DoFoo(Foo foo) {
    Bar? bar = foo.Bar;
    if (bar is null) throw new ArgumentNullException(nameof(bar), $"Foo named {foo.Name} had no Bar!"); // CA2208
}

The documentation says a lot about not mixing up the parameter name with the message, but doesn't say anything about the parameter name needing to match a method parameter.

Attempting to use NullReferenceException results in CA2201. I'm left wondering what to do if I want to raise an exception when some non-parameter variable is null.

Page URL

https://learn.microsoft.com/en-us/dotnet/fundamentals/code-analysis/quality-rules/ca2208

Content source URL

https://github.com/dotnet/docs/blob/main/docs/fundamentals/code-analysis/quality-rules/ca2208.md

Document Version Independent Id

cc2b5015-89a9-02ff-a585-fca3449dfa9a

Platform Id

09de10c1-92b4-8a2d-2ff4-db0e71226d62

Article author

@gewarren

Metadata

• ID: ff82be90-2d17-5880-4edd-a89b18a3ae2b
• PlatformId: 09de10c1-92b4-8a2d-2ff4-db0e71226d62
• Service: dotnet-fundamentals

Related Issues</issue_description>

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

@gewarren In your example, `foo.Bar` is not an "argument", so throwing `ArgumentNullException` doesn't seem like the right exception to throw. If you must throw an exception, perhaps something like `ApplicationException` is more appropriate.

• Fixes CA2208 - Undocumented check: ArgumentNullException paramName argument should match an actual method parameter #49421

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

---

Internal previews

📄 File	🔗 Preview link
docs/fundamentals/code-analysis/quality-rules/ca2208.md	CA2208: Instantiate argument exceptions correctly

[gewarren]

@copilot please don't use the names "Foo" and "Bar" for the type and property.

[Copilot]

@copilot please don't use the names "Foo" and "Bar" for the type and property.

Updated the examples to use Product/Description instead of Foo/Bar in commit a2a7f57.

[Copilot]

Pull Request Overview

This PR updates the CA2208 documentation to clarify that ArgumentNullException requires the paramName argument to match an actual method parameter. The documentation previously explained common mistakes like mixing up message and parameter name arguments, but didn't explicitly state the requirement that paramName must match a method parameter. The PR also provides guidance on using InvalidOperationException when validating non-parameter variables.

Key changes:

• Clarified the paramName matching requirement in the "Cause" section.
• Added code examples demonstrating incorrect usage with local variables and the correct fix using InvalidOperationException.
• Updated the ms.date to the current date.

Reviewed Changes

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

File	Description
ca2208.md	Added documentation explaining paramName requirement, added new code examples (snippet3 and snippet4), and updated date
ca2208.cs	Added C# code examples showing violation with local variable and fix using InvalidOperationException
ca2208-instantiate-argument-exceptions-correctly_1.vb	Added VB code examples showing violation with local variable and fix using InvalidOperationException

[BillWagner]

This LGTM @gewarren

Let's