Partilhar via

CA1819: As propriedades não devem retornar matrizes

  • Artigo
Propriedade valor
ID da regra CA1819
Cargo As propriedades não devem retornar matrizes
Categoria Desempenho
A correção está quebrando ou não quebrando Quebrando
Habilitado por padrão no .NET 8 Não

Causa

Uma propriedade retorna uma matriz.

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

Descrição da regra

As matrizes retornadas pelas propriedades não são protegidas contra gravação, mesmo que a propriedade seja somente leitura. Para manter a matriz inviolável, a propriedade deve retornar uma cópia da matriz. Normalmente, os usuários não entenderão as implicações de desempenho adverso de chamar tal 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 Attribute classe. Os atributos podem conter propriedades que retornam matrizes, mas não podem conter propriedades que retornam coleções.

Você pode suprimir o aviso se a propriedade fizer parte de uma classe DTO (Data Transfer Object).

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

Suprimir um aviso

Se você quiser apenas suprimir uma única violação, adicione diretivas de pré-processador ao seu arquivo de origem para desativar e, em seguida, reativar 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 para um arquivo, pasta ou projeto, defina sua severidade como none no arquivo de configuração.

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

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

Configurar código para análise

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

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

Incluir superfícies de API específicas

Você pode configurar em quais partes da sua base de código executar essa regra, com base em sua acessibilidade. Por exemplo, para especificar que a regra deve ser executada somente na superfície de API não pública, adicione o seguinte par chave-valor a um arquivo .editorconfig em seu projeto:

dotnet_code_quality.CAXXXX.api_surface = private, internal

Exemplo de violação

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

Alterar 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

Talvez você queira 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; }
    }
}