Schreiben Sie kommentarbasierte Hilfe für PowerShell-Skripts

1. Kommentarbasierte Hilfe in PowerShell
2. Kommentarbasierte Schlüsselwörter in PowerShell

Dieser Artikel zeigt, wie wir kommentarbasierte Hilfethemen für Skripte und Funktionen schreiben können. Wir werden spezielle Schlüsselwörter für Hilfekommentare verwenden, um die Themen zu erstellen.

Wir verwenden das Cmdlet Get-Help, um kommentarbasierte Hilfethemen anzuzeigen, die denen ähneln, die von XML-Dateien generiert werden.

Kommentarbasierte Hilfe in PowerShell

Unten ist die Syntax für kommentarbasierte Hilfe dargestellt.

# .<help keyword>
# <help content>

oder

<#
.<help keyword>
<help content>
#>

Wir schreiben kommentarbasierte Hilfethemen als eine Reihe von Kommentaren. Um Kommentare zu markieren, können wir entweder das Symbol # am Anfang jeder Kommentarzeile einfügen oder mit <# und #> einen Kommentarblock erstellen.

Die Konsole registriert die Zeilen innerhalb des Kommentarblocks als Kommentare.

Wir verwenden spezielle Schlüsselwörter, um jeden Abschnitt einer kommentarbasierten Themenhilfe zu definieren. Schlüsselwörter beginnen mit einem . und achten nicht auf Groß- und Kleinschreibung.

Hier ist ein Beispiel:

<#
.Description
Get-Clipboard fetches the content of our clipboard in the session.
#>

Im obigen Beispiel markiert das Schlüsselwort .Description den Kommentar als Beschreibung unserer Funktion.

Ein Kommentarblock muss mindestens ein Schlüsselwort enthalten. Manche Keywords kommen nur einmal vor, andere haben kein Limit.

Der Inhalt für ein Schlüsselwort sollte in der Zeile unmittelbar nach dem Schlüsselwort beginnen und hat keine Begrenzung.

Wenn Sie kommentarbasierte Hilfe für Funktionen hinzufügen, können Sie diese an einer der drei unten beschriebenen Stellen hinzufügen.

1. Am Anfang des Funktionskörpers.
2. Am Ende des Funktionskörpers.
3. Vor dem Schlüsselwort Funktion. Durch höchstens eine Leerzeile getrennt.

Beispiele:

function Get-Function
{
<#
.<help keyword>
<content>
#>

  # function logic
}

oder

function Get-Function
{
   # function logic

<#
.<help keyword>
<content>
#>
}

oder

<#
.<help keyword>
<content>
#>
function Get-Function { }

Kommentarbasierte Hilfe für Skripte kann entweder am Anfang oder am Ende des Skripts erscheinen. Hier sind einige Beispiele:

<#
.<help keyword>
<content>
#>

function Get-Function { }

oder

function Get-Function { }

<#
.<help keyword>
<content>
#>

Kommentarbasierte Schlüsselwörter in PowerShell

Nachfolgend sind die gültigen kommentarbasierten Hilfeschlüsselwörter aufgeführt. Sie können in beliebiger Reihenfolge erscheinen und es wird nicht zwischen Groß- und Kleinschreibung unterschieden.

.SYNOPSIS

Dies ist eine kurze Beschreibung der Funktion oder des Skripts. Das Keyword sollte in jedem Thema nur einmal vorkommen.

.BESCHREIBUNG

Dies ist eine detaillierte Beschreibung einer Funktion oder eines Skripts. Wir verwenden es nur einmal in jedem Thema.

.PARAMETER

Dies beschreibt die Parameter in Ihrem Skript oder Ihrer Funktion. Wir fügen für jeden Parameter in unseren Skripten oder Funktionen ein Schlüsselwort .PARAMETER hinzu.

.PARAMETER <Parameter-Name>

Parameterschlüsselwörter folgen keiner strengen Reihenfolge im Kommentarblock. Die Syntax der Parameter im Skript oder in der Funktion bestimmt die Reihenfolge im Hilfethema.

Sie können die Reihenfolge ändern, indem Sie die Syntax ändern.

Wir können den Inhalt des Parameterschlüsselworts angeben, indem wir einen Kommentar in oder Funktion oder Skript hinzufügen. Dieser Kommentar sollte dem Namen der Parametervariablen vorangestellt werden.

PowerShell priorisiert die mit dem Parameterschlüsselwort verknüpfte Beschreibung gegenüber dem Syntaxkommentar, wenn beide verwendet werden.

<#
.SYNOPSIS
    Brief description
#>
function Noun-Verb {
    [CmdletBinding()]
    param (
        # It is the same as .Parameter
        [string]$CompName
    )
    # Logic
}

.BEISPIEL

Fügen Sie einen Beispielbefehl ein, der das Skript oder die Funktion verwendet. Wir können dieses Schlüsselwort für alle Beispiele in unserem Skript oder unserer Funktion einschließen.

.EINGABEN

Dies sind die .NET-Objekte, die wir an unser Skript oder unsere Funktion weiterleiten können. Wir können eine Beschreibung für die Eingabeobjekte hinzufügen.

.AUSGÄNGE

Dies sind die .NET-Objekte, die unser Cmdlet zurückgibt. Wir können eine Beschreibung für die zurückgegebenen Objekte hinzufügen.

.NOTEN

Dies sind alle zusätzlichen Informationen über das Skript oder die Funktion. Die Informationen können das Codierungsdatum, den Funktionsnamen oder den Namen des Erstellers enthalten.

.LINK

Dies sind die verwandten Themen.

Hier ist ein Beispiel für eine kommentarbasierte Hilfe für eine Funktion:

Zusammenfassend können wir kommentarbasierte Hilfe in Funktionen oder Skripte einfügen, indem wir sie in einen Kommentarblock einfügen. Verwenden Sie beim Hinzufügen von Hilfethemen das oben besprochene Schlüsselwort und denken Sie daran, wo Sie die Kommentarblöcke für Skripte und Funktionen platzieren müssen.