Nápověda_založená_na_komentářích

Krátký popis

Popisuje, jak psát obsah nápovědy založené na komentářích pro funkce a skripty.

Dlouhý popis

Obsah nápovědy založené na komentářích můžete psát pro funkce a skripty pomocí speciálních klíčových slov komentářů nápovědy.

Rutina Get-Help zobrazí nápovědu založenou na komentářích ve stejném formátu, ve kterém zobrazuje obsah nápovědy rutiny vygenerovaný ze souborů XML. Uživatelé můžou použít všechny parametry Get-Help, například Podrobné, Úplné, Příkladya Online, k zobrazení obsahu nápovědy založené na komentářích.

Můžete také napsat soubory nápovědy založené na JAZYCE XML pro funkce a skripty. Pokud chcete rutině Get-Help povolit vyhledání souboru nápovědy založeného na jazyce XML pro funkci nebo skript, použijte klíčové slovo .EXTERNALHELP. Bez tohoto klíčového slova Get-Help nemůže najít obsah nápovědy založený na jazyce XML pro funkce nebo skripty.

Toto téma vysvětluje, jak psát obsah nápovědy pro funkce a skripty. Informace o tom, jak zobrazit obsah nápovědy pro funkce a skripty, naleznete v tématu Get-Help.

Rutiny Update- Help a Save-Help fungují jenom u souborů XML. Aktualizovatelná nápověda nepodporuje obsah nápovědy na základě komentářů.

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

Pokud chcete vytvořit obsah nápovědy založené na komentářích, můžete použít styl komentářů: jednořádkové komentáře nebo blokovat komentáře.

Syntaxe nápovědy založené na komentářích je následující:

# .<help keyword>
# <help content>

nebo

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

Nápověda založená na komentářích je napsána jako řada komentářů. Před každý řádek komentářů můžete zadat symbol komentáře # nebo můžete k vytvoření bloku komentáře použít symboly <# a #>. Všechny řádky v bloku komentáře se interpretují jako komentáře.

Všechny řádky v tématu nápovědy založeném na komentářích musí být souvislé. Pokud téma nápovědy založené na komentáři následuje za komentářem, který není součástí tématu nápovědy, musí existovat alespoň jeden prázdný řádek mezi posledním řádkem komentáře bez nápovědy a začátkem nápovědy založené na komentáři.

Klíčová slova definují jednotlivé části nápovědy založené na komentářích. Každé klíčové slovo nápovědy založené na komentářích předchází tečka .. Klíčová slova se můžou zobrazit v libovolném pořadí. V názvech klíčových slov se nerozlišuje malá a velká písmena.

Například klíčové slovo .DESCRIPTION předchází popisu funkce nebo skriptu.

<#
.DESCRIPTION
Get-Function displays the name and syntax of all functions in the session.
#>

Blok komentáře musí obsahovat alespoň jedno klíčové slovo. Některá klíčová slova, například .EXAMPLE, se můžou objevit mnohokrát ve stejném bloku komentáře. Obsah nápovědy pro každé klíčové slovo začíná na řádku za klíčovým slovem a může obsahovat více řádků.

Syntaxe nápovědy založené na komentářích ve funkcích

Nápověda pro funkci založená na komentářích se může zobrazit na jednom ze tří míst:

Na začátku těla funkce.
Na konci těla funkce.
Před klíčovým slovem function. Mezi posledním řádkem nápovědy funkce a klíčovým slovem function nesmí být více než jeden prázdný řádek.

Například:

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

    # function logic
}

nebo

