CA1501:避免过度继承

项目
08/01/2023

属性	值
规则 ID	CA1501
标题	避免过度继承
类别	可维护性
修复是中断修复还是非中断修复	重大
默认阈值	5
在 .NET 8 中默认启用	否

原因

类型在继承层次结构中的深度超过五级。

规则说明

深度嵌套的类型层次结构可能很难遵循、理解和维护。此规则将分析限制在同一模块内的层次结构中。

可以按下列方式配置此规则：

默认情况下，此规则将排除 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
```
在此示例中，规则配置为在类型在其继承层次结构中深达 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` 或 `MyType2` 的类型，或其命名空间包含 `MyType1` 或 `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`	匹配具有相应的完全限定名称的特定类型 `MyType1` 和 `MyType2`（以及 `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