From 8fa885a16a88a1e7e774ef2d63bc2ee8a8d9e3a8 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Thu, 9 Jun 2022 14:35:24 -0700 Subject: [PATCH] add option --- .../code-analysis/quality-rules/ca1806.md | 59 +++++++++++++------ 1 file changed, 40 insertions(+), 19 deletions(-) diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1806.md b/docs/fundamentals/code-analysis/quality-rules/ca1806.md index 3c3adb655fb8d..e5d0f8ee6aeed 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1806.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1806.md @@ -1,7 +1,7 @@ --- title: "CA1806: Do not ignore method results (code analysis)" description: "Learn about code analysis rule CA1806: Do not ignore method results" -ms.date: 06/08/2020 +ms.date: 06/08/2022 ms.topic: reference f1_keywords: - CA1806 @@ -17,11 +17,11 @@ dev_langs: --- # CA1806: Do not ignore method results -| | Value | -|-|-| -| **Rule ID** |CA1806| -| **Category** |[Performance](performance-warnings.md)| -| **Fix is breaking or non-breaking** |Non-breaking| +| | Value | +|-------------------------------------|----------------------------------------| +| **Rule ID** | CA1806 | +| **Category** | [Performance](performance-warnings.md) | +| **Fix is breaking or non-breaking** | Non-breaking | ## Cause @@ -31,43 +31,66 @@ There are several possible reasons for this warning: - A method that creates and returns a new string is called and the new string is never used. -- A COM or P/Invoke method that returns a `HRESULT` or error code that is never used. +- A COM or P/Invoke method that returns a `HRESULT` or error code that's never used. -- A language-integrated query (LINQ) method that returns a result that is never used. +- A language-integrated query (LINQ) method that returns a result that's never used. ## Rule description Unnecessary object creation and the associated garbage collection of the unused object degrade performance. -Strings are immutable and methods such as String.ToUpper returns a new instance of a string instead of modifying the instance of the string in the calling method. +Strings are immutable and methods such as return a new instance of a string instead of modifying the instance of the string in the calling method. -Ignoring `HRESULT` or error code can lead to unexpected behavior in error conditions or to low-resource conditions. +Ignoring `HRESULT` or an error code can lead to low-resource conditions or unexpected behavior in error conditions. LINQ methods are known to not have side effects, and the result should not be ignored. ## How to fix violations -If method A creates a new instance of B object that is never used, pass the instance as an argument to another method or assign the instance to a variable. If the object creation is unnecessary, remove it. +If a method creates a new instance of an object that's never used, pass the instance as an argument to another method or assign the instance to a variable. If the object creation is unnecessary, remove it. -or- -If method A calls method B, but does not use the new string instance that the method B returns, pass the instance as an argument to another method, assign the instance to a variable. Or remove the call if it is unnecessary. +If method A calls method B but does not use the new string instance that method B returns, pass the instance as an argument to another method or assign the instance to a variable. Or remove the call if it's unnecessary. -or- -If method A calls method B, but does not use the `HRESULT` or error code that the method returns, use the result in a conditional statement, assign the result to a variable, or pass it as an argument to another method. +If method A calls method B but does not use the `HRESULT` or error code that the method returns, use the result in a conditional statement, assign the result to a variable, or pass it as an argument to another method. -or- -If a LINQ method A calls method B, but does not use the result, use the result in a conditional statement, assign the result to a variable, or pass it as an argument to another method. +If a LINQ method A calls method B but does not use the result, use the result in a conditional statement, assign the result to a variable, or pass it as an argument to another method. ## When to suppress warnings Do not suppress a warning from this rule unless the act of creating the object serves some purpose. +## Configure code to analyze + +Use the following option to configure which parts of your codebase to run this rule on. + +### Additional methods to enforce + +You can configure this rule to check that results from additional custom APIs are used. Specify one or more methods as the *value* of the `additional_use_results_methods` option. To specify multiple method names, separate them with `|`. The allowable formats for the method name are: + +- Method name only (which will include all methods with that name, regardless of their containing type or namespace). +- Fully qualified name in the [documentation ID format](/dotnet/csharp/language-reference/language-specification/documentation-comments#d4-processing-the-documentation-file), with an optional `M:` prefix. + +For example, to specify that rule CA1806 should also check that the result from a method named `MyMethod1` is used, add the following key-value pair to an *.editorconfig* file in your project. + +```ini +dotnet_code_quality.CA1806.additional_use_results_methods = MyMethod1 +``` + +Or, use the fully qualified name to disambiguate or ensure that only a specific method with that name is included. + +```ini +dotnet_code_quality.CA1806.additional_use_results_methods = M:MyNamespace.MyType.MyMethod1(ParamType) +``` + ## Example 1 -The following example shows a class that ignores the result of calling String.Trim. +The following example shows a class that ignores the result of calling . :::code language="csharp" source="snippets/csharp/all-rules/ca1806.cs" id="snippet1"::: @@ -75,7 +98,7 @@ The following example shows a class that ignores the result of calling String.Tr ## Example 2 -The following example fixes the previous violation by assigning the result of String.Trim back to the variable it was called on. +The following example fixes the [Example 1](#example-1) violation by assigning the result of back to the variable it was called on. :::code language="csharp" source="snippets/csharp/all-rules/ca1806.cs" id="snippet2"::: @@ -92,13 +115,11 @@ The following example shows a method that does not use an object that it creates ## Example 4 -The following example fixes the previous violation by removing the unnecessary creation of an object. +The following example fixes the [Example 3](#example-3) violation by removing the unnecessary creation of an object. :::code language="csharp" source="snippets/csharp/all-rules/ca1806.cs" id="snippet4":::