function Get-Function {
    # function logic

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

nebo

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

Syntaxe nápovědy založené na komentářích ve skriptech

Nápověda pro skript založená na komentářích se může zobrazit v jednom z následujících dvou umístění skriptu.

Na začátku souboru skriptu. Nápovědu ke skriptu můžou předcházet jenom komentáře a prázdné řádky.

Pokud první položka v těle skriptu (po nápovědě) je deklarace funkce, musí existovat alespoň dva prázdné řádky mezi koncem nápovědy skriptu a deklarací funkce. Jinak se nápověda interpretuje jako nápověda pro funkci, nikoli jako nápověda pro skript.
Na konci souboru skriptu. Pokud je však skript podepsaný, umístěte na začátek souboru skriptu nápovědu založenou na komentáři. Konec skriptu je obsazen blokem podpisu.

Například:

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

nebo

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

Klíčová slova nápovědy založené na komentářích

Následují platná klíčová slova nápovědy založené na komentářích. Tato klíčová slova se můžou v nápovědě založené na komentářích zobrazovat v libovolném pořadí a nerozlišují se u nich velká a malá písmena. Klíčová slova jsou uvedená v tomto článku v pořadí, v jakém se obvykle zobrazují v tématu nápovědy.

.SYNOPSIS

Stručný popis funkce nebo skriptu. Toto klíčové slovo lze použít pouze jednou v každém tématu.

.DESCRIPTION

Podrobný popis funkce nebo skriptu Toto klíčové slovo lze použít pouze jednou v každém tématu.

.PARAMETER

Popis parametru. Přidejte klíčové slovo .PARAMETER pro každý parametr v syntaxi funkce nebo skriptu.

Zadejte název parametru na stejný řádek jako klíčové slovo .PARAMETER. Zadejte popis parametru na řádcích za klíčovým slovem .PARAMETER. Windows PowerShell interpretuje veškerý text mezi řádkem .PARAMETER a dalším klíčovým slovem nebo koncem bloku komentáře jako součást popisu parametru. Popis může obsahovat konce odstavců.

.PARAMETER  <Parameter-Name>

Klíčová slova parametru se můžou v bloku komentáře zobrazovat v libovolném pořadí, ale funkce nebo syntaxe skriptu určuje pořadí, ve kterém se parametry (a jejich popisy) zobrazují v tématu nápovědy. Pokud chcete změnit pořadí, změňte syntaxi.

Popis parametru můžete také zadat umístěním komentáře do syntaxe funkce nebo skriptu bezprostředně před název proměnné parametru. Aby to fungovalo, musíte mít blok komentáře s alespoň jedním klíčovým slovem.

Pokud použijete komentář syntaxe i klíčové slovo .PARAMETER, použije se popis přidružený k .PARAMETER klíčovému slovu a komentář ke syntaxi se ignoruje.

<#
.SYNOPSIS
    Short description here
#>
function Verb-Noun {
    [CmdletBinding()]
    param (
        # This is the same as .PARAMETER
        [string]$ComputerName
    )
    # Verb the Noun on the computer
}

`.EXAMPLE`

Ukázkový příkaz, který používá funkci nebo skript, volitelně následovaný ukázkovým výstupem a popisem. Opakujte toto klíčové slovo pro každý příklad.

`.INPUTS`

Typy objektů .NET, které lze předvést do funkce nebo skriptu. Můžete také zahrnout popis vstupních objektů. Toto klíčové slovo opakujte pro každý typ vstupu.

`.OUTPUTS`

Typ .NET objektů, které rutina vrací. Můžete také zahrnout popis vrácených objektů. Opakujte toto klíčové slovo pro každý typ výstupu.

`.NOTES`

Další informace o funkci nebo skriptu

`.LINK`

Název souvisejícího tématu. Toto klíčové slovo opakujte pro každé související téma. Tento obsah se zobrazí v části Související odkazy tématu nápovědy.

Obsah klíčového slova .LINK může také obsahovat identifikátor URI (Uniform Resource Identifier) do online verze stejného tématu nápovědy. Online verze se otevře, když použijete parametr OnlineGet-Help. Identifikátor URI musí začínat http nebo https.

`.COMPONENT`

Název technologie nebo funkce, kterou funkce nebo skript používá nebo ke které souvisí. Parametr složky u používá tuto hodnotu k filtrování výsledků hledání, které vrátí .

`.ROLE`

Název role uživatele pro téma nápovědy. Parametr role v Get-Help používá tuto hodnotu k filtrování výsledků hledání vrácených Get-Help.

`.FUNCTIONALITY`

Klíčová slova, která popisují zamýšlené použití funkce. Parametr FunctionalityGet-Help používá tuto hodnotu k filtrování výsledků hledání vrácených Get-Help.

`.FORWARDHELPTARGETNAME <Command-Name>`

Přesměruje se na téma nápovědy pro zadaný příkaz. Uživatele můžete přesměrovat na jakékoli téma nápovědy, včetně obsahu nápovědy pro funkci, skript, rutinu nebo poskytovatele.

# .FORWARDHELPTARGETNAME <Command-Name>

`.FORWARDHELPCATEGORY`

Určuje kategorii nápovědy položky v .FORWARDHELPTARGETNAME. Platné hodnoty jsou Alias, Cmdlet, HelpFile, Function, Provider, General, FAQ, Glossary, ScriptCommand, ExternalScript, Filternebo All. Pomocí tohoto klíčového slova se vyhnete konfliktům, pokud existují příkazy se stejným názvem.

# .FORWARDHELPCATEGORY <Category>

`.REMOTEHELPRUNSPACE <PSSession-variable>`

Určuje relaci, která obsahuje téma nápovědy. Zadejte proměnnou, která obsahuje objekt PSSession. Toto klíčové slovo používá rutina Export-PSSession k vyhledání obsahu nápovědy pro exportované příkazy.

# .REMOTEHELPRUNSPACE <PSSession-variable>

`.EXTERNALHELP`

Určuje soubor nápovědy založený na jazyce XML pro skript nebo funkci.

# .EXTERNALHELP <XML Help File>

Klíčové slovo .EXTERNALHELP je vyžadováno, pokud je funkce nebo skript zdokumentované v souborech XML. Bez tohoto klíčového slova Get-Help nemůže najít soubor nápovědy založený na jazyce XML pro funkci nebo skript.

Klíčové slovo .EXTERNALHELP má přednost před jinými klíčovými slovy nápovědy založené na komentářích. Pokud je .EXTERNALHELP k dispozici, Get-Help nezobrazuje nápovědu založenou na komentářích, i když nemůže najít téma nápovědy, které odpovídá hodnotě .EXTERNALHELP klíčového slova.

Pokud je funkce exportována modulem, nastavte hodnotu klíčového slova .EXTERNALHELP na název souboru bez cesty. Get-Help vyhledá zadaný název souboru v podadresáři konkrétního jazyka adresáře modulu. Pro název souboru nápovědy založeného na jazyce XML pro funkci nejsou žádné požadavky. Počínaje PowerShellem 5.0 je možné funkce exportované modulem zdokumentovat v souboru nápovědy, který je pojmenovaný pro modul. Klíčové slovo komentáře nemusíte používat .EXTERNALHELP . Pokud Test-Function je například funkce exportována modulem MyModule , můžete soubor nápovědy MyModule-help.xmlpojmenovat . Rutina Get-Help hledá nápovědu Test-FunctionMyModule-help.xml pro funkci v souboru v adresáři modulu.

Pokud funkce není součástí modulu, zahrňte cestu k souboru nápovědy založenému na JAZYCE XML. Pokud hodnota zahrnuje cestu a cesta obsahuje podadresáře specifické pro jazykovou kulturu uživatelského rozhraní, Get-Help rekurzivně hledá v podadresářích soubor XML, který má název skriptu nebo funkce, v souladu se standardy jazykové náhražky vytvořenými pro Windows, stejným způsobem jako v případě adresáře modulu.

Další informace o formátu souboru nápovědy XML pro rutiny naleznete v tématu Jak psát nápovědu pro rutiny.

Automaticky vygenerovaný obsah

Rutina Get-Help automaticky vygeneruje název, syntaxi, seznam parametrů, tabulku atributů parametrů, běžné parametry a poznámky.

Jméno

Část Název v tématu nápovědy k funkci je odvozena z názvu funkce v její syntaxi. Název tématu nápovědy ke skriptu je převzat z názvu souboru skriptu. Pokud chcete změnit název nebo jeho velká písmena, změňte syntaxi funkce nebo název souboru skriptu.

Syntaxe

Část Syntaxe tématu nápovědy je generována z funkce nebo syntaxe skriptu. Pokud chcete přidat podrobnosti do syntaxe tématu nápovědy, například typ .NET parametru, přidejte do syntaxe podrobnosti. Pokud nezadáte typ parametru, Objekt typ se vloží jako výchozí hodnota.

Seznam parametrů

Seznam parametrů v tématu nápovědy se generuje ze syntaxe funkce nebo skriptu a z popisů, které přidáte pomocí klíčového slova .PARAMETER. Parametry funkce se zobrazí v části Parametry tématu nápovědy ve stejném pořadí, v jakém se zobrazují v syntaxi funkce nebo skriptu. Pravopis a velká písmena názvů parametrů jsou převzaty také ze syntaxe. Není ovlivněn názvem parametru určeným klíčovým slovem .PARAMETER.

Běžné parametry

Běžné parametry se přidají do syntaxe a seznamu parametrů tématu nápovědy, i když nemají žádný vliv. Další informace o společných parametrech naleznete v tématu about_CommonParameters.

Tabulka atributů parametru

Get-Help vygeneruje tabulku atributů parametrů, které se zobrazí při použití Full nebo parametr parametru Get-Help. Hodnota atributu Required, Positiona Default value attributes je převzata ze syntaxe funkce nebo skriptu.

Výchozí hodnoty a hodnota pro Přijmout zástupné znaky se v tabulce atributů parametrů nezobrazují ani v případě, že jsou definované ve funkci nebo skriptu. Pokud chcete uživatelům pomoct, zadejte tyto informace v popisu parametru.

Poznámky

Oddíl Poznámky v tématu nápovědy je automaticky generován z názvu funkce nebo skriptu. Nemůžete změnit ani ovlivnit jeho obsah.

Examples

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

http://www.fabrikam.com/extension.html

.LINK

Set-Item
#>
}

