Beispiele für kommentarbasierte Hilfe

2025-03-25

Dieses Thema enthält Beispiele, die veranschaulichen, wie sie kommentarbasierte Hilfe für Skripts und Funktionen verwenden.

Beispiel 1: Kommentarbasierte Hilfe für eine Funktion

Die folgende Beispielfunktion enthält kommentarbasierte Hilfe.

function Add-Extension
{
    param ([string]$Name,[string]$Extension = "txt")
    $Name = $Name + "." + $Extension
    $Name

    <#
        .SYNOPSIS
        Adds a file name extension to a supplied name.

        .DESCRIPTION
        Adds a file name extension to a supplied name.
        Takes any strings for the file name or extension.

        .PARAMETER Name
        Specifies the file name.

        .PARAMETER Extension
        Specifies the extension. "Txt" is the default.

        .INPUTS
        None. You can't pipe objects to Add-Extension.

        .OUTPUTS
        System.String. Add-Extension returns a string with the extension or file name.

        .EXAMPLE
        PS> Add-Extension -Name "File"
        File.txt

        .EXAMPLE
        PS> Add-Extension -Name "File" -Extension "doc"
        File.doc

        .EXAMPLE
        PS> Add-Extension "File" "doc"
        File.doc

        .LINK
        Online version: http://www.fabrikam.com/add-extension.html

        .LINK
        Set-Item
    #>
}

Die folgende Ausgabe zeigt die Ergebnisse eines Get-Help Befehls, der die Hilfe für die Add-Extension-Funktion anzeigt.

PS> Get-Help Add-Extension -Full

NAME
    Add-Extension

SYNOPSIS
    Adds a file name extension to a supplied name.

SYNTAX
    Add-Extension [[-Name] <String>] [[-Extension] <String>] [<CommonParameters>]

DESCRIPTION
    Adds a file name extension to a supplied name. Takes any strings for the file name or extension.

PARAMETERS
    -Name
        Specifies the file name.

        Required?                    false
        Position?                    0
        Default value
        Accept pipeline input?       false
        Accept wildcard characters?

    -Extension
        Specifies the extension. "Txt" is the default.

        Required?                    false
        Position?                    1
        Default value
        Accept pipeline input?       false
        Accept wildcard characters?

    <CommonParameters>
        This cmdlet supports the common parameters: -Verbose, -Debug,
        -ErrorAction, -ErrorVariable, -WarningAction, -WarningVariable,
        -OutBuffer and -OutVariable. For more information, type
        "Get-Help about_CommonParameters".

INPUTS
    None. You can't pipe objects to Add-Extension.

OUTPUTS
    System.String. Add-Extension returns a string with the extension or file name.

    -------------------------- EXAMPLE 1 --------------------------

    PS> Add-Extension -Name "File"
    File.txt

    -------------------------- EXAMPLE 2 --------------------------

    PS> Add-Extension -Name "File" -Extension "doc"
    File.doc

    -------------------------- EXAMPLE 3 --------------------------

    PS> Add-Extension "File" "doc"
    File.doc

RELATED LINKS
    Online version: http://www.fabrikam.com/add-extension.html
    Set-Item

Beispiel 2: Kommentarbasierte Hilfe für ein Skript

Die folgende Beispielfunktion enthält kommentarbasierte Hilfe.

Beachten Sie die leeren Zeilen zwischen der abschließenden #> und der param Anweisung. In einem Skript, das nicht über eine param-Anweisung verfügt, muss es mindestens zwei Leerzeilen zwischen dem endgültigen Kommentar im Hilfethema und der ersten Funktionsdeklaration geben. Ohne diese leeren Zeilen ordnet Get-Help das Hilfethema der Funktion anstelle des Skripts zu.

<#
  .SYNOPSIS
  Performs monthly data updates.

  .DESCRIPTION
  The Update-Month.ps1 script updates the registry with new data generated
  during the past month and generates a report.

  .PARAMETER InputPath
  Specifies the path to the CSV-based input file.

  .PARAMETER OutputPath
  Specifies the name and path for the CSV-based output file. By default,
  MonthlyUpdates.ps1 generates a name from the date and time it runs, and
  saves the output in the local directory.

  .INPUTS
  None. You can't pipe objects to Update-Month.ps1.

  .OUTPUTS
  None. Update-Month.ps1 doesn't generate any output.

  .EXAMPLE
  PS> .\Update-Month.ps1

  .EXAMPLE
  PS> .\Update-Month.ps1 -InputPath C:\Data\January.csv

  .EXAMPLE
  PS> .\Update-Month.ps1 -InputPath C:\Data\January.csv -OutputPath C:\Reports\2009\January.csv
#>

param ([string]$InputPath, [string]$OutputPath)

function Get-Data { }

