.NET 源代码分析概述
.NET Compiler Platform (Roslyn) 分析器会检查 C# 或 Visual Basic 代码的代码质量和样式问题。 从 .NET 5 开始，这些分析器包含在 .NET SDK 中，无需单独安装。 如果项目面向 .NET 5 或更高版本，则默认启用代码分析。 如果项目面向不同的 .NET 实现（例如 .NET Core、.NET Standard 或 .NET Framework），则必须通过将 EnableNETAnalyzers 属性设置为 true 以手动启用代码分析。
如果你不想移动到 .NET 5+ SDK、具有非 SDK 样式的 .NET Framework 项目或更倾向于使用基于 NuGet 包的模型，则也可以在 Microsoft.CodeAnalysis.NetAnalyzers NuGet 包中使用该分析器。 对于按需版本更新，你可能更倾向于使用基于包的模型。
注意
.NET 分析器与目标框架无关。 即，你的项目不需要面向特定的 .NET 实现。 分析器适用于面向 .NET 5+ 及更早 .NET 版本（如 .NET Core 3.1 和 .NET Framework 4.7.2）的项目。 但是，若要使用 EnableNETAnalyzers 属性启用代码分析，则项目必须引用项目 SDK。
如果分析器发现规则冲突，则这些冲突会被报告为建议、警告或错误，具体取决于每个规则的配置方式。 代码分析冲突以前缀“CA”或“IDE”显示，以便将它们与编译器错误区分开来。
代码质量分析
代码质量分析（“CAxxxx”）规则检查 C# 或 Visual Basic 代码的安全性、性能、设计及其他问题。 分析功能针对面向 .NET 5 或更高版本的项目默认启用。 可通过将 EnableNETAnalyzers 属性设置为 true，在面向 .NET 早期版本的项目上启用代码分析。 你也可通过将 EnableNETAnalyzers 设置为 false，对项目禁用代码分析。
提示
如果使用的是 Visual Studio，则许多分析器规则都有相关的代码修补程序，可以应用它们来纠正问题。 代码修补程序显示在灯泡图标菜单中。
已启用的规则
默认情况下，将启用以下规则作为 .NET 8 中的错误或警告。 其他规则作为建议启用。
| 诊断 ID | 类别 | Severity | 新增的版本 | 说明 |
|---|---|---|---|---|
| CA1416 | 互操作性 | 警告 | .NET 5 | 验证平台兼容性 |
| CA1417 | 互操作性 | 警告 | .NET 5 | 请勿对 P/Invokes 的字符串参数使用 OutAttribute |
| CA1418 | 互操作性 | 警告 | .NET 6 | 使用有效的平台字符串 |
| CA1420 | 互操作性 | 警告 | .NET 7 | 在禁用后使用需要运行时封送的功能将导致运行时异常 |
| CA1422 | 互操作性 | 警告 | .NET 7 | 验证平台兼容性 |
| CA1831 | 性能 | 警告 | .NET 5 | 在合适的情况下，对字符串使用 AsSpan 而不是基于范围的索引器 |
| CA1856 | 性能 | 错误 | .NET 8 | ConstantExpected 属性的用法不正确 |
| CA1857 | 性能 | 警告 | .NET 8 | 参数需要常数 |
| CA2013 | 可靠性 | 警告 | .NET 5 | 请勿将 ReferenceEquals 与值类型结合使用 |
| CA2014 | 可靠性 | 警告 | .NET 5 | 请勿在循环中使用 stackalloc |
| CA2015 | 可靠性 | 警告 | .NET 5 | 请勿为派生自 MemoryManager<T> 的类型定义终结器 |
| CA2017 | 可靠性 | 警告 | .NET 6 | 参数计数不匹配 |
| CA2018 | 可靠性 | 警告 | .NET 6 | Buffer.BlockCopy 的 count 参数应指定要复制的字节数 |
| CA2021 | 可靠性 | 警告 | .NET 8 | 请勿使用不兼容类型调用 Enumerable.Cast<T> 或 Enumerable.OfType<T> |
| CA2022 | 可靠性 | 警告 | .NET 9 | 避免使用 读取不精确 Stream.Read |
| CA2200 | 使用情况 | 警告 | .NET 5 | 再次引发以保留堆栈详细信息 |
| CA2247 | 使用情况 | 警告 | .NET 5 | 传递到 TaskCompletionSource 构造函数的参数应为 TaskCreationOptions 枚举，而不是 TaskContinuationOptions |
| CA2252 | 使用情况 | 错误 | .NET 6 | 选择预览功能 |
| CA2255 | 使用情况 | 警告 | .NET 6 | 不应在库中使用 ModuleInitializer 属性 |
| CA2256 | 使用情况 | 警告 | .NET 6 | 在父接口中声明的所有成员必须在 DynamicInterfaceCastableImplementation 特性的接口中具有实现 |
| CA2257 | 使用情况 | 警告 | .NET 6 | 使用 DynamicInterfaceCastableImplementationAttribute 在接口上定义的成员应为 static |
| CA2258 | 使用情况 | 警告 | .NET 6 | 不支持在 Visual Basic 中提供 DynamicInterfaceCastableImplementation 接口 |
| CA2259 | 使用情况 | 警告 | .NET 7 | ThreadStatic 仅影响静态字段 |
| CA2260 | 使用情况 | 警告 | .NET 7 | 使用正确的类型参数 |
| CA2261 | 使用情况 | 警告 | .NET 8 | 请勿将 ConfigureAwaitOptions.SuppressThrowing 和 Task<TResult> 搭配使用 |
可更改这些规则的严重性，以禁用这些规则或将它们提升为错误。 也可启用更多规则。
启用其他规则
分析模式指预定义的代码分析配置，在此配置下，未启用任何规则、启用某些规则或启用所有规则。 在默认分析模式 (Default) 下，只有少量规则作为生成警告启用。 可通过在项目文件中设置 <AnalysisMode> 属性来更改项目的分析模式。 允许的值为：
| 值 | 说明 |
|---|---|
None |
所有规则都处于禁用状态。 可以选择选择加入各条规则，以启用它们。 |
Default |
默认模式是指某些规则作为生成警告启用；在该模式下，某些规则作为 Visual Studio IDE 建议启用，其余规则被禁用。 |
Minimum |
比 Default 模式更主动的模式。 强烈建议生成实施的某些建议作为生成警告启用。 若要查看其中包含的规则，请检查 %ProgramFiles%/dotnet/sdk/[version]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_minimum.editorconfig 文件。 |
Recommended |
比 Minimum 模式更主动的模式，其中启用了更多规则作为生成警告。 若要查看其中包含的规则，请检查 %ProgramFiles%/dotnet/sdk/[version]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_recommended.editorconfig 文件。 |
All |
所有规则作为生成警告启用*。 可以选择选择退出各条规则，以禁用它们。 * 如果将 AnalysisMode 设置为 All，或者将 AnalysisLevel 设置为 latest-all，以下规则将不会启用：CA1017、CA1045、CA1005、CA1014、CA1060、CA1021 和代码指标分析器规则（CA1501、CA1502、CA1505、CA1506 和 CA1509）。 将来的版本可能会弃用这些旧规则。 但是，这些规则仍然可以通过使用 dotnet_diagnostic.CAxxxx.severity = <severity> 条目来单独启用。 |
从 .NET 6 开始，可省略 <AnalysisMode> 来支持 <AnalysisLevel> 属性的复合值。 例如，以下值为最新版本实现推荐的一组规则：<AnalysisLevel>latest-Recommended</AnalysisLevel>。 有关详细信息，请参阅 AnalysisLevel。
若要查找每个可用规则的默认严重性以及了解规则是否在 Default 分析模式下启用，请参阅完整规则列表。
视警告为错误
如果在生成项目时使用 -warnaserror 标志，则所有代码分析警告也会被视为错误。 如果不希望在出现 -warnaserror 时将代码质量警告 (CAxxxx) 视为错误，可在项目文件中将 CodeAnalysisTreatWarningsAsErrors MSBuild 属性设置为 false。
<PropertyGroup>
<CodeAnalysisTreatWarningsAsErrors>false</CodeAnalysisTreatWarningsAsErrors>
</PropertyGroup>
你仍会看到任何代码分析警告，但它们不会中断生成。
最新更新
默认情况下，在升级到较新版本的 .NET SDK 时，你将获得最新的代码分析规则和默认规则严重性。 如果你不希望出现此行为（例如，如果你想要确保未启用或禁用任何新规则），可通过以下方式之一来替代此行为：
将
AnalysisLevelMSBuild 属性设置为特定值，以将警告锁定到相应的集。 在升级到较新的 SDK 时，你仍会获得针对这些警告的 bug 修补程序，但系统不会启用新的警告，也不会禁用现有的警告。 例如，若要将规则集锁定为随 .NET SDK 5.0 版本一起提供的规则集，请向项目文件添加以下条目。<PropertyGroup> <AnalysisLevel>5.0</AnalysisLevel> </PropertyGroup>提示
AnalysisLevel属性的默认值为latest，这意味着在你移动到较新版本的 .NET SDK 时，你始终会获得最新的代码分析规则。如需了解详细信息，以及查看可能值的列表，请参阅AnalysisLevel。
安装 Microsoft.CodeAnalysis.NetAnalyzers NuGet 包，将规则更新与 .NET SDK 更新分离。 对于面向 .NET 5+ 的项目，安装该包将关闭内置 SDK 分析器。 如果 SDK 所含的分析器程序集版本比 NuGet 包所含的版本更新，你会收到生成警告。 若要禁用该警告，请将
_SkipUpgradeNetAnalyzersNuGetWarning属性设置为true。注意
如果你安装了 Microsoft.CodeAnalysis.NetAnalyzers NuGet 包，则不应将 EnableNETAnalyzers 属性添加到项目文件或 Directory.Build.props 文件。 在安装了 NuGet 包并将
EnableNETAnalyzers属性设置为true时，一个生成警告随即生成。
代码样式分析
通过代码样式分析（“IDExxxx”）规则，可在代码库中定义和维护一致的代码样式。 默认的启用设置为：
命令行生成：默认情况下，对命令行生成上的所有 .NET 项目禁用代码样式分析。
从 .NET 5 开始，无论是在命令行还是在 Visual Studio 内，你都可以在生成时启用代码样式分析。 代码样式冲突显示为带有“IDE”前缀的警告或错误。 这使你能够在生成时强制执行一致的代码样式。
Visual Studio：默认情况下，代码样式分析作为代码重构快速操作对 Visual Studio 中的所有 .NET 项目启用。
有关代码样式分析规则的完整列表，请参阅代码样式规则。
生成时启用
通过 .NET 5 SDK 及更高版本，可在从命令行和 Visual Studio 生成时启用代码样式分析。 （然而，出于性能方面的原因，一些代码样式规则仍仅适用于 Visual Studio IDE。）
执行以下步骤，在生成时启用代码样式分析：
将 MSBuild 属性 EnforceCodeStyleInBuild 设置为
true。在 .editorconfig 文件中，配置你希望在生成时作为警告或错误运行的每个“IDE”代码样式规则。 例如：
[*.{cs,vb}] # IDE0040: Accessibility modifiers required (escalated to a build warning) dotnet_diagnostic.IDE0040.severity = warning提示
从 .NET 9 开始，还可以使用选项格式 指定严重性，并在生成时考虑它。 例如：
[*.{cs,vb}] # IDE0040: Accessibility modifiers required (escalated to a build warning) dotnet_style_require_accessibility_modifiers = always:warning或者，可将整个类别默认配置为警告或错误，然后选择性地禁用该类别中你不希望在生成时运行的规则。 例如：
[*.{cs,vb}] # Default severity for analyzer diagnostics with category 'Style' (escalated to build warnings) dotnet_analyzer_diagnostic.category-Style.severity = warning # IDE0040: Accessibility modifiers required (disabled on build) dotnet_diagnostic.IDE0040.severity = silent
抑制警告
一种抑制规则冲突的方法是在 EditorConfig 文件中将该规则 ID 的严重性选项设置为 none。 例如：
dotnet_diagnostic.CA1822.severity = none
有关抑制警告的详细信息和其他方式，请参阅如何抑制代码分析警告。
第三方分析器
除了官方 .NET 分析器外，你也可以安装第三方分析器，如 StyleCop、Roslynator、XUnit Analyzers 和 Sonar Analyzer。
