CA1024: Adott esetben tulajdonságok használata

Cikk
09/06/2023

Tulajdonság	Érték
Szabályazonosító	CA1024
Cím	Adott esetben tulajdonságok használata
Kategória	Design
A javítás kompatibilitástörő vagy nem törik	Törés
Alapértelmezés szerint engedélyezve a .NET 8-ban	Nem

Ok

A metódusok neve a következővel Getkezdődik, nem vesz fel paramétereket, és olyan értéket ad vissza, amely nem tömb.

Ez a szabály alapértelmezés szerint csak külsőleg látható metódusokat tekint meg, de ez konfigurálható.

Szabály leírása

A legtöbb esetben a tulajdonságok az adatokat jelölik, a metódusok pedig műveleteket hajtanak végre. A tulajdonságok a mezőkhöz hasonlóan érhetők el, ami megkönnyíti a használatukat. A módszer jó jelölt arra, hogy ingatlansá váljon, ha az alábbi feltételek valamelyike fennáll:

A metódus nem vesz fel argumentumokat, és visszaadja egy objektum állapotadatait.
A metódus egyetlen argumentumot fogad el egy objektum állapotának egy részének beállításához.

Szabálysértések kijavítása

A szabály megsértésének kijavításához módosítsa a metódust egy tulajdonságra.

Mikor kell letiltani a figyelmeztetéseket?

A szabály figyelmeztetésének mellőzése, ha a metódus megfelel az alábbi feltételek egyikének. Ilyen helyzetekben a módszer előnyösebb egy tulajdonsághoz.

A metódus nem viselkedhet mezőként.
A metódus időigényes műveletet hajt végre. A metódus érzékelhetően lassabb, mint a mező értékének beállításához vagy lekéréséhez szükséges idő.
A metódus konverziót hajt végre. Egy mező elérése nem adja vissza az általa tárolt adatok konvertált verzióját.
A Get módszernek megfigyelhető mellékhatása van. Egy mező értékének beolvasása nem okoz semmilyen mellékhatást.
A végrehajtás sorrendje fontos. A mező értékének beállítása nem függ más műveletek előfordulásától.
A metódus egymás után kétszeri meghívása eltérő eredményeket hoz létre.
A metódus egy static olyan objektumot ad vissza, amelyet a hívó megváltoztathat. Egy mező értékének beolvasása nem teszi lehetővé a hívó számára a mező által tárolt adatok módosítását.
A metódus egy tömböt ad vissza.

Figyelmeztetés mellőzése

Ha csak egyetlen szabálysértést szeretne letiltani, adjon hozzá előfeldolgozási irányelveket a forrásfájlhoz a szabály letiltásához és újbóli engedélyezéséhez.

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

Ha le szeretné tiltani egy fájl, mappa vagy projekt szabályát, állítsa annak súlyosságát none a konfigurációs fájlban.

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

További információ: Kódelemzési figyelmeztetések letiltása.

Kód konfigurálása elemzéshez

A következő beállítással konfigurálhatja, hogy a kódbázis mely részein futtassa ezt a szabályt.

Adott API-felületek belefoglalása

Ezt a beállítást konfigurálhatja csak ehhez a szabályhoz, az összes szabályhoz, vagy az ebben a kategóriában (Tervezés) szereplő összes szabályhoz, amelyekre vonatkozik. További információ: Kódminőségi szabály konfigurációs beállításai.

Adott API-felületek belefoglalása

A kódbázis azon részeit konfigurálhatja, amelyeken futtathatja ezt a szabályt az akadálymentességük alapján. Ha például meg szeretné adni, hogy a szabály csak a nem nyilvános API-felületen fusson, adja hozzá a következő kulcs-érték párot a projekt egyik .editorconfig fájljához:

dotnet_code_quality.CAXXXX.api_surface = private, internal

Példa

Az alábbi példa számos olyan metódust tartalmaz, amelyeket tulajdonságokká kell konvertálni, és több olyan metódust is, amelyeket nem szabad, mert nem úgy viselkednek, mint a mezők.

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

Tulajdonságbővítés szabályozása a hibakeresőben

A programozók egyik oka, hogy nem használják a tulajdonságot, mert nem szeretnék, hogy a hibakereső automatikusan kibontsa azt. A tulajdonság például magában foglalhatja egy nagy objektum kiosztását vagy egy P/Invoke meghívását, de valójában nincs megfigyelhető mellékhatása.

Az alkalmazással megakadályozhatja, hogy a hibakereső automatikusan kibontsa a tulajdonságokat System.Diagnostics.DebuggerBrowsableAttribute. Az alábbi példa azt mutatja be, hogy ez az attribútum egy példánytulajdonságra van alkalmazva.

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

Megosztás a következőn keresztül: