隱藏程式碼分析違規項目

如果您在建立程式碼時與小組共同作業，指示不適用警告通常很有用。 隱藏程式碼分析違規指示小組成員已檢閱過程式碼，而且可以隱藏警告。 下列各節說明使用 Visual Studio IDE 隱藏程式碼分析違規的不同方式。

使用 EditorConfig 檔案隱藏違規

在解決方案或專案的 EditorConfig 檔案中，針對想要設定的每個規則新增項目，並將其嚴重性設定為 none。 例如：dotnet_diagnostic.CA1822.severity = none。 如需詳細資訊，請參閱<在 EditorConfig 檔案中，手動設定規則嚴重性>(機器翻譯)。 若要新增 EditorConfig 檔案，請參閱將 EditorConfig 檔案新增至專案。

隱藏原始程式碼中的違規

可以使用前置處理器指示詞來隱藏原始程式碼中的違規，這會隱藏特定程式碼的違規：

• C#：#pragma warning
• Visual Basic：停用警告

或者，可以使用 SuppressMessageAttribute 屬性 來隱藏 C# 和 Visual Basic 程式碼中的警告。

使用程式碼編輯器隱藏違規

若要使用程式碼編輯器隱藏違規，請遵循下列步驟：

1. 將游標放在具有違規的程式碼中，然後按 Ctrl+Period (.) 或 Alt+Enter 來開啟 [快速動作] 功能表。

2. 選取 [隱藏或設定問題]>[隱藏<規則編號>]，然後在 [在來源中] 或 [在來源 (屬性) 中] 中選擇。

   • 如果選擇 [在來源中]，會看到新增至程式碼中的前置處理器指示詞預覽。

     

   • 如果選擇 [在來源 (屬性) 中]，會看到將新增至程式碼的 SuppressMessage 屬性預覽。

     

使用錯誤清單隱藏違規

若要使用 [錯誤清單] 視窗隱藏違規，請遵循下列步驟：

1. 從 [錯誤清單] 視窗中，選取要隱藏的規則。

2. 以滑鼠右鍵按一下，然後選取 [隱藏]>[在來源中]。

   [預覽變更] 對話方塊隨即開啟，並顯示 C# #pragma warning 指示詞或 Visual Basic #Disable warning 指示詞的預覽，該指示詞會新增至原始程式碼。

   

3. 選取套用來儲存程式碼檔案的變更。

排除錯誤清單組建診斷

如果沒有在 [錯誤清單] 視窗中看到 [隱藏] 功能表選項，則違規可能來自組建，而不是即時分析。 [錯誤清單] 視窗會顯示即時程式碼分析和組建中的診斷或規則違規。 例如，由於組建診斷可能過時，如果已編輯程式碼來修正違規，但尚未重建，則無法從 [錯誤清單] 中隱藏這些診斷。

即時分析或 IntelliSense 中的診斷一律會與目前來源保持最新狀態，而且可以一律從[錯誤清單] 隱藏。 若要從選取範圍中排除組建診斷，請遵循下列步驟：

1. 在 [錯誤清單]來源篩選下拉式清單中，將選取範圍從 [組建 + IntelliSense] 變更為 [僅限 IntelliSense]。

   

2. 選取想要隱藏的診斷，並如先前所述繼續進行。

使用全域隱藏檔案隱藏違規

全域隱藏檔案會使用 SuppressMessage 屬性來隱藏程式碼違規。

從程式碼編輯器使用全域隱藏檔案

若要使用程式碼編輯器透過全域隱藏檔案來隱藏違規，請遵循下列步驟：

1. 在程式碼編輯器中，將游標放在具有違規的程式碼上，然後按 Ctrl+Period (.) 或 Alt+Enter 開啟 [快速動作] 功能表。

2. 選取 [隱藏<規則編號>]，然後選擇 [在隱藏檔案中]。

   Visual Studio 會在程式碼編輯器中建立索引標籤，其中包含新的全域隱藏檔案。

