about_Comment_Based_Help

Rövid leírás

Leírja, hogyan írhat megjegyzésalapú súgótémaköröket függvényekhez és szkriptekhez.

Hosszú leírás

Speciális súgókommentár-kulcsszavak használatával megjegyzésalapú súgótémaköröket írhat függvényekhez és szkriptekhez.

A Get-Help parancsmag a megjegyzésalapú súgót ugyanabban a formátumban jeleníti meg, amelyben az XML-fájlokból létrehozott parancsmag súgótémaköröket jeleníti meg. A felhasználók a megjegyzéseken alapuló súgó tartalmának megjelenítéséhez használhatják a Get-Helprészletes, a teljes, a példák és az online paramétereket.

Xml-alapú súgófájlokat is írhat függvényekhez és szkriptekhez. Ha engedélyezni szeretné, hogy a Get-Help parancsmag megkeresse egy függvény vagy szkript XML-alapú súgófájlját, használja a kulcsszót .ExternalHelp . E kulcsszó Get-Help nélkül nem található xml-alapú súgótémakörök függvényekhez vagy szkriptekhez.

Ez a témakör azt ismerteti, hogyan írhat súgótémaköröket függvényekhez és szkriptekhez. A függvényekkel és szkriptekkel kapcsolatos súgótémakörök megjelenítéséről a Get-Help című témakörben talál további információt.

Az Update-Help és a Save-Help parancsmagok csak XML-fájlokon működnek. Az frissíthető súgó nem támogatja a megjegyzésalapú súgótémaköröket.

A megjegyzésalapú súgó szintaxisa

A megjegyzésalapú súgó szintaxisa a következő:

# .<help keyword>
# <help content>

vagy

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

A megjegyzésalapú súgó megjegyzéssorozatként van megírva. Minden megjegyzéssor elé beírhat megjegyzésszimbólumot # , vagy a <##> szimbólumokkal megjegyzésblokkot hozhat létre. A megjegyzésblokk összes sorát megjegyzésként értelmezi a rendszer.

A megjegyzésalapú súgótémakör összes sorának egybefüggőnek kell lennie. Ha egy megjegyzésalapú súgótémakör olyan megjegyzést követ, amely nem része a súgótémakörnek, legalább egy üres sornak kell lennie az utolsó nem súgó megjegyzéssor és a megjegyzésalapú súgó kezdete között.

A kulcsszavak határozzák meg a megjegyzésalapú súgó egyes szakaszait. Minden megjegyzésalapú súgó kulcsszót pont előz meg .. A kulcsszavak bármilyen sorrendben megjelenhetnek. A kulcsszónevek nem megkülönböztetik a kis- és nagybetűket.

A kulcsszó például .Description megelőzi egy függvény vagy szkript leírását.

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

A megjegyzésblokknak legalább egy kulcsszót tartalmaznia kell. Egyes kulcsszavak, például .EXAMPLE, sokszor megjelenhetnek ugyanabban a megjegyzésblokkban. Az egyes kulcsszavak súgótartalma a kulcsszó utáni sorban kezdődik, és több sorra is kiterjedhet.

A függvények megjegyzésalapú súgójának szintaxisa

Egy függvény megjegyzésalapú súgója három helyen jelenhet meg:

  • A függvény törzsének elején.
  • A függvény törzsének végén.
  • A function kulcsszó előtt. A függvény súgójának utolsó sora és a function kulcsszó között nem lehet több üres sor.

Példa:

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

  # function logic
}

vagy

