about_Comment_Based_Help

Artykuł
05/09/2024

Krótki opis

Opisuje sposób pisania tematów pomocy opartych na komentarzach dotyczących funkcji i skryptów.

Długi opis

Tematy pomocy opartej na komentarzach dla funkcji i skryptów można pisać przy użyciu specjalnych słów kluczowych komentarza pomocy.

Polecenie cmdlet Get-Help wyświetla pomoc opartą na komentarzach w tym samym formacie, w którym wyświetla tematy pomocy polecenia cmdlet generowane na podstawie plików XML. Użytkownicy mogą używać wszystkich parametrów Get-Help, takich jak Szczegółowe, Pełne, Przykłady i Online, aby wyświetlić zawartość pomocy opartej na komentarzach.

Możesz również pisać pliki pomocy oparte na języku XML dla funkcji i skryptów. Aby włączyć Get-Help polecenie cmdlet w celu znalezienia pliku pomocy opartej na języku XML dla funkcji lub skryptu, użyj słowa kluczowego .ExternalHelp . Bez tego słowa kluczowego Get-Help nie można odnaleźć tematów pomocy opartych na języku XML dla funkcji lub skryptów.

W tym temacie wyjaśniono, jak pisać tematy pomocy dotyczące funkcji i skryptów. Aby uzyskać informacje na temat wyświetlania tematów pomocy dotyczących funkcji i skryptów, zobacz Get-Help (Uzyskiwanie pomocy).

Polecenia cmdlet Update-Help i Save-Help działają tylko na plikach XML. Pomoc aktualizowalna nie obsługuje tematów pomocy opartych na komentarzach.

Składnia pomocy opartej na komentarzach

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 #> do utworzenia bloku 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 oparte na komentarzach jest poprzedzone kropką .. Słowa kluczowe mogą być wyświetlane w dowolnej kolejności. W nazwach słów kluczowych nie jest uwzględniana wielkość liter.

Na przykład .Description słowo kluczowe 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.
function Przed słowem kluczowym. Między ostatnim wierszem pomocy funkcji a function słowem kluczowym 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 dotycząca 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 komentarzu na początku pliku skryptu. Koniec skryptu jest zajęty przez blok podpisu.

Na przykład:

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


function Get-Function { }

lub

function Get-Function { }

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

Składnia pomocy opartej na komentarzach w modułach skryptów

W module .psm1skryptu pomoc oparta na komentarzach używa składni dla funkcji, a nie składni skryptów. Nie można użyć składni skryptu, aby zapewnić pomoc dla wszystkich funkcji zdefiniowanych w module skryptu.

Jeśli na przykład używasz słowa kluczowego .ExternalHelp do identyfikowania plików pomocy opartych na języku XML dla funkcji w module skryptu, musisz dodać .ExternalHelp komentarz do każdej funkcji.

# .ExternalHelp <XML-file-name>
function <function-name>
{
  ...
}

Słowa kluczowe pomocy opartej na komentarzach

Poniżej przedstawiono prawidłowe słowa kluczowe pomocy oparte na komentarzach. Są one wymienione w kolejności, w której zwykle pojawiają się w temacie pomocy wraz z ich zamierzonym zastosowaniem. Te słowa kluczowe mogą pojawiać się w dowolnej kolejności w pomocy opartej na komentarzach i nie są uwzględniane wielkości liter.

.SYNOPSIS

Krótki opis funkcji lub skryptu. Tego słowa kluczowego można używać tylko raz w każdym temacie.

.DESCRIPTION

Szczegółowy opis funkcji lub skryptu. Tego słowa kluczowego można używać tylko raz w każdym temacie.

.PARAMETER

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

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

.PARAMETER  <Parameter-Name>

Słowa kluczowe parametru mogą pojawiać się w dowolnej kolejności w bloku komentarza, ale składnia funkcji lub skryptu określa kolejność wyświetlania parametrów (i ich opisów) w temacie pomocy. Aby zmienić kolejność, zmień składnię.

Opis parametru można również określić, 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 komentarza z co najmniej jednym słowem kluczowym.

Jeśli używasz zarówno komentarza składni, jak i słowa kluczowego .PARAMETER , używany jest opis skojarzony ze .PARAMETER słowem kluczowym, a komentarz składni 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, opcjonalnie 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ż uwzględnić opis obiektów wejściowych.

.OUTPUTS

Typ platformy .NET obiektów zwracanych przez polecenie cmdlet. Można również uwzględnić opis zwracanych obiektów.

.NOTES

Dodatkowe informacje na temat funkcji lub skryptu.

.LINK

Nazwa powiązanego tematu. Wartość pojawia się w wierszu poniżej słowa kluczowego ".LINK" i musi być poprzedzona symbolem # komentarza lub uwzględniona w bloku komentarza.

Powtórz słowo kluczowe dla każdego powiązanego .LINK tematu.

Ta zawartość jest wyświetlana w sekcji Powiązane linki tematu pomocy.

Zawartość .Link słowa kluczowego może również zawierać identyfikator URI (Uniform Resource Identifier) do wersji online tego samego tematu pomocy. Wersja online zostanie otwarta po użyciu parametru Online .Get-Help Identyfikator URI musi zaczynać się od ciągu "http" lub "https".

.COMPONENT

Nazwa technologii lub funkcji używanej przez funkcję lub skrypt albo, z którą jest powiązana. Parametr Component klasy używa tej wartości do filtrowania Get-Help wyników wyszukiwania zwróconych przez Get-Help.

