CA1819: Le proprietà non devono restituire matrici

Causa

Una proprietà restituisce una matrice.

Per impostazione predefinita, questa regola esamina solo le proprietà e i tipi visibili esternamente, ma è configurabile.

Descrizione regola

Le matrici restituite dalle proprietà non sono protette da scrittura, anche se la proprietà è di sola lettura. Affinché la matrice sia protetta da eventuali alterazioni, la proprietà deve restituire una copia della matrice. In genere, gli utenti non comprenderanno le implicazioni negative sulle prestazioni della chiamata di una proprietà di questo tipo. In particolare, possono usare la proprietà come proprietà indicizzata.

Come correggere le violazioni

Per correggere una violazione di questa regola, impostare la proprietà su un metodo o modificare la proprietà per restituire una raccolta.

Quando eliminare gli avvisi

È possibile eliminare un avviso generato per una proprietà di un attributo derivato dalla Attribute classe . Gli attributi possono contenere proprietà che restituiscono ma non possono contenere proprietà che restituiscono raccolte.

È possibile eliminare l'avviso se la proprietà fa parte di una classe DTO (Data Transfer Object).

In caso contrario, non eliminare un avviso da questa regola.

Eliminare un avviso

Se si vuole eliminare una singola violazione, aggiungere direttive del preprocessore al file di origine per disabilitare e quindi riabilitare la regola.

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

Per disabilitare la regola per un file, una cartella o un progetto, impostarne la gravità none su nel file di configurazione.

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

Per altre informazioni, vedere Come eliminare gli avvisi di analisi del codice.

Configurare il codice da analizzare

Usare l'opzione seguente per configurare le parti della codebase in cui eseguire questa regola.

• Includere superfici API specifiche

È possibile configurare questa opzione solo per questa regola, per tutte le regole a cui si applica o per tutte le regole di questa categoria (prestazioni) a cui si applica. Per altre informazioni, vedere Opzioni di configurazione delle regole di qualità del codice.

Includere superfici API specifiche

È possibile configurare le parti della codebase in modo da eseguire questa regola in base all'accessibilità. Ad esempio, per specificare che la regola deve essere eseguita solo sulla superficie dell'API non pubblica, aggiungere la coppia chiave-valore seguente a un file con estensione editorconfig nel progetto:

dotnet_code_quality.CAXXXX.api_surface = private, internal

Violazione di esempio

L'esempio seguente mostra una proprietà che viola questa regola:

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

Per correggere una violazione di questa regola, impostare la proprietà su un metodo o modificare la proprietà in modo da restituire una raccolta anziché una matrice.

Modificare la proprietà in un metodo

Nell'esempio seguente viene risolta la violazione modificando la proprietà in un metodo :

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

Modificare la proprietà per restituire una raccolta

Nell'esempio seguente viene risolta la violazione modificando la proprietà in modo da restituire un oggetto 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

Consentire agli utenti di modificare una proprietà

È possibile consentire al consumer della classe di modificare una proprietà. L'esempio seguente mostra una proprietà di lettura/scrittura che viola questa regola:

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

Nell'esempio seguente viene risolta la violazione modificando la proprietà in modo da restituire un oggetto 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; }
    }
}

Regole correlate

• CA1024: Usare proprietà dove appropriato