diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1510.md b/docs/fundamentals/code-analysis/quality-rules/ca1510.md new file mode 100644 index 0000000000000..1fee93f9b0279 --- /dev/null +++ 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 . + +## 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 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 . 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 new file mode 100644 index 0000000000000..aae3a33a92e13 --- /dev/null +++ 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 . + +## 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 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 . 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 new file mode 100644 index 0000000000000..6209ad25ddec6 --- /dev/null +++ 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 . + +## 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 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: + +- +- +- +- +- +- +- +- +- + +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 new file mode 100644 index 0000000000000..dd1e54db84ebb --- /dev/null +++ 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 . + +## 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 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 . 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 index a0f9e30d2b139..1c49e444a89ec 100644 --- 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 index 3fdd2c11b3119..9cd768e471bf4 100644 --- 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 index 8651337819162..a43d3e6c17580 100644 --- 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