about_Comment_Based_Help

Artykuł
10/04/2023

Krótki opis

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

Długi opis

Możesz pisać tematy pomocy opartej na komentarzach dla funkcji i skryptów, używając 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-Helptakich jak Szczegółowe, Pełne, Przykłady i 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ć Get-Help polecenie cmdlet 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żna znaleźć tematów pomocy opartych na języku XML dla funkcji lub skryptów.

W tym temacie opisano sposób pisania tematów pomocy dotyczących 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 komentarzy. 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ą uwzględniane w wielkości 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. Nie może istnieć więcej niż jeden pusty wiersz między ostatnim wierszem pomocy funkcji a function słowem kluczowym.

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

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 oparte na komentarzach

Poniżej przedstawiono prawidłowe słowa kluczowe pomocy oparte na komentarzach. Są one wymienione w kolejności, w której zazwyczaj pojawiają się w temacie pomocy wraz z ich zamierzonym użyciem. 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. 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. .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 po słowie .PARAMETER kluczowym. 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ładni, jak i .PARAMETER słowa kluczowego, używany jest opis skojarzony ze .PARAMETER słowem kluczowym, 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, opcjonalnie, a następnie przykładowe dane wyjściowe i opis. 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.

.OUTPUTS

Typ platformy .NET obiektów zwracanych przez polecenie cmdlet. Można również dołączyć opis zwracanych obiektów.

.NOTES

Dodatkowe informacje na temat funkcji lub skryptu.

.LINK

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

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

Ta zawartość jest wyświetlana w sekcji Powiązane linki w temacie 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 "http" lub "https".

.COMPONENT

Nazwa technologii lub funkcji używanej przez funkcję lub skrypt albo powiązana z nią funkcja. Parametr Component parametru 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. Parametr Get-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, 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ść .ExternalHelp słowa kluczowego na nazwę pliku bez ścieżki. Get-Help szuka określonej nazwy 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 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.

Nazwisko

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 wielkie litery, 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, takiej jak typ platformy .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 funkcji lub składni skryptu oraz z opisów dodanych za pomocą 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 wielkie litery nazw parametrów są również pobierane ze składni. Nie ma to wpływu na nazwę parametru .Parameter określoną przez słowo kluczowe.

Typowe parametry

Wspólne 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-HelpGeneruje tabelę atrybutów parametrów, które są wyświetlane podczas korzystania z parametru Full lub Parameter parametru .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ść akceptowania symboli wieloznacznych 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 generowana automatycznie 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 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 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 zamykającym #> i 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 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 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 { }
...

Poniższe 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 -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 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

Tematy pomocy opartej na języku XML można pisać dla funkcji i skryptów. Chociaż pomoc oparta na komentarzach jest łatwiejsza do zaimplementowania, pomoc oparta na formacie XML jest wymagana dla pomocy z możliwością aktualizowania i zapewniania tematów 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 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.
...