/analyze（代码分析）

  • 项目

启用代码分析和控制选项。

语法

一般分析选项：

/analyze[-]
/analyze:only
/analyze:quiet
/analyze:max_paths number
/analyze:stacksize number
/analyze:WX-

分析插件选项：

/analyze:plugin plugin_dll

外部文件分析选项：

/analyze:external-
/analyze:external:ruleset ruleset_files

分析日志选项：

/analyze:autolog[-]
/analyze:autolog:ext extension
/analyze:log log_path

日志文件格式选项：

/analyze:log:format:sarif
/analyze:log:format:xml

日志文件内容选项：

/analyze:sarif:analyzedfiles[-]
/analyze:sarif:configuration[-]
/analyze:log:compilerwarnings
/analyze:log:includesuppressed

规则集选项：

/analyze:rulesetruleset_file

规则集选项：

/analyze:projectdirectory project_directory
/analyze:rulesetdirectory ruleset_directories
/analyze:ruleset ruleset_files

参数

一般分析选项

/analyze[-]
打开代码分析。 使用 /analyze- 显式关闭分析。 默认行为是 /analyze-。

默认情况下，分析输出会像其他错误消息一样进入控制台或 Visual Studio 输出窗口。 代码分析还会创建一个名为 filename.nativecodeanalysis.xml 的日志文件，其中 filename 是分析的源文件的名称。

/analyze:only
默认情况下，编译器在运行代码分析之前编译代码以生成目标文件。 /analyze:only 选项使编译器跳过代码生成过程，直接进行代码分析。 编译器错误仍然会阻止代码分析运行。 但是，编译器不会报告在代码生成过程中可能发现的其他警告。 如果程序没有出现代码生成警告，分析结果可能不可靠。 我们建议你仅在代码通过代码生成语法检查且没有错误或警告的情况下使用此选项。

/analyze:quiet
关闭向控制台或 Visual Studio 输出窗口的分析输出。

/analyze:max_paths number
number 参数指定要分析的最大代码路径数。 分析默认为 256 条路径。 值越大，执行的检查越彻底，但分析时间可能会更长。

/analyze:stacksize number
number 参数指定生成警告 C6262 的堆栈帧的大小（以字节为单位）。 默认堆栈帧大小为 16KB。

/analyze:WX-
告知编译器不要将代码分析警告视为错误，即使使用了 /WX 选项也是如此。 有关详细信息，请参阅 /WX（警告级别）。

分析插件选项

/analyze:plugin plugin_dll
启用指定的代码分析插件 DLL 进行代码分析。

