CA1019:定义特性参数的访问器

属性
规则 ID CA1019
标题 定义特性参数的访问器
类别 设计
修复是中断修复还是非中断修复 非中断
在 .NET 9 中默认启用

原因

在其构造函数中,特性定义了没有相应属性的参数。

规则说明

特性可以定义强制自变量,在对目标应用该特性时必须指定这些自变量。 这些实参也称为位置实参,因为它们将作为位置形参提供给特性构造函数。 对于每一个强制变量,特性还必须提供一个相应的只读属性,以便可以在执行时检索该变量的值。 此规则检查是否已为每个构造函数参数定义了相应属性。

特性还可以定义可选实参,可选实参也称为命名实参。 这些变量按名称提供给特性构造函数,并且必须具有相应的读/写属性。

对于强制参数和可选参数,相应属性和构造函数参数应使用相同的名称,但大小写不同。 属性使用 Pascal 大小写,参数使用 Camel 大小写。

如何解决冲突

若要解决此规则的冲突,请为每个没有只读属性的构造函数参数添加一个只读属性。

何时禁止显示警告

如果不希望强制参数的值可检索,则禁止显示此规则的警告。

抑制警告

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

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

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

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

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

示例

自定义特性

下面的示例演示了定义强制(位置)参数的两个特性。 未正确定义特性的首个实现。 第二个实现正确。

// Violates rule: DefineAccessorsForAttributeArguments.
[AttributeUsage(AttributeTargets.All)]
public sealed class BadCustomAttribute : Attribute
{
    string _data;

    // Missing the property that corresponds to 
    // the someStringData constructor parameter.

    public BadCustomAttribute(string someStringData)
    {
        _data = someStringData;
    }
}

// Satisfies rule: Attributes should have accessors for all arguments.
[AttributeUsage(AttributeTargets.All)]
public sealed class GoodCustomAttribute : Attribute
{
    public GoodCustomAttribute(string someStringData)
    {
        SomeStringData = someStringData;
    }

    //The constructor parameter and property
    //name are the same except for case.

    public string SomeStringData { get; }
}
Imports System

Namespace ca1019

    ' Violates rule: DefineAccessorsForAttributeArguments.
    <AttributeUsage(AttributeTargets.All)>
    Public NotInheritable Class BadCustomAttribute
        Inherits Attribute
        Private data As String

        ' Missing the property that corresponds to 
        ' the someStringData parameter.
        Public Sub New(someStringData As String)
            data = someStringData
        End Sub 'New
    End Class 'BadCustomAttribute

    ' Satisfies rule: Attributes should have accessors for all arguments.
    <AttributeUsage(AttributeTargets.All)>
    Public NotInheritable Class GoodCustomAttribute
        Inherits Attribute

        Public Sub New(someStringData As String)
            Me.SomeStringData = someStringData
        End Sub 'New

        'The constructor parameter and property
        'name are the same except for case.

        Public ReadOnly Property SomeStringData() As String
    End Class

End Namespace

位置参数和命名参数

位置参数和命名参数使库的使用者清楚地了解对于特性而言,哪些参数是强制的,哪些参数是可选的。

下面的示例演示了具有位置参数和命名参数的特性的实现:

[AttributeUsage(AttributeTargets.All)]
public sealed class GoodCustomAttribute : Attribute
{
    public GoodCustomAttribute(string mandatoryData)
    {
        MandatoryData = mandatoryData;
    }

    public string MandatoryData { get; }

    public string? OptionalData { get; set; }
}

下面的示例演示了如何将自定义特性应用于两个属性:

[GoodCustomAttribute("ThisIsSomeMandatoryData", OptionalData = "ThisIsSomeOptionalData")]
public string? MyProperty { get; set; }

[GoodCustomAttribute("ThisIsSomeMoreMandatoryData")]
public string? MyOtherProperty { get; set; }

CA1813:避免使用非密封特性

请参阅