隱藏程式代碼分析違規

如果您在撰寫程式碼時與團隊合作，通常需要指出某個警告不適用。 抑制程式碼分析違規項表示程序代碼已被審查，團隊成員可以忽略該警告。 下列各節說明使用 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. 選取 隱藏或配置問題>隱藏 <規則編號>，然後選擇 在來源 或 在來源 (屬性)。

   • 如果您選擇在 Source 中，您會看到程式代碼中增加的預處理指令的預覽。

     

   • 如果您選擇 在 Source （attribute）中，您會看到已新增至程式代碼的 SuppressMessageAttribute 屬性 預覽。

     

使用錯誤清單隱藏違規

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

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

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

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

   

3. 選取 [套用 ] 以儲存程式代碼檔案的變更。

排除“錯誤清單”中的建置診斷

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

即時分析或 IntelliSense 的診斷一律會以目前來源 up-to日期，而且一律可從 錯誤清單隱藏。 若要從您的選取範圍中排除組建診斷，請遵循下列步驟：

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

   

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

使用全域抑制檔案抑制違規

全域歸並檔案會使用 SuppressMessageAttribute 屬性來隱藏程式代碼違規。

從代碼編輯器使用全域抑制檔案

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

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

屬性特徵包括：

• Category：規則的類別。 如需程式代碼分析規則類別的詳細資訊，請參閱 程式代碼質量規則。

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

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

• MessageId：每個訊息問題的唯一標識符。

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

  • module：此範圍會抑制針對元件的警告。 這是應用於整個專案的全域抑制。

  • resource:(僅限舊版 FxCop ）此範圍會隱藏寫入模組 （assembly） 之資源檔之診斷資訊中的警告。 此範圍不會在適用於 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 屬性新增至方法，則會隱藏特定規則的所有違規。

在某些情況下，您可能會想要隱藏特定違規實例。 請考慮未來程式代碼不會自動豁免程式碼分析規則的範例。 某些程式代碼分析規則可讓您使用 MessageId 屬性的 SuppressMessageAttribute 屬性來隱藏違規的特定實例。 一般而言，特定符號上違規的舊版規則（局部變數或參數）會遵守 MessageId 屬性。 CA1500：VariableNamesShouldNotMatchFieldNames 是這類規則的範例。 不過，用於違規的舊版規則不適用於可執行程式碼（非符號）且不遵守 MessageId 屬性。 此外，.NET 編譯程序平臺 （“Roslyn”） 分析器不會遵守 MessageId 屬性。

若要隱藏規則的特定符號違規，請為 MessageId 屬性的 SuppressMessageAttribute 屬性指定符號名稱。 下列範例顯示了兩個違反 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

全域層級抑制

Managed 程式代碼分析工具會分析應用在元件、模組、類型、成員或參數層級的 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 分析器規則