Pomoc na podstawie komentarzy

Krótki opis

Opisuje sposób pisania zawartości pomocy opartej na komentarzach dla funkcji i skryptów.

Długi opis

Możesz napisać zawartość pomocy opartą na komentarzach dla funkcji i skryptów, używając specjalnych słów kluczowych komentarzy pomocy.

Polecenie cmdlet Get-Help wyświetla pomoc opartą na komentarzach w tym samym formacie, w jakim prezentuje treść pomocy polecenia cmdlet wygenerowaną z plików XML. Użytkownicy mogą używać wszystkich parametrów Get-Help, takich jak Szczegółowe, Pełne, Przykładyi Online, aby wyświetlić zawartość pomocy opartej na komentarzach.

Możesz również pisać pliki pomocy opartej na formacie XML dla funkcji i skryptów. Aby włączyć polecenie cmdlet Get-Help w celu znalezienia pliku pomocy opartej na formacie XML dla funkcji lub skryptu, użyj słowa kluczowego .EXTERNALHELP. Bez tego słowa kluczowego Get-Help nie może znaleźć zawartości pomocy opartej na języku XML dla funkcji lub skryptów.

W tym temacie wyjaśniono, jak napisać zawartość pomocy dla funkcji i skryptów. Aby uzyskać informacje na temat wyświetlania zawartości pomocy dla funkcji i skryptów, zobacz Get-Help.

Polecenia cmdlet Update-Help i Save-Help działają tylko na plikach XML. Pomoc aktualizowana nie obsługuje zawartości opartej na komentarzach.

Składnia pomocy opartej na komentarzach

Aby utworzyć zawartość pomocy opartej na komentarzach, możesz użyć dowolnego stylu komentarzy: komentarzy jednowierszowych lub komentarzy blokowych.

Składnia pomocy opartej na komentarzach jest następująca:

# .<help keyword>
# <help content>

lub

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

Pomoc oparta na komentarzach jest napisana jako seria komentarzy. Możesz wpisać symbol komentarza # przed każdym wierszem komentarzy lub użyć symboli <# i #>, aby utworzyć blok komentarza. Wszystkie wiersze w bloku komentarza są interpretowane jako komentarze.

Wszystkie wiersze w temacie pomocy opartej na komentarzach muszą być ciągłe. Jeśli temat pomocy oparty na komentarzach jest zgodny z komentarzem, który nie jest częścią tematu pomocy, musi istnieć co najmniej jeden pusty wiersz między ostatnim wierszem komentarza bez pomocy a początkiem pomocy opartej na komentarzach.

Słowa kluczowe definiują każdą sekcję pomocy opartej na komentarzach. Każde słowo kluczowe pomocy opartej na komentarzach jest poprzedzone kropką .. Słowa kluczowe mogą być wyświetlane w dowolnej kolejności. Nazwy słów kluczowych nie są rozróżnialne pod względem wielkości liter.

Na przykład słowo kluczowe .DESCRIPTION poprzedza opis funkcji lub skryptu.

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

Blok komentarza musi zawierać co najmniej jedno słowo kluczowe. Niektóre słowa kluczowe, takie jak .EXAMPLE, mogą pojawiać się wiele razy w tym samym bloku komentarzy. Zawartość pomocy dla każdego słowa kluczowego rozpoczyna się w wierszu po słowie kluczowym i może obejmować wiele wierszy.

Składnia pomocy opartej na komentarzach w funkcjach

Pomoc oparta na komentarzach dla funkcji może pojawić się w jednej z trzech lokalizacji:

Na początku treści funkcji.
Na końcu treści funkcji.
Przed słowem kluczowym function. Między ostatnim wierszem pomocy funkcji a słowem kluczowym function nie może być więcej niż jeden pusty wiersz.

Na przykład:

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

    # function logic
}

lub

