about_Comment_Based_Help

  • Artikel
  • 15 minuten om te lezen

Korte beschrijving

Beschrijft hoe u helponderwerpen op basis van opmerkingen schrijft voor functies en scripts.

Lange beschrijving

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

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

U kunt ook helpbestanden op basis van XML schrijven voor functies en scripts. Als u de cmdlet wilt inschakelen om het helpbestand op basis van XML voor een functie of script te Get-Help vinden, gebruikt u het .ExternalHelp trefwoord . Zonder dit trefwoord Get-Help kunt u geen helponderwerpen op basis van XML 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 voorfuncties en scripts.

De cmdlets Update-Help en Save-Help werken alleen voor XML-bestanden. Bijwerkbare Help biedt geen ondersteuning voor helponderwerpen op basis van opmerkingen.

Syntaxis voor help op basis van opmerkingen

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

# .<help keyword>
# <help content>

of

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

Help 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 symbolen # en gebruiken om een <# #> opmerkingsblok 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 Help-onderwerp op basis van opmerkingen een opmerking volgt die geen deel uitmaakt van het Help-onderwerp, moet er ten minste één lege regel zijn tussen de laatste niet-help-opmerkingsregel en het begin van de help op basis van opmerkingen.

Trefwoorden definiëren elke sectie van help 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 sleutelwoordnamen zijn niet sleutelwoordgevoelig.

Het trefwoord .Description wordt bijvoorbeeld voorafgegaan door 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 , kunnen vaak in hetzelfde .EXAMPLE opmerkingenblok worden weergegeven. De Help-inhoud voor elk trefwoord begint op de regel na het trefwoord en kan meerdere regels overspannen.

Syntaxis voor help op basis van opmerkingen in functies

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

  • Aan het begin van de functie-body.
  • Aan het einde van de functie-body.
  • Vóór het function trefwoord . Er mag niet meer dan één lege regel zijn tussen de laatste regel van de Help van de functie en het function trefwoord .

Bijvoorbeeld:

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

  # function logic
}

of