使用 [錯誤清單] 中的全域歸並檔案

若要使用 [錯誤清單] 視窗透過全域隱藏檔案來隱藏違規，請遵循下列步驟：

1. 從 [錯誤清單] 視窗中，選取要隱藏的規則。

2. 以滑鼠右鍵按一下，然後選取 [隱藏]>[在隱藏檔案中]。

   [預覽變更] 對話框隨即開啟，並顯示新增至全域隱藏檔案的 SuppressMessageAttribute 屬性預覽。

   

3. 選取 [套用] 來儲存全域歸並檔案。

隱藏所有目前的違規

隱藏所有目前的違規有時稱為「基準化」。 若要隱藏解決方案或專案中的所有目前違規，請遵循下列步驟：

1. 從 Visual Studio 選單列中，選取 [分析]>[組建並隱藏作用中問題]。

2. 選取 [針對解決方案] 來隱藏整個解決方案的違規，或選取 [針對 <專案名稱>] 來僅隱藏專案的違規。

使用專案設定隱藏違規

若要使用 [方案總管] 專案設定來隱藏違規，請遵循下列步驟：

1. 在 [方案總管] 中選取專案。

2. 以滑鼠右鍵按一下，然後選取 [屬性] (或按 Alt + Enter)。

3. 從 [屬性] 視窗中，從左側窗格中選取 [程式碼分析]，然後清除 [隱藏所產生程式碼的結果]。

使用規則集隱藏違規

從規則集編輯器中，清除其名稱旁的核取方塊，或將 [動作] 設定為 [無]。

來源內隱藏和 SuppressMessageAttribute 屬性

來源內隱藏 (ISS) 會使用 SuppressMessageAttribute 屬性來隱藏警告。 可以將 SuppressMessageAttribute 屬性新增至產生警告的程式碼區段附近之來源檔案。

可以在程式碼編輯器中手動輸入屬性，或自動新增屬性，如下所示：

1. 在程式碼編輯器中，將游標放在具有違規的程式碼上，然後按 Ctrl+Period (.) 或 Alt+Enter 開啟 [快速動作] 功能表。

2. 從 [快速動作] 功能表中，選取 [隱藏或設定問題]>[隱藏<規則編號>]。

3. 執行下列其中一個步驟：

   • 選取[在來源 (屬性) 中]。

     Visual Studio 會將 SuppressMessageAttribute 屬性新增至程式碼。

   • 選取 [在隱藏檔案中]。

     Visual Studio 會在程式碼編輯器中建立索引標籤，其中包含具有 SuppressMessageAttribute 屬性的新全域隱藏檔案。

SuppressMessageAttribute 屬性是條件屬性，包含在受控程式碼組件的中繼資料中。 只有當編譯時間定義了 CODE_ANALYSIS 編譯符號時，才會包含這個屬性。

僅在 C++ 和 CLI 程式碼中，在標頭檔中使用巨集 CA_SUPPRESS_MESSAGE 或 CA_GLOBAL_SUPPRESS_MESSAGE 來新增屬性。

如果將專案移轉至 Visual Studio 的最新版本，可能會發現大量的程式碼分析警告。 如果您尚未準備好修正警告，可以選取 [分析]>[建置並隱藏作用中問題] 來隱藏所有警告。

注意

不要在發行組建上使用來源內隱藏，以避免意外傳送來源內隱藏中繼資料。

SuppressMessageAttribute 屬性格式

SuppressMessageAttribute 屬性的格式如下：

C#

[Scope:SuppressMessage("Rule Category", "Rule Id", Justification = "Justification", MessageId = "MessageId", Scope = "Scope", Target = "Target")]

VB

<Scope:SuppressMessage("Rule Category", "Rule Id", Justification = "Justification", MessageId = "MessageId", Scope = "Scope", Target = "Target")>

屬性 (Attribute) 的屬性 (Property) 包括：

