CA1051:不要声明可见实例字段

属性
规则 ID CA1051
标题 不要声明可见实例字段
类别 设计
修复是中断修复还是非中断修复 重大
在 .NET 9 中默认启用

原因

类型包含非私有实例字段。

默认情况下,此规则仅查看外部可见的类型,但这是可配置的。

规则说明

字段的主要用途应是作为实现的详细信息。 字段应为 privateinternal,并应通过使用属性公开这些字段。 在访问某个字段时,可轻松访问属性,而属性访问器中的代码可在扩展类型功能时更改,而不会引入重大更改。

仅返回私有或内部字段的值的属性,经过优化后,可在与访问字段相同的情况上执行;使用外部可见字段而不是属性时,所带来的性能提升最小。 “外部可见”是指 publicprotectedprotected internal(在 Visual Basic中为 PublicProtectedProtected Friend)可访问性级别。

此外,链接要求无法保护公共字段。 (链接要求不适用于 .NET Core 应用。)

如何解决冲突

要解决此规则的冲突,请将字段设置为 privateinternal,并使用外部可见的属性将其公开。

何时禁止显示警告

仅当确定使用者需要直接访问字段时,才禁止显示此警告。 对于大多数应用程序,公开的字段不会提供性能或优于属性的可维护权益。

在以下情况下,使用者可能需要字段访问权限:

  • ASP.NET Web Forms 中的内容控件。
  • 目标平台使用 ref(例如 WPF 和 UWP 的模型-视图-视图模型 (MVVM) 框架)来修改字段。

抑制警告

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

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

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

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

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

包含或排除 API

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

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

包含特定的 API 图面

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

dotnet_code_quality.CAXXXX.api_surface = private, internal

排除结构

可从分析中排除 struct(在 Visual Basic 中为 Structure)字段。

dotnet_code_quality.ca1051.exclude_structs = true

示例

下面的示例显示了与此规则发生冲突的类型 (BadPublicInstanceFields)。 GoodPublicInstanceFields 显示更正后的代码。

public class BadPublicInstanceFields
{
    // Violates rule DoNotDeclareVisibleInstanceFields.
    public int instanceData = 32;
}

public class GoodPublicInstanceFields
{
    private int instanceData = 32;

    public int InstanceData
    {
        get { return instanceData; }
        set { instanceData = value; }
    }
}

另请参阅