隱藏程式碼分析違規項目

發行項
04/11/2024

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

使用 EditorConfig 檔案隱藏違規

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

隱藏原始程式碼中的違規

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

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

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

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

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

將游標放在具有違規的程式碼中，然後按 Ctrl+Period (.) 或 Alt+Enter 來開啟 [快速動作] 功能表。
選取 [隱藏或設定問題]>[隱藏<規則編號>]，然後在 [在來源中] 或 [在來源 (屬性) 中] 中選擇。
- 如果選擇 [在來源中]，會看到新增至程式碼中的前置處理器指示詞預覽。
- 如果選擇 [在來源 (屬性) 中]，會看到將新增至程式碼的 SuppressMessage 屬性預覽。

使用錯誤清單隱藏違規

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

從 [錯誤清單] 視窗中，選取要隱藏的規則。
以滑鼠右鍵按一下，然後選取 [隱藏]>[在來源中]。

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

排除錯誤清單組建診斷

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

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

在 [錯誤清單]來源篩選下拉式清單中，將選取範圍從 [組建 + IntelliSense] 變更為 [僅限 IntelliSense]。
選取想要隱藏的診斷，並如先前所述繼續進行。

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

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

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

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

在程式碼編輯器中，將游標放在具有違規的程式碼上，然後按 Ctrl+Period (.) 或 Alt+Enter 開啟 [快速動作] 功能表。
選取 [隱藏<規則編號>]，然後選擇 [在隱藏檔案中]。

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

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

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

從 [錯誤清單] 視窗中，選取要隱藏的規則。
以滑鼠右鍵按一下，然後選取 [隱藏]>[在隱藏檔案中]。

[預覽變更] 對話框隨即開啟，並顯示新增至全域隱藏檔案的 SuppressMessageAttribute 屬性預覽。
選取 [套用] 來儲存全域歸並檔案。

隱藏所有目前的違規

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

從 Visual Studio 選單列中，選取 [分析]>[組建並隱藏作用中問題]。
選取 [針對解決方案] 來隱藏整個解決方案的違規，或選取 [針對 <專案名稱>] 來僅隱藏專案的違規。

使用專案設定隱藏違規

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

在 [方案總管] 中選取專案。
以滑鼠右鍵按一下，然後選取 [屬性] (或按 Alt + Enter)。
從 [屬性] 視窗中，從左側窗格中選取 [程式碼分析]，然後清除 [隱藏所產生程式碼的結果]。

使用規則集隱藏違規

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

來源內隱藏和 SuppressMessageAttribute 屬性

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

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

在程式碼編輯器中，將游標放在具有違規的程式碼上，然後按 Ctrl+Period (.) 或 Alt+Enter 開啟 [快速動作] 功能表。
從 [快速動作] 功能表中，選取 [隱藏或設定問題]>[隱藏<規則編號>]。
執行下列其中一個步驟：
- 選取[在來源 (屬性) 中]。
  
  Visual Studio 會將 SuppressMessageAttribute 屬性新增至程式碼。
- 選取 [在隱藏檔案中]。
  
  Visual Studio 會在程式碼編輯器中建立索引標籤，其中包含具有 SuppressMessageAttribute 屬性的新全域隱藏檔案。

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

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

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

注意

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

SuppressMessageAttribute 屬性格式

SuppressMessageAttribute 屬性的格式如下：

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

<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 符號的違規。

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}");
    }
}

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。

共用方式為

隱藏程式碼分析違規項目

使用 EditorConfig 檔案隱藏違規

隱藏原始程式碼中的違規

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

使用錯誤清單隱藏違規

排除錯誤清單組建診斷

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

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

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

隱藏所有目前的違規

使用專案設定隱藏違規

使用規則集隱藏違規

來源內隱藏和 SuppressMessageAttribute 屬性

SuppressMessageAttribute 屬性格式

SuppressMessageAttribute 使用方式

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

全域層級隱藏

全域隱藏檔案

模組隱藏範圍

產生的程式碼

意見反應

其他資源

共用方式為

隱藏程式碼分析違規項目

使用 EditorConfig 檔案隱藏違規

隱藏原始程式碼中的違規

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

使用錯誤清單隱藏違規

排除錯誤清單組建診斷

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

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

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

隱藏所有目前的違規

使用專案設定隱藏違規

使用規則集隱藏違規

來源內隱藏和 SuppressMessageAttribute 屬性

SuppressMessageAttribute 屬性格式

SuppressMessageAttribute 使用方式

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

全域層級隱藏

全域隱藏檔案

模組隱藏範圍

產生的程式碼

相關內容

意見反應

其他資源