• Category：規則的類別。 如需關於程式碼分析規則類別的詳細資訊，請參閱<程式碼品質規則>(機器翻譯)。

• CheckId: 規則的識別碼。 支援同時包含規則識別碼的短名稱和長名稱。 簡短名稱為 CAXXXX；完整名稱為 CAXXXX:FriendlyTypeName。

• Justification：用來記錄隱藏訊息原因的文字。

• MessageId：每個訊息問題的唯一識別碼。

• Scope：隱藏警告的目標。 如果未指定目標，則系統會將其設定為屬性的目標。 支援的範圍包括：

  • module：此範圍會針對組件隱藏警告。 這是套用至整個專案的全域隱藏。

  • resource：(僅限舊版 FxCop) 此範圍會隱藏寫入模組 (組件) 資源檔診斷資訊中的警告。 在適用於 Roslyn 分析器診斷 (只會分析來源檔案) 的 C#/VB 編譯器中不會讀取或遵守此範圍。

  • type：此範圍會針對類型隱藏警告。

  • member：此範圍會針對成員隱藏警告。

  • namespace：此範圍會針對命名空間本身隱藏警告。 其不會針對命名空間內類型隱藏警告。

  • namespaceanddescendants：(需要編譯器 3.x 版或更高版本及 Visual Studio 2019 或更高版本) 此範圍會隱藏命名空間及其所有子系符號中的警告。 舊版分析會忽略 namespaceanddescendants 值。

• Target：指定隱藏警告的目標識別碼。 其必須包含完整元件名稱。

當您在 Visual Studio 中看到警告時，可將隱藏新增至全域隱藏檔案來檢視 SuppressMessageAttribute 的範例。 隱藏屬性及其必要屬性會出現在預覽視窗中。

SuppressMessageAttribute 使用方式

程式碼分析警告會在套用 SuppressMessageAttribute 屬性的層級隱藏。 例如，屬性可以在組件、模組、類型、成員或參數層級套用。 套用這個屬性的目的是將隱藏資訊緊密結合至發生違規的程式碼。

一般形式的隱藏包括規則類別和規則識別碼，其中包含規則名稱的選擇性人類可讀取標記法。 例如：

[SuppressMessage("Microsoft.Design", "CA1039:ListsAreStrongTyped")]

如果在將來源內隱藏中繼資料最小化時有嚴格的效能原因，則可以省略規則名稱。 規則類別及其規則識別碼會共同形成足夠唯一的規則識別碼。 例如：

[SuppressMessage("Microsoft.Design", "CA1039")]

基於可維護性考量，不建議省略規則名稱。

隱藏方法主體中的選擇性違規

可以將隱藏屬性套用至方法，但無法內嵌在方法主體中。 如果您將 SuppressMessageAttribute 屬性新增至方法，則會隱藏特定規則的所有違規。

在某些情況下，您可能需要隱藏特定違規執行個體。 請考量未來程式碼不會自動豁免程式碼分析規則的範例。 某些程式碼分析規則可讓您使用 SuppressMessageAttribute 屬性 (attribute) 的 MessageId 屬性 (property) 來隱藏違規的特定執行個體。 一般而言，特定符號上違規的舊版規則 (區域變數或參數) 會遵守 MessageId 屬性。 CA1500:VariableNamesShouldNotMatchFieldNames 是這類規則的範例。 不過，可執行檔程式碼 (非符號) 違規的舊版規則並不遵守 MessageId 屬性。 此外，.NET Compiler Platform (「Roslyn」) 分析器不會遵守 MessageId 屬性。

若要隱藏規則的特定符號違規，請為 SuppressMessageAttribute 屬性 (attribute) 的 MessageId 屬性 (property) 指定符號名稱。 下列範例顯示違反兩個 CA1500:VariableNamesShouldNotMatchFieldNames 的程式碼：一個用於 name 變數，另一個用於 age 變數。 只會隱藏 age 符號的違規。

C#

public class Animal
{
    int age;
    string name;

