CA1819: Eigenschappen mogen geen matrices retourneren

Oorzaak

Een eigenschap retourneert een matrix.

Deze regel kijkt standaard alleen naar extern zichtbare eigenschappen en typen, maar dit kan worden geconfigureerd.

Beschrijving van regel

Matrices die door eigenschappen worden geretourneerd, zijn niet beveiligd tegen schrijven, zelfs niet als de eigenschap het kenmerk Alleen-lezen heeft. Als u de matrix manipulatiebestendig wilt houden, moet de eigenschap een kopie van de matrix retourneren. Normaal gesproken begrijpen gebruikers de negatieve gevolgen van het aanroepen van een dergelijke eigenschap niet. Ze kunnen de eigenschap gebruiken als een geïndexeerde eigenschap.

Schendingen oplossen

Als u een schending van deze regel wilt oplossen, maakt u de eigenschap een methode of wijzigt u de eigenschap om een verzameling te retourneren.

Wanneer waarschuwingen onderdrukken

U kunt een waarschuwing onderdrukken die wordt gegenereerd voor een eigenschap van een kenmerk dat is afgeleid van de Attribute klasse. Kenmerken kunnen eigenschappen bevatten die matrices retourneren, maar kunnen geen eigenschappen bevatten die verzamelingen retourneren.

U kunt de waarschuwing onderdrukken als de eigenschap deel uitmaakt van een DTO-klasse (Data Transfer Object).

Anders onderdrukt u geen waarschuwing van deze regel.

Een waarschuwing onderdrukken

Als u slechts één schending wilt onderdrukken, voegt u preprocessorrichtlijnen toe aan uw bronbestand om de regel uit te schakelen en vervolgens opnieuw in te schakelen.

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

Als u de regel voor een bestand, map of project wilt uitschakelen, stelt u de ernst none ervan in op het configuratiebestand.

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

Zie Codeanalysewaarschuwingen onderdrukken voor meer informatie.

Code configureren om te analyseren

Gebruik de volgende optie om te configureren op welke onderdelen van uw codebase deze regel moet worden uitgevoerd.

• Specifieke API-oppervlakken opnemen

U kunt deze optie configureren voor alleen deze regel, voor alle regels waarop deze van toepassing is, of voor alle regels in deze categorie (prestaties) waarop deze van toepassing is. Zie de configuratieopties voor de codekwaliteitsregel voor meer informatie.

Specifieke API-oppervlakken opnemen

U kunt configureren op welke onderdelen van uw codebase deze regel moet worden uitgevoerd, op basis van hun toegankelijkheid, door de optie api_surface in te stellen. Als u bijvoorbeeld wilt opgeven dat de regel alleen moet worden uitgevoerd op het niet-openbare API-oppervlak, voegt u het volgende sleutel-waardepaar toe aan een .editorconfig-bestand in uw project:

dotnet_code_quality.CAXXXX.api_surface = private, internal

Voorbeeldschending

In het volgende voorbeeld ziet u een eigenschap die deze regel schendt:

public class Book
{
    public Book(string[] pages)
    {
        Pages = pages;
    }

    public string[] Pages { get; }
}

Public Class Book
    Public Sub New(ByVal pages As String())
        Me.Pages = pages
    End Sub

    Public ReadOnly Property Pages() As String()
End Class

Als u een schending van deze regel wilt oplossen, maakt u de eigenschap een methode of wijzigt u de eigenschap om een verzameling te retourneren in plaats van een matrix.

De eigenschap wijzigen in een methode

In het volgende voorbeeld wordt de schending opgelost door de eigenschap te wijzigen in een methode:

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

De eigenschap wijzigen om een verzameling te retourneren

In het volgende voorbeeld wordt de schending opgelost door de eigenschap te wijzigen om een System.Collections.ObjectModel.ReadOnlyCollection<T>:

public class Book
{
    public Book(string[] pages)
    {
        Pages = new ReadOnlyCollection<string>(pages);
    }

    public ReadOnlyCollection<string> Pages { get; }
}

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

Gebruikers toestaan een eigenschap te wijzigen

Mogelijk wilt u de consument van de klasse toestaan een eigenschap te wijzigen. In het volgende voorbeeld ziet u een lees-/schrijfeigenschap die in strijd is met deze regel:

public class Book
{
    public Book(string[] pages)
    {
        Pages = pages;
    }

    public string[] Pages { get; set; }
}

Public Class Book
    Public Sub New(ByVal pages As String())
        Me.Pages = pages
    End Sub

    Public Property Pages() As String()

End Class

In het volgende voorbeeld wordt de schending opgelost door de eigenschap te wijzigen om een 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
{
    public Book(string[] pages)
    {
        Pages = new Collection<string>(pages);
    }

    public Collection<string> Pages { get; }
}

Gerelateerde regels

• CA1024: Eigenschappen gebruiken waar van toepassing