CA1819: свойства не должны возвращать массивы

  • Статья
Свойство Значение
Идентификатор правила CA1819
Заголовок Свойства не должны возвращать массивы
Категория Производительность
Исправление является критическим или не критическим Критическое
Включен по умолчанию в .NET 8 No

Причина

Свойство возвращает массив.

По умолчанию это правило проверяет только видимые извне свойства и типы, но это поведение можно настроить.

Описание правила

Массивы, возвращаемые свойствами, не защищены от записи, даже если свойство доступно только для чтения. Чтобы защитить массив от изменений, свойство должно возвращать копию массива. Как правило, пользователи не понимают требований к производительности при вызове такого свойства. В частности, они могут использовать свойство в качестве индексированного свойства.

Устранение нарушений

Чтобы устранить нарушение этого правила, либо сделайте свойство методом, либо измените свойство так, чтобы оно возвращало коллекцию.

Когда лучше отключить предупреждения

Предупреждение, возникающее для свойства атрибута, производного от класса Attribute, можно отключить. Атрибуты могут содержать свойства, которые возвращают массивы, но не могут содержать свойства, возвращающие коллекции.

Предупреждение можно отключить, если свойство является частью класса объекта передачи данных (DTO).

В противном случае для этого правила отключать вывод предупреждений не следует.

Отключение предупреждений

Если вы просто хотите отключить одно нарушение, добавьте директивы препроцессора в исходный файл, чтобы отключить и повторно включить правило.

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

Чтобы отключить правило для файла, папки или проекта, задайте его серьезность none в файле конфигурации.

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

Дополнительные сведения см. в разделе Практическое руководство. Скрытие предупреждений анализа кода.

Настройка кода для анализа

Используйте следующий параметр, чтобы выбрать части базы кода для применения этого правила.

Этот параметр можно настроить только для этого правила, для всех правил, к которым он применяется, или для всех правил в этой категории (производительности), к которым она применяется. Дополнительные сведения см. в статье Параметры конфигурации правила качества кода.

Включение определенных контактных зон API

Вы можете настроить, для каких частей базы кода следует выполнять это правило в зависимости от их доступности. Например, чтобы указать, что правило должно выполняться только для закрытой контактной зоны API, добавьте следующую пару "ключ-значение" в файл EDITORCONFIG в своем проекте:

dotnet_code_quality.CAXXXX.api_surface = private, internal

Пример нарушения

В следующем примере показано свойство, нарушающее это правило:

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

Чтобы устранить нарушение этого правила, либо сделайте свойство методом, либо измените свойство так, чтобы оно возвращало коллекцию, а не массив.

Преобразование свойства в метод

В следующем примере нарушение устраняется путем преобразования свойства в метод:

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

Изменение свойства для возврата коллекции

В следующем примере нарушение устраняется путем изменения свойства для возврата 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

Разрешение пользователям изменять свойство

Может потребоваться разрешить потребителю класса изменять свойство. В следующем примере показано свойство для чтения и записи, нарушающее это правило:

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

В следующем примере нарушение устраняется путем изменения свойства для возврата 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; }
    }
}