function Get-Function
{
   # function logic

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

vagy

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

Megjegyzéseken alapuló súgó szintaxisa szkriptekben

A szkript megjegyzésalapú súgója a szkript alábbi két helyének egyikén jelenhet meg.

  • A szkriptfájl elején. A szkript súgóját csak megjegyzések és üres sorok előzhetik meg a szkriptben.

    Ha a szkript törzsének első eleme (a súgó után) egy függvénydeklaráció, a szkript súgójának vége és a függvénydeklaráció között legalább két üres sornak kell lennie. Ellenkező esetben a súgót a függvény súgójaként értelmezi a rendszer, nem pedig a szkript súgójaként.

  • A szkriptfájl végén. Ha azonban aláírta a szkriptet, a szkriptfájl elején helyezzen el megjegyzésalapú súgót. A szkript végét az aláírási blokk foglalja el.

Példa:

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


function Get-Function { }

vagy

function Get-Function { }

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

Megjegyzésalapú súgó szintaxisa szkriptmodulokban

Egy szkriptmodulban .psm1a megjegyzésalapú súgó a függvények szintaxisát használja, nem pedig a szkriptek szintaxisát. A szkriptszintaxis nem használható a szkriptmodulban definiált összes függvény súgójának megadásához.

Ha például a kulcsszót használja a .ExternalHelp függvények XML-alapú súgófájljainak azonosítására egy szkriptmodulban, minden függvényhez megjegyzést .ExternalHelp kell fűznie.

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

Megjegyzésalapú súgó kulcsszavak

Az alábbiak érvényes megjegyzésalapú súgószavak. A lista a súgótémakörben való megjelenésük sorrendjében, a tervezett használatukkal együtt jelenik meg. Ezek a kulcsszavak bármilyen sorrendben megjelenhetnek a megjegyzésalapú súgóban, és nem érzékenyek a kis- és nagybetűkre.

.SYNOPSIS

A függvény vagy szkript rövid leírása. Ez a kulcsszó csak egyszer használható az egyes témakörökben.

.DESCRIPTION

A függvény vagy szkript részletes leírása. Ez a kulcsszó csak egyszer használható az egyes témakörökben.

.PARAMETER

Egy paraméter leírása. Adjon hozzá egy kulcsszót .PARAMETER a függvény vagy a szkript szintaxisának minden paraméteréhez.

Írja be a paraméter nevét a kulcsszóval .PARAMETER megegyező sorban. Írja be a paraméter leírását a kulcsszót követő sorokba .PARAMETER . A Windows PowerShell a paraméterleírás részeként értelmezi a .PARAMETER sor és a következő kulcsszó vagy a megjegyzésblokk vége közötti összes szöveget. A leírás bekezdéstöréseket is tartalmazhat.

.PARAMETER  <Parameter-Name>

A paraméterszavak bármilyen sorrendben megjelenhetnek a megjegyzésblokkban, de a függvény vagy a szkript szintaxisa határozza meg, hogy a paraméterek (és azok leírásai) milyen sorrendben jelenjenek meg a súgótémakörben. A sorrend módosításához módosítsa a szintaxist.

A paraméter leírását úgy is megadhatja, hogy közvetlenül a paraméterváltozó neve előtt megjegyzést helyez el a függvény vagy a szkript szintaxisában. Ahhoz, hogy ez működjön, rendelkeznie kell legalább egy kulcsszóval rendelkező megjegyzésblokkgal is.

Ha szintaxiskommentárt és kulcsszót .PARAMETER is használ, a rendszer a kulcsszóhoz .PARAMETER társított leírást használja, a szintaxis megjegyzését pedig figyelmen kívül hagyja.

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

.EXAMPLE

A függvényt vagy szkriptet használó mintaparancs, amelyet opcionálisan mintakimenet és leírás követ. Ismételje meg ezt a kulcsszót minden példában.

.INPUTS

A függvényhez vagy szkripthez csövezhető .NET típusú objektumok. A bemeneti objektumok leírását is megadhatja.

.OUTPUTS

A parancsmag által visszaadott objektumok .NET-típusa. A visszaadott objektumok leírását is megadhatja.

.NOTES

További információ a függvényről vagy a szkriptről.

Egy kapcsolódó témakör neve. Az érték a ".LINK" kulcsszó alatti sorban jelenik meg, és egy megjegyzésszimbólumnak # kell megelőznie, vagy szerepelnie kell a megjegyzésblokkban.

Ismételje meg az .LINK egyes kapcsolódó témakörök kulcsszóját.

Ez a tartalom a súgótémakör Kapcsolódó hivatkozások szakaszában jelenik meg.

A .Link kulcsszótartalmak tartalmazhatnak egységes erőforrás-azonosítót (URI) is ugyanannak a súgótémakörnek egy online verziójához. Az online verzió akkor nyílik meg, amikor az Online paramétert Get-Helphasználja. Az URI-nak "http" vagy "https" betűvel kell kezdődnie.

.COMPONENT

Annak a technológiának vagy funkciónak a neve, amelyet a függvény vagy a szkript használ, vagy amelyhez kapcsolódik. Az összetevő paramétere Get-Help ezt az értéket használja a visszaadott Get-Helpkeresési eredmények szűréséhez.

.ROLE

A súgótémakör felhasználói szerepkörének neve. A szerepkör paramétere Get-Help ezt az értéket használja a visszaadott Get-Helpkeresési eredmények szűréséhez.

.FUNCTIONALITY

A függvény rendeltetését leíró kulcsszavak. A funkcióparaméter Get-Help ezt az értéket használja a visszaadott Get-Helpkeresési eredmények szűréséhez.

.FORWARDHELPTARGETNAME

Átirányítja a megadott parancs súgótémakörére. A felhasználókat bármilyen súgótémakörbe átirányíthatja, beleértve a függvények, szkriptek, parancsmagok vagy szolgáltatók súgótémakörökét is.

# .FORWARDHELPTARGETNAME <Command-Name>

.FORWARDHELPCATEGORY

Megadja az elem súgókategóriáját a következőben .ForwardHelpTargetName: . Az érvényes értékek a következőkAlias: , HelpFileCmdlet, Function, Provider, General, FAQ, ScriptCommandGlossary, ExternalScript, , Filter, vagy All. Ezzel a kulcsszóval elkerülheti az ütközéseket, ha azonos nevű parancsok vannak.

# .FORWARDHELPCATEGORY <Category>

.REMOTEHELPRUNSPACE

A súgótémakört tartalmazó munkamenetet adja meg. Adjon meg egy pssession objektumot tartalmazó változót. Ezt a kulcsszót az Export-PSSession parancsmag használja az exportált parancsok súgótémaköreinek megkereséséhez.

# .REMOTEHELPRUNSPACE <PSSession-variable>

.EXTERNALHELP

Xml-alapú súgófájlt ad meg a szkripthez vagy függvényhez.

# .EXTERNALHELP <XML Help File>

A .ExternalHelp kulcsszóra akkor van szükség, ha egy függvény vagy szkript XML-fájlokban van dokumentálva. E kulcsszó Get-Help nélkül nem található a függvény vagy szkript XML-alapú súgófájlja.

A .ExternalHelp kulcsszó elsőbbséget élvez a többi megjegyzésalapú súgószavaval szemben. Ha .ExternalHelp jelen van, Get-Help nem jelenít meg megjegyzésalapú súgót, még akkor sem, ha nem talál olyan súgótémakört, amely megfelel a .ExternalHelp kulcsszó értékének.

Ha a függvényt egy modul exportálja, állítsa a .ExternalHelp kulcsszó értékét egy elérési út nélküli fájlnévre. Get-Help A megadott fájlnevet keresi a modulkönyvtár nyelvspecifikus alkönyvtárában. Egy függvény XML-alapú súgófájljának nevére nincsenek követelmények, de az ajánlott eljárás az alábbi formátum használata:

<ScriptModule.psm1>-help.xml

Ha a függvény nem szerepel egy modulban, adja meg az XML-alapú súgófájl elérési útját. Ha az érték tartalmaz egy elérési utat, és az elérési út UI-kultúraspecifikus alkönyvtárakat tartalmaz, Get-Help rekurzív módon keres az alkönyvtárakban egy OLYAN XML-fájlban, amelynek a neve a szkript vagy függvény neve a Windowshoz létrehozott nyelvi tartalék szabványoknak megfelelően történik, ugyanúgy, mint egy modulkönyvtárban.

A parancsmag xml-alapú súgófájlformátumával kapcsolatos további információkért tekintse meg a Parancsmag írása súgóját.

Automatikusan létrehozott tartalom

A parancsmag automatikusan létrehozza a nevet, a szintaxist, a paraméterlistát, a paraméterattribútumtáblát, a gyakori paramétereket és a Get-Help megjegyzéseket.

Név

A függvények súgótémakörének Név szakasza a függvény szintaxisában szereplő függvény nevéből származik. A szkript súgótémakörének neve a szkriptfájl nevéből származik. A név vagy a nagybetűsítés módosításához módosítsa a függvény szintaxisát vagy a szkriptfájl nevét.

Syntax

A súgótémakör Szintaxis szakasza a függvény vagy a szkript szintaxisából jön létre. Ha részletes adatokat szeretne hozzáadni a súgótémakör szintaxisához, például egy paraméter .NET-típusához, adja hozzá a részletet a szintaxishoz. Ha nem ad meg paramétertípust, a rendszer az objektumtípust szúrja be alapértelmezett értékként.

Paraméterlista

A súgótémakör paraméterlistája a függvény vagy a szkript szintaxisából, valamint a kulcsszóval .Parameter hozzáadott leírásokból jön létre. A függvényparaméterek a súgótémakör Paraméterek szakaszában ugyanabban a sorrendben jelennek meg, mint a függvény vagy a szkript szintaxisában. A paraméternevek helyesírása és nagybetűsítése szintén a szintaxisból származik. A kulcsszó által .Parameter megadott paraméternév nem befolyásolja.

Gyakori paraméterek

A gyakori paraméterek akkor is hozzáadódnak a súgótémakör szintaxisához és paraméterlistájához, ha nincs hatásuk. A gyakori paraméterekkel kapcsolatos további információkért lásd a about_CommonParameters.

Paraméterattribútum-tábla

Get-HelpLétrehozza a paraméterattribútumok tábláját, amely a teljes vagy paraméter paraméter paraméter Get-Helphasználatakor jelenik meg. A Szükséges, a Pozíció és az Alapértelmezett érték attribútum értéke a függvény vagy a szkript szintaxisából származik.

Az alapértelmezett értékek és a Helyettesítő karakterek elfogadása érték még akkor sem jelennek meg a paraméterattribútumtáblában, ha a függvényben vagy a szkriptben vannak definiálva. Ha segíteni szeretne a felhasználóknak, adja meg ezeket az információkat a paraméter leírásában.

Megjegyzések

A súgótémakör Megjegyzések szakasza automatikusan létrejön a függvény vagy a szkript nevéből. Tartalmát nem módosíthatja vagy nem befolyásolhatja.

Példák

Függvény megjegyzésalapú súgója

A következő mintafüggvény megjegyzésalapú súgót tartalmaz:

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

Az eredmények a következők:

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

Paraméterleírások a függvényszintaxisban

Ez a példa megegyezik az előző példával, azzal a kivételsel, hogy a paraméterleírások a függvény szintaxisában vannak beszúrva. Ez a formátum akkor hasznos, ha a leírások rövidek.

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

Szkript megjegyzésalapú súgója

Az alábbi példaszkript megjegyzésalapú súgót tartalmaz. Figyelje meg a záró #> és az Param utasítás közötti üres sorokat. Olyan szkriptben, amely nem rendelkezik utasítással Param , legalább két üres sornak kell lennie a súgótémakör utolsó megjegyzése és az első függvénydeklaráció között. Az üres sorok Get-Help nélkül a súgótémakört a függvényhez, nem a szkripthez társítja.

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

Az alábbi parancs a szkript súgóját kapja meg. Mivel a szkript nem szerepel a $env:Path környezeti változóban felsorolt könyvtárban, a Get-Help szkript súgóját lekérő parancsnak meg kell adnia a szkript elérési útját.

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

Átirányítás XML-fájlba

Xml-alapú súgótémaköröket írhat függvényekhez és szkriptekhez. Bár a megjegyzésalapú súgó egyszerűbben implementálható, xml-alapú segítségre van szükség az frissíthető súgóhoz, és több nyelven is segítséget nyújthat.

Az alábbi példa az Update-Month.ps1 szkript első néhány sorát mutatja be. A szkript a .ExternalHelp kulcsszó használatával adja meg a szkript XML-alapú súgótémakörének elérési útját.

Vegye figyelembe, hogy a .ExternalHelp kulcsszó értéke ugyanazon a sorban jelenik meg, mint a kulcsszó. Minden más elhelyezés hatástalan.

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

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

Az alábbi példák a kulcsszó három érvényes elhelyezését .ExternalHelp mutatják be egy függvényben.

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
}

Átirányítás másik súgótémakörre

Az alábbi kód egy részlet a PowerShell beépített súgófüggvényének elejéről, amely egyszerre egy súgószöveg-képernyőt jelenít meg. Mivel a parancsmag súgótémaköre leírja a Get-Help súgófüggvényt, a súgófüggvény a kulcsszavak és .ForwardHelpCategory a .ForwardHelpTargetName kulcsszavak használatával átirányítja a felhasználót a Get-Help parancsmag súgótémakörére.

function help
{

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

A következő parancs ezt a funkciót használja:

Get-Help -Name help
NAME

Get-Help

SYNOPSIS

Displays information about PowerShell cmdlets and concepts.
...

Lásd még