about_Comment_Based_Help

Artikel
04/13/2023

Deskripsi singkat

Menjelaskan cara menulis topik bantuan berbasis komentar untuk fungsi dan skrip.

Deskripsi panjang

Anda dapat menulis topik bantuan berbasis komentar untuk fungsi dan skrip dengan menggunakan kata kunci komentar bantuan khusus.

Cmdlet Get-Help menampilkan bantuan berbasis komentar dalam format yang sama di mana cmdlet menampilkan topik bantuan cmdlet yang dihasilkan dari file XML. Pengguna dapat menggunakan semua parameter Get-Help, seperti Terperinci, Lengkap, Contoh, dan Online, untuk menampilkan konten bantuan berbasis komentar.

Anda juga dapat menulis file bantuan berbasis XML untuk fungsi dan skrip. Untuk mengaktifkan Get-Help cmdlet untuk menemukan file bantuan berbasis XML untuk fungsi atau skrip, gunakan .ExternalHelp kata kunci. Tanpa kata kunci ini, Get-Help tidak dapat menemukan topik bantuan berbasis XML untuk fungsi atau skrip.

Topik ini menjelaskan cara menulis topik bantuan untuk fungsi dan skrip. Untuk informasi tentang cara menampilkan topik bantuan untuk fungsi dan skrip, lihat Get-Help.

Cmdlet Update-Help dan Save-Help hanya berfungsi pada file XML. Bantuan yang Dapat Diperbarui tidak mendukung topik bantuan berbasis komentar.

Sintaks untuk bantuan berbasis komentar

Sintaks untuk bantuan berbasis komentar adalah sebagai berikut:

# .<help keyword>
# <help content>

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

Bantuan berbasis komentar ditulis sebagai serangkaian komentar. Anda dapat mengetik simbol # komentar sebelum setiap baris komentar, atau Anda dapat menggunakan <# simbol dan #> untuk membuat blok komentar. Semua baris dalam blok komentar ditafsirkan sebagai komentar.

Semua baris dalam topik bantuan berbasis komentar harus bersebelahan. Jika topik bantuan berbasis komentar mengikuti komentar yang bukan bagian dari topik bantuan, setidaknya harus ada satu baris kosong antara baris komentar non-bantuan terakhir dan awal bantuan berbasis komentar.

Kata kunci menentukan setiap bagian bantuan berbasis komentar. Setiap kata kunci bantuan berbasis komentar didahului oleh titik .. Kata kunci dapat muncul dalam urutan apa pun. Nama kata kunci tidak peka huruf besar/kecil.

Misalnya, .Description kata kunci mendahului deskripsi fungsi atau skrip.

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

Blok komentar harus berisi setidaknya satu kata kunci. Beberapa kata kunci, seperti .EXAMPLE, dapat muncul berkali-kali di blok komentar yang sama. Konten bantuan untuk setiap kata kunci dimulai pada baris setelah kata kunci dan dapat menjangkau beberapa baris.

Sintaks untuk bantuan berbasis komentar dalam fungsi

Bantuan berbasis komentar untuk fungsi dapat muncul di salah satu dari tiga lokasi:

Di awal isi fungsi.
Di akhir isi fungsi.
Sebelum kata function kunci. Tidak boleh ada lebih dari satu baris kosong antara baris terakhir bantuan fungsi dan function kata kunci.

Contohnya:

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

  # function logic
}