Der folgende Befehl ruft die Skripthilfe ab. Da sich das Skript nicht in einem Verzeichnis befindet, das in der PATH-Umgebungsvariable aufgeführt ist, muss der Befehl Get-Help, der die Skripthilfe abruft, den Skriptpfad angeben.

PS> Get-Help C:\ps-test\update-month.ps1 -Full

NAME
    C:\ps-test\Update-Month.ps1

SYNOPSIS
    Performs monthly data updates.

SYNTAX
    C:\ps-test\Update-Month.ps1 [-InputPath] <String> [[-OutputPath]
    <String>] [<CommonParameters>]

DESCRIPTION
    The Update-Month.ps1 script updates the registry with new data
    generated during the past month and generates a report.

PARAMETERS
    -InputPath
        Specifies the path to the CSV-based input file.

        Required?                    true
        Position?                    0
        Default value
        Accept pipeline input?       false
        Accept wildcard characters?

    -OutputPath
        Specifies the name and path for the CSV-based output file. By
        default, MonthlyUpdates.ps1 generates a name from the date
        and time it runs, and saves the output in the local directory.

        Required?                    false
        Position?                    1
        Default value
        Accept pipeline input?       false
        Accept wildcard characters?

    <CommonParameters>
        This cmdlet supports the common parameters: -Verbose, -Debug,
        -ErrorAction, -ErrorVariable, -WarningAction, -WarningVariable,
        -OutBuffer and -OutVariable. For more information, type,
        "Get-Help about_CommonParameters".

INPUTS
        None. You can't pipe objects to Update-Month.ps1.

OUTPUTS
        None. Update-Month.ps1 doesn't generate any output.

-------------------------- EXAMPLE 1 --------------------------

PS> .\Update-Month.ps1

-------------------------- EXAMPLE 2 --------------------------

PS> .\Update-Month.ps1 -InputPath C:\Data\January.csv

-------------------------- EXAMPLE 3 --------------------------

PS> .\Update-Month.ps1 -InputPath C:\Data\January.csv -OutputPath
C:\Reports\2009\January.csv

RELATED LINKS

Beispiel 3: Parameterbeschreibungen in einer `param`-Anweisung

In diesem Beispiel wird gezeigt, wie Parameterbeschreibungen in die param-Anweisung einer Funktion oder eines Skripts eingefügt werden. Dieses Format ist am nützlichsten, wenn die Parameterbeschreibungen kurz sind.

function Add-Extension
{
    param
    (
        [string]
        # Specifies the file name.
        $Name,

        [string]
        # Specifies the file name extension. "Txt" is the default.
        $Extension = "txt"
    )
    $Name = $Name + "." + $Extension
    $Name

    <#
        .SYNOPSIS
        Adds a file name extension to a supplied name.
...
    #>
}

Die Ergebnisse entsprechen den Ergebnissen für Beispiel 1. Get-Help interpretiert die Parameterbeschreibungen so, als ob sie vom schlüsselwort .PARAMETER begleitet wurden.

Beispiel 4: Umleiten zu einer XML-Datei

Sie können XML-basierte Hilfethemen für Funktionen und Skripts schreiben. Obwohl die kommentarbasierte Hilfe einfacher zu implementieren ist, ist die XML-basierte Hilfe erforderlich, wenn Sie eine genauere Kontrolle über Hilfeinhalte wünschen oder Wenn Sie Hilfethemen in mehrere Sprachen übersetzen. Das folgende Beispiel zeigt die ersten Zeilen des skripts Update-Month.ps1. Das Skript verwendet das schlüsselwort .EXTERNALHELP, um den Pfad zu einem XML-basierten Hilfethema für das Skript anzugeben.

# .EXTERNALHELP C:\MyScripts\Update-Month-Help.xml

    param ([string]$InputPath, [string]$OutputPath)

    function Get-Data { }

Das folgende Beispiel zeigt die Verwendung des schlüsselworts .EXTERNALHELP in einer Funktion.

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 vom Anfang der integrierten help-Funktion in PowerShell, der jeweils einen Bildschirm mit Hilfetext anzeigt. Da das Hilfethema für das Cmdlet Get-Help die Hilfefunktion beschreibt, verwendet die Hilfefunktion die .FORWARDHELPTARGETNAME und .FORWARDHELPCATEGORY Schlüsselwörter, um den Benutzer an das Hilfethema Get-Help Cmdlet umzuleiten.

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. Wenn ein Benutzer einen Get-Help-Befehl für die help-Funktion eingibt, zeigt Get-Help das Hilfethema für das Cmdlet Get-Help an.

PS> Get-Help help

NAME
    Get-Help

SYNOPSIS
    Displays information about Windows PowerShell cmdlets and concepts.
...

Freigeben über