Sdílet prostřednictvím

CA1819: Vlastnosti by neměly vracet pole

  • Článek
Vlastnost Hodnota
ID pravidla CA1819
Název Vlastnosti by neměly vracet pole
Kategorie Výkon
Oprava způsobující chybu nebo chybu způsobující chybu Narušující
Povoleno ve výchozím nastavení v .NET 8 No

Příčina

Vlastnost vrátí matici.

Ve výchozím nastavení toto pravidlo sleduje pouze externě viditelné vlastnosti a typy, ale dá se konfigurovat.

Popis pravidla

Pole vrácená vlastnostmi nejsou chráněna proti zápisu, i když je vlastnost jen pro čtení. Abyste pole ochránili před změnou, musí vlastnost vrátit kopii tohoto pole. Uživatelé obvykle nebudou rozumět nepříznivým dopadům na výkon volání takové vlastnosti. Konkrétně mohou tuto vlastnost použít jako indexovanou vlastnost.

Jak opravit porušení

Chcete-li opravit porušení tohoto pravidla, proveďte vlastnost metodu nebo změňte vlastnost na vrácení kolekce.

Kdy potlačit upozornění

Můžete potlačit upozornění, které je vyvolány pro vlastnost atributu odvozeného z Attribute třídy. Atributy mohou obsahovat vlastnosti, které vracejí pole, ale nemohou obsahovat vlastnosti, které vracejí kolekce.

Upozornění můžete potlačit, pokud je vlastnost součástí třídy DTO (Data Transfer Object).

Jinak nepotlačujte upozornění z tohoto pravidla.

Potlačení upozornění

Pokud chcete pouze potlačit jedno porušení, přidejte do zdrojového souboru direktivy preprocesoru, abyste pravidlo zakázali a znovu povolili.

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

Pokud chcete pravidlo pro soubor, složku nebo projekt zakázat, nastavte jeho závažnost v none konfiguračním souboru.

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

Další informace naleznete v tématu Jak potlačit upozornění analýzy kódu.

Konfigurace kódu pro analýzu

Pomocí následující možnosti nakonfigurujte, ve kterých částech základu kódu se má toto pravidlo spouštět.

Tuto možnost můžete nakonfigurovat jenom pro toto pravidlo, pro všechna pravidla, která platí, nebo pro všechna pravidla v této kategorii (Výkon), na která platí. Další informace naleznete v tématu Možnosti konfigurace pravidla kvality kódu.

Zahrnutí konkrétních povrchů rozhraní API

Na základě přístupnosti můžete nakonfigurovat, na kterých částech základu kódu se má toto pravidlo spouštět. Pokud chcete například určit, že pravidlo by se mělo spouštět jenom na neveřejné ploše rozhraní API, přidejte do souboru .editorconfig v projektu následující pár klíč-hodnota:

dotnet_code_quality.CAXXXX.api_surface = private, internal

Příklad porušení

Následující příklad ukazuje vlastnost, která porušuje toto pravidlo:

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

Chcete-li opravit porušení tohoto pravidla, proveďte vlastnost metodu nebo změňte vlastnost tak, aby vrátila kolekci místo pole.

Změna vlastnosti na metodu

Následující příklad opravuje porušení změnou vlastnosti na metodu:

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

Změna vlastnosti tak, aby vrátila kolekci

Následující příklad opravuje porušení změnou vlastnosti na vrácení 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

Povolit uživatelům úpravu vlastnosti

Je možné, že chcete uživateli třídy povolit úpravu vlastnosti. Následující příklad ukazuje vlastnost pro čtení a zápis, která porušuje toto pravidlo:

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

Následující příklad opravuje porušení změnou vlastnosti na vrácení 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; }
    }
}