Informationen zum Testen von Abfragehilfedateien
Teste Abfragehilfedateien, indem du sie als Markdown renderst, um sicherzustellen, dass sie gültig sind, bevor du sie in das CodeQL-Repository hochlädst oder sie bei der Codeüberprüfung verwendest.
Die Abfragehilfe ist eine begleitende Dokumentation zu einer Abfrage, in der erklärt wird, wie die Abfrage funktioniert, und die Informationen zu dem möglichen Problem liefert, das die Abfrage ermittelt hat. Es empfiehlt sich, Abfragehilfen für alle neuen Abfragen zu schreiben. Weitere Informationen findest du unter Beitragen zu CodeQL im CodeQL-Repository.
Die CodeQL CLI enthält einen Befehl zum Testen der Abfragehilfe und zum Rendern des Inhalts als Markdowndatei, sodass du eine einfache Vorschau des Inhalts in deiner IDE anzeigen kannst. Verwende den Befehl, um Abfragehilfedateien zu überprüfen, bevor du sie in das CodeQL-Repository hochlädst oder sie für andere Benutzer freigibst. Ab CodeQL CLI 2.7.1 kannst du auch die mit Markdown gerenderte Abfragehilfe in SARIF-Dateien einschließen, die bei CodeQL-Analysen generiert werden, sodass die Abfragehilfe auf der Benutzeroberfläche für die Codeüberprüfung angezeigt werden kann. Weitere Informationen findest du unter Analysieren des Codes mit CodeQL-Abfragen.
Voraussetzungen
- Zur Abfragehilfedatei (
.qhelp) muss eine begleitende Abfragedatei (.ql) mit identischem Basisnamen vorhanden sein. - Die Abfragehilfedatei sollte der Standardstruktur und dem Standardstil der Dokumentation zur Abfragehilfe entsprechen. Weitere Informationen findest du im Leitfaden zur Abfragehilfe im CodeQL-Repository.
Wird ausgeführt codeql generate query-help
Du kannst Abfragehilfedateien testen, indem du den folgenden Befehl ausführst:
codeql generate query-help <qhelp|query|dir|suite> --format=<format> [--output=<dir|file>]
Für diesen Befehl muss <qhelp|query|dir|suite> der Pfad zu einer .qhelp-Datei, der Pfad zu einer .ql-Datei, der Pfad zu einem Verzeichnis, das Abfragen und Abfragehilfedateien enthält, oder der Pfad zu einer Abfragesammlung sein.
Du musst eine --format-Option angeben, die definiert, wie die Abfragehilfe gerendert wird. Derzeit musst du markdown angeben, um die Abfragehilfe als Markdowndatei zu rendern.
Die --output-Option definiert einen Dateipfad, in dem die gerenderte Abfragehilfe gespeichert wird.
- Für Verzeichnisse mit
.qhelp-Dateien oder Abfragesammlungen, die eine oder mehrere.qhelp-Dateien definieren, musst du ein--output-Verzeichnis angeben. Dateinamen innerhalb des Ausgabeverzeichnisses werden von den.qhelp-Dateinamen abgeleitet. - Für einzelne
.qhelp- oder.ql-Dateien kannst du eine--output-Option angeben. Wenn du keinen Ausgabepfad angibst, wird die gerenderte Abfragehilfe instdoutgeschrieben.
Ausführliche Informationen zu allen Optionen, die du beim Testen von Abfragehilfedateien verwenden kannst, findest du unter generate query-help.
Ergebnisse
Wenn du den Befehl ausführst, versucht CodeQL, jede .qhelp-Datei zu rendern, zu der eine .ql-Datei vorhanden ist. Bei einzelnen Dateien wird der gerenderte Inhalt als stdout ausgegeben, wenn du keine --output-Option angibst. Für alle anderen Anwendungsfälle wird der gerenderte Inhalt im angegebenen Ausgabepfad gespeichert.
Standardmäßig gibt die CodeQL CLI eine Warnmeldung aus, wenn Folgendes zutrifft:
- Ein Teil der Abfragehilfe ist ungültig. Außerdem wird eine Beschreibung der ungültigen Elemente der Abfragehilfe angegeben.
- Alle im Befehl angegebenen
.qhelp-Dateien haben nicht den gleichen Basisnamen wie die zugehörige.ql-Datei. - Alle im Befehl angegebenen
.ql-Dateien haben nicht den gleichen Basisnamen wie die zugehörige.qhelp-Datei.
Du kannst der CodeQL CLI vorgeben, wie diese Warnungen behandelt werden sollen, indem du eine --warnings-Option in deinen Befehl einfügst. Weitere Informationen findest du unter generate query-help.