Menulis Bantuan untuk Modul PowerShell

Modul PowerShell dapat menyertakan topik Bantuan tentang modul dan tentang anggota modul, seperti cmdlet, penyedia, fungsi, dan skrip. Get-Help Cmdlet menampilkan topik Bantuan modul dalam format yang sama karena menampilkan Bantuan untuk item PowerShell lainnya, dan pengguna menggunakan perintah standar Get-Help untuk mendapatkan topik Bantuan.

Dokumen ini menjelaskan format dan penempatan topik Bantuan modul yang benar, dan menyarankan panduan untuk konten Bantuan modul.

Jenis Bantuan Modul

Modul dapat menyertakan jenis Bantuan berikut.

Bantuan berbasis XML
- Bantuan Cmdlet. Topik Bantuan yang menjelaskan cmdlet dalam modul adalah file XML yang menggunakan skema bantuan perintah
- Bantuan Penyedia. Topik Bantuan yang menjelaskan penyedia dalam modul adalah file XML yang menggunakan skema bantuan penyedia.
- Bantuan Fungsi. Topik Bantuan yang menjelaskan fungsi dalam modul dapat berupa file XML yang menggunakan skema bantuan perintah atau topik Bantuan berbasis komentar dalam fungsi, atau modul skrip atau skrip
- Bantuan Skrip. Topik Bantuan yang menjelaskan skrip dalam modul dapat berupa file XML yang menggunakan skema bantuan perintah atau topik Bantuan berbasis komentar dalam modul skrip atau skrip.
- Folder $PSHOME\Schemas\PSMaml berisi file skema yang menentukan format XML.
File teks bantuan konseptual ("Tentang")

Anda dapat menggunakan topik Bantuan konseptual ("tentang") untuk menjelaskan modul dan anggotanya dan untuk menjelaskan bagaimana anggota dapat digunakan bersama-sama untuk melakukan tugas. Secara default, PowerShell menyertakan lebih dari 100 topik Tentang Bantuan konseptual ini. Nama file harus menggunakan about_<name>.help.txt format , seperti about_MyModule.help.txt.

Nota

Header TOPIC bagian harus dimulai di kolom pertama dari baris pertama file. Konten bagian pada baris kedua harus cocok dengan nama file, tanpa akhiran .help.txt . Anda harus mengindentasi konten tepat 4 spasi. Baris ketiga harus kosong. Header SYNOPSIS bagian harus dimulai di kolom pertama dari baris keempat. Anda harus mengindentasi konten pada baris kelima tepat 4 spasi. Persyaratan ini diperlukan agar Get-Help cmdlet mengenali konten dengan benar.
```
TOPIC
    about_<subject or module name>

SYNOPSIS
    A short, one-line description of the topic contents.
```
Anda dapat menggunakan templat sampel berikut sebagai titik awal untuk menulis topik Bantuan konseptual. Kecuali untuk dua bagian pertama, struktur topik Bantuan konseptual segan-segan. Judul bagian yang tersisa bisa menjadi apa pun yang sesuai untuk konten Anda.
```
TOPIC
    about_<subject or module name>

SYNOPSIS
    A short, one-line description of the topic contents.

LONG DESCRIPTION

A detailed, full description of the subject or purpose of the module.

EXAMPLES

Examples of how to use the module or how the subject feature works in
practice.

TROUBLESHOOTING

Instructions for resolving common problems.

SEE ALSO

Text-only references for further reading. Hyperlinks can't work in the
PowerShell console.
```
Anda dapat menggunakan gaya dan markup apa pun yang Anda inginkan, tetapi PowerShell melihatnya sebagai teks biasa dan tidak ada penyajian khusus teks di konsol PowerShell. Saran berikut memastikan hasil tampilan dan keterbacaan terbaik.
- Gunakan UTF-8 dengan pengodean BOM untuk memastikan setiap karakter khusus (multi-byte) ditampilkan dengan benar.
- Garis bawahi header bagian atau gunakan semua huruf besar untuk membuatnya menonjol. Ini membuat konten lebih mudah dipindai.
- Batasi panjang setiap baris hingga 80 karakter.
- Blok kode inden dan contoh output untuk memisahkannya dari prosa di sekitarnya.

Penempatan Bantuan Modul

Get-Help Cmdlet mencari file topik Bantuan modul dalam subdirektori khusus bahasa direktori modul.

Misalnya, diagram struktur direktori berikut menunjukkan lokasi topik Bantuan untuk modul SampleModule.

<ModulePath>
    \SampleModule
        \<en-US>
            \about_SampleModule.help.txt
            \SampleModule.dll-help.xml
            \SampleNestedModule.dll-help.xml
        \<fr-FR>
            \about_SampleModule.help.txt
            \SampleModule.dll-help.xml
            \SampleNestedModule.dll-help.xml

