Share via

CA1024: Använd egenskaper där det är lämpligt

  • Artikel
Property Värde
Regel-ID CA1024
Rubrik Använd egenskaper där det är lämpligt
Kategori Designa
Korrigeringen är icke-bakåtkompatibel Bryta
Aktiverad som standard i .NET 8 Nej

Orsak

En metod har ett namn som börjar med Get, tar inga parametrar och returnerar ett värde som inte är en matris.

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

Regelbeskrivning

I de flesta fall representerar egenskaper data och metoder utför åtgärder. Egenskaper används som fält, vilket gör dem enklare att använda. En metod är en bra kandidat för att bli en egenskap om något av dessa villkor finns:

  • Metoden tar inga argument och returnerar tillståndsinformationen för ett objekt.
  • Metoden accepterar ett enda argument för att ange en del av tillståndet för ett objekt.

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

Om du vill åtgärda ett brott mot den här regeln ändrar du metoden till en egenskap.

När du ska ignorera varningar

Ignorera en varning från den här regeln om metoden uppfyller något av följande villkor. I dessa situationer är en metod att föredra framför en egenskap.

  • Metoden kan inte fungera som ett fält.
  • Metoden utför en tidskrävande åtgärd. Metoden är märkbart långsammare än den tid som krävs för att ange eller hämta värdet för ett fält.
  • Metoden utför en konvertering. Åtkomst till ett fält returnerar inte en konverterad version av de data som lagras.
  • Metoden Get har en observerbar bieffekt. Om du hämtar värdet för ett fält får du inga biverkningar.
  • Körningsordningen är viktig. Om du anger värdet för ett fält förlitar du dig inte på förekomsten av andra åtgärder.
  • Om du anropar metoden två gånger i följd skapas olika resultat.
  • Metoden är static men returnerar ett objekt som kan ändras av anroparen. Om du hämtar värdet för ett fält kan anroparen inte ändra de data som lagras av fältet.
  • Metoden returnerar en matris.

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

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.CA1024.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 gäller för eller för alla regler i den här kategorin (design) 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

Exempel

Följande exempel innehåller flera metoder som ska konverteras till egenskaper och flera som inte bör eftersom de inte fungerar som fält.

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

Kontrollera egenskapsexpansionen i felsökningsprogrammet

En orsak till att programmerare undviker att använda en egenskap är att de inte vill att felsökaren ska kunnaexponeras automatiskt. Egenskapen kan till exempel innebära att du allokerar ett stort objekt eller anropar en P/Invoke, men den kanske inte har några observerbara biverkningar.

Du kan förhindra att felsökningsprogrammet expanderar egenskaper automatiskt genom att tillämpa System.Diagnostics.DebuggerBrowsableAttribute. I följande exempel visas det här attributet som tillämpas på en instansegenskap.

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
                // [...]
            }
        }
    }
}