om_kommentarbaserad_hjälp

2025-05-21

Kort beskrivning

Beskriver hur du skriver kommentarsbaserat hjälpinnehåll för funktioner och skript.

Lång beskrivning

Du kan skriva kommentarsbaserat hjälpinnehåll 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 som cmdlet-hjälpinnehållet som genereras från XML-filer. 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 kan Get-Help inte hitta XML-baserat hjälpinnehåll för funktioner eller skript.

Det här avsnittet beskriver hur du skriver hjälpinnehåll för funktioner och skript. Information om hur du visar hjälpinnehåll 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 kommentarsbaserat hjälpinnehåll.

Syntax för kommentarsbaserad hjälp

Om du vill skapa kommentarsbaserat hjälpinnehåll kan du använda antingen kommentarsformat: enradskommentarer eller blockkommentarer.

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 hjälp och början på 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 nyckelordet function.

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

Kommentarsbaserade hjälpnyckelord

Följande är giltiga kommentarsbaserade hjälpnyckelord. Dessa nyckelord kan visas i valfri ordning i den kommentarsbaserade hjälpen och de är inte skiftlägeskänsliga. Nyckelorden visas i den här artikeln i den ordning som de vanligtvis visas i ett hjälpavsnitt.

.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. Upprepa det här nyckelordet för varje indatatyp.

`.OUTPUTS`

.NET-typen för de objekt som cmdleten returnerar. Du kan också ta med en beskrivning av de returnerade objekten. Upprepa det här nyckelordet för varje utdatatyp.

`.NOTES`

Ytterligare information om funktionen eller skriptet.

`.LINK`

Namnet på ett relaterat ämne. Upprepa det här nyckelordet 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 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 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 för använder det här värdet för att filtrera sökresultaten som returneras av Get-Help.

`.FORWARDHELPTARGETNAME <Command-Name>`

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

# .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 <PSSession-variable>`

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älpinnehållet 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 kan Get-Help 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 visar Get-Help inte kommentarsbaserad hjälp, även om det 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. Från och med PowerShell 5.0 kan funktioner som exporteras av en modul dokumenteras i en hjälpfil med namnet på modulen. Du behöver inte använda .EXTERNALHELP nyckelord för kommentarer. Om funktionen Test-Function till exempel exporteras av modulen MyModule kan du ge hjälpfilen MyModule-help.xmlnamnet . Cmdleten Get-Help söker efter hjälp för Test-Function funktionen i MyModule-help.xml filen i modulkatalogen.

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 .

Namn

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 objekt typ 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.

Examples

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 can't pipe objects to Add-Extension.

.OUTPUTS

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

.EXAMPLE

PS> Add-Extension -Name "File"
File.txt

.EXAMPLE

PS> Add-Extension -Name "File" -Extension "doc"
File.doc

.EXAMPLE

PS> Add-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 can't pipe objects to Add-Extension.

OUTPUTS

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

Example 1

PS> Add-Extension -Name "File"
File.txt

Example 2

PS> Add-Extension -Name "File" -Extension "doc"
File.doc

Example 3

PS> Add-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 can't pipe objects to Add-Extension.

.OUTPUTS

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

.EXAMPLE

PS> Add-Extension -Name "File"
File.txt

.EXAMPLE

PS> Add-Extension -Name "File" -Extension "doc"
File.doc

.EXAMPLE

PS> Add-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 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 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 can't pipe objects to Update-Month.ps1.

.OUTPUTS

None. Update-Month.ps1 doesn't 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 måste det Get-Help kommando 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 can't pipe objects to Update-Month.ps1.

# OUTPUTS

None. Update-Month.ps1 doesn't 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-baserat hjälpinnehåll 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älpinnehåll 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

Var den här sidan till hjälp?

Dela via

om_kommentarbaserad_hjälp

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

Kommentarsbaserade hjälpnyckelord

.SYNOPSIS

.DESCRIPTION

.PARAMETER

.EXAMPLE

.INPUTS

.OUTPUTS

.NOTES

.LINK

.COMPONENT

.ROLE

.FUNCTIONALITY

.FORWARDHELPTARGETNAME <Command-Name>

.FORWARDHELPCATEGORY

.REMOTEHELPRUNSPACE <PSSession-variable>

.EXTERNALHELP

Automatiskt genererat innehåll

Namn

Syntax

Parameterlista

Vanliga parametrar

Parameterattributtabell

Kommentarer

Examples

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

Ytterligare resurser

`.EXAMPLE`

`.INPUTS`

`.OUTPUTS`

`.NOTES`

`.LINK`

`.COMPONENT`

`.ROLE`

`.FUNCTIONALITY`

`.FORWARDHELPTARGETNAME <Command-Name>`

`.FORWARDHELPCATEGORY`

`.REMOTEHELPRUNSPACE <PSSession-variable>`

`.EXTERNALHELP`