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-Helpi , 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. Använd nyckelordet för att aktivera cmdleten Get-Help för att hitta den XML-baserade hjälpfilen för en funktion eller ett skript .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 Get-Help.
Cmdletarna Update-Help och Save-Help fungerar endast på XML-filer. Uppdaterad 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 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 ingår i hjälpavsnittet måste det finnas minst en tom rad mellan den sista kommentarsraden som inte är till 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 av nyckelorden, 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.
Till 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. Om skriptet är signerat placerar du dock kommentarsbaserad hjälp i början av skriptfilen. Slutet av skriptet används av signaturblocket.
Till 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 .psm1anvä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 XML-baserade hjälpfiler 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.
Skriv parameternamnet på samma rad som nyckelordet .PARAMETER . Ange parameterbeskrivningen på raderna som följer 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. Om du vill ändra ordningen ändrar du syntaxen.
Du kan också ange en parameterbeskrivning genom att placera en kommentar i funktionen eller skriptsyntaxen omedelbart 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 syntaxkommentare 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-typerna av objekt som kan skickas till funktionen eller skriptet. Du kan också ta med en beskrivning av indataobjekten.
.OUTPUTS
.NET-typen för de objekt som cmdleten returnerar. Du kan också ta med 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 kommentarsblocket.
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 också innehålla en URI (Uniform Resource Identifier) till en onlineversion av samma hjälpavsnitt. Onlineversionen öppnas när du använder onlineparametern Get-Helpfö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. Komponentparametern Get-Help för 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 Get-Help Roll 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 för 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 du 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 det inte kan hitta ett hjälpavsnitt som matchar nyckelordets .ExternalHelp värde.
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 bästa praxis ä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 Get-Help söker underkatalogerna rekursivt efter en XML-fil med namnet på skriptet eller funktionen i enlighet med de språkstandarder för återställning av språk som fastställts 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 cmdlethjä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 skriptfilens namn. 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 syntaxen för hjälpavsnittet, 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
De vanliga parametrarna läggs till i syntax- och parameterlistan för hjälpavsnittet, även om de inte har någon effekt. Mer information om de vanliga parametrarna finns i about_CommonParameters.
Parameterattributtabell
Get-Help genererar tabellen med parameterattribut som visas när du använder parametern Full eller Parameter för Get-Help. Värdet för attributen Required, Position och Default 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 definieras 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 innehållet.
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
#>
}
Resultaten ä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. Observera de tomma raderna mellan stängningen #> och -instruktionen Param . I ett skript som inte har någon 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 du 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 kommentarsbaserad hjälp är enklare att implementera krävs XML-baserad hjälp för uppdaterbar 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 nyckelordets .ExternalHelp värde 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.
...
Se även
Feedback
Kommer snart: Under hela 2024 kommer vi att fasa ut GitHub-problem som feedbackmekanism för innehåll och ersätta det med ett nytt feedbacksystem. Mer information finns i: https://aka.ms/ContentUserFeedback.
Skicka och visa feedback för