CA1819 : Les propriétés ne doivent pas retourner des tableaux

  • Article
Propriété Value
Identificateur de la règle CA1819
Titre Les propriétés ne doivent pas retourner des tableaux
Catégorie Performances
Le correctif est cassant ou non cassant Rupture
Activé par défaut dans .NET 8 Non

Cause

Une propriété retourne un tableau.

Par défaut, cette règle examine uniquement les types et propriétés visibles en externe, mais elle est configurable.

Description de la règle

Les tableaux retournés par des propriétés ne sont pas protégés en écriture, même si la propriété est en lecture seule. Pour protéger le tableau de toute falsification, la propriété doit retourner une copie du tableau. En général, les utilisateurs ne comprendront pas l’incidence négative en matière de performances de l’appel à une telle propriété. Plus spécifiquement, ils risquent d’utiliser la propriété en tant que propriété indexée.

Comment corriger les violations

Pour corriger une violation de cette règle, convertissez la propriété en méthode ou modifiez la propriété de façon à retourner une collection.

Quand supprimer les avertissements

Vous pouvez supprimer un avertissement déclenché pour une propriété d’un attribut dérivé de la classe Attribute. Les attributs peuvent contenir des propriétés qui retournent des tableaux, mais pas des propriétés qui retournent des collections.

Vous pouvez supprimer l’avertissement si la propriété fait partie d’une classe DTO (Data Transfer Object).

Autrement, ne supprimez pas un avertissement de cette règle.

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 CA1819
// The code that's violating the rule is on this line.
#pragma warning restore CA1819

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.CA1819.severity = none

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

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 elle s’applique ou pour toutes les règles de cette catégorie (Performances) auxquelles elle s’applique. Pour plus d’informations, consultez Options de configuration des règles de qualité du code.

Inclure des surfaces d’API spécifiques

Vous pouvez configurer les parties de votre codebase sur lesquelles exécuter cette règle, en fonction de leur accessibilité. Par exemple, pour spécifier que la règle doit s’exécuter uniquement sur la surface d’API non publique, ajoutez la paire clé-valeur suivante à un fichier .editorconfig dans votre projet :

dotnet_code_quality.CAXXXX.api_surface = private, internal

Exemple de violation

L’exemple suivant montre une propriété qui enfreint cette règle :

public class Book
{
    private string[] _Pages;

    public Book(string[] pages)
    {
        _Pages = pages;
    }

    public string[] Pages
    {
        get { return _Pages; }
    }
}

Public Class Book
    Public Sub New(ByVal pages As String())
        Me.Pages = pages
    End Sub

    Public ReadOnly Property Pages() As String()
End Class

Pour corriger une violation de cette règle, convertissez la propriété en méthode ou modifiez la propriété de façon à retourner une collection plutôt qu’un tableau.

Convertir la propriété en méthode

L’exemple suivant corrige la violation en convertissant la propriété en méthode :

Public Class Book

    Private _Pages As String()

    Public Sub New(ByVal pages As String())
        _Pages = pages
    End Sub

    Public Function GetPages() As String()
        ' Need to return a clone of the array so that consumers            
        ' of this library cannot change its contents            
        Return DirectCast(_Pages.Clone(), String())
    End Function

End Class

public class Book
{
    private string[] _Pages;

    public Book(string[] pages)
    {
        _Pages = pages;
    }

    public string[] GetPages()
    {
        // Need to return a clone of the array so that consumers            
        // of this library cannot change its contents            
        return (string[])_Pages.Clone();
    }
}

Modifier la propriété de façon à retourner une collection

L’exemple suivant corrige la violation en modifiant la propriété de façon à retourner une System.Collections.ObjectModel.ReadOnlyCollection<T> :

public class Book
{
    private ReadOnlyCollection<string> _Pages;
    public Book(string[] pages)
    {
        _Pages = new ReadOnlyCollection<string>(pages);
    }

    public ReadOnlyCollection<string> Pages
    {
        get { return _Pages; }
    }
}

Public Class Book
    Public Sub New(ByVal pages As String())
        Me.Pages = New ReadOnlyCollection(Of String)(pages)
    End Sub

    Public ReadOnly Property Pages() As ReadOnlyCollection(Of String)

End Class

Autoriser les utilisateurs à modifier une propriété

Vous souhaiterez peut-être autoriser le consommateur de la classe à modifier une propriété. L’exemple suivant montre une propriété en lecture/écriture qui enfreint cette règle :

public class Book
{
    private string[] _Pages;

    public Book(string[] pages)
    {
        _Pages = pages;
    }

    public string[] Pages
    {
        get { return _Pages; }
        set { _Pages = value; }
    }
}

Public Class Book
    Public Sub New(ByVal pages As String())
        Me.Pages = pages
    End Sub

    Public Property Pages() As String()

End Class

L’exemple suivant corrige la violation en modifiant la propriété de façon à retourner une System.Collections.ObjectModel.Collection<T> :

Public Class Book
    Public Sub New(ByVal pages As String())
        Me.Pages = New Collection(Of String)(pages)
    End Sub

    Public ReadOnly Property Pages() As Collection(Of String)
End Class

public class Book
{
    private Collection<string> _Pages;

    public Book(string[] pages)
    {
        _Pages = new Collection<string>(pages);
    }

    public Collection<string> Pages
    {
        get { return _Pages; }
    }
}