Výsledky jsou následující:

Get-Help -Name "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

http://www.fabrikam.com/extension.html
Set-Item

Popisy parametrů v syntaxi funkce

Tento příklad je stejný jako předchozí, s tím rozdílem, že popisy parametrů jsou vloženy do syntaxe funkce. Tento formát je nejužitečnější, pokud jsou popisy 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.

.DESCRIPTION

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

.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

http://www.fabrikam.com/extension.html

.LINK

Set-Item
#>
}

Nápověda založená na komentářích pro skript

Následující ukázkový skript 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ů přidruží Get-Help téma nápovědy k funkci, nikoli ke skriptu.

<#
.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 zobrazí nápovědu ke skriptu. Vzhledem k tomu, že skript není v adresáři, který je uvedený v proměnné prostředí $Env:PATH, musí příkaz Get-Help, který získá nápovědu ke skriptu, zadat cestu ke skriptu.

Get-Help -Name .\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řesměrování na soubor XML

Obsah nápovědy založený na jazyce XML můžete napsat pro funkce a skripty. I když je pomoc založená na komentářích jednodušší implementovat, pro aktualizovatelnou nápovědu a k poskytování obsahu nápovědy ve více jazycích se vyžaduje nápověda založená na jazyce XML.

Následující příklad ukazuje několik prvních řádků skriptu Update-Month.ps1. Skript pomocí klíčového slova .EXTERNALHELP určuje cestu k tématu nápovědy založenému na jazyce XML pro skript.

