Příklady nápovědy založené na komentářích

Článek
2025-03-25

Toto téma obsahuje příklady, které ukazují, jak používat nápovědu založenou na komentářích pro skripty a funkce.

Příklad 1: Nápověda založená na komentářích pro funkci

Následující ukázková funkce obsahuje nápovědu založenou na komentářích.

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
    #>
}

Následující výstup ukazuje výsledky příkazu Get-Help, který zobrazí nápovědu pro funkci Add-Extension.

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

Příklad 2: Nápověda založená na komentářích pro skript

Následující ukázková funkce obsahuje nápovědu založenou na komentářích.

Všimněte si prázdných řádků mezi uzavřením #> a příkazem param. Ve skriptu, který nemá příkaz param, musí existovat alespoň dva prázdné řádky mezi posledním komentářem v tématu nápovědy a první deklarací funkce. Bez těchto prázdných řádků Get-Help místo skriptu přidruží téma nápovědy k funkci.

<#
  .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 { }

Následující příkaz získá nápovědu ke skriptu. Protože skript není v adresáři, který je uveden v proměnné prostředí PATH, Get-Help příkaz, který získá nápovědu skriptu, musí zadat cestu ke skriptu.

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

Příklad 3: Popisy parametrů v příkazu `param`

Tento příklad ukazuje, jak vložit popisy parametrů do param příkazu funkce nebo skriptu. Tento formát je nejužitečnější, pokud jsou popisy parametrů stručné.

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.
...
    #>
}

Výsledky jsou stejné jako výsledky pro příklad 1. Get-Help interpretuje popisy parametrů, jako by byly doprovázeny klíčovým slovem .PARAMETER.

Příklad 4: Přesměrování na soubor XML

Témata nápovědy založená na jazyce XML můžete psát pro funkce a skripty. I když je implementace nápovědy založená na komentářích jednodušší, vyžaduje se nápověda založená na jazyce XML, pokud chcete přesnější kontrolu nad obsahem nápovědy nebo pokud překládáte témata nápovědy do více jazyků. Následující příklad ukazuje několik prvních řádků skriptu Update-Month.ps1. Skript používá klíčové slovo .EXTERNALHELP k určení cesty k tématu nápovědy založenému na jazyce XML pro skript.

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

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

    function Get-Data { }

Následující příklad ukazuje použití klíčového slova .EXTERNALHELP ve funkci.

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

    # .EXTERNALHELP C:\ps-test\Add-Extension.xml
}

Příklad 5: Přesměrování na jiné téma nápovědy

Následující kód je výňatek od začátku integrované funkce help v PowerShellu, která zobrazuje najednou jednu obrazovku textu nápovědy. Protože téma nápovědy pro rutinu Get-Help popisuje funkci Nápověda, funkce Nápověda používá klíčová slova .FORWARDHELPTARGETNAME a .FORWARDHELPCATEGORY k přesměrování uživatele na téma nápovědy rutiny Get-Help.

function help
{
    <#
      .FORWARDHELPTARGETNAME Get-Help
      .FORWARDHELPCATEGORY Cmdlet
    #>
    [CmdletBinding(DefaultParameterSetName='AllUsersView')]
    param(
            [Parameter(Position=0, ValueFromPipelineByPropertyName=$true)]
            [System.String]
            ${Name},
    ...
}

Tuto funkci používá následující příkaz. Když uživatel zadá Get-Help příkaz pro funkci help, Get-Help zobrazí téma nápovědy pro rutinu Get-Help.

PS> Get-Help help

NAME
    Get-Help

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

Sdílet prostřednictvím