about_Comment_Based_Help
Kort beskrivning
Beskriver hur du skriver kommentarsbaserade hjälpavsnitt för funktioner och skript.
Lång beskrivning
Du kan skriva kommentarsbaserade hjälpavsnitt för funktioner och skript med hjälp av särskilda nyckelord för hjälpkommenterar.
Cmdleten Get-Help visar kommentarsbaserad hjälp i samma format där cmdlet-hjälpavsnitten som genereras från XML-filer visas. Användare kan använda alla parametrar Get-Help
i , till exempel Detaljerad, Fullständig, Exempel och Online, för att visa innehållet i kommentarsbaserad hjälp.
Du kan också skriva XML-baserade hjälpfiler för funktioner och skript. Om du vill aktivera cmdleten Get-Help
för att hitta den XML-baserade hjälpfilen för en funktion eller ett skript använder du nyckelordet .ExternalHelp
. Utan det här nyckelordet Get-Help
kan du 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 Få hjälp.
Cmdletarna Update-Help och Save-Help fungerar bara på XML-filer. Uppdateringsbar hjälp stöder inte kommentarsbaserade hjälpavsnitt.
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 kommentarsrad, eller så kan du använda symbolerna <#
och #>
för att skapa ett kommentarsblock. Alla rader i kommentarblocket 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 ingår i hjälpavsnittet måste det finnas minst en tom rad mellan den sista kommentarsraden som inte är 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 skiftlägeskä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 nyckelordet
function
. Det får inte finnas mer än en tom rad mellan den sista raden i funktionshjälpen och nyckelordetfunction
.
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älp 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 som 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 .ExternalHelp
för att identifiera DE XML-baserade hjälpfilerna för funktionerna i en skriptmodul måste du lägga till en .ExternalHelp
kommentar till varje funktion.
# .ExternalHelp <XML-file-name>
function <function-name>
{
...
}
Kommentarsbaserade hjälpnyckelord
Följande är giltiga kommentarsbaserade hjälpnyckelord. De visas i den ordning de vanligtvis visas i ett hjälpavsnitt tillsammans med deras avsedda användning. Dessa nyckelord kan visas i valfri ordning i den kommentarsbaserade hjälpen och de är inte skiftlägeskä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 ett .PARAMETER
nyckelord för varje parameter i funktionen eller skriptsyntaxen.
Ange parameternamnet på samma rad som nyckelordet .PARAMETER
. Ange parameterbeskrivningen på raderna efter nyckelordet .PARAMETER
. Windows PowerShell tolkar all text mellan .PARAMETER
raden och nästa nyckelord eller slutet av kommentarsblocket som en del av parameterbeskrivningen.
Beskrivningen kan innehålla styckebrytningar.
.PARAMETER <Parameter-Name>
Nyckelorden Parameter kan visas i valfri ordning i kommentarsblocket, men funktions- eller skriptsyntaxen avgör i vilken ordning parametrarna (och deras beskrivningar) visas i hjälpavsnittet. Ändra syntaxen om du vill ändra ordningen.
Du kan också ange en parameterbeskrivning genom att placera en kommentar i funktionen eller skriptsyntaxen direkt före parametervariabelnamnet. För att detta ska fungera måste du också ha ett kommentarsblock med minst ett nyckelord.
Om du använder både en syntaxkommentare och ett .PARAMETER
nyckelord används beskrivningen som är associerad med nyckelordet .PARAMETER
och syntaxkommenten 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 skickas 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 ".LINK" och måste föregås av en kommentarssymbol #
eller inkluderas i kommentarblocket.
Upprepa nyckelordet .LINK
för varje relaterat ämne.
Det här innehållet visas i avsnittet Relaterade länkar i hjälpavsnittet.
Nyckelordsinnehållet .Link
kan även innehålla en URI (Uniform Resource Identifier) till en onlineversion av samma hjälpavsnitt. Onlineversionen öppnas när du använder onlineparametern Get-Help
för . URI:n måste börja med "http" eller "https".
.COMPONENT
Namnet på den teknik eller funktion som funktionen eller skriptet använder, eller till vilken den är relaterad. KomponentparameternGet-Help
i 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. RollparameternGet-Help
för 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 Get-Help
Funktionalitet i 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 valfritt 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
, Function
, Provider
, General
, FAQ
, Glossary
, ScriptCommand
, ExternalScript
, Filter
eller 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 cmdleten Export-PSSession för att hitta hjälpavsnitten 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 nyckelordet Get-Help
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 Get-Help
visas inte kommentarsbaserad hjälp, även om den inte kan hitta ett hjälpavsnitt som matchar värdet för nyckelordet .ExternalHelp
.
Om funktionen exporteras av en modul anger du värdet för nyckelordet .ExternalHelp
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 på namnet på den XML-baserade hjälpfilen för en funktion, men vi rekommenderar att du använder 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 Get-Help
söker underkatalogerna rekursivt efter en XML-fil med namnet på skriptet eller funktionen i enlighet med de standarder för språkåterställning som har upprättats för Windows, precis som i en modulkatalog.
Mer information om xml-baserat hjälpfilformat för cmdlet-hjälp finns i Så här skriver du cmdlet-hjälp.
Automatiskt genererat innehåll
Namn, syntax, parameterlista, parameterattributtabell, vanliga parametrar och kommentarer genereras automatiskt av cmdleten Get-Help
.
Name
Avsnittet Namn i ett funktionshjälpavsnitt hämtas från funktionsnamnet i funktionssyntaxen. Namnet på ett skripthjälpavsnitt hämtas från skriptets filnamn. Om du vill ändra namnet eller dess versaler ändrar du funktionssyntaxen eller skriptfilens namn.
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 informationen i syntaxen. Om du inte anger någon parametertyp infogas objekttypen 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 nyckelordet .Parameter
. Funktionsparametrarna visas i avsnittet Parametrar i hjälpavsnittet i samma ordning som de visas i funktionen eller skriptsyntaxen. Stavning och versaler för parameternamn hämtas också från syntaxen. Det påverkas inte av parameternamnet som anges av nyckelordet .Parameter
.
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.
Tabell för parameterattribut
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 Standard hämtas från funktionen eller skriptsyntaxen.
Standardvärden och ett värde för Acceptera jokertecken visas inte i parameterattributtabellen även när de har definierats i funktionen eller skriptet. Ange den här informationen i parameterbeskrivningen för att hjälpa användarna.
Kommentarer
Avsnittet Kommentarer i hjälpavsnittet genereras automatiskt från funktionen 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 detsamma 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. Lägg märke till de tomma raderna mellan avslutningen #>
och -instruktionen Param
. I ett skript som inte har en Param
-instruktion måste det finnas minst två tomma rader mellan den slutliga kommentaren i hjälpavsnittet och den första funktionsdeklarationen. Utan dessa tomma rader Get-Help
associerar 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 visas i $env:Path
miljövariabeln Get-Help
måste kommandot som hämtar skripthjälpen ange skriptsökvägen.
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
Omdirigera till en XML-fil
Du kan skriva XML-baserade hjälpavsnitt för funktioner och skript. Även om det är enklare att implementera kommentarsbaserad hjälp krävs XML-baserad hjälp för uppdateringsbar hjälp och för att tillhandahålla hjälpämnen på flera språk.
I följande exempel visas de första raderna i skriptet Update-Month.ps1.
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 nyckelordet .ExternalHelp
visas på samma rad som nyckelordet. Alla andra placeringar är ineffektiva.
# .ExternalHelp C:\MyScripts\Update-Month-Help.xml
param ([string]$InputPath, [string]$OutPutPath)
function Get-Data { }
...
I följande exempel visas tre giltiga placeringar av nyckelordet .ExternalHelp
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 Get-Help
beskriver hjälpfunktionen använder hjälpfunktionen nyckelorden .ForwardHelpTargetName
och .ForwardHelpCategory
för att omdirigera användaren till cmdlet-hjälpavsnittet Get-Help
.
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.
...