CA1024: Eigenschappen gebruiken waar van toepassing

Eigenschappen	Weergegeven als
Regel-id	CA1024
Titel	Eigenschappen gebruiken, indien van toepassing
Categorie	Ontwerpen
Oplossing is brekend of niet-brekend	Breken
Standaard ingeschakeld in .NET 8	Nee

Oorzaak

Een methode heeft een naam die begint met Get, heeft geen parameters en retourneert een waarde die geen matrix is.

Deze regel kijkt standaard alleen naar extern zichtbare methoden, maar dit is configureerbaar.

Beschrijving van regel

In de meeste gevallen vertegenwoordigen eigenschappen gegevens en methoden om acties uit te voeren. Eigenschappen worden geopend als velden, waardoor ze gemakkelijker te gebruiken zijn. Een methode is een goede kandidaat om een eigenschap te worden als een van deze voorwaarden aanwezig is:

• De methode heeft geen argumenten en retourneert de statusgegevens van een object.
• De methode accepteert één argument om een deel van de status van een object in te stellen.

Schendingen oplossen

Als u een schending van deze regel wilt oplossen, wijzigt u de methode in een eigenschap.

Wanneer waarschuwingen onderdrukken

Onderdrukt een waarschuwing van deze regel als de methode voldoet aan een van de volgende criteria. In deze situaties verdient een methode de voorkeur aan een eigenschap.

• De methode kan zich niet gedragen als een veld.
• De methode voert een tijdrovende bewerking uit. De methode is waarneembaar langzamer dan de tijd die nodig is om de waarde van een veld in te stellen of op te halen.
• De methode voert een conversie uit. Als u een veld opent, wordt geen geconverteerde versie geretourneerd van de gegevens die worden opgeslagen.
• De Get methode heeft een waarneembaar neveneffect. Het ophalen van de waarde van een veld levert geen bijwerkingen op.
• De uitvoeringsvolgorde is belangrijk. Het instellen van de waarde van een veld is niet afhankelijk van het optreden van andere bewerkingen.
• Als u de methode twee keer achter elkaar aanroept, worden er verschillende resultaten gemaakt.
• De methode is static , maar retourneert een object dat kan worden gewijzigd door de aanroeper. Door de waarde van een veld op te halen, kan de aanroeper de gegevens die door het veld zijn opgeslagen, niet wijzigen.
• De methode retourneert een matrix.

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 CA1024
// The code that's violating the rule is on this line.
#pragma warning restore CA1024

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.CA1024.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 (ontwerp) waarop deze van toepassing is. Zie de configuratieopties voor de codekwaliteitsregel voor meer informatie.

Specifieke API-oppervlakken opnemen

U kunt instellen op welke onderdelen van uw codebase deze regel moet worden uitgevoerd, op basis van hun toegankelijkheid. 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

Voorbeeld

Het volgende voorbeeld bevat verschillende methoden die moeten worden geconverteerd naar eigenschappen en verschillende methoden die niet moeten worden uitgevoerd omdat ze zich niet gedragen als velden.

public class Appointment
{
    static long nextAppointmentID;
    static double[] discountScale = { 5.0, 10.0, 33.0 };
    string? customerName;
    long customerID;
    DateTime when;

    // Static constructor.
    static Appointment()
    {
        // Initializes the static variable for Next appointment ID.
    }

    // This method violates the rule, but should not be a property.
    // This method has an observable side effect. 
    // Calling the method twice in succession creates different results.
    public static long GetNextAvailableID()
    {
        nextAppointmentID++;
        return nextAppointmentID - 1;
    }

    // This method violates the rule, but should not be a property.
    // This method performs a time-consuming operation. 
    // This method returns an array.
    public Appointment[] GetCustomerHistory()
    {
        // Connect to a database to get the customer's appointment history.
        return LoadHistoryFromDB(customerID);
    }

    // This method violates the rule, but should not be a property.
    // This method is static but returns a mutable object.
    public static double[] GetDiscountScaleForUpdate()
    {
        return discountScale;
    }

    // This method violates the rule, but should not be a property.
    // This method performs a conversion.
    public string GetWeekDayString()
    {
        return DateTimeFormatInfo.CurrentInfo.GetDayName(when.DayOfWeek);
    }

    // These methods violate the rule and should be properties.
    // They each set or return a piece of the current object's state.

    public DayOfWeek GetWeekDay()
    {
        return when.DayOfWeek;
    }

