Penamaan file Bantuan

Nota

Penulisan manual bantuan berbasis XML sangat sulit. Modul PlatyPS memungkinkan Anda menulis bantuan di Markdown lalu mengonversinya ke bantuan berbasis XML. Ini membuatnya jauh lebih mudah untuk menulis dan memelihara bantuan. PlatyPS juga dapat membuat paket Bantuan yang Dapat Diperbarui untuk Anda. Untuk informasi selengkapnya, lihat Membuat bantuan berbasis XML menggunakan PlatyPS.

Topik ini menjelaskan cara memberi nama file bantuan berbasis XML sehingga cmdlet Get-Help dapat menemukannya. Persyaratan nama berbeda untuk setiap jenis perintah.

File Bantuan Cmdlet

File bantuan untuk cmdlet C# harus dinamai untuk rakitan tempat cmdlet ditentukan. Gunakan format nama file berikut:

<AssemblyName>.dll-help.xml

Format nama rakitan diperlukan bahkan ketika rakitan adalah modul berlapis.

Misalnya, cmdlet Get-WinEvent didefinisikan dalam rakitan Microsoft.PowerShell.Diagnostics.dll. Cmdlet Get-Help mencari topik bantuan untuk cmdlet Get-WinEvent hanya dalam file Microsoft.PowerShell.Diagnostics.dll-help.xml di direktori modul.

File Bantuan Penyedia

File bantuan untuk penyedia PowerShell harus diberi nama untuk perakitan tempat penyedia ditentukan. Gunakan format nama file berikut:

<AssemblyName>.dll-help.xml

Format nama rakitan diperlukan bahkan ketika rakitan adalah modul berlapis.

Misalnya, Penyedia sertifikat ditentukan dalam rakitan Microsoft.PowerShell.Security.dll. Cmdlet Get-Help mencari topik bantuan untuk penyedia Sertifikat hanya dalam file Microsoft.PowerShell.Security.dll-help.xml di direktori modul.

File Bantuan Fungsi

Fungsi dapat didokumentasikan menggunakan bantuan berbasis komentar atau didokumentasikan dalam file bantuan XML. Ketika fungsi didokumentasikan dalam file XML, fungsi harus memiliki kata kunci komentar .EXTERNALHELP yang mengaitkan fungsi dengan file XML. Jika tidak, cmdlet Get-Help tidak dapat menemukan file bantuan.

Tidak ada persyaratan teknis untuk nama file bantuan fungsi. Namun, praktik terbaik adalah memberi nama file bantuan untuk modul skrip tempat fungsi ditentukan. Misalnya, fungsi berikut didefinisikan dalam file MyModule.psm1.

#.EXTERNALHELP MyModule.psm1-help.xml
function Test-Function { ... }

File Bantuan Perintah CIM

File bantuan untuk perintah CIM harus diberi nama untuk file CDXML tempat perintah CIM ditentukan. Gunakan format nama file berikut:

<FileName>.cdxml-help.xml

Perintah CIM didefinisikan dalam file CDXML yang dapat disertakan dalam modul sebagai modul berlapis. Ketika perintah CIM diimpor ke sesi sebagai fungsi, PowerShell menambahkan kata kunci komentar .EXTERNALHELP ke definisi fungsi yang mengaitkan fungsi dengan file bantuan XML yang dinamai untuk file CDXML tempat perintah CIM ditentukan.

File Bantuan Alur Kerja Skrip

Alur kerja skrip yang disertakan dalam modul dapat didokumenkan dalam file bantuan berbasis XML. Tidak ada persyaratan teknis untuk nama file bantuan. Namun, praktik terbaik adalah memberi nama file bantuan untuk modul skrip tempat alur kerja skrip ditentukan. Contohnya:

<ScriptModule>.psm1-help.xml

Tidak seperti perintah berskrip lainnya, alur kerja skrip tidak memerlukan kata kunci komentar .EXTERNALHELP untuk mengaitkannya dengan file bantuan. Sebagai gantinya, PowerShell mencari subdirektori khusus UI-Culture dari direktori modul untuk file bantuan berbasis XML dan mencari bantuan untuk alur kerja skrip di semua file. .EXTERNALHELP kata kunci komentar diabaikan.

Karena kata kunci komentar .EXTERNALHELP diabaikan, cmdlet Get-Help dapat menemukan bantuan untuk alur kerja skrip hanya saat disertakan dalam modul.