Nota

Dalam contoh, <ModulePath> tempat penampung mewakili salah satu jalur dalam PSModulePath variabel lingkungan, seperti $HOME\Documents\Modules, , $PSHOME\Modulesatau jalur kustom yang ditentukan pengguna.

Mendapatkan Bantuan Modul

Saat pengguna mengimpor modul ke dalam sesi, topik Bantuan untuk modul tersebut diimpor ke dalam sesi bersama dengan modul. Anda dapat mencantumkan file topik Bantuan dalam nilai kunci FileList dalam manifes modul, tetapi topik Bantuan tidak terpengaruh oleh Export-ModuleMember cmdlet.

Anda dapat menyediakan topik Bantuan modul dalam bahasa yang berbeda. Get-Help Cmdlet secara otomatis menampilkan topik Bantuan modul dalam bahasa yang ditentukan untuk pengguna saat ini di item Opsi Regional dan Bahasa di Panel Kontrol. Di Windows Vista dan versi Windows yang lebih baru, Get-Help cari topik Bantuan dalam subdirektori khusus bahasa direktori modul sesuai dengan standar fallback bahasa yang ditetapkan untuk Windows.

Dimulai di PowerShell 3.0, menjalankan Get-Help perintah untuk cmdlet atau fungsi memicu impor otomatis modul. Get-Help Cmdlet segera menampilkan konten topik bantuan dalam modul.

Jika modul tidak berisi topik bantuan dan tidak ada topik bantuan untuk perintah dalam modul di komputer pengguna, Get-Help menampilkan bantuan yang dihasilkan secara otomatis. Bantuan yang dihasilkan secara otomatis mencakup sintaks perintah, parameter, dan jenis input dan output, tetapi tidak menyertakan deskripsi apa pun. Bantuan yang dihasilkan secara otomatis mencakup teks yang mengarahkan pengguna untuk mencoba menggunakan Update-Help cmdlet untuk mengunduh bantuan untuk perintah dari internet atau berbagi file. Ini juga merekomendasikan penggunaan parameter Online cmdlet Get-Help untuk mendapatkan versi online topik bantuan.

Mendukung Bantuan yang Dapat Diperbarui

Pengguna PowerShell 3.0 dan versi PowerShell yang lebih baru dapat mengunduh dan menginstal file bantuan yang diperbarui untuk modul dari internet atau dari berbagi file lokal. Update-Help cmdlet dan Save-Help menyembunyikan detail manajemen dari pengguna. Pengguna menjalankan Update-Help cmdlet lalu menggunakan Get-Help cmdlet untuk membaca file bantuan terbaru untuk modul di prompt perintah PowerShell. Pengguna tidak perlu memulai ulang Windows atau PowerShell.

Pengguna di belakang firewall dan mereka yang tidak memiliki akses internet juga dapat menggunakan Bantuan yang Dapat Diperbarui. Administrator dengan akses internet menggunakan Save-Help cmdlet untuk mengunduh dan menginstal file bantuan terbaru ke berbagi file. Kemudian, pengguna menggunakan parameter Update-Help cmdlet untuk mendapatkan file bantuan terbaru dari berbagi file.

Penulis modul dapat menyertakan file bantuan dalam modul dan menggunakan Bantuan yang Dapat Diperbarui untuk memperbarui file bantuan, atau menghilangkan file bantuan dari modul dan menggunakan Bantuan yang Dapat Diperbarui untuk menginstal dan memperbaruinya.

Untuk informasi selengkapnya tentang Bantuan yang Dapat Diperbarui, lihat Mendukung Bantuan yang Dapat Diperbarui.

Mendukung Bantuan Online

Pengguna yang tidak dapat atau tidak menginstal file bantuan yang diperbarui di komputer mereka sering mengandalkan versi online topik bantuan modul. Parameter Online cmdlet Get-Help membuka versi online cmdlet atau topik bantuan fungsi lanjutan untuk pengguna di browser internet default mereka.

Get-Help Cmdlet menggunakan nilai properti HelpUri dari cmdlet atau fungsi untuk menemukan versi online topik bantuan.

Dimulai di PowerShell 3.0, Anda dapat membantu pengguna menemukan versi online cmdlet dan topik bantuan fungsi dengan menentukan atribut HelpUri pada kelas cmdlet atau properti HelpUri dari atribut CmdletBinding . Nilai atribut adalah nilai properti HelpUri dari cmdlet atau fungsi.

Untuk informasi selengkapnya, lihat Bantuan Online Pendukung.

Lihat Juga

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2025-10-02