CA1819: Propriedades não devem retornar matrizes

Causa

Uma propriedade retorna uma matriz.

Por padrão, essa regra analisa apenas propriedades e tipos visíveis externamente, mas isso é configurável.

Descrição da regra

Matrizes retornadas por propriedades não são protegidas contra gravação, mesmo que a propriedade seja somente leitura. Para manter a matriz à prova de adulteração, a propriedade deve retornar uma cópia da matriz. Normalmente, os usuários não entenderão as implicações adversas de desempenho de chamar essa propriedade. Especificamente, eles podem usar a propriedade como uma propriedade indexada.

Como corrigir violações

Para corrigir uma violação dessa regra, torne a propriedade um método ou altere a propriedade para retornar uma coleção.

Quando suprimir avisos

Você pode suprimir um aviso gerado para uma propriedade de um atributo derivado da classe Attribute. Os atributos podem conter propriedades que retornam matrizes, mas não podem conter propriedades que retornam coleções.

É possível suprimir o aviso se a propriedade fizer parte de uma classe DTO (Objeto de Transferência de Dados).

Caso contrário, não suprima um aviso dessa regra.

Suprimir um aviso

Para suprimir apenas uma violação, adicione diretivas de pré-processador ao arquivo de origem a fim de desabilitar e, em seguida, reabilitar a regra.

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

Para desabilitar a regra em um arquivo, uma pasta ou um projeto, defina a severidade como none no arquivo de configuração.

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

Para obter mais informações, confira Como suprimir avisos de análise de código.

Configurar código para analisar

Use a opção a seguir para configurar em quais partes da base de código essa regra deve ser executada.

• Incluir superfícies de API específicas

Você pode configurar essa opção apenas para essa regra, para todas as regras às quais ela se aplica ou para todas as regras nessa categoria (Desempenho) às quais ela se aplica. Para saber mais, confira Opções de configuração de regra de qualidade de código.

Incluir superfícies de API específicas

É possível configurar em quais partes da base de código essa regra deverá ser executada, com base na acessibilidade. Por exemplo, para especificar que a regra deve ser executada apenas na superfície de API não pública, adicione o seguinte par chave-valor a um arquivo .editorconfig no projeto:

dotnet_code_quality.CAXXXX.api_surface = private, internal

Violação de exemplo

O exemplo a seguir mostra uma propriedade que viola essa regra:

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

Para corrigir uma violação dessa regra, torne a propriedade um método ou altere a propriedade para retornar uma coleção em vez de uma matriz.

Alterar a propriedade para um método

O exemplo a seguir corrige a violação alterando a propriedade para um método:

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

Altere a propriedade para retornar uma coleção

O exemplo a seguir corrige a violação alterando a propriedade para retornar um 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

Permitir que os usuários modifiquem uma propriedade

Você pode permitir que o consumidor da classe modifique uma propriedade. O exemplo a seguir mostra uma propriedade de leitura/gravação que viola essa regra:

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

O exemplo a seguir corrige a violação alterando a propriedade para retornar um 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; }
    }
}

Regras relacionadas

• CA1024: Usar propriedades quando apropriado