    public void SetCustomerName(string customerName)
    {
        this.customerName = customerName;
    }

    public string? GetCustomerName()
    {
        return customerName;
    }

    public void SetCustomerID(long customerID)
    {
        this.customerID = customerID;
    }

    public long GetCustomerID()
    {
        return customerID;
    }

    public void SetScheduleTime(DateTime when)
    {
        this.when = when;
    }

    public DateTime GetScheduleTime()
    {
        return when;
    }

    // Time-consuming method that is called by GetCustomerHistory.
    Appointment[] LoadHistoryFromDB(long customerID)
    {
        ArrayList records = new ArrayList();
        // Load from database.
        return (Appointment[])records.ToArray();
    }
}

Public Class Appointment
    Shared nextAppointmentID As Long
    Shared discountScale As Double() = {5.0, 10.0, 33.0}
    Private customerName As String
    Private customerID As Long
    Private [when] As Date

    ' Static constructor.
    Shared Sub New()
        ' Initializes the static variable for Next appointment ID.
    End Sub

    ' This method violates the rule, but should not be a property.
    ' This method has an observable side effect. 
    ' Calling the method twice in succession creates different results.
    Public Shared Function GetNextAvailableID() As Long
        nextAppointmentID += 1
        Return nextAppointmentID - 1
    End Function

    ' This method violates the rule, but should not be a property.
    ' This method performs a time-consuming operation. 
    ' This method returns an array.
    Public Function GetCustomerHistory() As Appointment()
        ' Connect to a database to get the customer's appointment history.
        Return LoadHistoryFromDB(customerID)
    End Function

    ' This method violates the rule, but should not be a property.
    ' This method is static but returns a mutable object.
    Public Shared Function GetDiscountScaleForUpdate() As Double()
        Return discountScale
    End Function

    ' This method violates the rule, but should not be a property.
    ' This method performs a conversion.
    Public Function GetWeekDayString() As String
        Return DateTimeFormatInfo.CurrentInfo.GetDayName([when].DayOfWeek)
    End Function

    ' These methods violate the rule and should be properties.
    ' They each set or return a piece of the current object's state.

    Public Function GetWeekDay() As DayOfWeek
        Return [when].DayOfWeek
    End Function

    Public Sub SetCustomerName(customerName As String)
        Me.customerName = customerName
    End Sub

    Public Function GetCustomerName() As String
        Return customerName
    End Function

    Public Sub SetCustomerID(customerID As Long)
        Me.customerID = customerID
    End Sub

    Public Function GetCustomerID() As Long
        Return customerID
    End Function

    Public Sub SetScheduleTime([when] As Date)
        Me.[when] = [when]
    End Sub

    Public Function GetScheduleTime() As Date
        Return [when]
    End Function

    ' Time-consuming method that is called by GetCustomerHistory.
    Private Function LoadHistoryFromDB(customerID As Long) As Appointment()
        Dim records As ArrayList = New ArrayList()
        Return CType(records.ToArray(), Appointment())
    End Function
End Class

Uitbreiding van besturingselementeigenschappen in het foutopsporingsprogramma

Een van de redenen waarom programmeurs het gebruik van een eigenschap vermijden, is omdat ze niet willen dat het foutopsporingsprogramma deze automatisch uitbreidt. De eigenschap kan bijvoorbeeld betrekking hebben op het toewijzen van een groot object of het aanroepen van een P/Invoke, maar het heeft mogelijk geen waarneembare bijwerkingen.

U kunt voorkomen dat het foutopsporingsprogramma automatisch uitbreidt door eigenschappen toe te passen System.Diagnostics.DebuggerBrowsableAttribute. In het volgende voorbeeld ziet u dat dit kenmerk wordt toegepast op een exemplaareigenschap.

Imports System.Diagnostics

Namespace Microsoft.Samples
    Public Class TestClass
        ' [...]

        <DebuggerBrowsable(DebuggerBrowsableState.Never)> _
        Public ReadOnly Property LargeObject() As LargeObject
            Get
                ' Allocate large object
                ' [...]
            End Get
        End Property
    End Class
End Namespace

using System.Diagnostics;

namespace Microsoft.Samples
{
    class TestClass
    {
        // [...]

        [DebuggerBrowsable(DebuggerBrowsableState.Never)]
        public LargeObject LargeObject
        {
            get
            {
                // Allocate large object
                // [...]
            }
        }
    }
}