使用注解优化代码检查

代码检查和许多其他 JetBrains Rider 功能在很大程度上依赖于了解语言结构的行为来检测问题、提出可能的改进建议，并以其他方式帮助您。

然而，这种分析无法检测到所有问题。例如，如果一个方法被设计为格式化方法，那么如果方法调用中缺少必要的参数，任何结构化分析都无法发现可能的问题。

在这种情况下以及许多其他情况下，JetBrains Rider 的 JetBrains.Annotations 非常有帮助。通过使用此框架中声明的属性，您可以使 JetBrains Rider 按照您的需求分析代码。例如，您可以使用 [StringFormatMethod] 为方法添加注解，以指示自定义方法与 System.String.Format() 的工作方式相同：

[StringFormatMethod("message")]
void ShowError(string message, params object[] args) { /* do something */ }

void Foo(string failureDetails) {
  ShowError("Failed: {0}"); // Warning: Non-existing argument in format string
}
    
 

这是最简单的示例，还有其他具有更复杂用例的有用属性。您可以在参考文档中找到这些属性的完整列表。

在大多数情况下，代码注解属性可以启用特定的代码检查，例如：

StringFormatMethodAttribute 有助于检测字符串格式化方法的误用。
CanBeNullAttribute 和 NotNullAttribute 与“可能将 'null' 分配给标记为 'Value cannot be null' 属性的实体”检查相关联。如需更多信息，请参阅值和可空性分析。
CannotApplyEqualityOperatorAttribute 绑定到“ 与标记为 'CannotApplyEqualityOperatorAttribute' 的类型进行 '==' 比较 ”检查
ContractAnnotationAttribute 可用于定义函数的契约并启用相应的检查。例如，您可以使用 [ContractAnnotation("input:null => false")] 通知函数的使用者 bool Foo(object input) 在参数 秒 为 null 时，总是返回 false。

此外，代码注解还可以在注解的项目上启用更多快速修复、代码补全建议和代码生成功能。注解还需要用于创建和使用源代码模板。

JetBrains Rider 允许您通过两种方式为代码符号添加注解：

您可以像上面的示例一样，在源代码中为符号添加注解。在这种情况下，您需要在项目中引用 JetBrains.Annotations 命名空间。更多信息请参阅源代码中的注解。
即使您无法访问源代码，您也可以为已编译的库代码中的符号添加注解。欲了解更多信息，请参阅外部注解。

最后修改日期： 2025年 9月 26日