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
functiontrefwoord. Er mag niet meer dan één lege regel zijn tussen de laatste regel van de functiehulp en hetfunctiontrefwoord.
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
Feedback
Binnenkort beschikbaar: In de loop van 2024 zullen we GitHub-problemen geleidelijk uitfaseren als het feedbackmechanisme voor inhoud en deze vervangen door een nieuw feedbacksysteem. Zie voor meer informatie: https://aka.ms/ContentUserFeedback.
Feedback verzenden en weergeven voor