Beschreibt, wie kommentarbasierte Hilfethemen für Funktionen und (about_Comment_Based_Help)
THEMAabout_Comment_Based_HelpKURZBESCHREIBUNGBeschreibt, wie kommentarbasierte Hilfethemen für Funktionen und Skripts geschrieben werden.DETAILBESCHREIBUNGMithilfe spezieller Schlüsselwörter für Hilfekommentare können Sie kommentarbasierte Hilfethemen für Funktionen und Skripts schreiben. Vom Cmdlet "Get-Help" wird die kommentarbasierte Hilfe in dem Format angezeigt, in dem auch die aus XML-Dateien generierten Cmdlet-Hilfethemen angezeigt werden. Die Hilfe zu Funktionen und Skripts können Sie mit allen Parametern von "Get-Help" anzeigen, z. B. mit "Detailed", "Full", "Example" und "Online". Mithilfe von Schlüsselwörtern für Hilfekommentare können Sie auch XML-Hilfedateien für Skripts und Funktionen schreiben, und Sie können Benutzer zu einer anderen Hilfedatei umleiten. In diesem Thema wird erläutert, wie Hilfethemen für Funktionen und Skripts geschrieben werden. Informationen zum Anzeigen von Hilfethemen für Funktionen und Skripts finden Sie unter "Get-Help". SYNTAX FÜR DIE KOMMENTARBASIERTE HILFE Für die kommentarbasierte Hilfe gilt die folgende Syntax: # .<Hilfeschlüsselwort> # <Hilfeinhalt> -oder - <# .<Hilfeschlüsselwort> <Hilfeinhalt> #> Die kommentarbasierte Hilfe wird als Folge von Kommentaren verfasst. Sie können vor jeder Zeile mit Kommentaren ein Kommentarsymbol (#) eingeben oder mithilfe der Symbole "<#" und "#>" einen Kommentarblock erstellen. Alle Zeilen innerhalb des Kommentarblocks werden als Kommentare interpretiert. Alle Zeilen in einem kommentarbasierten Hilfethema müssen zusammenhängend sein. Wenn ein kommentarbasiertes Hilfethema auf einen Kommentar folgt, der kein Teil des Hilfethemas ist, muss mindestens eine Leerzeile zwischen der letzten nicht zur Hilfe gehörenden Kommentarzeile und dem Anfang der kommentarbasierten Hilfe eingefügt werden. Die einzelnen Abschnitte der kommentarbasierten Hilfe werden durch Schlüsselwörter definiert. Jedem Schlüsselwort der kommentarbasierten Hilfe ist ein Punkt (.) vorangestellt. Die Schlüsselwörter können in beliebiger Reihenfolge angegeben werden. Bei den Namen der Schlüsselwörter wird die Groß- und Kleinschreibung nicht beachtet. Das Description-Schlüsselwort steht z. B. vor der Beschreibung einer Funktion oder eines Skripts. <# .Description Mit Get-Function werden der Name und die Syntax aller Funktionen in der Sitzung angezeigt. #> Der Kommentarblock muss mindestens ein Schlüsselwort enthalten. Einige Schlüsselwörter (z. B. EXAMPLE) können mehrfach im gleichen Kommentarblock angegeben werden. Der Hilfeinhalt für das jeweilige Schlüsselwort beginnt in der Zeile nach dem Schlüsselwort und kann mehrere Zeilen umfassen. SYNTAX FÜR DIE KOMMENTARBASIERTE HILFE IN FUNKTIONEN Die kommentarbasierte Hilfe für eine Funktion kann an drei Stellen angezeigt werden: -- Am Anfang des Funktionstexts. -- Am Ende des Funktionstexts. -- Vor dem Function-Schlüsselwort. Zwischen der letzten Zeile der Funktionshilfe und dem Function-Schlüsselwort darf höchstens eine Leerzeile vorhanden sein. Beispiel: function MeineFunktion { <# .<Hilfeschlüsselwort> <Hilfeinhalt> #> <Funktionsbefehle> } -oder - function MeineFunktion { <Funktionsbefehle> <# .<Hilfeschlüsselwort> <Hilfeinhalt> #> } -oder - <# .<Hilfeschlüsselwort> <Hilfeinhalt> #> function MeineFunktion { } SYNTAX FÜR DIE KOMMENTARBASIERTE HILFE IN SKRIPTS Die kommentarbasierte Hilfe für ein Skript kann im Skript an einer der folgenden beiden Stellen angezeigt werden. -- Am Anfang der Skriptdatei. Der Skripthilfe dürfen im Skript nur Kommentare und Leerzeilen vorangestellt sein. -- Wenn das erste Element im Skripttext (nach der Hilfe) eine Funktionsdeklaration ist, müssen zwischen dem Ende der Skripthilfe und der Funktionsdeklaration mindestens zwei Leerzeilen eingefügt werden. Andernfalls wird die Hilfe als Hilfe für die Funktion und nicht als Hilfe für das Skript interpretiert. -- Am Ende der Skriptdatei. Beispiel: <# .<Hilfeschlüsselwort> <Hilfeinhalt> #> function MeineFunktion { } -oder- function MeineFunktion { } <# .<Hilfeschlüsselwort> <Hilfeinhalt> #> SCHLÜSSELWÖRTER FÜR DIE KOMMENTARBASIERTE HILFE Im Folgenden sind gültige Schlüsselwörter für die kommentarbasierte Hilfe in der Reihenfolge aufgeführt, in der sie normalerweise in einem Hilfethema angegeben werden. Darüber hinaus wird ihr Verwendungszweck angegeben. Diese Schlüsselwörter können in der kommentarbasierten Hilfe in beliebiger Reihenfolge angegeben werden, und ihre Groß- und Kleinschreibung wird nicht berücksichtigt. .SYNOPSIS Eine kurze Beschreibung der Funktion oder des Skripts. Dieses Schlüsselwort kann in jedem Thema nur einmal angegeben werden. .DESCRIPTION Eine ausführliche Beschreibung der Funktion oder des Skripts. Dieses Schlüsselwort kann in jedem Thema nur einmal angegeben werden. .PARAMETER <Parametername> Die Beschreibung eines Parameters. Für jeden Parameter in der Funktions- oder Skriptsyntax kann ein Parameter-Schlüsselwort angegeben werden. Die Parameter-Schlüsselwörter können im Kommentarblock in beliebiger Reihenfolge angezeigt werden, die Funktions- oder Skriptsyntax bestimmt jedoch die Reihenfolge, in der die Parameter (und ihre Beschreibungen) im Hilfethema angezeigt werden. Wenn die Reihenfolge geändert werden soll, müssen Sie die Syntax ändern. Sie können auch eine Parameterbeschreibung angeben, indem Sie direkt vor dem Parametervariablennamen einen Kommentar in der Funktions- oder Skriptsyntax platzieren. Wenn Sie sowohl einen Syntaxkommentar als auch ein Parameter-Schlüsselwort verwenden, wird die zum Parameter-Schlüsselwort gehörende Beschreibung verwendet, während der Syntaxkommentar ignoriert wird. .EXAMPLE Ein Beispielbefehl, der die Funktion oder das Skript verwendet, nach dem optional eine Beispielausgabe und eine Beschreibung angegeben sein können. Wiederholen Sie dieses Schlüsselwort für jedes Beispiel. .INPUTS Die Microsoft .NET Framework-Typen von Objekten, die über die Pipeline an die Funktion oder das Skript übergeben werden können. Sie können auch eine Beschreibung der Eingabeobjekte einschließen. .OUTPUTS Der .NET Framework-Typ der Objekte, die vom Cmdlet zurück- gegeben werden. Sie können auch eine Beschreibung der zurückgegebenen Objekte einschließen. .NOTES Weitere Informationen zur Funktion oder zum Skript. .LINK Der Name eines verwandten Themas. Wiederholen Sie dieses Schlüsselwort für jedes verwandte Thema. Dieser Inhalt wird im Abschnitt "Verwandte Links" des Hilfethemas angezeigt. Der Inhalt zum Link-Schlüsselwort kann auch einen URI (Uniform Resource Identifier) zu einer Onlineversion desselben Hilfethemas enthalten. Die Onlineversion wird geöffnet, wenn Sie den Online-Parameter von "Get-Help" verwenden. Der URI muss mit "http" oder "https" beginnen. .COMPONENT Die Technologie oder das Feature, die von der Funktion oder vom Skript verwendet werden bzw. auf die sie sich beziehen. Dieser Inhalt wird angezeigt, wenn der Befehl "Get-Help" den Component-Parameter von "Get-Help" enthält. .ROLE Die Benutzerrolle für das Hilfethema. Dieser Inhalt wird angezeigt, wenn der Befehl "Get-Help" den Role-Parameter von "Get-Help" enthält. .FUNCTIONALITY Die vorgesehene Verwendung der Funktion. Dieser Inhalt wird angezeigt, wenn der Befehl "Get-Help" den Functionality- Parameter von "Get-Help" enthält. .FORWARDHELPTARGETNAME <Befehlsname> Führt eine Umleitung zum Hilfethema für den angegebenen Befehl aus. Sie können Benutzer zu einem beliebigen Hilfethema umleiten, u. a. zu Hilfethemen für eine Funktion, ein Skript, ein Cmdlet oder einen Anbieter. .FORWARDHELPCATEGORY <Kategorie> Gibt die Hilfekategorie des Elements in "ForwardHelpTargetName" an. Gültige Werte sind Alias, Cmdlet, HelpFile, Function, Provider, General, FAQ, Glossary, ScriptCommand, ExternalScript, Filter und All. Vermeiden Sie mithilfe dieses Schlüsselworts Konflikte, die auf Befehle mit demselben Namen zurückzuführen sind. .REMOTEHELPRUNSPACE <Variable PSSession> Gibt eine Sitzung an, die das Hilfethema enthält. Geben Sie eine Variable ein, die eine PSSession enthält. Mit diesem Schlüsselwort werden vom Cmdlet "Export-PSSession" die Hilfethemen für exportierte Befehle gesucht. .EXTERNALHELP <XML-Hilfedateipfad> Gibt den Pfad zu einer XML-Hilfedatei für das Skript oder die Funktion an. Wenn der angegebene Pfad zur XML-Datei unter Windows Vista und höheren Windows-Versionen Unterverzeichnisse enthält, die spezifisch für die jeweilige Benutzeroberflächenkultur sind, durchsucht "Get-Help" die Unterverzeichnisse rekursiv nach einer XML-Datei mit dem Namen des Skripts bzw. der Funktion. Dabei werden die für Windows Vista festgelegten Ersatzsprachenstandards eingehalten, ebenso wie bei allen XML-Hilfethemen. Weitere Informationen zum XML-Hilfedateiformat für die Cmdlet-Hilfe finden Sie unter "How to Create Cmdlet Help" in der MSDN (Microsoft Developer Network) Library unter "http://go.microsoft.com/fwlink/?LinkID=123415" (möglicher- weise auf Englisch). AUTOMATISCH GENERIERTER INHALT Der Name, die Syntax, die Parameterliste, die Parameterattribut- tabelle, allgemeine Parameter und Hinweise werden automatisch vom Cmdlet "Get-Help" generiert. Name: Der Abschnitt "Name" eines Hilfethemas für eine Funktion wird aus dem Funktionsnamen in die Funktionssyntax übernommen. Der Name eines Hilfethemas für ein Skript wird aus dem Skriptdateinamen übernommen. Wenn Sie den Namen oder seine Großschreibung ändern möchten, müssen Sie die Funktionssyntax oder den Skriptdateinamen ändern. Syntax: Der Abschnitt "Syntax" des Hilfethemas wird aus der Funktion oder der Skriptsyntax generiert. Um der Hilfethemasyntax Details hinzuzufügen (z. B. den .NET Framework-Typ eines Parameters), fügen Sie der Syntax die gewünschten Details hinzu. Wenn Sie keinen Parameter- typ angeben, wird der Typ "Object" als Standardwert eingefügt. Parameterliste: Die Parameterliste im Hilfethema wird aus der Funktion bzw. der Skriptsyntax sowie aus den Beschreibungen generiert, die Sie mit dem Parameters-Schlüsselwort hinzufügen. Die Funktionsparameter werden im Abschnitt "Parameters" des Hilfethemas in derselben Reihenfolge wie in der Funktions- oder Skriptsyntax angezeigt. Die Schreibweise und die Großschreibung von Parameternamen werden ebenfalls aus der Syntax übernommen. Der durch das Parameter-Schlüsselwort angegebene Parametername hat keine Auswirkungen. Allgemeine Parameter: Der Syntax und der Parameterliste des Hilfethemas werden die allgemeinen Parameter hinzugefügt, selbst wenn sie keine Auswirkungen haben. Weitere Informationen zu den allgemeinen Parametern finden Sie unter "about_CommonParameters". Parameterattributtabelle: "Get-Help" generiert die Tabelle der Parameterattribute, die angezeigt wird, wenn der Full-Parameter oder der Parameter-Parameter von Get-Help verwendet wird. Der Wert der Attribute "Erforderlich", "Position" und "Standardwert" wird aus der Funktions- bzw. Skriptsyntax übernommen. Hinweise: Der Abschnitt "Hinweise" des Hilfethemas wird automatisch vom Funktions- oder Skriptnamen generiert. Sein Inhalt kann nicht geändert oder bearbeitet werden. BEISPIELE Beispiel 1: Kommentarbasierte Hilfe für eine Funktion Die folgende Beispielfunktion enthält eine kommentarbasierte Hilfe: function Add-Extension { param ([string]$Name,[string]$Extension = "txt") $name = $name + "." + $extension $name <# .ÜBERSICHT Fügt einem angegebenen Namen eine Dateinamenerweiterung hinzu. .DESCRIPTION Fügt einem angegebenen Namen eine Dateinamenerweiterung hinzu. Akzeptiert beliebige Zeichenfolgen für den Dateinamen oder die Dateinamenerweiterung. .PARAMETER Name Gibt den Dateinamen an. .PARAMETER Extension Gibt die Dateinamenerweiterung an. Der Standardwert ist "txt". .INPUTS Keine. Objekte können nicht über die Pipeline an Add-Extension übergeben werden. .OUTPUTS System.String. Add-Extension gibt eine Zeichenfolge mit der Erweiterung oder dem Dateinamen zurück. .EXAMPLE C:\PS> extension -name "Datei" Datei.txt .EXAMPLE C:\PS> extension -name "Datei" -extension "doc" Datei.doc .EXAMPLE C:\PS> extension "Datei" "doc" Datei.doc .LINK Onlineversion: http://www.fabrikam.com/extension.html .LINK Set-Item #> } Die Ergebnisse lauten wie folgt: C:\PS> get-help add-extension -full NAME Add-Extension ÜBERSICHT Fügt einem angegebenen Namen eine Dateinamenerweiterung hinzu. SYNTAX Add-Extension [[-Name] <String>] [[-Extension] <String>] [<CommonParameters>] BESCHREIBUNG Fügt einem angegebenen Namen eine Dateinamenerweiterung hinzu. Akzeptiert beliebige Zeichenfolgen für den Dateinamen oder die Dateinamenerweiterung. PARAMETER -Name Gibt den Dateinamen an. Erforderlich? false Position? 0 Standardwert Pipelineeingaben akzeptieren? false Platzhalterzeichen akzeptieren? -Extension Gibt die Erweiterung an. Der Standardwert ist "txt". Erforderlich? false Position? 1 Standardwert Pipelineeingaben akzeptieren? false Platzhalterzeichen akzeptieren? <CommonParameters> Dieses Cmdlet unterstützt die folgenden allgemeinen Parameter: -Verbose, -Debug, ErrorAction, -ErrorVariable, -WarningAction, -WarningVariable, OutBuffer und -OutVariable. Weitere Informationen erhalten Sie mit folgendem Befehl: "get-help about_commonparameters". EINGABEN Keine. Objekte können nicht über die Pipeline an Add-Extension übergeben werden. AUSGABEN System.String. Add-Extension gibt eine Zeichenfolge mit der Erweiterung oder dem Dateinamen zurück.Beispiele
BEISPIEL 1C:\PS> extension -name "Datei" Datei.txtBEISPIEL 2C:\PS> extension -name "Datei" -extension "doc" Datei.docBEISPIEL 3C:\PS> extension "Datei" "doc" Datei.doc VERWANDTE LINKS Onlineversion: http://www.fabrikam.com/extension.html Set-Item Beispiel 2: Parameterbeschreibungen in Funktionssyntax Dieses Beispiel entspricht dem vorherigen. Hier werden jedoch die Parameterbeschreibungen in der Funktionssyntax eingefügt. Dieses Format ist insbesondere bei kurzen Beschreibungen nützlich. function Add-Extension { param ( [string] # Gibt den Dateinamen an. $name, [string] # Gibt die Erweiterung an. Der Standardwert ist "txt". $extension = "txt" ) $name = $name + "." + $extension $name <# .SYNOPSIS Fügt einem angegebenen Namen eine Dateinamenerweiterung hinzu. .DESCRIPTION Fügt einem angegebenen Namen eine Dateinamenerweiterung hinzu. Akzeptiert beliebige Zeichenfolgen für den Dateinamen oder die Dateinamenerweiterung. .INPUTS Keine. Objekte können nicht über die Pipeline an Add-Extension übergeben werden. .OUTPUTS System.String. Add-Extension gibt eine Zeichenfolge mit der Erweiterung oder dem Dateinamen zurück. .EXAMPLE C:\PS> extension -name "Datei" Datei.txt .BEISPIEL C:\PS> extension -name "Datei" -extension "doc" Datei.doc .EXAMPLE C:\PS> extension "Datei" "doc" Datei.doc .LINK Onlineversion: http://www.fabrikam.com/extension.html .LINK Set-Item #> } Beispiel 3: Kommentarbasierte Hilfe für ein Skript Das folgende Beispielskript enthält eine kommentarbasierte Hilfe. Beachten Sie die Leerzeilen zwischen der schließenden spitzen Klammer mit Raute "#>" und der Param-Anweisung. In einem Skript ohne Param-Anweisung müssen mindestens zwei Leerzeilen zwischen dem letzten Kommentar im Hilfethema und der ersten Funktionsdeklaration vorhanden sein. Ohne diese Leerzeile ordnet Get-Help das Hilfethema der Funktion und nicht dem Skript zu. <# .SYNOPSIS Führt monatliche Datenupdates aus. .DESCRIPTION Das Skript "Update-Monat.ps1" aktualisiert die Registrierung mit neuen Daten, die während des vergangenen Monats generiert wurden. Außerdem wird ein Bericht generiert. .PARAMETER InputPath Gibt den Pfad der CSV-Eingabedatei an. .PARAMETER OutputPath Gibt den Namen und den Pfad für die CSV-Ausgabedatei an. Standardmäßig generiert "Update-Monat.ps1" einen Namen aus Datum und Uhrzeit seiner Ausführung und speichert die Ausgabe im lokalen Verzeichnis. .INPUTS Keine. Sie können keine Objekte über die Pipeline an "Update-Monat.ps1" übergeben. .OUTPUTS Keine. "Update-Monat.ps1" generiert keine Ausgabe. .EXAMPLE C:\PS> .\Update-Monat.ps1 .EXAMPLE C:\PS> .\Update-Monat.ps1 -inputpath C:\Daten\Januar.csv .EXAMPLE C:\PS> .\Update-Monat.ps1 -inputpath C:\Daten\Januar.csv -outputPath C:\Berichte\2009\Januar.csv #> param ([string]$InputPath, [string]$OutPutPath) function Get-Data { } ... Mit dem folgenden Befehl wird die Skripthilfe aufgerufen. Da sich das Skript nicht in einem Verzeichnis befindet, das in der Path-Umgebungsvariablen aufgeführt ist, muss im Befehl "Get-Help" zum Abrufen der Skripthilfe der Skriptpfad angegeben sein. PS C:\ps-test> get-help .\update-monat.ps1 -full NAME C:\ps-test\Update-Monat.ps1 ÜBERSICHT Führt monatliche Datenupdates aus. SYNTAX C:\ps-test\Update-Monat.ps1 [-InputPath] <String> [[-OutputPath] ]<String>] [<CommonParameters>] BESCHREIBUNG Das Skript "Update-Monat.ps1" aktualisiert die Registrierung mit neuen Daten, die während des vergangenen Monats generiert wurden. Außerdem wird ein Bericht generiert. PARAMETER -InputPath Gibt den Pfad der CSV-Eingabedatei an. Erforderlich? true Position? 0 Standardwert Pipelineeingaben akzeptieren? false Platzhalterzeichen akzeptieren? -OutputPath Gibt den Namen und den Pfad für die CSV-Ausgabedatei an. Standardmäßig generiert "Update-Monat.ps1" einen Namen aus Datum und Uhrzeit seiner Ausführung und speichert die Ausgabe im lokalen Verzeichnis. Erforderlich? false Position? 1 Standardwert Pipelineeingaben akzeptieren? false Platzhalterzeichen akzeptieren? <CommonParameters> Dieses Cmdlet unterstützt die folgenden allgemeinen Parameter: -Verbose, -Debug, ErrorAction, -ErrorVariable, -WarningAction, -WarningVariable, OutBuffer und -OutVariable. Weitere Informationen erhalten Sie mit folgendem Befehl: "get-help about_commonparameters". EINGABEN Keine. Sie können keine Objekte über die Pipeline an "Update-Monat.ps1" übergeben. AUSGABEN Keine. "Update-Monat.ps1" generiert keine Ausgabe.BEISPIEL 1C:\PS> .\Update-Monat.ps1BEISPIEL 2C:\PS> .\Update-Monat.ps1 -inputpath C:\Daten\Januar.csvBEISPIEL 3C:\PS> .\Update-Monat.ps1 -inputpath C:\Daten\Januar.csv -outputPath C:\Berichte\2009\Januar.csv VERWANDTE LINKS Beispiel 4: Umleiten zu einer XML-Datei Sie können XML-Hilfethemen für Funktionen und Skripts schreiben. Die kommentarbasierte Hilfe kann zwar leichter implementiert werden, die XML-Hilfe ist jedoch erforderlich, wenn Sie den Hilfeinhalt genauer festlegen möchten oder wenn Hilfethemen in mehrere Sprachen übersetzt werden sollen. Im folgenden Beispiel werden die ersten Zeilen des Skripts "Update-Monat.ps1" veranschaulicht. Das Skript gibt mithilfe des ExternalHelp-Schlüsselworts den Pfad zu einem XML-Hilfethema für das Skript an. # .ExternalHelp C:\MeineSkripts\Update-Monat-Hilfe.xml param ([string]$InputPath, [string]$OutPutPath) function Get-Data { } ... Im folgenden Beispiel wird die Verwendung des ExternalHelp- Schlüsselworts in einer Funktion veranschaulicht. function Add-Extension { param ([string] $name, [string]$extension = "txt") $name = $name + "." + $extension $name # .ExternalHelp C:\ps-test\Add-Extension.xml } Beispiel 5: Umleiten zu einem anderen Hilfethema Der folgende Code ist ein Auszug aus dem Anfang der integrierten Windows PowerShell-Hilfefunktion, von der jeweils ein Bildschirm mit Hilfetext angezeigt wird. Da im Hilfethema für das Cmdlet "Get-Help" die Hilfefunktion beschrieben wird, wird der Benutzer mit dem ForwardHelpTarget Name-Schlüsselwort und dem ForwardHelpCategory-Schlüsselwort zum Hilfethema für das Cmdlet "Get-Help" umgeleitet. function help { <# .FORWARDHELPTARGETNAME Get-Help .FORWARDHELPCATEGORY Cmdlet #> [CmdletBinding(DefaultParameterSetName='AllUsersView')] param( [Parameter(Position=0, ValueFromPipelineByPropertyName=$true)] [System.String] ${Name}, ... Der folgende Befehl verwendet dieses Feature: C:\PS> get-help help NAME Get-Help ÜBERSICHT Zeigt Informationen zu Windows PowerShell-Cmdlets und -Konzepten an. ... SIEHE AUCH about_Functions about_Functions_Advanced_Parameters about_Scripts "How to Write Cmdlet Help" (http://go.microsoft.com/fwlink/?LinkID=123415) C:\Windows>powershell get-help about_CommonParameters -full
Microsoft Windows [Version 10.0.19045.3693]
Copyright (c) 2023 Microsoft Corporation.
ColorConsole [Version 3.7.1000] PowerShell 2.0-Export
