add ca1510-1513 (#38295)

dotnet · Nov 17, 2023 · f3f1fe9 · f3f1fe9
1 parent 0243749
commit f3f1fe9
Show file tree

Hide file tree

Showing 7 changed files with 356 additions and 0 deletions.
diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1510.md b/docs/fundamentals/code-analysis/quality-rules/ca1510.md
@@ -0,0 +1,74 @@
+---
+title: "CA1510: Use ArgumentNullException throw helper"
+description: "Learn about code analysis rule CA1510: Use ArgumentNullException throw helper"
+ms.date: 11/16/2023
+f1_keywords:
+- CA1510
+helpviewer_keywords:
+- CA1510
+---
+# CA1510: Use ArgumentNullException throw helper
+
+| Property                            | Value                                          |
+|-------------------------------------|------------------------------------------------|
+| **Rule ID**                         | CA1510                                         |
+| **Title**                           | Use ArgumentNullException throw helper         |
+| **Category**                        | [Maintainability](maintainability-warnings.md) |
+| **Fix is breaking or non-breaking** | Non-Breaking                                   |
+| **Enabled by default in .NET 8**    | No                                             |
+
+## Cause
+
+Code checks whether an argument is `null` and then conditionally throws an <xref:System.ArgumentNullException>.
+
+## Rule description
+
+Argument checks have a substantial impact on code size and often dominate the code for small functions and property setters. These checks prevent inlining and cause substantial instruction-cache pollution. Throw-helper methods such as <xref:System.ArgumentNullException.ThrowIfNull%2A?displayProperty=nameWithType> are simpler and more efficient than `if` blocks that construct a new exception instance.
+
+## Example
+
+The following code snippet shows a violation of CA1510:
+
+```csharp
+void M(string arg)
+{
+    if (arg is null)
+        throw new ArgumentNullException(nameof(arg));
+}
+```
+
+The following code snippet shows the fix:
+
+```csharp
+void M(string arg)
+{
+    ArgumentNullException.ThrowIfNull(arg);
+}
+```
+
+## How to fix violations
+
+Replace the `if` block that throws the exception with a call to <xref:System.ArgumentNullException.ThrowIfNull%2A?displayProperty=nameWithType>. Or, in Visual Studio, use the lightbulb menu to fix your code automatically.
+
+## When to suppress warnings
+
+It's safe to suppress a violation of this rule if you're not concerned about the maintainability of your code. It is also fine to suppress violations that are identified to be false positives.
+
+## Suppress a warning
+
+If you just want to suppress a single violation, add preprocessor directives to your source file to disable and then re-enable the rule.
+
+```csharp
+#pragma warning disable CA1510
+// The code that's violating the rule is on this line.
+#pragma warning restore CA1510
+```
+
+To disable the rule for a file, folder, or project, set its severity to `none` in the [configuration file](../configuration-files.md).
+
+```ini
+[*.{cs,vb}]
+dotnet_diagnostic.CA1510.severity = none
+```
+
+For more information, see [How to suppress code analysis warnings](../suppress-warnings.md).
diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1511.md b/docs/fundamentals/code-analysis/quality-rules/ca1511.md
@@ -0,0 +1,74 @@
+---
+title: "CA1511: Use ArgumentException throw helper"
+description: "Learn about code analysis rule CA1511: Use ArgumentException throw helper"
+ms.date: 11/16/2023
+f1_keywords:
+- CA1511
+helpviewer_keywords:
+- CA1511
+---
+# CA1511: Use ArgumentException throw helper
+
+| Property                            | Value                                          |
+|-------------------------------------|------------------------------------------------|
+| **Rule ID**                         | CA1511                                         |
+| **Title**                           | Use ArgumentException throw helper             |
+| **Category**                        | [Maintainability](maintainability-warnings.md) |
+| **Fix is breaking or non-breaking** | Non-Breaking                                   |
+| **Enabled by default in .NET 8**    | No                                             |
+
+## Cause
+
+Code checks whether an argument is `null` or an empty string and then conditionally throws an <xref:System.ArgumentException>.
+
+## Rule description
+
+Argument checks have a substantial impact on code size and often dominate the code for small functions and property setters. These checks prevent inlining and cause substantial instruction-cache pollution. Throw-helper methods such as <xref:System.ArgumentException.ThrowIfNullOrEmpty(System.String,System.String)?displayProperty=nameWithType> are simpler and more efficient than `if` blocks that construct a new exception instance.
+
+## Example
+
+The following code snippet shows a violation of CA1511:
+
+```csharp
+void M(string arg)
+{
+    if (string.IsNullOrEmpty(arg))
+        throw new ArgumentException("", "arg");
+}
+```
+
+The following code snippet shows the fix:
+
+```csharp
+void M(string arg)
+{
+    ArgumentException.ThrowIfNullOrEmpty(arg);
+}
+```
+
+## How to fix violations
+
+Replace the `if` block that throws the exception with a call to <xref:System.ArgumentException.ThrowIfNullOrEmpty(System.String,System.String)?displayProperty=nameWithType>. Or, in Visual Studio, use the lightbulb menu to fix your code automatically.
+
+## When to suppress warnings
+
+It's safe to suppress a violation of this rule if you're not concerned about the maintainability of your code. It is also fine to suppress violations that are identified to be false positives.
+
+## Suppress a warning
+
+If you just want to suppress a single violation, add preprocessor directives to your source file to disable and then re-enable the rule.
+
+```csharp
+#pragma warning disable CA1511
+// The code that's violating the rule is on this line.
+#pragma warning restore CA1511
+```
+
+To disable the rule for a file, folder, or project, set its severity to `none` in the [configuration file](../configuration-files.md).
+
+```ini
+[*.{cs,vb}]
+dotnet_diagnostic.CA1511.severity = none
+```
+
+For more information, see [How to suppress code analysis warnings](../suppress-warnings.md).
diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1512.md b/docs/fundamentals/code-analysis/quality-rules/ca1512.md
@@ -0,0 +1,110 @@
+---
+title: "CA1512: Use ArgumentOutOfRangeException throw helper"
+description: "Learn about code analysis rule CA1512: Use ArgumentOutOfRangeException throw helper"
+ms.date: 11/16/2023
+f1_keywords:
+- CA1512
+helpviewer_keywords:
+- CA1512
+---
+# CA1512: Use ArgumentOutOfRangeException throw helper
+
+| Property                            | Value                                          |
+|-------------------------------------|------------------------------------------------|
+| **Rule ID**                         | CA1512                                         |
+| **Title**                           | Use ArgumentOutOfRangeException throw helper   |
+| **Category**                        | [Maintainability](maintainability-warnings.md) |
+| **Fix is breaking or non-breaking** | Non-Breaking                                   |
+| **Enabled by default in .NET 8**    | No                                             |
+
+## Cause
+
+Code checks whether an argument is less than or greater than a given value and then conditionally throws an <xref:System.ArgumentOutOfRangeException>.
+
+## Rule description
+
+Argument checks have a substantial impact on code size and often dominate the code for small functions and property setters. These checks prevent inlining and cause substantial instruction-cache pollution. Throw-helper methods such as <xref:System.ArgumentOutOfRangeException.ThrowIfGreaterThan%2A?displayProperty=nameWithType> are simpler and more efficient than `if` blocks that construct a new exception instance.
+
+## Example
+
+The following code snippet shows violations of CA1512:
+
+```csharp
+void M(int arg)
+{
+    if (arg is 0)
+        throw new ArgumentOutOfRangeException(nameof(arg));
+    if (arg < 0)
+        throw new ArgumentOutOfRangeException(nameof(arg));
+    if (arg <= 0)
+        throw new ArgumentOutOfRangeException(nameof(arg));
+    if (arg <= 42)
+        throw new ArgumentOutOfRangeException(nameof(arg));
+    if (arg < 42)
+        throw new ArgumentOutOfRangeException(nameof(arg));
+    if (arg > 42)
+        throw new ArgumentOutOfRangeException(nameof(arg));
+    if (arg >= 42)
+        throw new ArgumentOutOfRangeException(nameof(arg));
+    if (arg == 42)
+        throw new ArgumentOutOfRangeException(nameof(arg));
+    if (arg != 42)
+        throw new ArgumentOutOfRangeException(nameof(arg));
+}
+```
+
+The following code snippet shows the fixes:
+
+```csharp
+void M(int arg)
+{
+    ArgumentOutOfRangeException.ThrowIfZero(arg);
+    ArgumentOutOfRangeException.ThrowIfNegative(arg);
+    ArgumentOutOfRangeException.ThrowIfNegativeOrZero(arg);
+    ArgumentOutOfRangeException.ThrowIfLessThanOrEqual(arg, 42);
+    ArgumentOutOfRangeException.ThrowIfLessThan(arg, 42);
+    ArgumentOutOfRangeException.ThrowIfGreaterThan(arg, 42);
+    ArgumentOutOfRangeException.ThrowIfGreaterThanOrEqual(arg, 42);
+    ArgumentOutOfRangeException.ThrowIfEqual(arg, 42);
+    ArgumentOutOfRangeException.ThrowIfNotEqual(arg, 42);
+}
+```
+
+## How to fix violations
+
+Replace the `if` block that throws the exception with a call to one of the following throw-helper methods:
+
+- <xref:System.ArgumentOutOfRangeException.ThrowIfZero%60%601(%60%600,System.String)?displayProperty=nameWithType>
+- <xref:System.ArgumentOutOfRangeException.ThrowIfNegative%60%601(%60%600,System.String)?displayProperty=nameWithType>
+- <xref:System.ArgumentOutOfRangeException.ThrowIfNegativeOrZero%60%601(%60%600,System.String)?displayProperty=nameWithType>
+- <xref:System.ArgumentOutOfRangeException.ThrowIfLessThanOrEqual%60%601(%60%600,%60%600,System.String)?displayProperty=nameWithType>
+- <xref:System.ArgumentOutOfRangeException.ThrowIfLessThan%60%601(%60%600,%60%600,System.String)?displayProperty=nameWithType>
+- <xref:System.ArgumentOutOfRangeException.ThrowIfGreaterThanOrEqual%60%601(%60%600,%60%600,System.String)?displayProperty=nameWithType>
+- <xref:System.ArgumentOutOfRangeException.ThrowIfGreaterThan%60%601(%60%600,%60%600,System.String)?displayProperty=nameWithType>
+- <xref:System.ArgumentOutOfRangeException.ThrowIfEqual%60%601(%60%600,%60%600,System.String)?displayProperty=nameWithType>
+- <xref:System.ArgumentOutOfRangeException.ThrowIfNotEqual%60%601(%60%600,%60%600,System.String)?displayProperty=nameWithType>
+
+Or, in Visual Studio, use the lightbulb menu to fix your code automatically.
+
+## When to suppress warnings
+
+It's safe to suppress a violation of this rule if you're not concerned about the maintainability of your code. It is also fine to suppress violations that are identified to be false positives.
+
+## Suppress a warning
+
+If you just want to suppress a single violation, add preprocessor directives to your source file to disable and then re-enable the rule.
+
+```csharp
+#pragma warning disable CA1512
+// The code that's violating the rule is on this line.
+#pragma warning restore CA1512
+```
+
+To disable the rule for a file, folder, or project, set its severity to `none` in the [configuration file](../configuration-files.md).
+
+```ini
+[*.{cs,vb}]
+dotnet_diagnostic.CA1512.severity = none
+```
+
+For more information, see [How to suppress code analysis warnings](../suppress-warnings.md).
diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1513.md b/docs/fundamentals/code-analysis/quality-rules/ca1513.md
@@ -0,0 +1,82 @@
+---
+title: "CA1513: Use ObjectDisposedException throw helper"
+description: "Learn about code analysis rule CA1513: Use ObjectDisposedException throw helper"
+ms.date: 11/16/2023
+f1_keywords:
+- CA1513
+helpviewer_keywords:
+- CA1513
+---
+# CA1513: Use ObjectDisposedException throw helper
+
+| Property                            | Value                                          |
+|-------------------------------------|------------------------------------------------|
+| **Rule ID**                         | CA1513                                         |
+| **Title**                           | Use ObjectDisposedException throw helper       |
+| **Category**                        | [Maintainability](maintainability-warnings.md) |
+| **Fix is breaking or non-breaking** | Non-Breaking                                   |
+| **Enabled by default in .NET 8**    | No                                             |
+
+## Cause
+
+Code checks if an object is disposed and then conditionally throws an <xref:System.ObjectDisposedException>.
+
+## Rule description
+
+Object checks have a substantial impact on code size and often dominate the code for small functions and property setters. These checks prevent inlining and cause substantial instruction-cache pollution. Throw-helper methods such as <xref:System.ObjectDisposedException.ThrowIf%2A> are simpler and more efficient than `if` blocks that construct a new exception instance.
+
+## Example
+
+The following code snippet shows a violation of CA1513:
+
+```csharp
+class C
+{
+    private bool _disposed = false;
+    void M()
+    {
+        if (_disposed)
+            throw new ObjectDisposedException(GetType().Name);
+    }
+}
+```
+
+The following code snippet shows the fix:
+
+```csharp
+class C
+{
+    private bool _disposed = false;
+    void M()
+    {
+        ObjectDisposedException.ThrowIf(_disposed, GetType().Name);
+    }
+}
+```
+
+## How to fix violations
+
+Replace the `if` block that throws the exception with a call to <xref:System.ObjectDisposedException.ThrowIf%2A>. Or, in Visual Studio, use the lightbulb menu to fix your code automatically.
+
+## When to suppress warnings
+
+It's safe to suppress a violation of this rule if you're not concerned about the maintainability of your code. It is also fine to suppress violations that are identified to be false positives.
+
+## Suppress a warning
+
+If you just want to suppress a single violation, add preprocessor directives to your source file to disable and then re-enable the rule.
+
+```csharp
+#pragma warning disable CA1513
+// The code that's violating the rule is on this line.
+#pragma warning restore CA1513
+```
+
+To disable the rule for a file, folder, or project, set its severity to `none` in the [configuration file](../configuration-files.md).
+
+```ini
+[*.{cs,vb}]
+dotnet_diagnostic.CA1513.severity = none
+```
+
+For more information, see [How to suppress code analysis warnings](../suppress-warnings.md).
diff --git a/docs/fundamentals/code-analysis/quality-rules/index.md b/docs/fundamentals/code-analysis/quality-rules/index.md
@@ -89,6 +89,10 @@ The following table lists code quality analysis rules.
 > | [CA1507: Use nameof in place of string](ca1507.md) | A string literal is used as an argument where a `nameof` expression could be used. |
 > | [CA1508: Avoid dead conditional code](ca1508.md) | A method has conditional code that always evaluates to `true` or `false` at run time. This leads to dead code in the `false` branch of the condition. |
 > | [CA1509: Invalid entry in code metrics configuration file](ca1509.md) | Code metrics rules, such as [CA1501](ca1501.md), [CA1502](ca1502.md), [CA1505](ca1505.md) and [CA1506](ca1506.md), supplied a configuration file named `CodeMetricsConfig.txt` that has an invalid entry. |
+> | [CA1510: Use ArgumentNullException throw helper](ca1510.md) | Throw helpers are simpler and more efficient than `if` blocks that construct a new exception instance. |
+> | [CA1511: Use ArgumentException throw helper](ca1511.md) | Throw helpers are simpler and more efficient than `if` blocks that construct a new exception instance. |
+> | [CA1512: Use ArgumentOutOfRangeException throw helper](ca1512.md) | Throw helpers are simpler and more efficient than `if` blocks that construct a new exception instance. |
+> | [CA1513: Use ObjectDisposedException throw helper](ca1513.md) | Throw helpers are simpler and more efficient than `if` blocks that construct a new exception instance. |
 > | [CA1514: Avoid redundant length argument](ca1514.md) | A redundant length argument is used when slicing to the end of a string or buffer. A calculated length can be error-prone and is also unnecessary. |
 > | [CA1700: Do not name enum values 'Reserved'](ca1700.md) | This rule assumes that an enumeration member that has a name that contains "reserved" is not currently used but is a placeholder to be renamed or removed in a future version. Renaming or removing a member is a breaking change. |
 > | [CA1707: Identifiers should not contain underscores](ca1707.md) | By convention, identifier names do not contain the underscore (_) character. This rule checks namespaces, types, members, and parameters. |

diff --git a/docs/fundamentals/code-analysis/quality-rules/maintainability-warnings.md b/docs/fundamentals/code-analysis/quality-rules/maintainability-warnings.md
@@ -26,6 +26,10 @@ Maintainability rules support library and application maintenance.
 | [CA1507: Use nameof in place of string](ca1507.md) | A string literal is used as an argument where a `nameof` expression could be used. |
 | [CA1508: Avoid dead conditional code](ca1508.md) | A method has conditional code that always evaluates to `true` or `false` at run time. This leads to dead code in the `false` branch of the condition. |
 | [CA1509: Invalid entry in code metrics configuration file](ca1509.md) | Code metrics rules, such as [CA1501](ca1501.md), [CA1502](ca1502.md), [CA1505](ca1505.md) and [CA1506](ca1506.md), supplied a configuration file named `CodeMetricsConfig.txt` that has an invalid entry. |
+| [CA1510: Use ArgumentNullException throw helper](ca1510.md) | Throw helpers are simpler and more efficient than `if` blocks that construct a new exception instance. |
+| [CA1511: Use ArgumentException throw helper](ca1511.md) | Throw helpers are simpler and more efficient than `if` blocks that construct a new exception instance. |
+| [CA1512: Use ArgumentOutOfRangeException throw helper](ca1512.md) | Throw helpers are simpler and more efficient than `if` blocks that construct a new exception instance. |
+| [CA1513: Use ObjectDisposedException throw helper](ca1513.md) | Throw helpers are simpler and more efficient than `if` blocks that construct a new exception instance. |
 | [CA1514: Avoid redundant length argument](ca1514.md) | A redundant length argument is used when slicing to the end of a string or buffer. A calculated length can be error-prone and is also unnecessary. |
 
 ## See also

diff --git a/docs/navigate/tools-diagnostics/toc.yml b/docs/navigate/tools-diagnostics/toc.yml
@@ -858,6 +858,14 @@ items:
                     href: ../../fundamentals/code-analysis/quality-rules/ca1508.md
                   - name: CA1509
                     href: ../../fundamentals/code-analysis/quality-rules/ca1509.md
+                  - name: CA1510
+                    href: ../../fundamentals/code-analysis/quality-rules/ca1510.md
+                  - name: CA1511
+                    href: ../../fundamentals/code-analysis/quality-rules/ca1511.md
+                  - name: CA1512
+                    href: ../../fundamentals/code-analysis/quality-rules/ca1512.md
+                  - name: CA1513
+                    href: ../../fundamentals/code-analysis/quality-rules/ca1513.md
                   - name: CA1514
                     href: ../../fundamentals/code-analysis/quality-rules/ca1514.md
               - name: Naming rules