Freigeben über

CA1819: Eigenschaften sollten keine Arrays zurückgeben.

  • Artikel
Eigenschaft Wert
Regel-ID CA1819
Titel Eigenschaften sollten keine Arrays zurückgeben.
Kategorie Leistung
Fix führt oder führt nicht zur Unterbrechung Breaking
Standardmäßig in .NET 9 aktiviert No

Ursache

Eine Eigenschaft gibt ein Array zurück.

Standardmäßig werden mit dieser Regel nur extern sichtbare Eigenschaften und Typen überprüft, aber dies ist konfigurierbar.

Regelbeschreibung

Von Eigenschaften zurückgegebene Arrays sind nicht schreibgeschützt, auch wenn die Eigenschaft schreibgeschützt ist. Damit das Array gegen Manipulationen geschützt bleibt, muss die Eigenschaft eine Kopie des Arrays zurückgeben. Normalerweise verstehen die Benutzer nicht, welche negativen Auswirkungen der Aufruf einer solchen Eigenschaft auf die Leistung hat. Insbesondere kann die Eigenschaft als indizierte Eigenschaft verwendet werden.

Behandeln von Verstößen

Um einen Verstoß gegen diese Regel zu beheben, stellen Sie entweder die Eigenschaft als Methode dar, oder ändern Sie die Eigenschaft, um eine Auflistung zurückzugeben.

Wann sollten Warnungen unterdrückt werden?

Sie können eine Warnung unterdrücken, die für eine Eigenschaft eines Attributs ausgelöst wird, das von der Attribute-Klasse abgeleitet ist. Attribute können Eigenschaften enthalten, die Arrays zurückgeben, aber keine Eigenschaften enthalten, die Auflistungen zurückgeben.

Sie können die Warnung unterdrücken, wenn die Eigenschaft Teil einer Datenübertragungsobjeks (DTO)-Klasse ist.

Andernfalls sollten Sie keine Warnung dieser Regel unterdrücken.

Unterdrücken einer Warnung

Um nur eine einzelne Verletzung zu unterdrücken, fügen Sie der Quelldatei Präprozessoranweisungen hinzu, um die Regel zu deaktivieren und dann wieder zu aktivieren.

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

Um die Regel für eine Datei, einen Ordner oder ein Projekt zu deaktivieren, legen Sie den Schweregrad in der Konfigurationsdatei auf none fest.

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

Weitere Informationen finden Sie unter Vorgehensweise: Unterdrücken von Codeanalyse-Warnungen.

Konfigurieren des zu analysierenden Codes

Mithilfe der folgenden Option können Sie konfigurieren, für welche Teile Ihrer Codebasis diese Regel ausgeführt werden soll.

Sie können diese Option nur für diese Regel, für alle zutreffenden Regeln oder für alle zutreffenden Regeln in dieser Kategorie (Leistung) konfigurieren. Weitere Informationen finden Sie unter Konfigurationsoptionen für die Codequalitätsregel.

Einschließen bestimmter API-Oberflächen

Sie können je nach Zugänglichkeit festlegen, für welche Bestandteile Ihrer Codebasis diese Regel ausgeführt wird. Sie können beispielsweise festlegen, dass die Regel nur für die nicht öffentliche API-Oberfläche ausgeführt werden soll, indem Sie einer EDITORCONFIG-Datei in Ihrem Projekt das folgende Schlüssel-Wert-Paar hinzufügen:

dotnet_code_quality.CAXXXX.api_surface = private, internal

Beispiel für einen Verstoß

Das folgende Beispiel zeigt eine Eigenschaft, die gegen diese Regel verstößt:

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

Um einen Verstoß gegen diese Regel zu beheben, stellen Sie entweder die Eigenschaft als Methode dar, oder ändern Sie die Eigenschaft, um eine Auflistung zurückzugeben, anstatt eines Arrays.

Ändern Sie die Eigenschaft in eine Methode

Im folgenden Beispiel wird die Verletzung durch Ändern der Eigenschaft in eine Methode behoben:

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();
    }
}

Ändern Sie die Eigenschaft, um eine Auflistung zurückzugeben

Im folgenden Beispiel wird die Verletzung durch Ändern der Eigenschaft in eine Methode behoben, um eine System.Collections.ObjectModel.ReadOnlyCollection<T> zurückzugeben:

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

Benutzern das Ändern einer Eigenschaft gestatten

Möglicherweise möchten Sie dem Consumer der Klasse gestatten, eine Eigenschaft zu ändern. Das folgende Beispiel zeigt eine Lesen-/Schreiben-Eigenschaft, die gegen diese Regel verstößt:

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

Im folgenden Beispiel wird die Verletzung durch Ändern der Eigenschaft in eine Methode behoben, um eine System.Collections.ObjectModel.Collection<T> zurückzugeben:

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; }
    }
}