CA1802：在適當時使用常值

屬性 值
規則識別碼 CA1802
職稱 適當時使用字面值
類別 效能
修正是造成中斷還是不中斷 不中斷
在 .NET 10 中預設啟用 否
適用語言 C# 與 Visual Basic

原因

欄位以static和readonly（在Visual Basic中，則為Shared和ReadOnly）宣告，並以在編譯時期可計算的值來初始化。

根據預設，此規則只會查看外部可見的靜態、只讀字段，但這是可設定的。

規則描述

當呼叫宣告型別的靜態建構子時，欄位的 static readonly 值會被計算出來。 static readonly如果欄位在宣告時初始化，且未明確宣告靜態建構函式，編譯程式會發出靜態建構函式來初始化字段。

欄位的值 const 會在編譯時計算並儲存在元資料中，這在與欄位 static readonly 比較時提升了執行時的效能。

由於分配給目標欄位的值在編譯時可計算，請將宣告改為 const 欄位，使值在編譯時而非執行時計算。

如何修正違規

若要修正此規則的違規，請將 static 和 readonly 修飾詞替換為 const 修飾詞。

注意

不建議在所有案例中使用 const 修飾詞。

隱藏警告的時機

如果效能不是主要考量，則可以安全地抑制此規則的警告或關閉該規則。

警告

針對公用或外部可見的成員，將 static readonly 變更為 const 可能會導致問題。 const 值會內嵌在編譯階段的相依元件中，因此連結庫值中的變更可能不會傳播，可能會導致錯誤。 如果成員的值未來可能會變更，請隱藏此規則。

注意

使用 const 對於 private 成員是安全的，對於 internal 成員通常也是安全的，除非透過 InternalsVisibleTo 曝露或個別部署。

隱藏警告

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

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

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

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

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

設定程式代碼以分析

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

您可以只針對此規則、套用至的所有規則，或套用至此類別的所有規則（效能）設定這些選項。 如需詳細資訊，請參閱 程式代碼品質規則組態選項。

包含特定 API 介面

您可以藉由設定 [api_surface] 選項，根據程式代碼基底的存取範圍，設定執行此規則的哪些部分。 例如，若要指定規則只應該針對非公用 API 介面執行，請將下列機碼/值組新增至 專案中的 .editorconfig 檔案：

dotnet_code_quality.CAXXXX.api_surface = private, internal

注意

以適用規則的標識碼取代 XXXX 的 CAXXXX 部分。

必要的修飾詞

您可以設定此規則以覆寫必填欄位的修飾符。 根據預設， static 和 readonly 都是分析欄位的必要修飾詞。 您可以將其覆寫為一個以逗號分隔的列表，內容為來自下表中的一個或多個修飾詞值。

選項值 摘要
none 不需要修飾詞。
static 或 Shared 必須在Visual Basic中宣告為 『static』 （'Shared'）。
const 必須宣告為 const。
readonly 必須宣告為 『readonly』。

例如，若要指定規則應該針對靜態和實例欄位執行，請將下列機碼/值組新增至專案中的 .editorconfig 檔案：

dotnet_code_quality.CA1802.required_modifiers = none

範例

下列範例顯示違反規則的類型 UseReadOnly，以及滿足規則的類型 UseConstant。

Imports System

Namespace ca1802

    ' This class violates the rule.
    Public Class UseReadOnly

        Shared ReadOnly x As Integer = 3
        Shared ReadOnly y As Double = x + 2.1
        Shared ReadOnly s As String = "readonly"

    End Class

    ' This class satisfies the rule.
    Public Class UseConstant

        Const x As Integer = 3
        Const y As Double = x + 2.1
        Const s As String = "const"

    End Class

End Namespace

// This class violates the rule.
public class UseReadOnly
{
    static readonly int x = 3;
    static readonly double y = x + 2.1;
    static readonly string s = "readonly";

    public void Print()
    {
        Console.WriteLine(s);
    }
}

// This class satisfies the rule.
public class UseConstant
{
    const int x = 3;
    const double y = x + 2.1;
    const string s = "const";
}
  • Last updated on