CA1024:在适用处使用属性

属性	值
规则 ID	CA1024
标题	在适用处使用属性
类别	设计
修复是中断修复还是非中断修复	重大
在 .NET 8 中默认启用	否

原因

一个方法的名称以 Get 开头，不采用任何参数，并返回一个非数组的值。

默认情况下，此规则仅查看外部可见的方法，但这是可配置的。

规则说明

在大多数情况下，属性表示数据，方法执行操作。 访问属性的方式类似于访问字段，这使得它们更易于使用。 如果一个方法具备以下条件之一，则该方法可能很适合成为属性：

• 方法不采用任何自变量，并返回对象的状态信息。
• 方法接受单个自变量，以设置对象的部分状态。

如何解决冲突

若要解决此规则的冲突，请将方法更改为属性。

何时禁止显示警告

如果方法满足以下条件之一，则禁止显示此规则发出的警告。 在下面的情形下，方法比属性更可取。

• 方法表现的行为不像字段。
• 方法执行耗时的操作。 方法设置或获取字段值所需的时间明显更长。
• 方法执行了一个转换。 访问一个字段不会返回它所存储的数据的转换版本。
• Get 方法有一个明显的副作用。 检索字段的值不会产生任何副作用。
• 执行的顺序很重要。 设置字段的值不依赖于其他操作的发生。
• 连续调用方法两次会产生不同的结果。
• 方法是 static，但返回一个可由调用方更改的对象。 检索字段的值不允许调用方更改由字段存储的数据。
• 方法返回一个数组。

抑制警告

如果只想抑制单个冲突，请将预处理器指令添加到源文件以禁用该规则，然后重新启用该规则。

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

若要对文件、文件夹或项目禁用该规则，请在配置文件中将其严重性设置为 none。

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

有关详细信息，请参阅如何禁止显示代码分析警告。

配置代码以进行分析

使用下面的选项来配置代码库的哪些部分要运行此规则。

• 包含特定的 API 图面

可以仅为此规则、为适用的所有规则或为适用的此类别（设计）中的所有规则配置此选项。 有关详细信息，请参阅代码质量规则配置选项。

包含特定的 API 图面

你可以根据代码库的可访问性，配置要针对其运行此规则的部分。 例如，若要指定规则应仅针对非公共 API 图面运行，请将以下键值对添加到项目中的 .editorconfig 文件：

dotnet_code_quality.CAXXXX.api_surface = private, internal

示例

下面的示例包含了几个应转换为属性的方法，和几个不应转换为属性的方法（因为它们的行为不像字段）。

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

控制调试器中的属性扩展

编程人员避免使用属性的一个原因是，它们不希望调试器自动扩展它。 例如，属性可能涉及到分配一个大型对象或调用一个 P/Invoke，但它实际上可能没有任何明显的副作用。

可以通过应用 System.Diagnostics.DebuggerBrowsableAttribute 来阻止调试器自动扩展属性。 下面的示例展示了如何将此特性应用于实例属性。

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