如果路径不需要双引号 (")，则 /analyze:plugin 和 plugin_dll 文件路径之间的空格是可选的。 例如，可在写入 /analyze:plugin EspxEngine.dll。 但如果路径用双引号括起来，则 /analyze:plugin 和文件路径之间不能有空格。 下面是一个示例：/analyze:plugin"c:\path\to\EspxEngine.dll"。

代码分析引擎使用插件来帮助查找特定类别的缺陷。 代码分析引擎带有一些内置插件，可以检测各种缺陷。 要将另一个插件与代码分析引擎一起使用，请使用 /analyze:plugin 选项指定。

LocalEspC.dll 可插件实现与并发相关的分析检查。 这些检查会在 C261XX 范围内发出警告，例如 C26100 到 C26167。

要加载 LocalEspC.dll，请使用编译器选项 /analyze:plugin LocalEspC.dll。

一些插件（如 Visual Studio 附带的 EspXEngine.dll）使用可以进行进一步分析的扩展。 Visual Studio 包括了下列适用于 EspXEngine 的扩展：ConcurrencyCheck.dll、CppCoreCheck.dll、EnumIndex.dll、HResultCheck.dll 和 VariantClear.dll。 它们分别检查并发问题、CppCoreGuidelines 违规、分别将 enum 值、HRESULT 值或 VARIANT 值不当用作索引。

在命令行上构建时，可以使用 Esp.Extensions 环境变量来指定 EspXEngine 扩展。 例如：

set Esp.Extensions=ConcurrencyCheck.dll;CppCoreCheck.dll;

使用分号 (;) 分隔扩展名，如示例中所示。 不需要尾随分号。 你可以使用绝对文件路径作为扩展名，或从包含 EspXEngine.dll 的目录中指定一个相对路径。

EspXEngine.dll 插件使用 ConcurrencyCheck.dll 来实现与并发相关的代码分析检查。 这些检查会在 C261XX 范围内发出警告，例如 C26100 到 C26167。

如果你在开发人员命令提示符窗口中构建，请首先设置环境变量 Esp.Extensions 以指定 ConcurrencyCheck.dll 扩展名：

set Esp.Extensions=ConcurrencyCheck.dll

然后，使用编译器选项 /analyze:plugin EspXEngine.dll 来使用 EspXEngine 插件。

外部文件分析选项

从 Visual Studio 2019 版本 16.10 开始，你可以为外部标头指定不同的分析规则和行为。 使用 /external:I、/external:env 或 /external:anglebrackets 选项将目录指定为“外部”目录。 使用 #include 从外部目录或其子目录中包含的任何文件都被视为外部标头。 有关详细信息，请参阅 /external（外部标头诊断）。

代码分析提供了这些选项来控制对外部文件的分析：

/analyze:external-
跳过对外部头文件的分析。 默认情况下，代码分析会像分析其他文件一样分析外部头文件。 设置 /analyze:external- 选项后，代码分析会跳过任何指定为外部的文件，但来自外部文件的模板除外。 使用 /external:templates- 选项将外部标头中定义的模板视为非外部模板。 /external:Wn 选项不影响代码分析。 例如，代码分析分析外部文件并报告缺陷，即使在指定了 /external:W0 时也是如此。

/analyze:external:ruleset ruleset_files
ruleset_files 参数指定一个或多个以分号分隔的规则集文件以用于分析外部文件。 有关规则集的信息，请参阅“规则集选项”部分。

有一个环境变量 (CAExcludePath) 提供了类似但更简单的功能，可以跳过对环境变量中指定的目录下的文件的分析。 如果同时在 /external:* 选项和 CAExcludePath 环境变量中指定了某个目录，则将其视为已排除，并且 /analyze:external* 选项将不适用于该目录。

分析日志选项

/analyze:autolog[-]
此标志过去是为每个正在分析的源文件创建分析日志文件所必需的。 现在默认创建日志文件，所以这个标志很多时候是多余的。 使用时，它将默认日志扩展名更改为 *.pftlog 而不是 .xml。 使用 /analyze:autolog- 可禁用记录到文件。

/analyze:autolog:ext extension
覆盖分析日志文件的默认扩展名，并改为使用 extension。 如果你使用 .sarif 扩展名，日志文件将使用 SARIF 格式而不是默认的 XML 格式。

/analyze:log log_path
指定日志文件路径 log_path，而不是自动生成的日志文件路径。 当 log_path 路径结尾有反斜杠并引用现有目录时，代码分析会在指定目录中创建所有日志文件。 否则，log_path 将指定文件路径。 文件路径指示编译器将所有分析的源文件的日志合并到指定的日志文件中。 如果文件路径有 .sarif 扩展名，则日志文件使用 SARIF 格式而不是默认的 XML 格式。 使用 /analyze:log:format:* 选项可重写此行为。

日志文件格式选项

从 Visual Studio 2019 版本 16.9 开始，你可以为代码分析指定不同的日志格式选项。

/analyze:log:format:xml
强制使用 XML 日志格式，无论使用哪种文件扩展名。

/analyze:log:format:sarif
强制使用与使用的文件扩展名无关的 SARIF 日志格式。

日志文件内容选项

从 Visual Studio 2019 版本 16.9 开始，你可以为代码分析指定不同的日志内容选项。

/analyze:sarif:analyzedfiles[-]
将文件项目条目添加到 SARIF 日志文件，用于分析不发出警告的文件。 默认已禁用此选项。 始终会包含源文件的项目和发出结果的文件的项目。

/analyze:sarif:configuration[-]
添加规则配置条目以确定用户如何覆盖默认规则配置（默认禁用）。

/analyze:log:compilerwarnings
将分析引擎发现的任何缺陷和所有编译器警告都添加到分析日志文件中。 默认情况下，编译器警告不包含在分析日志文件中。 有关代码分析期间编译器警告的更多信息，请参阅 /analyze:only 选项。

/analyze:log:includesuppressed
将禁止的警告和未禁止的警告添加到分析日志文件中。 默认情况下，分析日志文件中不包含禁止的警告。 如果为分析指定了规则集文件，则即使指定了 /analyze:log:includesuppressed，规则集文件禁用的警告也不会包含在日志中。

规则集选项

/analyze:projectdirectory project_directory
指定当前项目目录。 如果规则集（或它包含的项目）是文件名，编译器首先会在指定的 project_directory 下面查找文件。 如果没有找到，接下来搜索由 /analyze:rulesetdirectory 指定的 ruleset_directories，如果有的话。 如果规则集（或它包含的项目）是相对路径，编译器首先在项目目录下查找文件。 如果未找到规则集，则在当前工作目录中查找。 此选项自 Visual Studio 2019 版本 16.9 起可用。

/analyze:rulesetdirectory ruleset_directories
指定以分号分隔的规则集搜索路径列表。 如果规则集（或其包含的项）是文件名，则编译器首先在 /analyze:projectdirectory 指定的 project_directory 下面查找文件，然后是 ruleset_directories 指定的。 此选项自 Visual Studio 2019 版本 16.9 起可用。

/analyze:ruleset ruleset_files
指定一个或多个用于分析的规则集文件。 此选项可以提高分析效率；分析引擎在运行之前尝试排除在规则集文件中没有指定活动规则的检查器。 否则，引擎将运行所有启用的检查器。

/analyze:ruleset ruleset_file
指定用于分析的规则集文件。 此选项可以提高分析效率；分析引擎在运行之前尝试排除在规则集文件中没有指定活动规则的检查器。 否则，引擎将运行所有启用的检查器。

Visual Studio 附带的规则集文件位于 %VSINSTALLDIR%\Team Tools\Static Analysis Tools\Rule Sets 中。

以下示例自定义规则集告知分析引擎检查是否存在 C6001 和 C26494，并将它们报告为警告。

可以将此文件放在任何位置，前提是你在参数中指定了完整路径。

只要你在参数中指定完整路径，或者在 /analyze:projectdirectory 或 /analyze:rulesetdirectory 选项中指定的目录下，你就可以将此文件放置在任何位置。

<?xml version="1.0" encoding="utf-8"?>
<RuleSet Name="New Rule Set" Description="New rules to apply." ToolsVersion="15.0">
  <Rules AnalyzerId="Microsoft.Analyzers.NativeCodeAnalysis" RuleNamespace="Microsoft.Rules.Native">
    <Rule Id="C6001" Action="Warning" />
    <Rule Id="C26494" Action="Warning" />
  </Rules>
</RuleSet>

默认情况下，规则集文件的文件扩展名为 *.ruleset。 Visual Studio 在浏览规则集文件时使用默认扩展名。 但你可以使用任何扩展名。

有关规则集的详细信息，请参阅使用规则集指定要运行的 C++ 规则。

备注

有关详细信息，请参阅 C/C++ 概述的代码分析和 C/C++ 警告的代码分析。

在 Visual Studio 开发环境中设置此编译器选项

  1. 打开项目的“属性页” 对话框。 有关详细信息，请参阅在 Visual Studio 中设置 C++ 编译器和生成属性。

  2. 选择“配置属性”>“代码分析”>“常规”属性页。

  3. 修改一个或多个“代码分析”属性。

  4. 选择“确定”或“应用”以保存更改。

在 Visual Studio 2019 版本 16.10 及更高版本中设置外部文件分析选项：

  1. 打开项目的“属性页” 对话框。

  2. 选择“配置属性”>“C/C++”>“外部包含”属性页。

  3. 设置属性：

    • “对外部头禁用代码分析”将设置 /analyze:external- 选项。

    • “外部标题的分析规则集”设置 /analyze:external:ruleset path 选项。

  4. 选择“确定”或“应用”以保存更改。

以编程方式设置此编译器选项

  1. 请参阅 EnablePREfast。

另请参阅

MSVC 编译器选项
MSVC 编译器命令行语法