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

Article
02/01/2024

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ée par défaut dans .NET 9	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 :

Par défaut, la règle exclut les types de l’espace de noms System. Vous pouvez configurer également la règle pour exclure d’autres types ou espaces de noms.
Vous pouvez configurer la profondeur de l’arborescence d’héritage à laquelle cette règle se déclenche.

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.

Créez un fichier texte nommé CodeMetricsConfig.txt.
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.
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.

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

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

Partager via