CA1024:在适用处使用属性

项

“值”

RuleId

CA1024

类别

设计

修复是中断修复还是非中断修复

重大

原因

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

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

规则说明

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

方法不采用任何自变量，并返回对象的状态信息。

方法接受单个自变量，以设置对象的部分状态。

如何解决冲突

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

何时禁止显示警告

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

方法表现的行为不像字段。

方法执行耗时的操作。 方法设置或获取字段值所需的时间明显更长。

方法执行了一个转换。 访问一个字段不会返回它所存储的数据的转换版本。

Get 方法有一个明显的副作用。 检索字段的值不会产生任何副作用。

执行的顺序很重要。 设置字段的值不依赖于其他操作的发生。

连续调用方法两次会产生不同的结果。

方法是 static，但返回一个可由调用方更改的对象。 检索字段的值不允许调用方更改由字段存储的数据。

方法返回一个数组。

抑制警告

可以通过多种方式来禁止显示代码分析警告，包括禁用项目的规则、使用预处理器指令为特定代码行禁用该规则或应用 SuppressMessageAttribute 特性。 有关详细信息，请参阅如何禁止显示代码分析警告。

配置代码以进行分析

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

包含特定的 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

// [...]

}

}

}

}