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-Help
ré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 afunction
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 .psm1
a 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.
.LINK
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-Help
haszná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-Help
keresé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-Help
keresé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-Help
keresé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
: , HelpFile
Cmdlet
, Function
, Provider
, General
, FAQ
, ScriptCommand
Glossary
, 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-Help
Létrehozza a paraméterattribútumok tábláját, amely a teljes vagy paraméter paraméter paraméter Get-Help
haszná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
Visszajelzés
https://aka.ms/ContentUserFeedback.
Hamarosan elérhető: 2024-ben fokozatosan kivezetjük a GitHub-problémákat a tartalom visszajelzési mechanizmusaként, és lecseréljük egy új visszajelzési rendszerre. További információ:Visszajelzés küldése és megtekintése a következőhöz: