CA1819:属性不应返回数组
属性 | 值 |
---|---|
规则 ID | CA1819 |
标题 | 属性不应返回数组 |
类别 | “性能” |
修复是中断修复还是非中断修复 | 重大 |
在 .NET 9 中默认启用 | 否 |
原因
属性返回数组。
默认情况下,此规则仅查看外部可见的属性和类型,但这是可配置的。
规则说明
即使属性是只读的,该属性返回的数组也不受写入保护。 若要使数组不会被更改,属性必须返回数组的副本。 通常,用户不能理解调用这种属性的负面性能影响。 具体来说,他们可能将索引属性作为属性使用。
如何解决冲突
要解决此规则的冲突,请将属性设置为方法或更改属性以返回集合。
何时禁止显示警告
可禁止显示从 Attribute 类派生的特性中由属性引发的警告。 特性可以包含返回数组的属性,但不能包含返回集合的属性。
如果属性是数据传输对象 (DTO) 类的一部分,则可以禁止显示警告.
否则,请勿禁止显示此规则发出的警告。
抑制警告
如果只想抑制单个冲突,请将预处理器指令添加到源文件以禁用该规则,然后重新启用该规则。
#pragma warning disable CA1819
// The code that's violating the rule is on this line.
#pragma warning restore CA1819
若要对文件、文件夹或项目禁用该规则,请在配置文件中将其严重性设置为 none
。
[*.{cs,vb}]
dotnet_diagnostic.CA1819.severity = none
有关详细信息,请参阅如何禁止显示代码分析警告。
配置代码以进行分析
使用下面的选项来配置代码库的哪些部分要运行此规则。
可以仅为此规则、为适用的所有规则或为适用的此类别(性能)中的所有规则配置此选项。 有关详细信息,请参阅代码质量规则配置选项。
包含特定的 API 图面
你可以根据代码库的可访问性,配置要针对其运行此规则的部分。 例如,若要指定规则应仅针对非公共 API 图面运行,请将以下键值对添加到项目中的 .editorconfig 文件:
dotnet_code_quality.CAXXXX.api_surface = private, internal
示例冲突
下面的示例显示了与此规则发生冲突的属性:
public class Book
{
private string[] _Pages;
public Book(string[] pages)
{
_Pages = pages;
}
public string[] Pages
{
get { return _Pages; }
}
}
Public Class Book
Public Sub New(ByVal pages As String())
Me.Pages = pages
End Sub
Public ReadOnly Property Pages() As String()
End Class
若要解决此规则的冲突,请将属性设置为方法或更改属性以返回集合而不是数组。
将属性更改为方法
以下示例通过将属性更改为方法来解决冲突:
Public Class Book
Private _Pages As String()
Public Sub New(ByVal pages As String())
_Pages = pages
End Sub
Public Function GetPages() As String()
' Need to return a clone of the array so that consumers
' of this library cannot change its contents
Return DirectCast(_Pages.Clone(), String())
End Function
End Class
public class Book
{
private string[] _Pages;
public Book(string[] pages)
{
_Pages = pages;
}
public string[] GetPages()
{
// Need to return a clone of the array so that consumers
// of this library cannot change its contents
return (string[])_Pages.Clone();
}
}
更改属性以返回集合
以下示例通过更改属性以返回 System.Collections.ObjectModel.ReadOnlyCollection<T> 来解决冲突:
public class Book
{
private ReadOnlyCollection<string> _Pages;
public Book(string[] pages)
{
_Pages = new ReadOnlyCollection<string>(pages);
}
public ReadOnlyCollection<string> Pages
{
get { return _Pages; }
}
}
Public Class Book
Public Sub New(ByVal pages As String())
Me.Pages = New ReadOnlyCollection(Of String)(pages)
End Sub
Public ReadOnly Property Pages() As ReadOnlyCollection(Of String)
End Class
允许用户修改属性
你可能希望允许类的使用者修改属性。 以下示例显示与此规则冲突的读/写属性:
public class Book
{
private string[] _Pages;
public Book(string[] pages)
{
_Pages = pages;
}
public string[] Pages
{
get { return _Pages; }
set { _Pages = value; }
}
}
Public Class Book
Public Sub New(ByVal pages As String())
Me.Pages = pages
End Sub
Public Property Pages() As String()
End Class
以下示例通过更改属性以返回 System.Collections.ObjectModel.Collection<T> 来解决冲突:
Public Class Book
Public Sub New(ByVal pages As String())
Me.Pages = New Collection(Of String)(pages)
End Sub
Public ReadOnly Property Pages() As Collection(Of String)
End Class
public class Book
{
private Collection<string> _Pages;
public Book(string[] pages)
{
_Pages = new Collection<string>(pages);
}
public Collection<string> Pages
{
get { return _Pages; }
}
}