function Get-Function
{
   # function logic

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

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

Sintaks untuk bantuan berbasis komentar dalam skrip

Bantuan berbasis komentar untuk skrip dapat muncul di salah satu dari dua lokasi berikut dalam skrip.

Di awal file skrip. Bantuan skrip dapat didahului dalam skrip hanya dengan komentar dan baris kosong.

Jika item pertama dalam isi skrip (setelah bantuan) adalah deklarasi fungsi, setidaknya harus ada dua baris kosong antara akhir bantuan skrip dan deklarasi fungsi. Jika tidak, bantuan ditafsirkan sebagai bantuan untuk fungsi, bukan bantuan untuk skrip.
Di akhir file skrip. Namun, jika skrip ditandatangani, tempatkan bantuan berbasis Komentar di awal file skrip. Akhir skrip ditempati oleh blok tanda tangan.

Contohnya:

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


function Get-Function { }

function Get-Function { }

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

Sintaks untuk bantuan berbasis komentar dalam modul skrip

Dalam modul .psm1skrip, bantuan berbasis komentar menggunakan sintaks untuk fungsi, bukan sintaks untuk skrip. Anda tidak dapat menggunakan sintaks skrip untuk memberikan bantuan untuk semua fungsi yang ditentukan dalam modul skrip.

Misalnya, jika Anda menggunakan .ExternalHelp kata kunci untuk mengidentifikasi file bantuan berbasis XML untuk fungsi dalam modul skrip, Anda harus menambahkan .ExternalHelp komentar ke setiap fungsi.

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

Kata kunci bantuan berbasis komentar

Berikut ini adalah kata kunci bantuan berbasis komentar yang valid. Mereka tercantum dalam urutan di mana mereka biasanya muncul dalam topik bantuan bersama dengan penggunaan yang dimaksudkan. Kata kunci ini dapat muncul dalam urutan apa pun dalam bantuan berbasis komentar, dan kata kunci tersebut tidak peka huruf besar/kecil.

.SYNOPSIS

Deskripsi singkat tentang fungsi atau skrip. Kata kunci ini hanya dapat digunakan sekali di setiap topik.

.DESCRIPTION

Deskripsi terperinci tentang fungsi atau skrip. Kata kunci ini hanya dapat digunakan sekali di setiap topik.

.PARAMETER

Deskripsi parameter. .PARAMETER Tambahkan kata kunci untuk setiap parameter dalam fungsi atau sintaks skrip.

Ketik nama parameter pada baris yang sama dengan .PARAMETER kata kunci. Ketik deskripsi parameter pada baris yang mengikuti .PARAMETER kata kunci. Windows PowerShell menginterpretasikan semua teks antara .PARAMETER baris dan kata kunci berikutnya atau akhir blok komentar sebagai bagian dari deskripsi parameter. Deskripsi dapat menyertakan hentian paragraf.

.PARAMETER  <Parameter-Name>

Kata kunci Parameter dapat muncul dalam urutan apa pun di blok komentar, tetapi sintaks fungsi atau skrip menentukan urutan parameter (dan deskripsinya) muncul dalam topik bantuan. Untuk mengubah urutan, ubah sintaks.

Anda juga dapat menentukan deskripsi parameter dengan menempatkan komentar dalam fungsi atau sintaks skrip segera sebelum nama variabel parameter. Agar ini berfungsi, Anda juga harus memiliki blok komentar dengan setidaknya satu kata kunci.

Jika Anda menggunakan komentar sintaks dan .PARAMETER kata kunci, deskripsi yang terkait dengan .PARAMETER kata kunci digunakan, dan komentar sintaks diabaikan.

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

.EXAMPLE

Contoh perintah yang menggunakan fungsi atau skrip, secara opsional diikuti oleh sampel output dan deskripsi. Ulangi kata kunci ini untuk setiap contoh.

.INPUTS

Jenis objek .NET yang dapat disalurkan ke fungsi atau skrip. Anda juga dapat menyertakan deskripsi objek input.

.OUTPUTS

Jenis .NET objek yang dikembalikan cmdlet. Anda juga dapat menyertakan deskripsi objek yang dikembalikan.

.NOTES

Informasi tambahan tentang fungsi atau skrip.

.LINK

Nama topik terkait. Nilai muncul pada baris di bawah kata kunci ".LINK" dan harus didahului oleh simbol # komentar atau disertakan dalam blok komentar.

.LINK Ulangi kata kunci untuk setiap topik terkait.

Konten ini muncul di bagian Tautan Terkait dari topik bantuan.

Konten .Link kata kunci juga dapat menyertakan Pengidentifikasi Sumber Daya Seragam (URI) ke versi online dari topik bantuan yang sama. Versi online terbuka saat Anda menggunakan parameter Online .Get-Help URI harus dimulai dengan "http" atau "https".

.COMPONENT

Nama teknologi atau fitur yang digunakan fungsi atau skrip, atau yang terkait dengannya. Parameter Get-Help Komponen menggunakan nilai ini untuk memfilter hasil pencarian yang dikembalikan oleh Get-Help.

.ROLE

Nama peran pengguna untuk topik bantuan. Parameter Get-Help Peran menggunakan nilai ini untuk memfilter hasil pencarian yang dikembalikan oleh Get-Help.

.FUNCTIONALITY

Kata kunci yang menjelaskan penggunaan fungsi yang dimaksudkan. Parameter Get-Help Fungsionalitas menggunakan nilai ini untuk memfilter hasil pencarian yang dikembalikan oleh Get-Help.

.FORWARDHELPTARGETNAME

Mengalihkan ke topik bantuan untuk perintah yang ditentukan. Anda dapat mengalihkan pengguna ke topik bantuan apa pun, termasuk topik bantuan untuk fungsi, skrip, cmdlet, atau penyedia.

# .FORWARDHELPTARGETNAME <Command-Name>

.FORWARDHELPCATEGORY

Menentukan kategori bantuan item di .ForwardHelpTargetName. Nilai yang valid adalah Alias, , HelpFileCmdlet, Function, Provider, General, FAQ, Glossary, ScriptCommand, ExternalScript, Filter, atau All. Gunakan kata kunci ini untuk menghindari konflik ketika ada perintah dengan nama yang sama.

# .FORWARDHELPCATEGORY <Category>

.REMOTEHELPRUNSPACE

Menentukan sesi yang berisi topik bantuan. Masukkan variabel yang berisi objek PSSession . Kata kunci ini digunakan oleh cmdlet Ekspor-PSSession untuk menemukan topik bantuan untuk perintah yang diekspor.

# .REMOTEHELPRUNSPACE <PSSession-variable>

.EXTERNALHELP

Menentukan file bantuan berbasis XML untuk skrip atau fungsi.

# .EXTERNALHELP <XML Help File>

Kata .ExternalHelp kunci diperlukan ketika fungsi atau skrip didokumenkan dalam file XML. Tanpa kata kunci ini, Get-Help tidak dapat menemukan file bantuan berbasis XML untuk fungsi atau skrip.

Kata .ExternalHelp kunci lebih diutamakan daripada kata kunci bantuan berbasis komentar lainnya. Jika .ExternalHelp ada, Get-Help tidak menampilkan bantuan berbasis komentar, meskipun tidak dapat menemukan topik bantuan yang cocok dengan nilai .ExternalHelp kata kunci.

Jika fungsi diekspor oleh modul, atur nilai .ExternalHelp kata kunci ke nama file tanpa jalur. Get-Help mencari nama file yang ditentukan dalam subdirektori khusus bahasa direktori modul. Tidak ada persyaratan untuk nama file bantuan berbasis XML untuk fungsi, tetapi praktik terbaiknya adalah menggunakan format berikut:

<ScriptModule.psm1>-help.xml

Jika fungsi tidak disertakan dalam modul, sertakan jalur ke file bantuan berbasis XML. Jika nilai menyertakan jalur dan jalur berisi subdirektori khusus budaya UI, Get-Help cari subdirektori secara rekursif untuk file XML dengan nama skrip atau fungsi sesuai dengan standar fallback bahasa yang ditetapkan untuk Windows, seperti halnya dalam direktori modul.

Untuk informasi selengkapnya tentang format file bantuan berbasis XML bantuan cmdlet, lihat Cara Menulis Bantuan Cmdlet.

Konten yang dibuat secara otomatis

Nama, sintaks, daftar parameter, tabel atribut parameter, parameter umum, dan komentar secara otomatis dihasilkan oleh Get-Help cmdlet.

Nama

Bagian Nama dari topik bantuan fungsi diambil dari nama fungsi dalam sintaks fungsi. Nama topik bantuan skrip diambil dari nama file skrip. Untuk mengubah nama atau kapitalisasinya, ubah sintaks fungsi atau nama file skrip.

Sintaks

Bagian Sintaks dari topik bantuan dihasilkan dari fungsi atau sintaks skrip. Untuk menambahkan detail ke sintaks topik bantuan, seperti jenis .NET parameter, tambahkan detail ke sintaks. Jika Anda tidak menentukan jenis parameter, jenis Objek disisipkan sebagai nilai default.

Daftar Parameter

Daftar parameter dalam topik bantuan dihasilkan dari fungsi atau sintaks skrip dan dari deskripsi yang Anda tambahkan dengan menggunakan .Parameter kata kunci. Parameter fungsi muncul di bagian Parameter dari topik bantuan dalam urutan yang sama dengan yang muncul dalam fungsi atau sintaks skrip. Ejaan dan kapitalisasi nama parameter juga diambil dari sintaks. Ini tidak dipengaruhi oleh nama parameter yang ditentukan oleh .Parameter kata kunci.

Parameter Umum

Parameter Umum ditambahkan ke sintaksis dan daftar parameter topik bantuan, meskipun tidak berpengaruh. Untuk informasi selengkapnya tentang parameter umum, lihat about_CommonParameters.

Tabel Atribut Parameter

Get-Helpmenghasilkan tabel atribut parameter yang muncul saat Anda menggunakan parameter Lengkap atau Parameter .Get-Help Nilai atribut nilai Wajib, Posisi, dan Default diambil dari fungsi atau sintaks skrip.

Nilai default dan nilai untuk karakter Terima KartuBebas tidak muncul dalam tabel atribut parameter bahkan ketika ditentukan dalam fungsi atau skrip. Untuk membantu pengguna, berikan informasi ini dalam deskripsi parameter.

Keterangan

Bagian Keterangan dari topik bantuan secara otomatis dihasilkan dari fungsi atau nama skrip. Anda tidak dapat mengubah atau memengaruhi isinya.

Contoh

Bantuan berbasis komentar untuk Fungsi

Contoh fungsi berikut mencakup bantuan berbasis komentar:

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

Hasilnya adalah sebagai berikut:

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

Deskripsi Parameter dalam Sintaks Fungsi

Contoh ini sama dengan yang sebelumnya, kecuali deskripsi parameter disisipkan dalam sintaks fungsi. Format ini paling berguna ketika deskripsi singkat.

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

Bantuan berbasis komentar untuk Skrip

Contoh skrip berikut menyertakan bantuan berbasis komentar. Perhatikan baris kosong antara penutup #> dan Param pernyataan. Dalam skrip yang tidak memiliki Param pernyataan, setidaknya harus ada dua baris kosong antara komentar akhir dalam topik bantuan dan deklarasi fungsi pertama. Tanpa baris kosong ini, Get-Help mengaitkan topik bantuan dengan fungsi, bukan skrip.

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

Perintah berikut mendapatkan bantuan skrip. Karena skrip tidak berada dalam direktori yang tercantum dalam $env:Path variabel lingkungan, Get-Help perintah yang mendapatkan bantuan skrip harus menentukan jalur skrip.

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

Mengalihkan ke File XML

Anda dapat menulis topik bantuan berbasis XML untuk fungsi dan skrip. Meskipun bantuan berbasis komentar lebih mudah diterapkan, bantuan berbasis XML diperlukan untuk Bantuan yang Dapat Diperbarui dan untuk memberikan topik bantuan dalam beberapa bahasa.

Contoh berikut menunjukkan beberapa baris pertama skrip Update-Month.ps1. Skrip menggunakan .ExternalHelp kata kunci untuk menentukan jalur ke topik bantuan berbasis XML untuk skrip.

Perhatikan bahwa nilai .ExternalHelp kata kunci muncul pada baris yang sama dengan kata kunci. Penempatan lainnya tidak efektif.

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

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

Contoh berikut menunjukkan tiga penempatan kata kunci yang .ExternalHelp valid dalam fungsi.

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
}

Mengalihkan ke Topik Bantuan Lain

Kode berikut adalah kutipan dari awal fungsi bantuan bawaan di PowerShell, yang menampilkan satu layar teks bantuan pada satu waktu. Karena topik bantuan untuk Get-Help cmdlet menjelaskan fungsi bantuan, fungsi bantuan menggunakan .ForwardHelpTargetName kata kunci dan .ForwardHelpCategory untuk mengalihkan pengguna ke Get-Help topik bantuan cmdlet.

function help
{

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

Perintah berikut menggunakan fitur ini:

Get-Help -Name help

NAME

Get-Help

SYNOPSIS

Displays information about PowerShell cmdlets and concepts.
...