Skip to main content

测试查询帮助文件

可以使用 CodeQL CLI 以 Markdown 的形式预览查询帮助文件,并确保它们有效。

谁可以使用此功能?

CodeQL 可用于以下存储库类型:

关于查询帮助文件

通过将查询帮助文件呈现为 Markdown 来对其进行测试,以先确保其有效,然后再将其上传到 CodeQL 存储库或在代码扫描中使用它们。

查询帮助是一个文档,它附带了一个查询来说明查询的工作原理,并提供有关查询识别的潜在问题的信息。 建议为所有新查询编写查询帮助。 有关详细信息,请参阅 CodeQL 存储库中的参与 CodeQL

CodeQL CLI 包含一个命令,用于测试查询帮助并将内容呈现为 markdown,使用户可以在 IDE 中轻松预览内容。 先使用该命令验证查询帮助文件,再将这些文件上传到 CodeQL 存储库或与其他用户共享。 从 CodeQL CLI 2.7.1 开始,还可以在 CodeQL 分析期间生成的 SARIF 文件中包含呈现为 markdown 的查询帮助,以便查询帮助可以在代码扫描 UI 中显示。 有关详细信息,请参阅“使用 CodeQL 查询分析代码”。

先决条件

  • 查询帮助 (.qhelp) 文件必须附带一个具有相同基名称的查询 (.ql) 文件。
  • 查询帮助文件应遵循查询帮助文档的标准结构和样式。 有关详细信息,请参阅 CodeQL 存储库中的查询帮助样式指南

正在运行 codeql generate query-help

可以运行以下命令来测试查询帮助文件:

codeql generate query-help <qhelp|query|dir|suite> --format=<format> [--output=<dir|file>]

对于此命令,<qhelp|query|dir|suite> 必须是 .qhelp 文件的路径、.ql 文件的路径、包含查询和查询帮助文件的目录的路径或查询套件的路径。

必须指定一个 --format 选项,用于定义查询帮助的呈现方式。 目前,必须指定 markdown,以将查询帮助呈现为 markdown。

--output 选项定义将在其中保存呈现的查询帮助的文件路径。

  • 对于包含 .qhelp 文件的目录或定义一个或多个 .qhelp 文件的查询套件,必须指定 --output 目录。 输出目录中的文件名将派生自 .qhelp 文件名。
  • 对于单个 .qhelp.ql 文件,可以指定一个 --output 选项。 如果未指定输出路径,则呈现的查询帮助将写入 stdout

有关测试查询帮助文件时可使用的所有选项的完整详细信息,请参阅“generate query-help”。

结果

运行命令时,CodeQL 会尝试呈现每个具有随附 .ql 文件的 .qhelp 文件。 对于单个文件,如果未指定 --output 选项,则将在 stdout 中显示呈现的内容。 对于所有其他用例,呈现的内容将保存到指定的输出路径。

默认情况下,CodeQL CLI 将在以下情况下显示警告消息:

  • 任何查询帮助都无效,无效查询帮助元素的说明也是如此
  • 命令中指定的任何 .qhelp 文件都不具有与随附 .ql 文件相同的基名称
  • 命令中指定的任何 .ql 文件都不具有与随附 .qhelp 文件相同的基名称

可以通过在命令中包含 --warnings 选项来告诉 CodeQL CLI 如何处理这些警告。 有关详细信息,请参阅“generate query-help”。

延伸阅读