关于查询帮助文件
通过将查询帮助文件呈现为 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文件的路径。- 包含查询和查询帮助文件的目录的路径。
- 查询套件的路径，或 CodeQL 包的已知查询套件的名称。 有关详细信息，请参阅“创建 CodeQL 查询套件”。
必须指定一个 --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”。