about_Comment_Based_Help

Artikel
10/09/2021
13 minuter för att läsa

Kort beskrivning

Beskriver hur du skriver kommentarsbaserade hjälpavsnitt för funktioner och skript.

Lång beskrivning

Du kan skriva kommentarsbaserade hjälpämnen för funktioner och skript med hjälp av särskilda nyckelord för hjälpkommentarer.

Cmdleten Get-Help visar kommentarsbaserad hjälp i samma format som den visar de cmdlet-hjälpämnen som genereras från XML-filer. Användare kan använda alla parametrar för , till exempel Detaljerad, Fullständig , Exempel och Online , för att visa innehållet Get-Help i kommentarsbaserad hjälp.

Du kan också skriva XML-baserade hjälpfiler för funktioner och skript. Om du vill Get-Help aktivera cmdleten för att hitta den XML-baserade hjälpfilen för en funktion eller ett skript använder du .ExternalHelp nyckelordet . Utan det här Get-Help nyckelordet kan inte hitta XML-baserade hjälpavsnitt för funktioner eller skript.

Det här avsnittet beskriver hur du skriver hjälpavsnitt för funktioner och skript. Information om hur du visar hjälpavsnitt för funktioner och skript finns i Get-Help.

Cmdletarna Update-Help och Save-Help fungerar bara på XML-filer. Uppdatabel hjälp har inte stöd för kommentarsbaserade hjälpämnen.

Syntax för kommentarsbaserad hjälp

Syntaxen för kommentarsbaserad hjälp är följande:

# .<help keyword>
# <help content>

eller

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

Kommentarsbaserad hjälp skrivs som en serie kommentarer. Du kan skriva en # kommentarssymbol före varje rad med kommentarer, eller så kan du använda symbolerna och för att skapa ett <# #> kommentarsblock. Alla rader i kommentarsblocket tolkas som kommentarer.

Alla rader i ett kommentarsbaserat hjälpavsnitt måste vara sammanhängande. Om ett kommentarsbaserat hjälpavsnitt följer en kommentar som inte är en del av hjälpavsnittet måste det finnas minst en tom rad mellan den senaste kommentarsraden utan hjälp och början av den kommentarsbaserade hjälpen.

Nyckelord definierar varje avsnitt i kommentarsbaserad hjälp. Varje kommentarsbaserat hjälpnyckelord föregås av en punkt . . Nyckelorden kan visas i valfri ordning. Nyckelordsnamnen är inte fallkänsliga.

Nyckelordet .Description föregår till exempel en beskrivning av en funktion eller ett skript.

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

Kommentarsblocket måste innehålla minst ett nyckelord. Vissa nyckelord, till exempel .EXAMPLE , kan visas många gånger i samma kommentarsblock. Hjälpinnehållet för varje nyckelord börjar på raden efter nyckelordet och kan sträcka sig över flera rader.

Syntax för kommentarsbaserad hjälp i funktioner

Kommentarsbaserad hjälp för en funktion kan visas på någon av tre platser:

I början av funktionstexten.
I slutet av funktionstexten.
Före function nyckelordet . Det får inte finnas mer än en tom rad mellan den sista raden i funktionshjälpen och function nyckelordet .

Exempel:

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

  # function logic
}

eller

