CA1802:建議在適當時使用常值

發行項
02/04/2025

屬性	值
規則識別碼	CA1802
職稱	建議在適當時使用常值
類別	效能
修正程式是中斷或非中斷	不中斷
預設在 .NET 9 中啟用	No

原因

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

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

檔案描述

呼叫宣告類型的靜態建構函式時，會在運行時間計算欄位的值 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 介面

您可以藉由設定 [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";
}

共用方式為