Ca2251 (#24463)

Author: NewellClark

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

@@ -0,0 +1,40 @@
+---
+title: "CA2251: Use `String.Equals` over `String.Compare`"
+description: "Learn about code analysis rule CA2251: Use `String.Equals` over `String.Compare`"
+ms.date: 05/31/2021
+ms.topic: reference
+f1_keywords:
+- CA2251
+- UseStringEqualsOverStringCompare
+helpviewer_keywords:
+- UseStringEqualsOverStringCompare
+- CA2251
+author: NewellClark
+---
+# CA2251: Use `String.Equals` over `String.Compare`
+
+| | Value |
+|-|-|
+| **Rule ID** |CA2251|
+| **Category** |[Usage](usage-warnings.md)|
+| **Fix is breaking or non-breaking** |Non-breaking|
+
+## Cause
+
+The result of a call to <xref:System.String.Compare%2A?displayProperty=nameWithType> is compared to zero.
+
+## Rule description
+
+<xref:System.String.Compare%2A?displayProperty=nameWithType> is designed to produce a total-order comparison that can be used for sorting. If you only care whether the strings are equal, it is both clearer and likely faster to use an equivalent overload of <xref:System.String.Equals%2A?displayProperty=nameWithType>.
+
+## How to fix violations
+
+To fix violations of this rule, replace the expression comparing the result of <xref:System.String.Compare%2A?displayProperty=nameWithType> with a call to <xref:System.String.Equals%2A?displayProperty=nameWithType>.
+
+## When to suppress warnings
+
+It is safe to suppress warnings from this rule.
+
+## See also
+
+- [Performance warnings](performance-warnings.md)

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

@@ -181,6 +181,7 @@ The following table lists code quality analysis rules.
 > | [CA2248: Provide correct enum argument to Enum.HasFlag](ca2248.md) | The enum type passed as an argument to the `HasFlag` method call is different from the calling enum type. |
 > | [CA2249: Consider using String.Contains instead of String.IndexOf](ca2249.md) | Calls to `string.IndexOf` where the result is used to check for the presence/absence of a substring can be replaced by `string.Contains`. |
 > | [CA2250: Use `ThrowIfCancellationRequested`](ca2250.md) | `ThrowIfCancellationRequested` automatically checks whether the token has been canceled, and throws an `OperationCanceledException` if it has. |
+> | [CA2251: Use `String.Equals` over `String.Compare`](ca2251.md) | It is both clearer and likely faster to use `String.Equals` instead of comparing the result of `String.Compare` to zero. |
 > | [CA2300: Do not use insecure deserializer BinaryFormatter](ca2300.md) | Insecure deserializers are vulnerable when deserializing untrusted data. An attacker could modify the serialized data to include unexpected types to inject objects with malicious side effects. |
 > | [CA2301: Do not call BinaryFormatter.Deserialize without first setting BinaryFormatter.Binder](ca2301.md) | Insecure deserializers are vulnerable when deserializing untrusted data. An attacker could modify the serialized data to include unexpected types to inject objects with malicious side effects. |
 > | [CA2302: Ensure BinaryFormatter.Binder is set before calling BinaryFormatter.Deserialize](ca2302.md) | Insecure deserializers are vulnerable when deserializing untrusted data. An attacker could modify the serialized data to include unexpected types to inject objects with malicious side effects. |

docs/fundamentals/code-analysis/quality-rules/usage-warnings.md

@@ -53,3 +53,4 @@ Usage rules support proper usage of .NET.
 |[CA2248: Provide correct 'enum' argument to 'Enum.HasFlag'](ca2248.md)|The enum type passed as an argument to the `HasFlag` method call is different from the calling enum type.|
 |[CA2249: Consider using String.Contains instead of String.IndexOf](ca2249.md)|Calls to `string.IndexOf` where the result is used to check for the presence or absence of a substring can be replaced by `string.Contains`.|
 |[CA2250: Use `ThrowIfCancellationRequested`](ca2250.md) | `ThrowIfCancellationRequested` automatically checks whether the token has been canceled, and throws an `OperationCanceledException` if it has.|
+|[CA2251: Use `String.Equals` over `String.Compare`](ca2251.md)|It is both clearer and likely faster to use `String.Equals` instead of comparing the result of `String.Compare` to zero.|

docs/fundamentals/toc.yml

@@ -1231,6 +1231,8 @@ items:
             href: code-analysis/quality-rules/ca2249.md
           - name: CA2250
             href: code-analysis/quality-rules/ca2250.md
+          - name: CA2251
+            href: code-analysis/quality-rules/ca2251.md            
       - name: Code style rules
         items:
         - name: Overview