Všimněte si, že hodnota klíčového slova .EXTERNALHELP se zobrazí na stejném řádku jako klíčové slovo. Jakékoli jiné umístění je neefektivní.

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

param ([string]$InputPath, [string]$OutputPath)
function Get-Data { }
...

Následující příklady ukazují tři platná umístění klíčového slova .EXTERNALHELP ve funkci.

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

    param ([string] $Name, [string]$Extension = "txt")
    $Name = $Name + "." + $Extension
    $Name
}

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

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

# .EXTERNALHELP C:\ps-test\Add-Extension.xml
function Add-Extension {
    param ([string] $Name, [string]$Extension = "txt")
    $Name = $Name + "." + $Extension
    $Name
}

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

Následující kód je výňatek od začátku integrované funkce nápovědy 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ědy, jsou klíčová slova .FORWARDHELPTARGETNAME a .FORWARDHELPCATEGORY použita funkcí nápovědy k přesměrování uživatele na téma nápovědy pro rutinu Get-Help.

function help {
    <#
    .FORWARDHELPTARGETNAME Get-Help
    .FORWARDHELPCATEGORY Cmdlet
    #>

    [CmdletBinding(DefaultParameterSetName='AllUsersView')]
    param(
        [Parameter(Position=0, ValueFromPipelineByPropertyName=$true)]
        [System.String]
        ${Name},
    ...

Následující příkaz používá tuto funkci:

Get-Help -Name help

NAME

Get-Help

SYNOPSIS

Displays information about PowerShell cmdlets and concepts.
...

Viz také

Váš názor

Byla tato stránka užitečná?

Last updated on 2025-09-23

Sdílet prostřednictvím

Nápověda_založená_na_komentářích

Krátký popis

Dlouhý popis

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

Syntaxe nápovědy založené na komentářích ve funkcích

Syntaxe nápovědy založené na komentářích ve skriptech

Klíčová slova nápovědy založené na komentářích

.SYNOPSIS

.DESCRIPTION

.PARAMETER

.EXAMPLE

.INPUTS

.OUTPUTS

.NOTES

.LINK

.COMPONENT

.ROLE

.FUNCTIONALITY

.FORWARDHELPTARGETNAME <Command-Name>

.FORWARDHELPCATEGORY

.REMOTEHELPRUNSPACE <PSSession-variable>

.EXTERNALHELP

Automaticky vygenerovaný obsah

Jméno

Syntaxe

Seznam parametrů

Běžné parametry

Tabulka atributů parametru

Poznámky

Examples

Nápověda založená na komentářích pro funkci

Popisy parametrů v syntaxi funkce

Nápověda založená na komentářích pro skript

Přesměrování na soubor XML

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

Viz také

Váš názor

Další materiály

`.EXAMPLE`

`.INPUTS`

`.OUTPUTS`

`.NOTES`

`.LINK`

`.COMPONENT`

`.ROLE`

`.FUNCTIONALITY`

`.FORWARDHELPTARGETNAME <Command-Name>`

`.FORWARDHELPCATEGORY`

`.REMOTEHELPRUNSPACE <PSSession-variable>`

`.EXTERNALHELP`