CA1806:不要忽略方法的結果

發行項
09/06/2023

屬性	值
規則識別碼	CA1806
標題	不要忽略方法的結果
類別	效能
修正程式是中斷或非中斷	不中斷
預設在 .NET 8 中啟用	建議

原因

此警告有數個可能的原因：

系統會建立新的物件，但從未使用過。
會呼叫建立並傳回新字串的方法，而且永遠不會使用新的字串。
COM 或 P/Invoke 方法，會傳回 HRESULT 從未使用過的或錯誤碼。
語言整合式查詢（LINQ）方法，會傳回從未使用的結果。

檔案描述

不必要的物件建立和未使用之物件的相關聯垃圾收集會降低效能。

字串是不可變的，例如 String.ToUpper 傳回字串的新實例，而不是修改呼叫方法中的字串實例。

HRESULT忽略或錯誤碼可能會導致低資源狀況或錯誤狀況中的非預期行為。

已知 LINQ 方法沒有副作用，因此不應忽略結果。

如何修正違規

如果方法建立從未使用過之物件的新實例，請將實例當做引數傳遞至另一個方法，或將實例指派給變數。如果不需要建立物件，請將其移除。

-或-

如果方法 A 會呼叫方法 B，但未使用方法 B 傳回的新字串實例，請將實例當做引數傳遞至另一個方法，或將實例指派給變數。或者，如果不需要，請移除呼叫。

-或-

如果方法 A 會呼叫方法 B，但未使用方法傳回的 HRESULT 或錯誤碼，請在條件陳述式中使用結果、將結果指派給變數，或將它當做引數傳遞給另一個方法。

-或-

如果 LINQ 方法 A 會呼叫方法 B 但未使用結果，請在條件陳述式中使用結果、將結果指派給變數，或將它當做引數傳遞給另一個方法。

隱藏警告的時機

除非建立物件的行為有某種用途，否則請勿隱藏此規則的警告。

隱藏警告

如果您只想要隱藏單一違規，請將預處理器指示詞新增至原始程式檔以停用，然後重新啟用規則。

#pragma warning disable CA1806
// The code that's violating the rule is on this line.
#pragma warning restore CA1806

若要停用檔案、資料夾或專案的規則，請在組態檔中將其嚴重性設定為。 none

[*.{cs,vb}]
dotnet_diagnostic.CA1806.severity = none

如需詳細資訊，請參閱如何隱藏程式碼分析警告。

設定程式碼以分析

使用下列選項來設定程式碼基底要執行此規則的部分。

要強制執行的其他方法

您可以設定此規則來檢查是否使用其他自訂 API 的結果。將一或多個方法指定為 選項的值 additional_use_results_methods 。若要指定多個方法名稱，請使用 | 分隔它們。方法名稱的允許格式如下：

僅限方法名稱（不論其包含類型或命名空間為何，都會包含該名稱的所有方法）。
檔識別碼格式的完整名稱，具有選擇性 M: 前置詞。

例如，若要指定規則 CA1806 也應該檢查是否使用名為 MyMethod1 的方法的結果，請將下列機碼/值組新增至專案中的 .editorconfig 檔案。

dotnet_code_quality.CA1806.additional_use_results_methods = MyMethod1

或者，使用完整名稱來厘清或確保只包含具有該名稱的特定方法。

dotnet_code_quality.CA1806.additional_use_results_methods = M:MyNamespace.MyType.MyMethod1(ParamType)

範例 1

下列範例顯示忽略呼叫 String.Trim 結果的類別。

public class Book
{
    private readonly string? _Title;

    public Book(string title)
    {
        if (title != null)
        {
            // Violates this rule
            title.Trim();
        }

        _Title = title;
    }

    public string? Title
    {
        get { return _Title; }
    }
}

Public Class Book
    Public Sub New(ByVal title As String)

        If title IsNot Nothing Then
            ' Violates this rule                
            title.Trim()
        End If

        Me.Title = title

    End Sub

    Public ReadOnly Property Title() As String

End Class

範例 2

下列範例會藉由將傳回的結果 String.Trim 指派給呼叫的變數，來修正範例 1 違規。

public class Book
{
    private readonly string? _Title;

    public Book(string title)
    {
        if (title != null)
        {
            title = title.Trim();
        }

        _Title = title;
    }

    public string? Title
    {
        get { return _Title; }
    }
}

Public Class Book
    Public Sub New(ByVal title As String)

        If title IsNot Nothing Then
            title = title.Trim()
        End If

        Me.Title = title

    End Sub

    Public ReadOnly Property Title() As String

End Class

範例 3

下列範例示範的方法不會使用它所建立的物件。

注意

此違規無法在 Visual Basic 中重現。

public class Book
{
    public Book()
    {
    }

    public static Book CreateBook()
    {
        // Violates this rule
        new Book();
        return new Book();
    }
}

範例 4

下列範例會藉由移除不必要的物件建立，修正範例 3 違規。

public class Book
{
    public Book()
    {
    }

    public static Book CreateBook()
    {
        return new Book();
    }
}

共用方式為