about_Comment_Based_Help

Korte beschrijving

Hierin wordt beschreven hoe u help-onderwerpen op basis van opmerkingen schrijft voor functies en scripts.

Lange beschrijving

U kunt helponderwerpen op basis van opmerkingen schrijven voor functies en scripts met speciale trefwoorden voor help-opmerkingen.

De Cmdlet Get-Help geeft hulp op basis van opmerkingen weer in dezelfde indeling waarin de Help-onderwerpen voor cmdlets worden weergegeven die zijn gegenereerd op basis van XML-bestanden. Gebruikers kunnen alle parameters van Get-Help, zoals Gedetailleerd, Volledig, Voorbeelden en Online, gebruiken om de inhoud van hulp op basis van opmerkingen weer te geven.

U kunt ook OP XML gebaseerde Help-bestanden schrijven voor functies en scripts. Gebruik het .ExternalHelp trefwoord om de Get-Help cmdlet in te schakelen om het XML-helpbestand voor een functie of script te vinden. Zonder dit trefwoord kunt Get-Help u geen op XML gebaseerde Help-onderwerpen vinden voor functies of scripts.

In dit onderwerp wordt uitgelegd hoe u Help-onderwerpen schrijft voor functies en scripts. Zie Get-Help voor informatie over het weergeven van Help-onderwerpen voor functies en scripts.

De cmdlets Update-Help en Save-Help werken alleen voor XML-bestanden. Help-informatie die kan worden bijgewerkt, biedt geen ondersteuning voor help-onderwerpen op basis van opmerkingen.

Syntaxis voor hulp op basis van opmerkingen

De syntaxis voor hulp op basis van opmerkingen is als volgt:

# .<help keyword>
# <help content>

or

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

Hulp op basis van opmerkingen wordt geschreven als een reeks opmerkingen. U kunt een opmerkingsymbool # typen vóór elke regel met opmerkingen, of u kunt de <# en #> symbolen gebruiken om een opmerkingenblok te maken. Alle regels in het opmerkingenblok worden geïnterpreteerd als opmerkingen.

Alle regels in een Help-onderwerp op basis van opmerkingen moeten aaneengesloten zijn. Als een hulponderwerp op basis van opmerkingen een opmerking volgt die geen deel uitmaakt van het Help-onderwerp, moet er ten minste één lege regel tussen de laatste regel voor niet-help-opmerkingen en het begin van de hulp op basis van opmerkingen staan.

Trefwoorden definiëren elke sectie met hulp op basis van opmerkingen. Elk help-trefwoord op basis van opmerkingen wordt voorafgegaan door een punt .. De trefwoorden kunnen in elke volgorde worden weergegeven. De namen van trefwoorden zijn niet hoofdlettergevoelig.

Het trefwoord gaat bijvoorbeeld .Description vooraf aan een beschrijving van een functie of script.

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

Het opmerkingenblok moet ten minste één trefwoord bevatten. Sommige trefwoorden, zoals .EXAMPLE, kunnen vaak worden weergegeven in hetzelfde opmerkingenblok. De Help-inhoud voor elk trefwoord begint op de regel na het trefwoord en kan meerdere regels omvatten.

Syntaxis voor hulp op basis van opmerkingen in functies

Hulp op basis van opmerkingen voor een functie kan worden weergegeven op een van de drie locaties:

• Aan het begin van de hoofdtekst van de functie.
• Aan het einde van de hoofdtekst van de functie.
• Voor het function trefwoord. Er mag niet meer dan één lege regel zijn tussen de laatste regel van de functiehulp en het function trefwoord.

Voorbeeld:

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

  # function logic
}

or

