CA1819: Właściwości nie powinny zwracać tablic

Przyczyna

Właściwość zwraca tablicę.

Domyślnie ta reguła analizuje tylko właściwości i typy widoczne zewnętrznie, ale można to skonfigurować.

Opis reguły

Tablice zwracane przez właściwości nie są chronione przed zapisem, nawet jeśli właściwość jest tylko do odczytu. Aby zachować tablicę odporną na manipulacje, właściwość musi zwracać kopię tablicy. Zazwyczaj użytkownicy nie rozumieją negatywnych skutków związanych z wydajnością wywoływania takiej właściwości. W szczególności mogą używać właściwości jako właściwości indeksowanej.

Jak naprawić naruszenia

Aby naprawić naruszenie tej reguły, ustaw właściwość jako metodę lub zmień właściwość, aby zwrócić kolekcję.

Kiedy pomijać ostrzeżenia

Można pominąć ostrzeżenie, które jest wywoływane dla właściwości atrybutu pochodzącego Attribute z klasy. Atrybuty mogą zawierać właściwości zwracające tablice, ale nie mogą zawierać właściwości, które zwracają kolekcje.

Ostrzeżenie można pominąć, jeśli właściwość jest częścią klasy obiektu transferu danych (DTO ).

W przeciwnym razie nie pomijaj ostrzeżenia z tej reguły.

Pomijanie ostrzeżenia

Jeśli chcesz po prostu pominąć pojedyncze naruszenie, dodaj dyrektywy preprocesora do pliku źródłowego, aby wyłączyć, a następnie ponownie włączyć regułę.

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

Aby wyłączyć regułę dla pliku, folderu lub projektu, ustaw jego ważność na none w pliku konfiguracji.

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

Aby uzyskać więcej informacji, zobacz Jak pominąć ostrzeżenia dotyczące analizy kodu.

Konfigurowanie kodu do analizowania

Użyj następującej opcji, aby skonfigurować, które części bazy kodu mają być uruchamiane w tej regule.

• Uwzględnij określone powierzchnie interfejsu API

Tę opcję można skonfigurować tylko dla tej reguły, dla wszystkich reguł, do których ma ona zastosowanie, lub dla wszystkich reguł w tej kategorii (wydajność), których dotyczy. Aby uzyskać więcej informacji, zobacz Opcje konfiguracji reguły jakości kodu.

Uwzględnij określone powierzchnie interfejsu API

Możesz skonfigurować, na których częściach bazy kodu ma być uruchamiana ta reguła, na podstawie ich ułatwień dostępu. Aby na przykład określić, że reguła powinna być uruchamiana tylko na powierzchni niepublicznego interfejsu API, dodaj następującą parę klucz-wartość do pliku editorconfig w projekcie:

dotnet_code_quality.CAXXXX.api_surface = private, internal

Przykładowe naruszenie

W poniższym przykładzie przedstawiono właściwość, która narusza tę regułę:

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

Aby naprawić naruszenie tej reguły, ustaw właściwość jako metodę lub zmień właściwość tak, aby zwracała kolekcję zamiast tablicy.

Zmienianie właściwości na metodę

Poniższy przykład naprawia naruszenie, zmieniając właściwość na metodę:

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

Zmienianie właściwości w celu zwrócenia kolekcji

Poniższy przykład naprawia naruszenie przez zmianę właściwości w celu zwrócenia elementu 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

Zezwalanie użytkownikom na modyfikowanie właściwości

Możesz zezwolić użytkownikowi klasy na modyfikowanie właściwości. W poniższym przykładzie przedstawiono właściwość odczytu/zapisu, która narusza tę regułę:

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

Poniższy przykład naprawia naruszenie przez zmianę właściwości w celu zwrócenia elementu 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; }
    }
}

Powiązane reguły

• CA1024: Używaj właściwości wszędzie tam, gdzie jest to odpowiednie