Add documentation for CA1864. (#36059)

dotnet · Jul 7, 2023 · b9faab9 · b9faab9
1 parent ea53ce5
commit b9faab9
Show file tree

Hide file tree

Showing 4 changed files with 103 additions and 5 deletions.
diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1864.md b/docs/fundamentals/code-analysis/quality-rules/ca1864.md
@@ -0,0 +1,94 @@
+---
+title: "CA1864: Prefer the 'IDictionary.TryAdd(TKey, TValue)' method"
+description: "Learn about code analyzer rule CA1864 - Prefer the 'IDictionary.TryAdd(TKey, TValue)' method"
+ms.date: 06/30/2023
+ms.topic: reference
+f1_keywords:
+ - CA1864
+ - PreferDictionaryTryMethodsOverContainsKeyGuardAnalyzer
+helpviewer_keywords:
+ - CA1864
+dev_langs:
+ - CSharp
+ - VB
+---
+
+# CA1864: Prefer the 'IDictionary.TryAdd(TKey, TValue)' method
+
+|                                     | Value                                  |
+| ----------------------------------- |----------------------------------------|
+| **Rule ID**                         | CA1864                                 |
+| **Category**                        | [Performance](performance-warnings.md) |
+| **Fix is breaking or non-breaking** | Non-breaking                           |
+| **Enabled by default in .NET 7**    | No                                     |
+
+## Cause
+
+<xref:System.Collections.Generic.Dictionary%602.Add%2A?displayProperty=nameWithType> is guarded by a <xref:System.Collections.Generic.Dictionary%602.ContainsKey(%600)?displayProperty=nameWithType> call.
+
+## Rule description
+
+Both <xref:System.Collections.Generic.Dictionary%602.ContainsKey(%600)?displayProperty=nameWithType> and <xref:System.Collections.Generic.Dictionary%602.Add%2A?displayProperty=nameWithType> perform a lookup, which is redundant. <xref:System.Collections.Generic.Dictionary%602.Add%2A?displayProperty=nameWithType> also throws an exception if the key is already present in the dictionary. It's more efficient to call <xref:System.Collections.Generic.Dictionary%602.TryAdd%2A?displayProperty=nameWithType>, which returns a Boolean value that indicates if the value was added or not. `TryAdd` doesn't overwrite the key's value if the key is already present.
+
+## How to fix violations
+
+Replace a call to <xref:System.Collections.Generic.Dictionary%602.ContainsKey(%600)?displayProperty=nameWithType> that's followed by a call to <xref:System.Collections.Generic.Dictionary%602.Add%2A?displayProperty=nameWithType> with a single call to <xref:System.Collections.Generic.Dictionary%602.TryAdd%2A?displayProperty=nameWithType>.
+
+## Example
+
+The following code snippet shows a violation of CA1864:
+
+```csharp
+void Run(IDictionary<int, string> dictionary)
+{
+    if(!dictionary.ContainsKey(2)) {
+        dictionary.Add(2, "Hello World");
+    }
+}
+```
+
+```vb
+Sub Run(dictionary As IDictionary(Of Integer, String))
+    If Not dictionary.ContainsKey(2) Then
+        dictionary.Add(2, "Hello World")
+    End If
+End Sub
+```
+
+The following code snippet fixes the violation:
+
+```csharp
+void Run(IDictionary<int, string> dictionary)
+{
+    dictionary.TryAdd(2, "Hello World");
+}
+```
+
+```vb
+Sub Run(dictionary As IDictionary(Of Integer, String))
+    dictionary.TryAdd(2, "Hello World")
+End Sub
+```
+
+## When to suppress warnings
+
+It's safe to suppress this warning if performance isn't a concern and if you handle the exception that might be thrown by <xref:System.Collections.Generic.Dictionary%602.Add%2A?displayProperty=nameWithType>.
+
+## 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 CA1864
+// The code that's violating the rule is on this line.
+#pragma warning restore CA1864
+```
+
+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.CA1864.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
@@ -157,6 +157,7 @@ The following table lists code quality analysis rules.
 > | [CA1859: Use concrete types when possible for improved performance](ca1859.md) | Code uses interface types or abstract types, leading to unnecessary interface calls or virtual calls. |
 > | [CA1860: Avoid using 'Enumerable.Any()' extension method](ca1860.md) | It's more efficient and clearer to use `Length`, `Count`, or `IsEmpty` (if possible) than to call <xref:System.Linq.Enumerable.Any%2A?displayProperty=nameWithType> to determine whether a collection type has any elements. |
 > | [CA1861: Avoid constant arrays as arguments](ca1861.md) | Constant arrays passed as arguments are not reused which implies a performance overhead. Consider extracting them to 'static readonly' fields to improve performance. |
+> | [CA1864: Prefer the 'IDictionary.TryAdd(TKey, TValue)' method](ca1864.md) | Both <xref:System.Collections.Generic.Dictionary%602.ContainsKey(%600)?displayProperty=nameWithType> and <xref:System.Collections.Generic.Dictionary%602.Add%2A?displayProperty=nameWithType> perform a lookup, which is redundant. It's is more efficient to call <xref:System.Collections.Generic.Dictionary%602.TryAdd%2A?displayProperty=nameWithType>, which returns a `bool` indicating if the value was added or not. `TryAdd` doesn't overwrite the key's value if the key is already present. |
 > | [CA2000: Dispose objects before losing scope](ca2000.md) | Because an exceptional event might occur that will prevent the finalizer of an object from running, the object should be explicitly disposed before all references to it are out of scope. |
 > | [CA2002: Do not lock on objects with weak identity](ca2002.md) |An object is said to have a weak identity when it can be directly accessed across application domain boundaries. A thread that tries to acquire a lock on an object that has a weak identity can be blocked by a second thread in a different application domain that has a lock on the same object. |
 > | [CA2007: Do not directly await a Task](ca2007.md) | An asynchronous method [awaits](../../../csharp/language-reference/operators/await.md) a <xref:System.Threading.Tasks.Task> directly. When an asynchronous method awaits a <xref:System.Threading.Tasks.Task> directly, continuation occurs in the same thread that created the task. This behavior can be costly in terms of performance and can result in a deadlock on the UI thread. Consider calling <xref:System.Threading.Tasks.Task.ConfigureAwait(System.Boolean)?displayProperty=nameWithType> to signal your intention for continuation. |

diff --git a/docs/fundamentals/code-analysis/quality-rules/performance-warnings.md b/docs/fundamentals/code-analysis/quality-rules/performance-warnings.md
@@ -70,3 +70,4 @@ Performance rules support high-performance libraries and applications.
 | [CA1859: Use concrete types when possible for improved performance](ca1859.md) | Code uses interface types or abstract types, leading to unnecessary interface calls or virtual calls. |
 | [CA1860: Avoid using 'Enumerable.Any()' extension method](ca1860.md) | It's more efficient and clearer to use `Length`, `Count`, or `IsEmpty` (if possible) than to call <xref:System.Linq.Enumerable.Any%2A?displayProperty=nameWithType> to determine whether a collection type has any elements. |
 | [CA1861: Avoid constant arrays as arguments](ca1861.md) | Constant arrays passed as arguments are not reused which implies a performance overhead. Consider extracting them to 'static readonly' fields to improve performance. |
+| [CA1864: Prefer the 'IDictionary.TryAdd(TKey, TValue)' method](ca1864.md) | Both <xref:System.Collections.Generic.Dictionary%602.ContainsKey(%600)?displayProperty=nameWithType> and <xref:System.Collections.Generic.Dictionary%602.Add%2A?displayProperty=nameWithType> perform a lookup, which is redundant. It's is more efficient to call <xref:System.Collections.Generic.Dictionary%602.TryAdd%2A?displayProperty=nameWithType>, which returns a `bool` indicating if the value was added or not. `TryAdd` doesn't overwrite the key's value if the key is already present. |
diff --git a/docs/navigate/tools-diagnostics/toc.yml b/docs/navigate/tools-diagnostics/toc.yml
@@ -349,7 +349,7 @@ items:
     - name: Specialized diagnostics
       items:
       - name: Overview
-        href: ../../core/diagnostics/specialized-diagnostics-overview.md    
+        href: ../../core/diagnostics/specialized-diagnostics-overview.md
       - name: Event Source
         items:
         - name: Overview
@@ -386,7 +386,7 @@ items:
           - name: Type-system events
             href: ../../fundamentals/diagnostics/runtime-type-events.md
       - name: Collect diagnostics in containers
-        href: ../../core/diagnostics/diagnostics-in-containers.md   
+        href: ../../core/diagnostics/diagnostics-in-containers.md
       - name: Dumps
         items:
         - name: Overview
@@ -401,9 +401,9 @@ items:
         - name: Collect dumps on crash
           href: ../../core/diagnostics/collect-dumps-crash.md
       - name: Symbols
-        href: ../../core/diagnostics/symbols.md    
+        href: ../../core/diagnostics/symbols.md
       - name: EventPipe
-        href: ../../core/diagnostics/eventpipe.md    
+        href: ../../core/diagnostics/eventpipe.md
       - name: Diagnostic port
         items:
         - name: Overview
@@ -418,7 +418,7 @@ items:
       - name: DiagnosticSource and DiagnosticListener
         items:
         - name: Get started
-          href: ../../core/diagnostics/diagnosticsource-diagnosticlistener.md                
+          href: ../../core/diagnostics/diagnosticsource-diagnosticlistener.md
     - name: .NET CLI global tools
       items:
       - name: Overview
@@ -801,6 +801,8 @@ items:
                     href: ../../fundamentals/code-analysis/quality-rules/ca1860.md
                   - name: CA1861
                     href: ../../fundamentals/code-analysis/quality-rules/ca1861.md
+                  - name: CA1864
+                    href: ../../fundamentals/code-analysis/quality-rules/ca1864.md
               - name: SingleFile rules
                 items:
                   - name: Overview