function Get-Function
{
   # function logic

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

eller

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

Syntax för kommentarsbaserad hjälp i skript

Kommentarsbaserad hjälp för ett skript kan visas på någon av följande två platser i skriptet.

I början av skriptfilen. Skripthjälpen kan endast föregås av kommentarer och tomma rader i skriptet.

Om det första objektet i skripttexten (efter hjälpen) är en funktionsdeklaration måste det finnas minst två tomma rader mellan slutet av skripthjälpen och funktionsdeklarationen. Annars tolkas hjälpen som hjälp för funktionen, inte hjälp för skriptet.
I slutet av skriptfilen. Men om skriptet är signerat placerar du Kommentarsbaserad hjälp i början av skriptfilen. Slutet av skriptet används av signaturblocket.

Exempel:

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


function Get-Function { }

eller

function Get-Function { }

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

Syntax för kommentarsbaserad hjälp i skriptmoduler

I en skriptmodul .psm1 använder kommentarsbaserad hjälp syntaxen för funktioner, inte syntaxen för skript. Du kan inte använda skriptsyntaxen för att ge hjälp för alla funktioner som definierats i en skriptmodul.

Om du till exempel använder nyckelordet för att identifiera DE XML-baserade hjälpfilerna för funktionerna i en skriptmodul måste du lägga till en .ExternalHelp .ExternalHelp kommentar till varje funktion.

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

Nyckelord för kommentarsbaserad hjälp

Följande är giltiga nyckelord för kommentarsbaserad hjälp. De visas i den ordning som de vanligtvis visas i ett hjälpavsnitt tillsammans med den avsedda användningen. Dessa nyckelord kan visas i valfri ordning i den kommentarsbaserade hjälpen, och de är inte fallkänsliga.

.SYNOPSIS

En kort beskrivning av funktionen eller skriptet. Det här nyckelordet kan bara användas en gång i varje ämne.

.DESCRIPTION

En detaljerad beskrivning av funktionen eller skriptet. Det här nyckelordet kan bara användas en gång i varje ämne.

.PARAMETER

Beskrivningen av en parameter. Lägg till .PARAMETER ett nyckelord för varje parameter i funktionen eller skriptsyntaxen.

Skriv parameternamnet på samma rad som .PARAMETER nyckelordet . Ange parameterbeskrivningen på raderna efter .PARAMETER nyckelordet . Windows PowerShell tolkar all text mellan raden och nästa nyckelord eller slutet .PARAMETER av kommentarsblocket som en del av parameterbeskrivningen. Beskrivningen kan innehålla styckenbrytningar.

.PARAMETER  <Parameter-Name>

Parameternyckelorden kan visas i valfri ordning i kommentarsblocket, men funktionen eller skriptsyntaxen avgör i vilken ordning parametrarna (och deras beskrivningar) visas i hjälpavsnittet. Ändra syntaxen om du vill ändra ordning.

Du kan också ange en parameterbeskrivning genom att placera en kommentar i funktionen eller skriptsyntaxen direkt före parametervariabelns namn. För att detta ska fungera måste du också ha ett kommentarsblock med minst ett nyckelord.

Om du använder både en syntaxkommentar och ett nyckelord används beskrivningen som är associerad med nyckelordet .PARAMETER .PARAMETER och syntaxkommentaren ignoreras.

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

.EXAMPLE

Ett exempelkommando som använder funktionen eller skriptet, eventuellt följt av exempelutdata och en beskrivning. Upprepa det här nyckelordet för varje exempel.

.INPUTS

.NET-typer av objekt som kan ledas till funktionen eller skriptet. Du kan också inkludera en beskrivning av indataobjekten.

.OUTPUTS

.NET-typen för de objekt som cmdleten returnerar. Du kan också inkludera en beskrivning av de returnerade objekten.

.NOTES

Ytterligare information om funktionen eller skriptet.

.LINK

Namnet på ett relaterat ämne. Värdet visas på raden under nyckelordet " " och måste föregås .LINK av en kommentarssymbol # eller inkluderas i kommentarsblocket.

Upprepa .LINK nyckelordet för varje relaterat ämne.

Det här innehållet visas i avsnittet Relaterade länkar i hjälpavsnittet.

.LinkNyckelordsinnehållet kan också innehålla en Uniform Resource Identifier (URI) till en onlineversion av samma hjälpavsnitt. Onlineversionen öppnas när du använder onlineparametern Get-Help . URI:en måste börja med "http" eller "https".

.COMPONENT

Namnet på tekniken eller funktionen som funktionen eller skriptet använder, eller som den är relaterad till. Parametern Komponent i Get-Help använder det här värdet för att filtrera sökresultaten som returneras av Get-Help .

.ROLE

Namnet på användarrollen för hjälpavsnittet. Parametern Role för Get-Help använder det här värdet för att filtrera sökresultaten som returneras av Get-Help .

.FUNCTIONALITY

Nyckelorden som beskriver den avsedda användningen av funktionen. Parametern Funktioner i Get-Help använder det här värdet för att filtrera sökresultaten som returneras av Get-Help .

.FORWARDHELPTARGETNAME

Omdirigerar till hjälpavsnittet för det angivna kommandot. Du kan omdirigera användare till alla hjälpavsnitt, inklusive hjälpavsnitt för en funktion, ett skript, en cmdlet eller en provider.

# .FORWARDHELPTARGETNAME <Command-Name>

.FORWARDHELPCATEGORY

Anger hjälpkategorin för objektet i .ForwardHelpTargetName . Giltiga värden är Alias , , , , , , , , Cmdlet , , , HelpFile , eller Function Provider General FAQ Glossary ScriptCommand ExternalScript Filter All . Använd det här nyckelordet för att undvika konflikter när det finns kommandon med samma namn.

# .FORWARDHELPCATEGORY <Category>

.REMOTEHELPRUNSPACE

Anger en session som innehåller hjälpavsnittet. Ange en variabel som innehåller ett PSSession-objekt. Det här nyckelordet används av export-PSSession-cmdleten för att hitta hjälpavsnitt för de exporterade kommandona.

# .REMOTEHELPRUNSPACE <PSSession-variable>

.EXTERNALHELP

Anger en XML-baserad hjälpfil för skriptet eller funktionen.

# .EXTERNALHELP <XML Help File>

Nyckelordet .ExternalHelp krävs när en funktion eller ett skript dokumenteras i XML-filer. Utan det här Get-Help nyckelordet kan inte hitta den XML-baserade hjälpfilen för funktionen eller skriptet.

Nyckelordet .ExternalHelp har företräde framför andra kommentarsbaserade hjälpnyckelord. Om .ExternalHelp finns visas inte kommentarsbaserad hjälp, även om det inte går att hitta ett Get-Help hjälpavsnitt som matchar värdet för .ExternalHelp nyckelordet .

Om funktionen exporteras av en modul anger du värdet för .ExternalHelp nyckelordet till ett filnamn utan sökväg. Get-Help söker efter det angivna filnamnet i en språkspecifik underkatalog i modulkatalogen. Det finns inga krav för namnet på den XML-baserade hjälpfilen för en funktion, men det bästa sättet är att använda följande format:

<ScriptModule.psm1>-help.xml

Om funktionen inte ingår i en modul inkluderar du en sökväg till den XML-baserade hjälpfilen. Om värdet innehåller en sökväg och sökvägen innehåller UI-kulturspecifika underkataloger, söker underkatalogerna rekursivt efter en XML-fil med namnet på skriptet eller funktionen i enlighet med de språkstandarder som har upprättats för Windows, precis som i en Get-Help modulkatalog.

Mer information om xml-baserat hjälpfilformat för cmdlet-hjälp finns i How to Write Cmdlet Help (Så här skriver du cmdlet-hjälpen).

Automatiskt genererat innehåll

Namn, syntax, parameterlista, parameterattributtabell, gemensamma parametrar och kommentarer genereras automatiskt av Get-Help cmdleten .

Name

Avsnittet Namn i ett funktionshjälpavsnitt kommer från funktionsnamnet i funktionssyntaxen. Namnet på ett skripthjälpavsnitt kommer från skriptfilnamnet. Om du vill ändra namnet eller dess versaler ändrar du funktionssyntaxen eller skriptfilnamnet.

Syntax

Avsnittet Syntax i hjälpavsnittet genereras från funktionen eller skriptsyntaxen. Om du vill lägga till information i hjälpämnessyntaxen, till exempel .NET-typen för en parameter, lägger du till information i syntaxen. Om du inte anger någon parametertyp infogas Objekttyp som standardvärde.

Parameterlista

Parameterlistan i hjälpavsnittet genereras från funktionen eller skriptsyntaxen och från de beskrivningar som du lägger till med hjälp av .Parameter nyckelordet . Funktionsparametrarna visas i avsnittet Parametrar i hjälpavsnittet i samma ordning som de visas i funktionen eller skriptsyntaxen. Stavning och versaler för parameternamn kommer också från syntaxen. Det påverkas inte av parameternamnet som anges av .Parameter nyckelordet .

Vanliga parametrar

Vanliga parametrar läggs till i syntax- och parameterlistan i hjälpavsnittet, även om de inte har någon effekt. Mer information om vanliga parametrar finns i about_CommonParameters.

Parameterattributtabell

Get-Help genererar tabellen med parameterattribut som visas när du använder parametern Fullständig eller Parameter för Get-Help . Värdet för attributen Obligatoriskt, Position och Standardvärde kommer från funktionen eller skriptsyntaxen.

Standardvärden och ett värde för Acceptera jokertecken visas inte i parameterattributtabellen även om de definieras i funktionen eller skriptet. Du kan hjälpa användarna genom att ange den här informationen i parameterbeskrivningen.

Kommentarer

Avsnittet Kommentarer i hjälpavsnittet genereras automatiskt från funktions- eller skriptnamnet. Du kan inte ändra eller påverka dess innehåll.

Exempel

Kommentarsbaserad hjälp för en funktion

Följande exempelfunktion innehåller kommentarsbaserad hjälp:

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

Resultatet är följande:

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

Parameterbeskrivningar i funktionssyntax

Det här exemplet är samma som det föregående, förutom att parameterbeskrivningarna infogas i funktionssyntaxen. Det här formatet är mest användbart när beskrivningarna är korta.

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

Kommentarsbaserad hjälp för ett skript

Följande exempelskript innehåller kommentarsbaserad hjälp. Observera de tomma raderna mellan den avslutande #> och Param -instruktionen. I ett skript som inte har en -instruktion måste det finnas minst två tomma rader mellan den sista kommentaren i hjälpavsnittet Param och den första funktionsdeklarationen. Utan dessa tomma rader Get-Help associeras hjälpavsnittet med funktionen, inte skriptet.

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

Följande kommando hämtar skripthjälpen. Eftersom skriptet inte finns i en katalog som anges i miljövariabeln måste kommandot som hämtar $env:Path Get-Help skripthjälpen ange skriptsökvägen.

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

Omdirigera till en XML-fil

Du kan skriva XML-baserade hjälpavsnitt för funktioner och skript. Även om kommentarsbaserad hjälp är enklare att implementera krävs XML-baserad hjälp för uppdatabel hjälp och för att tillhandahålla hjälpavsnitt på flera språk.

I följande exempel visas de första raderna i Update-Month.ps1 skript. Skriptet använder nyckelordet .ExternalHelp för att ange sökvägen till ett XML-baserat hjälpavsnitt för skriptet.

Observera att värdet för .ExternalHelp nyckelordet visas på samma rad som nyckelordet . All annan placering är ineffektiv.

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

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

I följande exempel visas tre giltiga placeringen av .ExternalHelp nyckelordet i en funktion.

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
}