function Get-Function {
    # function logic

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

lub

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

Składnia pomocy opartej na komentarzach w skryptach

Pomoc oparta na komentarzach dla skryptu może pojawić się w jednej z następujących dwóch lokalizacji w skrycie.

Na początku pliku skryptu. Pomoc skryptu może być poprzedzona tylko komentarzami i pustymi wierszami.

Jeśli pierwszy element w treści skryptu (po pomocy) jest deklaracją funkcji, musi istnieć co najmniej dwa puste wiersze między końcem pomocy skryptu a deklaracją funkcji. W przeciwnym razie pomoc jest interpretowana jako pomoc dla funkcji, a nie pomoc dla skryptu.
Na końcu pliku skryptu. Jeśli jednak skrypt jest podpisany, umieść pomoc opartą na komentarzach na początku pliku skryptu. Koniec skryptu jest zajmowany przez blok podpisu.

Na przykład:

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

lub

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

Słowa kluczowe pomocy oparte na komentarzach

Poniżej przedstawiono prawidłowe słowa kluczowe dotyczące pomocy opartej na komentarzach. Te słowa kluczowe mogą występować w dowolnej kolejności w pomocy komentowanej i nie są wrażliwe na wielkość liter. Słowa kluczowe są wymienione w tym artykule w kolejności, w której zwykle pojawiają się w temacie pomocy.

.SYNOPSIS

Krótki opis funkcji lub skryptu. To słowo kluczowe może być używane tylko raz w każdym temacie.

.DESCRIPTION

Szczegółowy opis funkcji lub skryptu. To słowo kluczowe może być używane tylko raz w każdym temacie.

.PARAMETER

Opis parametru. Dodaj słowo kluczowe .PARAMETER dla każdego parametru w funkcji lub składni skryptu.

Wpisz nazwę parametru w tym samym wierszu co słowo kluczowe .PARAMETER. Wpisz opis parametru w wierszach po słowie kluczowym .PARAMETER. Program Windows PowerShell interpretuje cały tekst między wierszem .PARAMETER a następnym słowem kluczowym lub końcem bloku komentarzy w ramach opisu parametru. Opis może zawierać podziały akapitów.

.PARAMETER  <Parameter-Name>

Słowa kluczowe parametru mogą być wyświetlane w dowolnej kolejności w bloku komentarza, ale składnia funkcji lub skryptu określa kolejność, w jakiej parametry (i ich opisy) pojawiają się w temacie pomocy. Aby zmienić kolejność, zmień składnię.

Można również określić opis parametru, umieszczając komentarz w funkcji lub składni skryptu bezpośrednio przed nazwą zmiennej parametru. Aby to działało, musisz również mieć blok komentarzy z co najmniej jednym słowem kluczowym.

Jeśli używasz zarówno komentarza składniowego, jak i słowa kluczowego .PARAMETER, używany jest opis skojarzony ze słowem kluczowym .PARAMETER, a komentarz składniowy jest ignorowany.

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

`.EXAMPLE`

Przykładowe polecenie, które używa funkcji lub skryptu, ewentualnie z przykładowymi danymi wyjściowymi i opisem. Powtórz to słowo kluczowe dla każdego przykładu.

`.INPUTS`

Typy obiektów platformy .NET, które mogą być przesyłane potokami do funkcji lub skryptu. Można również dołączyć opis obiektów wejściowych. Powtórz to słowo kluczowe dla każdego typu danych wejściowych.

`.OUTPUTS`

Typ obiektów .NET zwracanych przez polecenie cmdlet. Można również dołączyć opis zwracanych obiektów. Powtórz to słowo kluczowe dla każdego typu danych wyjściowych.

`.NOTES`

Dodatkowe informacje na temat funkcji lub skryptu.

`.LINK`

Nazwa powiązanego tematu. Powtórz to słowo kluczowe dla każdego powiązanego tematu. Ta zawartość jest wyświetlana w sekcji Powiązane linki w temacie Pomoc.

Zawartość słowa kluczowego .LINK może również zawierać identyfikator URI (Uniform Resource Identifier) prowadzący do wersji tego samego tematu pomocy dostępnej online. Wersja online otwiera się po użyciu parametru Online w Get-Help. Identyfikator URI musi zaczynać się od http lub https.

`.COMPONENT`

Nazwa technologii lub funkcji używanej przez funkcję lub skrypt albo powiązane z nią funkcje. Parametr Component używa tej wartości do filtrowania wyników wyszukiwania zwróconych przez .

`.ROLE`

Nazwa roli użytkownika dla tematu pomocy. Parametr RolaGet-Help używa tej wartości do filtrowania wyników wyszukiwania zwróconych przez Get-Help.

`.FUNCTIONALITY`

Słowa kluczowe opisujące zamierzone użycie funkcji. Parametr funkcji w używa tej wartości do filtrowania wyników wyszukiwania zwróconych przez .

`.FORWARDHELPTARGETNAME <Command-Name>`

Przekierowuje do tematu pomocy dla określonego polecenia. Możesz przekierować użytkowników do dowolnego tematu pomocy, w tym zawartości pomocy dotyczącej funkcji, skryptu, cmdlet lub dostawcy.

# .FORWARDHELPTARGETNAME <Command-Name>

`.FORWARDHELPCATEGORY`

Określa kategorię pomocy elementu w .FORWARDHELPTARGETNAME. Prawidłowe wartości to Alias, Cmdlet, HelpFile, Function, Provider, General, FAQ, Glossary, ScriptCommand, ExternalScript, Filterlub All. Użyj tego słowa kluczowego, aby uniknąć konfliktów, gdy istnieją polecenia o tej samej nazwie.

# .FORWARDHELPCATEGORY <Category>

`.REMOTEHELPRUNSPACE <PSSession-variable>`

Określa sesję zawierającą temat pomocy. Wprowadź zmienną zawierającą obiekt PSSession. To słowo kluczowe jest używane przez polecenie cmdlet Export-PSSession w celu znalezienia zawartości pomocy dla wyeksportowanych poleceń.

# .REMOTEHELPRUNSPACE <PSSession-variable>

`.EXTERNALHELP`

Określa plik pomocy opartej na formacie XML dla skryptu lub funkcji.

# .EXTERNALHELP <XML Help File>

Słowo kluczowe .EXTERNALHELP jest wymagane, gdy funkcja lub skrypt są udokumentowane w plikach XML. Bez tego słowa kluczowego Get-Help nie może znaleźć pliku pomocy opartej na formacie XML dla funkcji lub skryptu.

Słowo kluczowe .EXTERNALHELP ma pierwszeństwo przed innymi słowami kluczowymi pomocy opartymi na komentarzach. Jeśli .EXTERNALHELP jest obecny, Get-Help nie wyświetla pomocy opartej na komentarzach, nawet jeśli nie może znaleźć tematu pomocy zgodnego z wartością słowa kluczowego .EXTERNALHELP.

Jeśli funkcja jest eksportowana przez moduł, ustaw wartość słowa kluczowego .EXTERNALHELP na nazwę pliku bez ścieżki. Get-Help wyszukuje określoną nazwę pliku w podkatalogu specyficznym dla języka katalogu modułu. Nie ma wymagań dotyczących nazwy pliku pomocy opartej na formacie XML dla funkcji. Począwszy od programu PowerShell 5.0, funkcje wyeksportowane przez moduł można udokumentować w pliku pomocy o nazwie dla modułu. Nie musisz używać .EXTERNALHELP słowa kluczowego komentarza. Jeśli na przykład Test-Function funkcja zostanie wyeksportowana przez MyModule moduł, możesz nazwać plik MyModule-help.xmlpomocy . Polecenie Get-Help cmdlet szuka pomocy dla Test-Function funkcji w MyModule-help.xml pliku w katalogu modułu.

Jeśli funkcja nie jest uwzględniona w module, dołącz ścieżkę do pliku pomocy opartej na formacie XML. Jeśli wartość zawiera ścieżkę, a ścieżka zawiera podkatalogi specyficzne dla kultury interfejsu użytkownika, Get-Help przeszukuje podkatalogi rekursywnie dla pliku XML o nazwie skryptu lub funkcji zgodnie ze standardami rezerwowymi języka ustanowionymi dla systemu Windows, podobnie jak w katalogu modułu.

Aby uzyskać więcej informacji na temat formatu pliku pomocy opartej na xml polecenia cmdlet, zobacz How to Write Cmdlet Help.

Automatycznie wygenerowana zawartość

Nazwa, składnia, lista parametrów, tabela atrybutów parametrów, typowe parametry i uwagi są generowane automatycznie przez polecenie cmdlet Get-Help.

Nazwa

Sekcja Nazwa w temacie pomocy funkcji jest zaczerpnięta z nazwy funkcji w jej składni. Nazwa Name tematu pomocy skryptu jest pobierana z nazwy pliku skryptu. Aby zmienić nazwę lub jego wielkie litery, zmień składnię funkcji lub nazwę pliku skryptu.

Składnia

Sekcja Składnia w temacie pomocy jest generowana na podstawie składni funkcji lub skryptu. Aby dodać szczegóły do składni tematu pomocy, takie jak typ .NET parametru, dodaj szczegóły do składni. Jeśli nie określisz typu parametru, typ Object zostanie wstawiony jako wartość domyślna.

Lista parametrów

Lista parametrów w temacie pomocy jest generowana na podstawie funkcji lub składni skryptu oraz z opisów dodanych przy użyciu słowa kluczowego .PARAMETER. Parametry funkcji pojawiają się w sekcji Parametry w temacie pomocy w tej samej kolejności, w jakiej występują w składni funkcji lub skryptu. Pisownia i wielkie litery nazw parametrów są również pobierane ze składni. Nie ma to wpływu na nazwę parametru określoną przez słowo kluczowe .PARAMETER.

Typowe parametry

Typowe parametry są dodawane do składni i listy parametrów tematu pomocy, nawet jeśli nie mają żadnego efektu. Aby uzyskać więcej informacji na temat typowych parametrów, zobacz about_CommonParameters.

Tabela atrybutów parametrów

Get-Help generuje tabelę atrybutów parametrów, która pojawia się, gdy używasz parametru Full lub parametruGet-Help. Wartość atrybutów wartości Required, Positioni Domyślne atrybuty wartości są pobierane z funkcji lub składni skryptu.

Wartości domyślne i wartość dla Akceptuj symbole wieloznaczne nie są wyświetlane w tabeli atrybutów parametrów nawet wtedy, gdy są zdefiniowane w funkcji lub skrypcie. Aby pomóc użytkownikom, podaj te informacje w opisie parametru.

Uwagi

Sekcja Uwagi tematu pomocy jest automatycznie generowana na podstawie nazwy funkcji lub skryptu. Nie można zmienić ani wpłynąć na jego zawartość.

Przykłady

Pomoc oparta na komentarzach dla funkcji

Poniższa przykładowa funkcja zawiera pomoc opartą na komentarzach:

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

Wyniki są następujące:

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

Opisy parametrów w składni funkcji

Ten przykład jest taki sam jak poprzedni, z tą różnicą, że opisy parametrów są wstawiane w składni funkcji. Ten format jest najbardziej przydatny, gdy opisy są krótkie.

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

Pomoc oparta na komentarzach dla skryptu

Poniższy przykładowy skrypt zawiera pomoc opartą na komentarzach. Zwróć uwagę na puste wiersze między zamknięciem #> a instrukcją param. W skrycie, który nie ma instrukcji param, musi istnieć co najmniej dwa puste wiersze między ostatnim komentarzem w temacie pomocy a pierwszą deklaracją funkcji. Bez tych pustych wierszy Get-Help kojarzy temat pomocy z funkcją, a nie skrypt.

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

Poniższe polecenie pobiera pomoc dotyczącą skryptu. Ponieważ skrypt nie znajduje się w katalogu wymienionym w zmiennej środowiskowej $Env:PATH, polecenie Get-Help, które pobiera pomoc skryptu, musi określić ścieżkę skryptu.

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

Przekierowywanie do pliku XML

Zawartość pomocy opartej na formacie XML można pisać dla funkcji i skryptów. Mimo że pomoc oparta na komentarzach jest łatwiejsza do zaimplementowania, pomoc oparta na formacie XML jest wymagana dla pomocy z możliwością aktualizowania i udostępniania zawartości pomocy w wielu językach.

Poniższy przykład przedstawia kilka pierwszych wierszy skryptu Update-Month.ps1. Skrypt używa słowa kluczowego .EXTERNALHELP, aby określić ścieżkę do tematu pomocy opartej na języku XML dla skryptu.

Należy pamiętać, że wartość słowa kluczowego .EXTERNALHELP jest wyświetlana w tym samym wierszu co słowo kluczowe. Wszelkie inne umieszczanie jest nieskuteczne.

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

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

W poniższych przykładach pokazano trzy prawidłowe umieszczanie słowa kluczowego .EXTERNALHELP w funkcji.

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
}

Przekierowywanie do innego tematu pomocy

Poniższy kod jest fragmentem wbudowanej funkcji pomocy programu PowerShell, która wyświetla jednocześnie jeden ekran tekstu pomocy. Ponieważ temat pomocy dla polecenia cmdlet Get-Help opisuje funkcję pomocy, funkcja pomocy używa słów kluczowych .FORWARDHELPTARGETNAME i .FORWARDHELPCATEGORY, aby przekierować użytkownika do tematu pomocy polecenia cmdlet Get-Help.

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

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

Następujące polecenie używa tej funkcji:

Get-Help -Name help

NAME

Get-Help

SYNOPSIS

Displays information about PowerShell cmdlets and concepts.
...

Zobacz także

Opinia

Czy ta strona była pomocna?

Last updated on 2025-09-24