关于测试查询帮助文件
通过将查询帮助文件呈现为 Markdown 来测试它们，以确保在将它们上传到 CodeQL 代码库或在代码扫描中使用它们之前它们有效。
查询帮助是伴随查询的文档，用于解释查询的工作原理，以及提供有关查询标识的潜在问题的信息。为所有新查询编写查询帮助是一种良好的实践。有关更多信息，请参阅 CodeQL 代码库中的 为 CodeQL 作出贡献。
CodeQL CLI 包含一个用于测试查询帮助并将其内容呈现为 markdown 的命令，以便您可以轻松地在 IDE 中预览内容。在将查询帮助文件上传到 CodeQL 代码库或与其他用户共享之前，使用此命令验证查询帮助文件。从 CodeQL CLI 2.7.1 开始，您还可以将 markdown 呈现的查询帮助包含在 CodeQL 分析期间生成的 SARIF 文件中，以便可以在代码扫描 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 如何处理这些警告。更多信息，请参见 "生成查询帮助."
进一步阅读
- "查询帮助文件"