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

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

原因

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

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

规则说明

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

仅返回私有或内部字段的值的属性，经过优化后，可在与访问字段相同的情况上执行；使用外部可见字段而不是属性时，所带来的性能提升最小。 “外部可见”是指 public、protected 和 protected internal（在 Visual Basic中为 Public、Protected 和 Protected Friend）可访问性级别。

此外，链接要求无法保护公共字段。 （链接要求不适用于 .NET Core 应用。）

如何解决冲突

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

何时禁止显示警告

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

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

  • 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; }
    }
}

另请参阅