function Get-Function
{
   # function logic

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

of

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

Syntaxis voor help op basis van opmerkingen in scripts

Help 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. Hulp bij scripts kan in het script alleen worden voorafgegaan door opmerkingen en lege regels.

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

  • Aan het einde van het scriptbestand. Als het script echter is ondertekend, kunt u help op basis van opmerkingen aan het begin van het scriptbestand plaatsen. Het einde van het script wordt in beslag genomen door het handtekeningblok.

Bijvoorbeeld:

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


function Get-Function { }

of

function Get-Function { }

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

Syntaxis voor help op basis van opmerkingen in scriptmodules

In een scriptmodule .psm1 gebruikt help op basis van opmerkingen de syntaxis voor functies, niet de syntaxis voor scripts. U kunt de scriptsyntaxis niet gebruiken om hulp te bieden voor alle functies die zijn gedefinieerd in een scriptmodule.

Als u bijvoorbeeld het trefwoord gebruikt om de helpbestanden op basis van XML voor de functies in een scriptmodule te identificeren, moet u een opmerking toevoegen .ExternalHelp .ExternalHelp 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 vermeld in de volgorde waarin ze doorgaans worden weergegeven in een Help-onderwerp, samen met hun beoogde gebruik. Deze trefwoorden kunnen in elke volgorde worden weergegeven in de help op basis van opmerkingen en ze zijn niet case-gevoelig.

.SYNOPSIS

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

.DESCRIPTION

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

.PARAMETER

De beschrijving van een parameter. Voeg een .PARAMETER trefwoord toe voor elke parameter in de functie- of scriptsyntaxis.

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

.PARAMETER  <Parameter-Name>

De sleutelwoorden Parameter kunnen in elke volgorde worden weergegeven in het opmerkingenblok, maar de functie- of scriptsyntaxis 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 direct vóór de naam van de parametervariabele te plaatsen. Dit werkt alleen als u ook een opmerkingsblok met ten minste één trefwoord hebt.

Als u zowel een syntaxis-opmerking als een trefwoord gebruikt, wordt de beschrijving die is gekoppeld aan het trefwoord gebruikt en wordt de .PARAMETER .PARAMETER syntaxis-opmerking 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 doorspijpt naar de functie of het script. U kunt ook een beschrijving van de invoerobjecten opnemen.

.OUTPUTS

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

.NOTES

Aanvullende informatie over de functie of het script.

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

Herhaal het .LINK trefwoord voor elk gerelateerd onderwerp.

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

De .Link trefwoordinhoud kan ook een Uniform Resource Identifier (URI) voor een online versie van hetzelfde Help-onderwerp bevatten. De onlineversie wordt geopend wanneer u de parameter Online van Get-Help gebruikt. 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 van gebruikt deze waarde om de zoekresultaten te filteren die worden geretourneerd door Get-Help Get-Help .

.ROLE

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

.FUNCTIONALITY

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

.FORWARDHELPTARGETNAME

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

# .FORWARDHELPTARGETNAME <Command-Name>

.FORWARDHELPCATEGORY

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

# .FORWARDHELPCATEGORY <Category>

.REMOTEHELPRUNSPACE

Hiermee geeft u een sessie 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 helpbestand op basis van XML op voor het script of de functie.

# .EXTERNALHELP <XML Help File>

Het .ExternalHelp trefwoord is vereist wanneer een functie of script wordt beschreven in XML-bestanden. Zonder dit trefwoord Get-Help kan het helpbestand op basis van XML voor de functie of het script niet vinden.

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

Als de functie wordt geëxporteerd door een module, stelt u de waarde van het trefwoord in .ExternalHelp 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 helpbestand op basis van XML voor een functie, maar een best practice is om de volgende indeling te gebruiken:

<ScriptModule.psm1>-help.xml

Als de functie niet is opgenomen in een module, moet u een pad naar het helpbestand op basis van XML opnemen. Als de waarde een pad bevat en het pad UI-cultuurspecifieke subdirectory's bevat, zoekt recursief in de subdirectory's naar een XML-bestand met de naam van het script of de functie in overeenstemming met de taalterugvalstandaarden die zijn vastgesteld voor Windows, net als Get-Help in een modulemap.

Zie How to Write Cmdlet Help(Help voor cmdlet schrijven) voor meer informatie over de helpbestandsindeling van de cmdlet Help op basis van XML.

Automatisch gegenereerde inhoud

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

Name

De sectie Naam van een Help-onderwerp voor een functie is afkomstig uit de functienaam in de functiesyntaxis. De naam van een Help-onderwerp voor een script is afkomstig uit de bestandsnaam van het script. Als u de naam of de hoofdletter wilt wijzigen, wijzigt u de functiesyntaxis of de bestandsnaam van het script.

Syntax

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.

Lijst met parameters

De lijst met parameters in het Help-onderwerp wordt gegenereerd op basis van de functie- of scriptsyntaxis en op basis 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 hoofdletters van parameternamen zijn ook afkomstig uit de syntaxis. 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 de parameterlijst van het Help-onderwerp, zelfs als ze geen effect hebben. Zie voor meer informatie over de algemene parameters about_CommonParameters.

Parameterkenmerktabel

Get-Help genereert de tabel met parameterkenmerken die wordt weergegeven wanneer u de parameter Full of Parameter van Get-Help gebruikt. De waarde van de kenmerken Vereist, Positie en Standaardwaarde wordt overgenomen uit de functie- of scriptsyntaxis.

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 beschrijving van de parameter 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 help 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 het vorige voorbeeld, behalve dat de parameterbeschrijvingen worden ingevoegd in de functiesyntaxis. 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 help op basis van opmerkingen. Let op de lege regels tussen de afsluitende #> en de Param instructie . In een script dat geen instructie heeft, moeten er ten minste twee lege regels zijn tussen de laatste opmerking in het Help-onderwerp en de eerste Param functiedeclaratie. Zonder deze lege regels Get-Help koppelt 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 wordt de help voor het script op te vragen. Omdat het script zich niet in een map die wordt vermeld in de omgevingsvariabele, moet de opdracht die de $env:Path Get-Help scripthulp krijgt, het scriptpad opgeven.

Get-Help -Path .\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 help op basis van opmerkingen eenvoudiger te implementeren is, is er op XML gebaseerde help vereist voor Help die kan worden bijwerkt en helponderwerpen in meerdere talen te bieden.

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

Houd er rekening mee dat de waarde .ExternalHelp van het 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 worden drie geldige plaatsingen van het .ExternalHelp trefwoord in een functie weergegeven.

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 in het Help-onderwerp voor de cmdlet de Help-functie wordt beschreven, gebruikt de Help-functie de trefwoorden en om de gebruiker om te leiden naar het Get-Help .ForwardHelpTargetName Help-onderwerp voor de .ForwardHelpCategory Get-Help cmdlet.

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 voor cmdlet schrijven