如果你的 .NET 6+ 项目引用一个启用源生成代码的包(例如日志记录解决方案),则特定于源生成的分析器将在编译时运行。 本文列出了与源生成代码相关的编译器诊断。
按照约定,标识符名称不包含下划线 (_) 字符。 该规则将检查命名空间、类型、成员和参数。
对于引用类型,相等运算符的默认实现几乎始终是正确的。 默认情况下,仅当两个引用指向同一对象时,它们才相等。
抽象类型的构造函数只能由派生类型调用。 由于公共构造函数可创建类型的实例,但无法创建抽象类型的实例,因此具有公共构造函数的抽象类型在设计上是错误的。
参数和成员的名称更好地用于传达其含义而不是描述其类型,类型描述通常由开发工具提供。 对于成员的名称,如果必须使用数据类型名称,请使用与语言无关的名称,而不要使用语言特定的名称。 例如,请使用与语言无关的数据类型名称 Int32,而不要使用 C# 类型名称 int。
泛型类型包含的类型参数越多,越难以知道并记住每个类型参数各代表什么。 它通常有一个类型参数,如在 List<T> 中,而在某些情况下有两个类型参数,如在 Dictionary<TKey, TValue> 中。 如果存在两个以上的类型参数,则大多数用户都会感到过于困难(例如 C# 中的 TooManyTypeParameters<T, K, V> 或 Visual Basic 中的 TooManyTypeParameters(Of T, K, V))。
类型包含索引器,该索引器使用的索引类型不是 System.Int32、System.Int64、System.Object 或 System.String。
接口定义提供某个行为或使用协定的成员。 接口所描述的功能可以被任何类型采用,而不管该类型出现在继承层次结构中的哪个位置。 类型通过实现接口的成员来实现接口。 空接口不定义任何成员。 因此,它不定义可实现的协定。
未密封的外部可见类型提供了显式实现公共接口的方法,但没有提供具有相同名称的其他外部可见方法。
泛型类型包含 static(在 Visual Basic 中为 Shared)成员。
System.Collections.ReadOnlyCollectionBase
LoggerMessageAttribute 属性的消息字符串包含一个前缀(例如 INFO: 或 ERROR:),这是多余的,因为每个日志消息都有相应的日志级别。
应在命名空间内声明类型以避免名称冲突,并作为一种在对象层次结构中组织相关类型的方式。 任何命名的命名称空间之外的类型均位于无法在代码中引用的全局命名空间中。
日志记录方法的第一个日志级别参数在日志记录消息中作为模板引用。 不必要这样做,因为第一个日志级别会显式传递给日志记录基础结构。 不需要在日志记录消息中重复它。
日志记录方法的第一个异常参数在日志记录消息中作为模板引用。 不必要这样做,因为第一个异常将显式传递给日志记录基础结构。 不需要在日志记录消息中重复它。
.NET 使用版本号来唯一标识程序集,并绑定到强名称程序集中的类型。 版本号与版本和发行者策略一起使用。 默认情况下,仅使用用于生成应用程序的程序集版本运行应用程序。
如果不能提供完整的构造函数集,要正确处理异常将变得比较困难。 例如,具有签名 NewException(string, Exception) 的构造函数用于创建由其他异常引起的异常。 如果没有此构造函数,你无法创建和引发包含内部(嵌套)异常的自定义异常实例,在这种情况下,托管代码应执行此操作。
建议尽量使用解决方法之一。 但是,如果无法更改代码,可以通过 #pragma 指令或 <NoWarn> 项目设置来禁止显示警告。 如果 SYSLIB1XXX 源生成器诊断未显示为错误,则可以在代码或项目文件中禁止警告。
枚举是一种值类型,它定义一组相关的已命名常数。 默认情况下,System.Int32 数据类型用于存储常量值。 虽然你可以更改此基础类型,但对于大多数情况,既不需要,也不建议你这样做。 使用小于 Int32 的数据类型不会显著提高性能。 如果无法使用默认数据类型,则应使用某种符合公共语言规范 (CLS) 的整型类型,例如 Byte、Int16、Int32 或 Int64,以确保枚举的所有值都可以用符合 CLS 的编程语言表示。
枚举的值是两个值的幂或枚举中定义的其他值的组合,且不存在 System.FlagsAttribute 属性。 为了减少误报,此规则不对具有连续值的枚举报告冲突。
类型实现 System.IComparable 接口,并且不重写 System.Object.Equals,也不重载表示相等、不等、小于或大于的语言特定运算符。 如果类型仅继承接口的实现,则规则不会报告冲突。
异步方法直接等待 Task 时,延续任务通常会出现在创建任务的同一线程中,具体取决于异步上下文。 此行为可能会降低性能,并且可能会导致 UI 线程发生死锁。 请考虑调用 Task.ConfigureAwait(Boolean) 以表示延续任务意图。
使用 LoggerMessageAttribute 进行注释的方法的参数之一必须是 ILogger 类型或实现 ILogger 的类型。
该规则检测名称通常用于事件的方法。 事件遵循“观察者”或“发布-订阅”设计模式;当必须将一个对象的状态更改传达给其他对象时,它们适用。 如果为响应明确定义的状态更改而调用一个方法,则应由事件处理程序调用该方法。 调用该方法的对象应引发事件而不是直接调用该方法。
类型名与具有一个或多个外部可见类型的被引用命名空间名称冲突。 名称比较不区分大小写。
公共类型是 sealed(在 Visual basic 中为 NotInheritable),并声明了一个受保护的成员或受保护的嵌套类型。 此规则不报告 Finalize 方法的冲突,这些方法必须遵循此模式。
按照约定,扩展某些基类型或实现某些接口的类型的名称,或者由这些类型派生的类型的名称应具有与相应基类型或接口关联的后缀。
类型实现 System.Collections.IEnumerable 接口,但不能实现 System.Collections.Generic.IEnumerable<T> 接口和包含程序集的目标 .NET。 此规则会忽略能够实现 System.Collections.IDictionary 的类型。
使用 LoggerMessageAttribute 进行注释的方法包含泛型类型的参数。
非中断 - 如果系统提示你向无标志枚举添加 None 值。 中断 - 如果系统提示你重命名或删除任何枚举值。
从 .NET 6 开始,Rijndael 和 RijndaelManaged 类型标记为已过时。 在代码中使用这些 API 会在编译时生成警告 SYSLIB0022。
不能仅通过大小写区分命名空间、类型、成员和参数的标识符,因为针对公共语言运行时的语言不需要区分大小写。 例如,Visual Basic 是一种广泛使用的不区分大小写的语言。
从 .NET 6 开始,System.Runtime.CompilerServices.DisablePrivateReflectionAttribute 类型标记为已过时。 此属性在 .NET Core 2.1 和更高版本应用程序中不起作用。 对于 .NET 6 和更高版本的应用程序,在代码中使用会在编译时生成警告 SYSLIB0015。
不支持从进程状态已损坏异常中恢复。从 .NET 6 开始,HandleProcessCorruptedStateExceptionsAttribute 类型标记为已过时。 在代码中使用此 API 会在编译时生成警告 SYSLIB0032。
程序集包含基于 ResX 的资源,但没有向其应用 System.Resources.NeutralResourcesLanguageAttribute。
.NET Framework 中的加密配置系统不允许适当的加密灵活性,且不存在于 .NET Core 和 .NET 5+ 中。 .NET 的后向兼容性要求也禁止框架更新某些加密 API 以跟上加密技术的发展。 因此从 .NET 5 开始,以下 API 标记为已过时。 使用这些 API 会在编译时生成警告 SYSLIB0007,并在运行时生成 PlatformNotSupportedException。
从 .NET 6 开始,SuppressIldasmAttribute 类型标记为已过时。 在代码中使用会在编译时生成警告 SYSLIB0025。 IL 反汇编程序 (ildasm.exe) 不再支持此属性。
从 .NET 5 开始,一些新标记为已过时的 API 使用 ObsoleteAttribute 上的两个新属性。
默认情况下,此规则仅查看外部可见的命名空间、类型和成员,但你可以配置可见性和符号类型。
值 规则 ID CA2017 类别 可靠性 修复是中断修复还是非中断修复 非中断 原因 日志记录消息模板中提供的参数数目与命名占位符的数目不匹配。 规则说明 此规则标志记录器调用的消息参数数目不正确。 如何解决冲突 将模板格式的占位符的数量与传递的参数的数目匹配。 何时禁止显示警告 不禁止显示此规则发出的警告。 另请参阅 可靠性规则
泄漏异常信息可让攻击者深入了解应用程序的内部机制,从而帮助攻击者找到其他漏洞并利用这些漏洞。
枚举具有 System.FlagsAttribute,并且其名称不是以“s”结尾。
Get 访问器提供对属性的读取访问权限,而 set 访问器提供写入访问权限。 虽然可以接受且经常需要使用只读属性,但设计准则禁止使用只写属性。 这是因为允许用户设置值但又禁止该用户查看这个值不能提供任何安全性。 而且,如果没有读访问,将无法查看共享对象的状态,使其用处受到限制。
遵循这些 .NET 设计指南,在派生类中引发基类事件。 不要在基类中声明虚拟事件。 派生类中的重写事件具有未定义的行为。 C# 编译器不会正确处理此事件,并且无法预知派生事件的订阅者是否实际上会订阅基类事件。
即使属性是只读的,该属性返回的数组也不受写入保护。 若要使数组不会被更改,属性必须返回数组的副本。 通常,用户不能理解调用这种属性的负面性能影响。 具体来说,他们可能将索引属性作为属性使用。
类型和成员使用了未指定其 System.ObsoleteAttribute.Message 属性的 System.ObsoleteAttribute 特性进行标记。
从 .NET 6 开始,以下派生加密类型标记为已过时。 在代码中使用这些 API 会在编译时生成警告 SYSLIB0021。
损坏状态异常 (CSE) 指示进程中存在内存损坏。 如果攻击者可以将攻击放置到损坏的内存区域,则捕获它们(而非允许进程崩溃)可能导致安全漏洞。
字段的主要用途应是作为实现的详细信息。 字段应为 private 或 internal,并应通过使用属性公开这些字段。 在访问某个字段时,可轻松访问属性,而属性访问器中的代码可在扩展类型功能时更改,而不会引入重大更改。
领取专属 10元无门槛券
手把手带您无忧上云