Dela via

CA1819: Egenskaper bör inte returnera matriser

  • Artikel
Property Värde
Regel-ID CA1819
Title Egenskaper bör inte returnera matriser
Kategori Prestanda
Korrigeringen är icke-bakåtkompatibel Brott
Aktiverad som standard i .NET 9 Nej

Orsak

En egenskap returnerar en matris.

Som standard tittar den här regeln bara på externt synliga egenskaper och typer, men det kan konfigureras.

Regelbeskrivning

Matriser som returneras av egenskaper är inte skrivskyddade, även om egenskapen är skrivskyddad. För att hålla matrisen manipulationssäker måste egenskapen returnera en kopia av matrisen. Vanligtvis förstår användarna inte de negativa prestandakonsekvenserna av att anropa en sådan egenskap. Mer specifikt kan de använda egenskapen som en indexerad egenskap.

Så här åtgärdar du överträdelser

Om du vill åtgärda ett brott mot den här regeln gör du antingen egenskapen till en metod eller ändrar egenskapen för att returnera en samling.

När du ska ignorera varningar

Du kan ignorera en varning som genereras för en egenskap för ett attribut som härleds från Attribute klassen. Attribut kan innehålla egenskaper som returnerar matriser, men får inte innehålla egenskaper som returnerar samlingar.

Du kan ignorera varningen om egenskapen ingår i en DTO-klass (Data Transfer Object).

Annars ska du inte ignorera en varning från den här regeln.

Ignorera en varning

Om du bara vill förhindra en enda överträdelse lägger du till förprocessordirektiv i källfilen för att inaktivera och aktiverar sedan regeln igen.

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

Om du vill inaktivera regeln för en fil, mapp eller ett projekt anger du dess allvarlighetsgrad till none i konfigurationsfilen.

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

Mer information finns i Så här utelämnar du kodanalysvarningar.

Konfigurera kod för analys

Använd följande alternativ för att konfigurera vilka delar av kodbasen som regeln ska köras på.

Du kan konfigurera det här alternativet för bara den här regeln, för alla regler som den gäller för eller för alla regler i den här kategorin (Prestanda) som den gäller för. Mer information finns i Konfigurationsalternativ för kodkvalitetsregel.

Inkludera specifika API-ytor

Du kan konfigurera vilka delar av kodbasen som ska köras med den här regeln baserat på deras tillgänglighet. Om du till exempel vill ange att regeln endast ska köras mot den icke-offentliga API-ytan lägger du till följande nyckel/värde-par i en .editorconfig-fil i projektet:

dotnet_code_quality.CAXXXX.api_surface = private, internal

Not

Ersätt den XXXX delen av CAXXXX med ID:t för den tillämpliga regeln.

Exempelöverträdelse

I följande exempel visas en egenskap som bryter mot den här regeln:

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

Om du vill åtgärda ett brott mot den här regeln gör du antingen egenskapen till en metod eller ändrar egenskapen så att den returnerar en samling i stället för en matris.

Ändra egenskapen till en metod

I följande exempel åtgärdas överträdelsen genom att egenskapen ändras till en metod:

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

Ändra egenskapen för att returnera en samling

I följande exempel åtgärdas överträdelsen genom att egenskapen ändras så att den returnerar en 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

Tillåt användare att ändra en egenskap

Du kanske vill tillåta att klassens användare ändrar en egenskap. I följande exempel visas en läs-/skrivegenskap som bryter mot den här regeln:

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

I följande exempel åtgärdas överträdelsen genom att egenskapen ändras så att den returnerar en 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; }
    }
}