严重级别

本文档详细介绍诊断的严重级别，包括 Error、Warning、Info、Hidden 的选择指南。

文档信息

• 难度级别: 初级
• 预计阅读时间: 10 分钟

学习目标

• 理解四种严重级别的含义
• 学会选择合适的严重级别
• 掌握严重级别的使用场景

严重级别概述

Roslyn 提供了四个严重级别：

级别	显示	编译	用途
Error	红色波浪线	阻止	必须修复的问题
Warning	绿色波浪线	不阻止	应该修复的问题
Info	灰色点状线	不阻止	建议性的改进
Hidden	不显示	不阻止	代码修复触发

Error（错误）

Error 级别的诊断会阻止编译，在 IDE 中显示为红色波浪线。

public static readonly DiagnosticDescriptor ErrorRule = new DiagnosticDescriptor(
    id: "MYLIB001",
    title: "必须实现接口成员",
    messageFormat: "类 '{0}' 必须实现接口 '{1}' 的成员 '{2}'",
    category: "Design",
    defaultSeverity: DiagnosticSeverity.Error,
    isEnabledByDefault: true);

使用场景：

• 违反语言规则
• 缺少必需的实现
• 会导致运行时错误的问题
• 违反强制性的设计约束

Warning（警告）

Warning 级别的诊断不会阻止编译，但建议修复。

public static readonly DiagnosticDescriptor WarningRule = new DiagnosticDescriptor(
    id: "MYLIB002",
    title: "避免在循环中创建对象",
    messageFormat: "在循环中创建 '{0}' 对象可能导致性能问题",
    category: "Performance",
    defaultSeverity: DiagnosticSeverity.Warning,
    isEnabledByDefault: true);

使用场景：

• 命名约定违规
• 性能问题
• 可能的错误
• 未使用的代码
• 不推荐的做法

Info（信息）

Info 级别的诊断提供建议性的信息。

public static readonly DiagnosticDescriptor InfoRule = new DiagnosticDescriptor(
    id: "MYLIB003",
    title: "可以使用更简洁的语法",
    messageFormat: "可以使用 '{0}' 替代 '{1}'",
    category: "Style",
    defaultSeverity: DiagnosticSeverity.Info,
    isEnabledByDefault: true);

使用场景：

• 代码风格建议
• 可选的改进
• 文档建议
• 现代化建议

Hidden（隐藏）

Hidden 级别的诊断不在编辑器中显示，但可以通过代码修复触发。

public static readonly DiagnosticDescriptor HiddenRule = new DiagnosticDescriptor(
    id: "MYLIB004",
    title: "代码修复可用",
    messageFormat: "可以简化此代码",
    category: "Style",
    defaultSeverity: DiagnosticSeverity.Hidden,
    isEnabledByDefault: true,
    customTags: new[] { WellKnownDiagnosticTags.Unnecessary });

使用场景：

• 只通过代码修复触发的诊断
• 不必要的代码
• 不希望在编辑器中显示的诊断

选择指南

使用 Error 如果：

• 违反了 C# 语言规则
• 会导致编译失败
• 会导致运行时崩溃
• 违反了强制性的业务规则

使用 Warning 如果：

• 违反了最佳实践
• 可能导致问题但不会崩溃
• 影响性能或可维护性
• 不符合团队规范

使用 Info 如果：

• 提供建议性的改进
• 代码风格偏好
• 可选的优化
• 文档建议

使用 Hidden 如果：

• 只用于代码修复触发
• 标记不必要的代码
• 不希望在编辑器中显示

相关文档

• 上一篇: Diagnostic 报告
• 下一篇: DiagnosticAnalyzer 实现
• 返回: 诊断 API 索引

决策流程图

决策表

问题类型	严重级别	示例
违反语言规则	Error	类型不匹配、缺少必需实现
会导致运行时错误	Error	空引用解引用、数组越界
违反强制约束	Error	违反自定义的强制规则
命名约定	Warning	PascalCase、camelCase
性能问题	Warning	循环中创建对象、字符串拼接
可能的错误	Warning	可能的空引用、未使用的变量
代码风格	Info	可以简化、使用现代语法
文档建议	Info	添加 XML 注释
代码修复触发	Hidden	不必要的代码、可以移除

选择原则

1. Error：只用于必须修复的问题

   • 违反语言规则
   • 会导致编译失败或运行时错误
   • 违反强制性的设计约束

2. Warning：用于应该修复的问题

   • 不符合最佳实践
   • 可能导致问题
   • 影响代码质量

3. Info：用于建议性的改进

   • 代码风格偏好
   • 可选的优化
   • 文档建议

4. Hidden：用于不显示的诊断

   • 只通过代码修复触发
   • 配合 Unnecessary 标签标记不必要的代码

常见问题

Q: 什么时候使用 Error？

A: 只有在以下情况下使用 Error：

• 违反 C# 语言规则
• 会导致编译失败
• 会导致运行时崩溃
• 违反强制性的业务规则

Q: Warning 和 Info 的区别？

A:

• Warning: 应该修复的问题，可能导致错误或性能问题
• Info: 建议性的改进，不会导致问题

Q: 什么时候使用 Hidden？

A:

• 只用于代码修复触发的诊断
• 标记不必要的代码（配合 Unnecessary 标签）
• 不希望在编辑器中显示的诊断

Q: 如何让用户禁用诊断？

A: 用户可以通过：

1. .editorconfig 文件
2. #pragma warning disable
3. 项目文件中的 <NoWarn>