CA1501 : Éviter l'excès d'héritage

Propriété Value
Identificateur de la règle CA1501
Titre Éviter l'excès d'héritage
Catégorie Maintenabilité
Le correctif est cassant ou non cassant Rupture
Seuil par défaut 5
Activé par défaut dans .NET 8 Non

Cause

Un type est imbriqué de cinq niveaux ou plus dans sa hiérarchie d'héritage.

Description de la règle

Les hiérarchies de type profondément imbriquées peuvent être difficiles à suivre, comprendre et gérer. Cette règle limite l’analyse aux hiérarchies du même module.

Vous pouvez configurer cette règle de la façon suivante :

Comment corriger les violations

Pour corriger une violation de cette règle, dérivez le type d’un type de base moins profond dans la hiérarchie d’héritage ou supprimez certains des types de bases intermédiaires.

Quand supprimer les avertissements

Vous pouvez supprimer un avertissement de cette règle. Toutefois, le code peut être plus difficile à maintenir. Selon la visibilité des types de base, la résolution des violations de cette règle peut créer des changements cassants. Par exemple, la suppression de types de base publics est un changement cassant.

Remarque

Vous pouvez voir des avertissements de faux positifs de cette règle si tous les éléments suivants s’appliquent :

  • Vous utilisez Visual Studio 2022 version 17.5 ou ultérieure avec une version antérieure du Kit de développement logiciel (SDK) .NET, c’est-à-dire .NET 6 ou version antérieure.
  • Vous utilisez les analyseurs du Kit de développement logiciel (SDK) .NET 6 ou d’une version antérieure des packages d’analyseurs, comme Microsoft.CodeAnalysis.FxCopAnalyzers.

Les faux positifs sont dus à un changement cassant dans le compilateur C#. Envisagez d’utiliser un analyseur plus récent qui contient le correctif pour les avertissements faux positifs. Effectuez une mise à niveau vers Microsoft.CodeAnalysis.NetAnalyzers version 7.0.0-préversion1.22464.1 ou ultérieure ou utilisez les analyseurs du Kit de développement logiciel (SDK) .NET 7.

Supprimer un avertissement

Si vous voulez supprimer une seule violation, ajoutez des directives de préprocesseur à votre fichier source pour désactiver et réactiver la règle.

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

Pour désactiver la règle sur un fichier, un dossier ou un projet, définissez sa gravité sur none dans le fichier de configuration.

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

Pour plus d’informations, consultez Comment supprimer les avertissements de l’analyse de code.

Configurer le seuil

Vous pouvez configurer le seuil auquel cette règle se déclenche.

  1. Créez un fichier texte nommé CodeMetricsConfig.txt.

  2. Ajoutez le seuil souhaité au fichier texte au format suivant :

    CA1501: 8
    

    Dans cet exemple, la règle est configurée pour être déclenchée lorsqu’un type se trouve à huit niveaux de profondeur ou plus dans sa hiérarchie d’héritage.

  3. Dans le fichier projet, marquez l’action de génération du fichier config comme AdditionalFiles. Par exemple :

    <ItemGroup>
      <AdditionalFiles Include="CodeMetricsConfig.txt" />
    </ItemGroup>
    

Configurer le code à analyser

Utilisez l’option suivante pour configurer les parties de votre codebase sur lesquelles exécuter cette règle.

Vous pouvez configurer cette option pour cette règle uniquement, pour toutes les règles auxquelles elles s’appliquent ou pour toutes les règles de cette catégorie (Maintenabilité) auxquelles elles s’appliquent. Pour plus d’informations, consultez Options de configuration des règles de qualité du code.

Noms de type ou d’espace de noms exclus de l’héritage

Vous pouvez configurer la règle pour exclure certains types ou espaces de noms de l’arborescence de la hiérarchie d’héritage. Par défaut, tous les types de l’espace de noms System.* sont exclus. Quelle que soit la valeur que vous définissez, cette valeur par défaut est ajoutée.

Valeur d’option Récapitulatif
dotnet_code_quality.CA1501.additional_inheritance_excluded_symbol_names = MyType Correspond à tous les types nommés MyType ou dont l’espace de noms MyType contient (et tous les types de l’espace de noms System)
dotnet_code_quality.CA1501.additional_inheritance_excluded_symbol_names = MyType1|MyType2 Correspond à tous les types nommés MyType1 ou MyType2 dont l’espace de noms contient MyType1 ou MyType2 ( et tous les types de l’espace de noms System)
dotnet_code_quality.CA1501.additional_inheritance_excluded_symbol_names = T:NS.MyType Correspond à un type MyType spécifique dans l’espace de noms NS (et tous les types de l’espace System de noms)
dotnet_code_quality.CA1501.additional_inheritance_excluded_symbol_names = T:NS1.MyType1|T:NS2.MyType2 Correspond aux types spécifiques MyType1 et MyType2 avec des noms complets respectifs (et tous les types de l’espace de noms System)
dotnet_code_quality.CA1501.additional_inheritance_excluded_symbol_names = N:NS Correspond à tous les types de l’espace de noms NS (et tous les types de l’espace de noms System)
dotnet_code_quality.CA1501.additional_inheritance_excluded_symbol_names = My* Correspond à tous les types dont le nom commence par My ou dont les parties d’espaces de noms contenant commencent par My (et tous les types de l’espace de noms System)
dotnet_code_quality.CA1501.additional_inheritance_excluded_symbol_names = T:NS.My* Correspond à tous les types dont le nom commence par My dans l’espace de noms NS (et tous les types de l’espace de noms System)
dotnet_code_quality.CA1501.additional_inheritance_excluded_symbol_names = N:My* Correspond à tous les types dont l’espace de noms commence par My (et tous les types de l’espace de noms System)

Exemple

L’exemple suivant montre un type qui enfreint la règle :

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