function Get-Function
{
   # function logic

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

or

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

Syntaxis voor hulp op basis van opmerkingen in scripts

Hulp op basis van opmerkingen voor een script kan worden weergegeven op een van de volgende twee locaties in het script.

• Aan het begin van het scriptbestand. Scripthulp kan alleen worden voorafgegaan door opmerkingen en lege regels in het script.

  Als het eerste item in de scripttekst (na de help) een functiedeclaratie is, moet er ten minste twee lege regels zijn tussen het einde van de scripthulp en de functiedeclaratie. Anders wordt de help geïnterpreteerd als help voor de functie, niet als hulp voor het script.

• Aan het einde van het scriptbestand. Als het script echter is ondertekend, plaatst u hulp op basis van opmerkingen aan het begin van het scriptbestand. Het einde van het script wordt bezet door het handtekeningblok.

Voorbeeld:

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


function Get-Function { }

or

function Get-Function { }

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

Syntaxis voor hulp op basis van opmerkingen in scriptmodules

In een scriptmodule .psm1gebruikt hulp op basis van opmerkingen de syntaxis voor functies, niet de syntaxis voor scripts. U kunt de syntaxis van het script niet gebruiken om hulp te bieden voor alle functies die zijn gedefinieerd in een scriptmodule.

Als u bijvoorbeeld het .ExternalHelp trefwoord gebruikt om de XML-helpbestanden voor de functies in een scriptmodule te identificeren, moet u een .ExternalHelp opmerking toevoegen aan elke functie.

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

Help-trefwoorden op basis van opmerkingen

Hier volgen geldige Help-trefwoorden op basis van opmerkingen. Ze worden weergegeven in de volgorde waarin ze meestal worden weergegeven in een Help-onderwerp, samen met het beoogde gebruik. Deze trefwoorden kunnen in elke volgorde worden weergegeven in de help op basis van opmerkingen en ze zijn niet hoofdlettergevoelig.

.SYNOPSIS

Een korte beschrijving van de functie of het script. Dit trefwoord kan slechts eenmaal in elk onderwerp worden gebruikt.

.DESCRIPTION

Een gedetailleerde beschrijving van de functie of het script. Dit trefwoord kan slechts eenmaal in elk onderwerp worden gebruikt.

.PARAMETER

De beschrijving van een parameter. Voeg een .PARAMETER trefwoord toe voor elke parameter in de syntaxis van de functie of het script.

Typ de parameternaam op dezelfde regel als het .PARAMETER trefwoord. Typ de parameterbeschrijving op de regels na het .PARAMETER trefwoord. Windows PowerShell interpreteert alle tekst tussen de .PARAMETER regel en het volgende trefwoord of het einde van het opmerkingenblok als onderdeel van de parameterbeschrijving. De beschrijving kan alinea-einden bevatten.

.PARAMETER  <Parameter-Name>

De parametertrefwoorden kunnen in elke volgorde in het opmerkingenblok worden weergegeven, maar de syntaxis van de functie of het script bepaalt de volgorde waarin de parameters (en de bijbehorende beschrijvingen) worden weergegeven in het Help-onderwerp. Als u de volgorde wilt wijzigen, wijzigt u de syntaxis.

U kunt ook een parameterbeschrijving opgeven door een opmerking in de functie of scriptsyntaxis te plaatsen direct vóór de naam van de parametervariabele. Dit werkt alleen als u een opmerkingenblok met ten minste één trefwoord hebt.

Als u zowel een syntaxiscommentatie als een .PARAMETER trefwoord gebruikt, wordt de beschrijving gebruikt die aan het .PARAMETER trefwoord is gekoppeld en wordt de opmerking over de syntaxis genegeerd.

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

.EXAMPLE

Een voorbeeldopdracht die gebruikmaakt van de functie of het script, eventueel gevolgd door voorbeelduitvoer en een beschrijving. Herhaal dit trefwoord voor elk voorbeeld.

.INPUTS

De .NET-typen objecten die kunnen worden doorgesluisd naar de functie of het script. U kunt ook een beschrijving van de invoerobjecten opnemen.

.OUTPUTS

Het .NET-type van de objecten die door de cmdlet worden geretourneerd. U kunt ook een beschrijving van de geretourneerde objecten opnemen.

.NOTES

Aanvullende informatie over de functie of het script.

.LINK

De naam van een gerelateerd onderwerp. De waarde wordt weergegeven op de regel onder het trefwoord '.LINK' en moet worden voorafgegaan door een opmerkingsymbool # of opgenomen in het opmerkingenblok.

Herhaal het .LINK trefwoord voor elk gerelateerd onderwerp.

Deze inhoud wordt weergegeven in de sectie Verwante koppelingen van het Help-onderwerp.

De .Link trefwoordinhoud kan ook een URI (Uniform Resource Identifier) bevatten naar een onlineversie van hetzelfde Help-onderwerp. De onlineversie wordt geopend wanneer u de onlineparameter van Get-Help. De URI moet beginnen met http of https.

.COMPONENT

De naam van de technologie of functie die door de functie of het script wordt gebruikt of waaraan deze is gerelateerd. De parameter Component gebruikt Get-Help deze waarde om de zoekresultaten te filteren die worden geretourneerd door Get-Help.

.ROLE

De naam van de gebruikersrol voor het Help-onderwerp. De parameter Role van Get-Help deze waarde gebruikt om de zoekresultaten te filteren die worden geretourneerd door Get-Help.

.FUNCTIONALITY

De trefwoorden die het beoogde gebruik van de functie beschrijven. De parameter Functionaliteit van Get-Help deze waarde wordt gebruikt om de zoekresultaten te filteren die worden geretourneerd door Get-Help.

.FORWARDHELPTARGETNAME

Wordt omgeleid naar het Help-onderwerp voor de opgegeven opdracht. U kunt gebruikers omleiden naar elk Help-onderwerp, inclusief Help-onderwerpen voor een functie, script, cmdlet of provider.

# .FORWARDHELPTARGETNAME <Command-Name>

.FORWARDHELPCATEGORY

Hiermee geeft u de Help-categorie van het item in .ForwardHelpTargetName. Geldige waarden zijnAlias, , Cmdlet, HelpFile, Function, Provider, General, FAQ, , Glossary, ScriptCommand, , ExternalScriptof FilterAll. Gebruik dit trefwoord om conflicten te voorkomen wanneer er opdrachten met dezelfde naam zijn.

# .FORWARDHELPCATEGORY <Category>

.REMOTEHELPRUNSPACE

Hiermee geeft u een sessie op die het Help-onderwerp bevat. Voer een variabele in die een PSSession-object bevat. Dit trefwoord wordt gebruikt door de cmdlet Export-PSSession om de Help-onderwerpen voor de geëxporteerde opdrachten te vinden.

# .REMOTEHELPRUNSPACE <PSSession-variable>

.EXTERNALHELP

Hiermee geeft u een XML-helpbestand voor het script of de functie.

# .EXTERNALHELP <XML Help File>

Het .ExternalHelp trefwoord is vereist wanneer een functie of script wordt gedocumenteerd in XML-bestanden. Zonder dit trefwoord kunt Get-Help u het XML-helpbestand voor de functie of het script niet vinden.

Het .ExternalHelp trefwoord heeft voorrang op andere help-trefwoorden op basis van opmerkingen. Als .ExternalHelp deze aanwezig is, Get-Help wordt geen hulp op basis van opmerkingen weergegeven, zelfs niet als er geen Help-onderwerp kan worden gevonden dat overeenkomt met de waarde van het .ExternalHelp trefwoord.

Als de functie door een module wordt geëxporteerd, stelt u de waarde van het .ExternalHelp trefwoord in op een bestandsnaam zonder pad. Get-Help zoekt naar de opgegeven bestandsnaam in een taalspecifieke submap van de modulemap. Er zijn geen vereisten voor de naam van het XML-helpbestand voor een functie, maar u kunt het beste de volgende indeling gebruiken:

<ScriptModule.psm1>-help.xml

Als de functie niet is opgenomen in een module, neemt u een pad op naar het HELP-bestand op basis van XML. Als de waarde een pad bevat en het pad UI-cultuurspecifieke submappen bevat, Get-Help doorzoekt u de submappen recursief naar een XML-bestand met de naam van het script of de functie in overeenstemming met de taalvalstandaarden die zijn ingesteld voor Windows, net zoals in een modulemap.

Zie Help voor cmdlets schrijven voor meer informatie over de Help-indeling op basis van XML-help voor cmdlets.

Automatisch gegenereerde inhoud

De naam, syntaxis, parameterlijst, parameterkenmerktabel, algemene parameters en opmerkingen worden automatisch gegenereerd door de Get-Help cmdlet.

Naam

De sectie Naam van een Help-onderwerp van een functie wordt overgenomen uit de functienaam in de syntaxis van de functie. De naam van een Help-onderwerp voor scripts wordt opgehaald uit de bestandsnaam van het script. Als u de naam of hoofdlettergebruik wilt wijzigen, wijzigt u de syntaxis van de functie of de bestandsnaam van het script.

Syntaxis

De sectie Syntaxis van het Help-onderwerp wordt gegenereerd op basis van de functie- of scriptsyntaxis. Als u details wilt toevoegen aan de syntaxis van het Help-onderwerp, zoals het .NET-type van een parameter, voegt u de details toe aan de syntaxis. Als u geen parametertype opgeeft, wordt het objecttype ingevoegd als de standaardwaarde.

Parameterlijst

De lijst met parameters in het Help-onderwerp wordt gegenereerd op basis van de syntaxis van de functie of het script en van de beschrijvingen die u toevoegt met behulp van het .Parameter trefwoord. De functieparameters worden weergegeven in de sectie Parameters van het Help-onderwerp in dezelfde volgorde als in de functie- of scriptsyntaxis. De spelling en het hoofdlettergebruik van parameternamen worden ook uit de syntaxis gehaald. Dit wordt niet beïnvloed door de parameternaam die is opgegeven door het .Parameter trefwoord.

Algemene parameters

De algemene parameters worden toegevoegd aan de syntaxis en parameterlijst van het Help-onderwerp, zelfs als ze geen effect hebben. Zie about_CommonParameters voor meer informatie over de algemene parameters.

Parameterkenmerktabel

Get-Help genereert de tabel met parameterkenmerken die worden weergegeven wanneer u de parameter Volledig of Parameter van Get-Help. De waarde van de kenmerken Vereist, Positie en Standaardwaarde wordt opgehaald uit de syntaxis van de functie of het script.

Standaardwaarden en een waarde voor Jokertekens accepteren worden niet weergegeven in de parameterkenmerktabel, zelfs niet wanneer ze zijn gedefinieerd in de functie of het script. Geef deze informatie op in de parameterbeschrijving om gebruikers te helpen.

Opmerkingen

De sectie Opmerkingen van het Help-onderwerp wordt automatisch gegenereerd op basis van de functie- of scriptnaam. U kunt de inhoud ervan niet wijzigen of beïnvloeden.

Voorbeelden

Help op basis van opmerkingen voor een functie

De volgende voorbeeldfunctie bevat hulp op basis van opmerkingen:

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

De resultaten zijn als volgt:

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

Parameterbeschrijvingen in functiesyntaxis

Dit voorbeeld is hetzelfde als de vorige, behalve dat de parameterbeschrijvingen worden ingevoegd in de syntaxis van de functie. Deze indeling is het handigst wanneer de beschrijvingen kort zijn.

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

Help op basis van opmerkingen voor een script

Het volgende voorbeeldscript bevat hulp op basis van opmerkingen. Let op de lege regels tussen de afsluiting #> en de Param instructie. In een script dat geen instructie heeft Param , moeten er ten minste twee lege regels zijn tussen de laatste opmerking in het Help-onderwerp en de eerste functiedeclaratie. Zonder deze lege regels koppelt Get-Help u het Help-onderwerp aan de functie, niet aan het script.

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

Met de volgende opdracht krijgt u de help van het script. Omdat het script zich niet in een map bevindt die wordt vermeld in de $env:Path omgevingsvariabele, moet de Get-Help opdracht die de scripthulp ontvangt, het scriptpad opgeven.

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

Omleiden naar een XML-bestand

U kunt helponderwerpen op basis van XML schrijven voor functies en scripts. Hoewel hulp op basis van opmerkingen gemakkelijker te implementeren is, is XML-hulp vereist voor Help-informatie die kan worden bijgewerkt en om Help-onderwerpen in meerdere talen te bieden.

In het volgende voorbeeld ziet u de eerste paar regels van het script Update-Month.ps1. Het script gebruikt het .ExternalHelp trefwoord om het pad naar een OP XML gebaseerd Help-onderwerp voor het script op te geven.

De waarde van het .ExternalHelp trefwoord wordt weergegeven op dezelfde regel als het trefwoord. Elke andere plaatsing is ineffectief.

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

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

In de volgende voorbeelden ziet u drie geldige plaatsingen van het .ExternalHelp trefwoord in een functie.

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
}

Omleiden naar een ander Help-onderwerp

De volgende code is een fragment van het begin van de ingebouwde Help-functie in PowerShell, waarin één scherm met Help-tekst tegelijk wordt weergegeven. Omdat het Help-onderwerp voor de Get-Help cmdlet de Help-functie beschrijft, gebruikt de Help-functie de .ForwardHelpTargetName en .ForwardHelpCategory trefwoorden om de gebruiker om te leiden naar het Help-onderwerp voor cmdlets Get-Help .

function help
{

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

De volgende opdracht maakt gebruik van deze functie:

Get-Help -Name help

NAME

Get-Help

SYNOPSIS

Displays information about PowerShell cmdlets and concepts.
...

Zie ook

• about_Functions
• about_Functions_Advanced_Parameters
• about_Scripts
• Help-onderwerpen op basis van opmerkingen schrijven