.ROLE

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

.FUNCTIONALITY

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

.FORWARDHELPTARGETNAME

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

# .FORWARDHELPTARGETNAME <Command-Name>

.FORWARDHELPCATEGORY

Określa kategorię pomocy elementu w elemencie .ForwardHelpTargetName. Prawidłowe wartości to Alias, CmdletFunctionGeneralFAQProviderHelpFileScriptCommandExternalScriptGlossaryFilterlub .All Użyj tego słowa kluczowego, aby uniknąć konfliktów, gdy istnieją polecenia o tej samej nazwie.

# .FORWARDHELPCATEGORY <Category>

.REMOTEHELPRUNSPACE

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 , aby znaleźć tematy 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 .ExternalHelp kluczowe jest wymagane, gdy funkcja lub skrypt są udokumentowane w plikach XML. Bez tego słowa kluczowego Get-Help nie można odnaleźć pliku pomocy opartej na formacie XML dla funkcji lub skryptu.

Słowo .ExternalHelp kluczowe ma pierwszeństwo przed innymi słowami kluczowymi pomocy opartymi na komentarzach. Jeśli .ExternalHelp jest obecny, nie wyświetla pomocy opartej na komentarzach, Get-Help 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ść .ExternalHelp słowa kluczowego 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, ale najlepszym rozwiązaniem jest użycie następującego formatu:

<ScriptModule.psm1>-help.xml

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 cyklicznie dla pliku XML o nazwie skryptu lub funkcji zgodnie ze standardami rezerwowymi języka ustanowionymi dla systemu Windows, tak samo jak w katalogu modułu.

Aby uzyskać więcej informacji na temat formatu pliku pomocy opartej na języku XML polecenia cmdlet, zobacz How to Write Cmdlet Help (Jak napisać pomoc dotyczącą poleceń cmdlet).

Automatycznie wygenerowana zawartość

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

Nazwa

Sekcja Nazwa tematu pomocy funkcji jest pobierana z nazwy funkcji w składni funkcji. Nazwa tematu pomocy skryptu jest pobierana z nazwy pliku skryptu. Aby zmienić nazwę lub jego literę, zmień składnię funkcji lub nazwę pliku skryptu.

Składnia

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

Lista parametrów

Lista parametrów w temacie pomocy jest generowana na podstawie składni funkcji lub skryptu oraz z opisów dodanych przy użyciu słowa kluczowego .Parameter . Parametry funkcji są wyświetlane w sekcji Parametry tematu pomocy w tej samej kolejności, w której są wyświetlane w funkcji lub składni skryptu. Pisownia i kapitalizowanie nazw parametrów jest również pobierana ze składni. Nie ma to wpływu na nazwę parametru .Parameter określoną przez słowo kluczowe.

Typowe parametry

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

Tabela atrybutów parametrów

Get-Helpgeneruje tabelę atrybutów parametrów, które są wyświetlane podczas korzystania z parametru Full lub Parametr .Get-Help Wartość atrybutów Wymagane, Pozycja i Wartość domyślna jest pobierana ze składni funkcji lub skryptu.

Wartości domyślne i wartość akceptować symbole wieloznaczne nie są wyświetlane w tabeli atrybutów parametrów nawet wtedy, gdy są zdefiniowane w funkcji lub skryscie. 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 cannot pipe objects to Add-Extension.

.OUTPUTS

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

.EXAMPLE

PS> extension -name "File"
File.txt

.EXAMPLE

PS> extension -name "File" -extension "doc"
File.doc

.EXAMPLE

PS> 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 cannot pipe objects to Add-Extension.

OUTPUTS

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

Example 1

PS> extension -name "File"
File.txt

Example 2

PS> extension -name "File" -extension "doc"
File.doc

Example 3

PS> 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 wyjątkiem tego, ż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 cannot pipe objects to Add-Extension.

.OUTPUTS

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

.EXAMPLE

PS> extension -name "File"
File.txt

.EXAMPLE

PS> extension -name "File" -extension "doc"
File.doc

.EXAMPLE

PS> 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 Param instrukcji, musi istnieć co najmniej dwa puste wiersze między ostatnim komentarzem w temacie pomocy a pierwszą deklaracją funkcji. Bez tych pustych wierszy kojarzy Get-Help 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 cannot pipe objects to Update-Month.ps1.

.OUTPUTS

None. Update-Month.ps1 does not 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 { }
...

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

Get-Help -Path .\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 cannot pipe objects to Update-Month.ps1.

# OUTPUTS

None. Update-Month.ps1 does not 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

Możesz pisać tematy pomocy opartej na języku XML dla funkcji i skryptów. Chociaż pomoc oparta na komentarzach jest łatwiejsza do zaimplementowania, pomoc oparta na języku XML jest wymagana w przypadku pomocy z możliwością aktualizacji i zapewniania tematów pomocy w wielu językach.

W poniższym przykładzie przedstawiono 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.

Zwróć uwagę, ż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 od początku wbudowanej funkcji pomocy w programie PowerShell, która wyświetla jeden ekran tekstu pomocy naraz. Ponieważ temat pomocy dla Get-Help polecenia cmdlet opisuje funkcję pomocy, funkcja pomocy używa .ForwardHelpTargetName słów kluczowych i .ForwardHelpCategory do przekierowania użytkownika do tematu Get-Help pomocy polecenia cmdlet.

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 też

about_Functions

about_Functions_Advanced_Parameters

about_Scripts

How to Write Cmdlet Help

Udostępnij za pośrednictwem