    [System.Diagnostics.CodeAnalysis.SuppressMessage("Microsoft.Maintainability", "CA1500:VariableNamesShouldNotMatchFieldNames", MessageId = "age")]
    private void PrintInfo()
    {
        int age = 5;
        string name = "Charlie";

        Console.WriteLine($"Age {age}, Name {name}");
    }
}

VB

Public Class Animal
    Dim age As Integer
    Dim name As String

    <CodeAnalysis.SuppressMessage("Microsoft.Maintainability", "CA1500:VariableNamesShouldNotMatchFieldNames", MessageId:="age")>
    Sub PrintInfo()
        Dim age As Integer = 5
        Dim name As String = "Charlie"

        Console.WriteLine("Age {0}, Name {1}", age, name)
    End Sub

End Class

全域層級隱藏

受控程式碼分析工具會檢查組件、模組、類型、成員或參數層級所套用的 SuppressMessageAttribute 屬性。 其也會針對資源和命名空間提交違規。 這些違規必須在全域層級套用，並且設定範圍和目標。 例如，下列訊息會隱藏命名空間違規：

[module: SuppressMessage("Microsoft.Design", "CA1020:AvoidNamespacesWithFewTypes", Scope = "namespace", Target = "MyNamespace")]

對於全域層級隱藏：

• 當隱藏具有 namespace 範圍的警告時，其會針對命名空間本身隱藏警告。 其不會針對命名空間內的類型隱藏警告。

• Target 一律包含完整項目名稱。

• 您可以指定明確的範圍來表示任何隱藏。 這些隱藏必須存在於全域層級。 無法修改類型來指定成員層級隱藏。

• 全域層級隱藏是隱藏參考編譯器所產生程式碼訊息的唯一方法，這些程式碼不會對應至明確提供的使用者來源。 例如，下列程式碼會針對編譯器發出的建構函式隱藏違規：

  [module: SuppressMessage("Microsoft.Design", "CA1055:AbstractTypesDoNotHavePublicConstructors", Scope="member", Target="Microsoft.Tools.FxCop.Type..ctor()")]

全域隱藏檔案

全域隱藏檔案會維護全域層級隱藏的隱藏或不指定目標的隱藏。 例如，組件層級違規的隱藏會儲存在此檔案中。 此外，某些 ASP.NET 隱藏會儲存在這個檔案中，因為專案層級設定不適用於表單背後的程式碼。 第一次在 [錯誤清單] 視窗選取 [隱藏] 命令的 [在專案隱藏檔案] 選項時，Visual Studio 就會建立並新增全域隱藏檔案至專案。

模組隱藏範圍

可以使用 module 範圍來隱藏整個組件的程式碼品質違規。

例如，GlobalSuppressions 專案檔中的下列屬性會隱藏 ASP.NET Core 專案的 ConfigureAwait 違規：

[assembly: System.Diagnostics.CodeAnalysis.SuppressMessage("Reliability", "CA2007:Consider calling ConfigureAwait on the awaited task", Justification = "ASP.NET Core doesn't use thread context to store request context.", Scope = "module")]

產生的程式碼

受控程式碼編譯器和某些外部工具會產生程式碼，協助快速開發程式碼。 在來源檔案中出現的編譯器產生程式碼會以 GeneratedCodeAttribute 屬性標示。

針對原始程式碼分析，可以在 .editorconfig 檔案隱藏所產生程式碼的訊息。 如需詳細資訊，請參閱排除產生的程式碼。

針對舊版程式碼分析，您可以選擇是否要隱藏所產生程式碼的程式碼分析警告和錯誤。 如需關於如何隱藏這類警告和錯誤的資訊，請參閱<隱藏所產生之程式碼的程式碼分析警告>。

注意

當程式碼分析套用至整個組件或單一參數時，程式碼分析會忽略 GeneratedCodeAttribute。

相關內容

• Scope
• System.Diagnostics.CodeAnalysis
• 自訂 Roslyn 分析器規則