Omdirigera till ett annat hjälpavsnitt

Följande kod är ett utdrag från början av den inbyggda hjälpfunktionen i PowerShell, som visar en skärm med hjälptext i taget. Eftersom hjälpavsnittet för cmdleten beskriver hjälpfunktionen använder hjälpfunktionen nyckelorden och för att omdirigera användaren till Get-Help .ForwardHelpTargetName .ForwardHelpCategory Get-Help cmdlet-hjälpavsnittet.

function help
{

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

Följande kommando använder den här funktionen:

Get-Help -Name help

NAME

Get-Help

SYNOPSIS

Displays information about PowerShell cmdlets and concepts.
...

Se även

about_Functions

about_Functions_Advanced_Parameters

about_Scripts

Så här skriver du cmdlet-hjälp

about_Comment_Based_Help

Betygsätta din upplevelse

Kort beskrivning

Lång beskrivning

Syntax för kommentarsbaserad hjälp

Syntax för kommentarsbaserad hjälp i funktioner

Syntax för kommentarsbaserad hjälp i skript

Syntax för kommentarsbaserad hjälp i skriptmoduler

Nyckelord för kommentarsbaserad hjälp

.SYNOPSIS

.DESCRIPTION

.PARAMETER

.EXAMPLE

.INPUTS

.OUTPUTS

.NOTES

.LINK

.COMPONENT

.ROLE

.FUNCTIONALITY

.FORWARDHELPTARGETNAME

.FORWARDHELPCATEGORY

.REMOTEHELPRUNSPACE

.EXTERNALHELP

Automatiskt genererat innehåll

Name

Syntax

Parameterlista

Vanliga parametrar

Parameterattributtabell

Kommentarer

Exempel

Kommentarsbaserad hjälp för en funktion

Parameterbeskrivningar i funktionssyntax

Kommentarsbaserad hjälp för ett skript

Omdirigera till en XML-fil

Omdirigera till ett annat hjälpavsnitt

Se även

Feedback