CA1501:避免在物件間過度繼承

發行項
11/14/2023

屬性	值
規則識別碼	CA1501
職稱	避免在物件間過度繼承
類別	可維護性
修正程式是中斷或非中斷	中斷
默認閾值	5
預設在 .NET 9 中啟用	No

原因

類型是其繼承階層中的五個以上層級。

檔案描述

太深的巢狀類型階層架構可能會難以依循、了解和維護。此規則會將分析限制為相同課程模組中的階層。

您可以透過下列方式設定此規則：

根據預設，規則會從 System 命名空間中排除類型。您也可以設定規則來排除其他類型的或命名空間。
您可以設定此規則引發的繼承樹狀結構深度。

如何修正違規

若要修正此規則的違規，請從繼承階層中較不深的基底類型衍生類型，或排除某些中繼基底類型。

隱藏警告的時機

隱藏此規則的警告是安全的。不過，程式代碼可能更難維護。根據基底類型的可見度，解決此規則的違規可能會造成重大變更。例如，移除公用基底類型是重大變更。

注意

如果適用下列所有專案，您可能會看到來自此規則的誤判警告：

您使用 Visual Studio 2022 17.5 版或更新版本搭配舊版 .NET SDK，也就是 .NET 6 或更早版本。
您使用的是 .NET 6 SDK 或舊版分析器套件的分析器，例如 Microsoft.CodeAnalysis.FxCopAnalyzers。

誤判是由於 C# 編譯程式中的重大變更所造成。請考慮使用包含誤判警告修正的較新分析器。升級至 Microsoft.CodeAnalysis.NetAnalyzers 7.0.0-preview1.22464.1 版或更新版本，或使用 .NET 7 SDK 的分析器。

隱藏警告

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

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

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

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

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

設定臨界值

您可以設定此規則引發的臨界值。

建立名為 CodeMetricsConfig.txt 的文字檔。
以下列格式將所需的臨界值新增至文字檔：
```
CA1501: 8
```
在此範例中，當類型在其繼承階層中深度為八個或多個層級時，規則會設定為引發。
在項目檔中，將組態檔的建置動作標示為 AdditionalFiles。例如：
```
<ItemGroup>
  <AdditionalFiles Include="CodeMetricsConfig.txt" />
</ItemGroup>
```

設定程式代碼以分析

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

繼承排除的類型或命名空間名稱

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

繼承排除的類型或命名空間名稱

您可以將規則設定為從繼承階層樹狀結構中排除特定類型或命名空間。根據預設，會排除命名空間中的所有類型 System.* 。無論您設定的值為何，這個預設值會新增。

選項值	摘要
`dotnet_code_quality.CA1501.additional_inheritance_excluded_symbol_names = MyType`	比對名稱為 `MyType` 或包含命名空間的所有 `MyType` 類型（以及命名空間中的所有 `System` 類型）
`dotnet_code_quality.CA1501.additional_inheritance_excluded_symbol_names = MyType1\|MyType2`	比對名為 `MyType1` 或或且包含命名空間的所有型別包含 `MyType1` 或 `MyType2` `MyType2` （以及命名空間中的所有`System`類型）
`dotnet_code_quality.CA1501.additional_inheritance_excluded_symbol_names = T:NS.MyType`	符合命名空間`NS`中的特定類型`MyType`（以及命名空間中的所有`System`類型）
`dotnet_code_quality.CA1501.additional_inheritance_excluded_symbol_names = T:NS1.MyType1\|T:NS2.MyType2`	比對特定類型和`MyType1MyType2`個別的完整名稱（以及命名空間中的所有`System`類型）
`dotnet_code_quality.CA1501.additional_inheritance_excluded_symbol_names = N:NS`	符合命名空間中的所有類型 `NS` （以及命名空間中的所有 `System` 類型）
`dotnet_code_quality.CA1501.additional_inheritance_excluded_symbol_names = My*`	比對名稱開頭 `My` 為或包含命名空間部分 `My` 開頭的所有類型（以及命名空間中的所有 `System` 類型）
`dotnet_code_quality.CA1501.additional_inheritance_excluded_symbol_names = T:NS.My*`	比對名稱以命名空間`NS`開頭`My`的所有類型（以及命名空間中的所有`System`類型）
`dotnet_code_quality.CA1501.additional_inheritance_excluded_symbol_names = N:My*`	比對包含命名空間的所有類型開頭 `My` 為（以及命名空間中的所有 `System` 類型）

範例

下列範例顯示違反規則的類型：

class BaseClass {}
class FirstDerivedClass : BaseClass {}
class SecondDerivedClass : FirstDerivedClass {}
class ThirdDerivedClass : SecondDerivedClass {}
class FourthDerivedClass : ThirdDerivedClass {}

// This class violates the rule.
class FifthDerivedClass : FourthDerivedClass {}

Imports System

Namespace ca1501

    Class BaseClass
    End Class

    Class FirstDerivedClass
        Inherits BaseClass
    End Class

    Class SecondDerivedClass
        Inherits FirstDerivedClass
    End Class

    Class ThirdDerivedClass
        Inherits SecondDerivedClass
    End Class

    Class FourthDerivedClass
        Inherits ThirdDerivedClass
    End Class

    ' This class violates the rule.
    Class FifthDerivedClass
        Inherits FourthDerivedClass
    End Class

End Namespace

共用方式為