Windows PowerShell: Kommentare als Hilfe
Fügen Sie Ihren Skripten Kommentare hinzu, um Ihre eigene Onlinehilfe und ein System für ein Lernprogramm zu erstellen.
Don Jones
Eines der sauberste Dinge zu Windows PowerShell ist seine Hilfesystem. Die Hilfe Dateien sind Syntax-Übersichten, Erläuterungen, Beispiele und so weiter.
Angesichts der Tatsache, dass eine Befehlszeilenshell Erkennbarkeit Features wie Kontext-Menüs, Symbolleisten, Farbbänder usw. anbieten kann, steht die Hilfe-Datei als eine Erkennbarkeit Feature. Sie können mit Platzhaltern, beispielsweise neue Befehle zu entdecken. Dann lesen Sie ihre Hilfe zu erfahren, wie man sie benutzt.
Wie Sie Ihre eigenen Befehle als Funktionen und Skripts zu produzieren, Sie täten gut daran halten Ihre Arbeit als native Windows PowerShell-Cmdlets wie poliert. Sie sollten immer bemühen, Ihre Arbeit so konsistent wie möglich mit dem Rest der Schale zu machen. Teil dieser Konsistenz und Polnisch ist wie Sie sich vorbereiten und Bereitstellen von Hilfe.
Sie konnte genaue dieselbe Art von XML-basierten Dateien erzeugen, die Windows PowerShell selbst verwendet. Gibt es weitere Diskussion zu diesem Thema in meinem Selbstverlag Buch "Windows PowerShell Scripting und Werkzeugbau". Jedoch brauchen die meisten von Ihnen nicht die Flexibilität, denen helfen Dateien anbieten, wie die Fähigkeit, in mehreren Sprachen unterstützen.
Sie können einen viel einfacheren Weg nehmen. Sie können einfach die Kommentar-basierte Hilfe verwenden.
Kommentar-basierte Hilfe Regeln
Es gibt einige Regeln für die Kommentar-basierte Hilfe, dass ich vorne rechts abdecken sollte:
- Normalerweise sollten Sie Ihren speziellen Kommentarblöcke in einschließen die < # Block Kommentar #> Marker. Es ist auch legal, einfach jede Zeile Kommentar, indem Sie es mit der Kommentarzeichen # beginnen.
- Kommentar-basierte Hilfe sollte als erstes in der Skriptdatei. Es ist vorzuziehen, die Hilfe nicht nur vor, sondern innerhalb der Funktion. Das hilft der Kommentar die Funktion "Teil" zu halten und stellt sicher, dass Windows PowerShell wird nicht es für etwas anderes verwirren. Es ist auch zulässig, das Skript des Kommentar-basierte Hilfe am Ende der Datei setzen, aber ich mag nicht tun, denn es einige andere Vorteile der Verwendung von Kommentar-basierte Hilfe abnimmt.
- Wenn Sie Hilfe für eine Funktion zur Verfügung, kann der Kommentar-basierte Hilfe Block unmittelbar vor oder unmittelbar nach dem Funktionsnamen und geschweifte Klammer öffnen kommen.
- Wenn Sie mehrere Funktionen in einem Skript, z. B. ein Skriptmodul erhalten Sie Hilfe für die Datei, indem man den Kommentarblock an der Spitze. Vergewissern Sie sich, wenigstens ein paar Leerzeilen nach diesem Kommentarblock hinzufügen, damit nachfolgende funktionsspezifischen Hilfe richtig auseinander steht.
- Wenn Sie einem der Kommentar-basierte Hilfeschlüsselwörter falsch schreiben, könnte Windows PowerShell den gesamten Block einfach ignorieren. Also sei vorsichtig Ihre Rechtschreibung, weil es darauf ankommt.
Kommentar-basierte Hilfe syntax
Kommentar-basierte Hilfe besteht aus einem oder mehreren Abschnitten. Jeder Abschnitt beginnt mit einem gepunkteten-Schlüsselwort, gefolgt von einem oder mehreren Textzeilen. Hierzu ein Beispiel:
<# .SYNOPSIS The synopsis goes here. This can be one line, or many. .DESCRIPTION The description is usually a longer, more detailed explanation of what the script or function does. Take as many lines as you need. .PARAMETER computername Here, the dotted keyword is followed by a single parameter name. Don't precede that with a hyphen. The following lines describe the purpose of the parameter: .PARAMETER filePath Provide a PARAMETER section for each parameter that your script or function accepts. .EXAMPLE There's no need to number your examples. .EXAMPLE PowerShell will number them for you when it displays your help text to a user. #>
Dieses Beispiel enthält die vier am häufigsten verwendeten gepunkteten Schlüsselwörter. Sie werden feststellen, diese beginnen mit einem Punkt oder Zeitraum. Windows PowerShell ist über die Groß-/Kleinschreibung nicht, obwohl die Dokumentation listet ihnen alle Großbuchstaben (also ich neige dazu, das gleiche zu tun). Großbuchstaben verwenden, ist auch die Abschnitte zeichnen sich ein bisschen mehr wenn Sie den Code im Skript-Editor lesen.
Ein ordentlich Abschnitt können Sie verwenden, ist die Verbindung. Damit können Sie eine URL, beginnend mit dem http:// Adresse, um eine online-Version Ihre Hilfe aufnehmen. Buchen Ihre Hilfe auf einer Intranetsite kann beispielsweise jemand genauer, vielleicht mehr Beispiele erhalten, erfahren Sie, wie mit Ihnen Kontakt aufnehmen und so weiter.
Windows PowerShell generiert automatisch zusätzliche Hilfe durch das Skript bzw. die Funktion betrachten. Es leitet sich der Name, die grundlegende Syntax (inklusive Namen und Datentypen der Parameter) und andere Informationen. Es erkennt keine Standardwerte, die Sie programmiert haben, können in einem Parameter:
Param($computername = 'localhost')
Daher, Sie sollten darauf achten, um Standardwerte in der Hilfe für den Parameter selbst oder auch in der Beschreibung zu dokumentieren.
Kommentar-basierte awesomeness
Ein weiterer Vorteil des Kommentar-basierte Hilfe ist, dass es zwei Arten von Hilfe bietet. Eines ist für Leute, die Hilfe für Ihre Skripts und Funktionen ausführen. Die andere ist für jemanden der Ihre Skripte zu lesen.
Mit anderen Worten, können gut geschriebene Kommentar-basierte Hilfe auch verdoppeln als Inline-Dokumentation, die Sie wahrscheinlich lieber setzen in jeder Art von Skripts.
.jpg)
Don Jones ist ein Microsoft MVP Award Empfänger und Autor der "Lernen Sie Windows PowerShell in ein Monat von Mittagessen" (Manning Publications, 2011), ein Buch soll helfen, alle Administratoren, die mit Windows PowerShell zustande. Jones bietet öffentlichen und vor-Ort-Training an Windows PowerShell. Sie erreichen ihn über ConcentratedTech.com oder bit.ly/AskDon.