Bagikan melalui

Cara menambahkan sintaks ke topik bantuan cmdlet

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.

Sebelum Anda mulai membuat kode XML untuk diagram sintaks dalam file Bantuan cmdlet, baca bagian ini untuk mendapatkan gambaran yang jelas tentang jenis data yang perlu Anda berikan, seperti atribut parameter, dan bagaimana data tersebut ditampilkan dalam diagram sintaks..

Atribut parameter

  • Diperlukan
    • Jika true, parameter harus muncul di semua perintah yang menggunakan set parameter.
    • Jika false, parameter bersifat opsional di semua perintah yang menggunakan set parameter.
  • Posisi
    • Jika dinamai, nama parameter diperlukan.
    • Jika posisi, nama parameter bersifat opsional. Saat dihilangkan, nilai parameter harus berada dalam posisi yang ditentukan dalam perintah . Misalnya, jika nilainya adalah position="1", nilai parameter harus menjadi nilai parameter pertama atau hanya yang tidak diberi nama dalam perintah.
  • Input Alur
    • Jika true (ByValue), Anda dapat menyalurkan input ke parameter . Input dikaitkan dengan ("terikat ke") parameter meskipun nama properti dan jenis objek tidak cocok dengan jenis yang diharapkan. Komponen pengikatan parameter PowerShell mencoba mengonversi input ke jenis yang benar dan gagal perintah hanya ketika jenis tidak dapat dikonversi. Hanya satu parameter dalam set parameter yang dapat dikaitkan dengan nilai.
    • Jika true (ByPropertyName), Anda dapat menyalurkan input ke parameter . Namun, input dikaitkan dengan parameter hanya ketika nama parameter cocok dengan nama properti objek input. Misalnya, jika nama parameter Path, objek yang disalurkan ke cmdlet hanya dikaitkan dengan parameter tersebut ketika objek memiliki properti bernama jalur.
    • Jika true (ByValue, ByPropertyName), Anda dapat menyalurkan input ke parameter baik berdasarkan nama properti atau berdasarkan nilai. Hanya satu parameter dalam set parameter yang dapat dikaitkan dengan nilai.
    • Jika false, Anda tidak dapat menyalurkan input ke parameter ini.
  • Globbing
    • Jika true, teks yang ditiru pengguna untuk nilai parameter dapat menyertakan karakter kartubebas.
    • Jika false, teks yang jenis pengguna untuk nilai parameter tidak dapat menyertakan karakter kartubebas.

Atribut nilai parameter

  • Diperlukan
    • Jika true, nilai yang ditentukan harus digunakan setiap kali menggunakan parameter dalam perintah.
    • Jika false, nilai parameter bersifat opsional. Biasanya, nilai hanya bersifat opsional ketika nilai tersebut adalah salah satu dari beberapa nilai yang valid untuk parameter, seperti dalam jenis enumerasi.

Atribut Diperlukan dari nilai parameter berbeda dari atribut diperlukan parameter.

Atribut parameter yang diperlukan menunjukkan apakah parameter (dan nilainya) harus disertakan saat memanggil cmdlet. Sebaliknya, atribut nilai parameter yang diperlukan hanya digunakan saat parameter disertakan dalam perintah. Ini menunjukkan apakah nilai tertentu harus digunakan dengan parameter .

Biasanya, nilai parameter yang merupakan tempat penampung diperlukan dan nilai parameter yang harfiah tidak diperlukan, karena merupakan salah satu dari beberapa nilai yang mungkin digunakan dengan parameter .

Mengumpulkan informasi sintaks

  1. Mulai dengan nama cmdlet.

    SYNTAX
    Get-Tech

  2. Mencantumkan semua parameter cmdlet. Ketik tanda hubung (-) sebelum setiap nama parameter. Pisahkan parameter menjadi set parameter (beberapa cmdlet mungkin hanya memiliki satu set parameter). Dalam contoh ini cmdlet Get-Tech memiliki dua set parameter.

    SYNTAX
    Get-Tech -Name -Type
    Get-Tech -Id -List -Type

    Mulai setiap parameter yang diatur dengan nama cmdlet.

    Cantumkan parameter default yang ditetapkan terlebih dahulu. Parameter default ditentukan oleh kelas cmdlet.

    Untuk setiap set parameter, cantumkan parameter uniknya terlebih dahulu, kecuali ada parameter posisi yang harus muncul terlebih dahulu. Dalam contoh sebelumnya, parameter Nama dan Id adalah parameter unik untuk dua set parameter (setiap set parameter harus memiliki satu parameter yang unik untuk kumpulan parameter tersebut). Ini memudahkan pengguna untuk mengidentifikasi parameter apa yang mereka butuhkan untuk menyediakan set parameter.

    Cantumkan parameter dalam urutan yang akan muncul dalam perintah. Jika pesanan tidak masalah, cantumkan parameter terkait bersama-sama, atau cantumkan parameter yang paling sering digunakan terlebih dahulu.

    Pastikan untuk mencantumkan parameter WhatIf dan Konfirmasi jika cmdlet mendukung ShouldProcess.

    Jangan mencantumkan parameter umum (seperti Verbose, Debug, dan ErrorAction) dalam diagram sintaksIs Anda. cmdlet Get-Help menambahkan informasi tersebut untuk Anda saat menampilkan topik Bantuan.

  3. Tambahkan nilai parameter. Di PowerShell, nilai parameter diwakili oleh jenis .NET-nya. Namun, nama jenis dapat disingkat, seperti "string" untuk System.String.

    SYNTAX
    Get-Tech -Name string -Type Basic Advanced
    Get-Tech -Id int -List -Type Basic Advanced

    Singkatan jenis selama maknanya jelas, seperti string untuk System.String dan int untuk System.Int32.

    Cantumkan semua nilai enumerasi, seperti parameter -Type dalam contoh sebelumnya, yang dapat diatur ke dasar atau tingkat lanjut .

    Beralih parameter, seperti -List dalam contoh sebelumnya, tidak memiliki nilai.

  4. Tambahkan tanda kurung sudut ke nilai parameter yang merupakan tempat penampung, dibandingkan dengan nilai parameter yang literal.

    SYNTAX
    Get-Tech -Name <string> -Type Basic Advanced
    Get-Tech -Id <int> -List -Type Basic Advanced

  5. Sertakan parameter opsional dan katupnya dalam tanda kurung siku.

    SYNTAX
    Get-Tech -Name <string> [-Type Basic Advanced]
    Get-Tech -Id <int> [-List] [-Type Basic Advanced]

  6. Sertakan nama parameter opsional (untuk parameter posisi) dalam tanda kurung siku. Nama untuk parameter yang berposisi posisi, seperti parameter Nama dalam contoh berikut, tidak harus disertakan dalam perintah.

    SYNTAX
    Get-Tech [-Name] <string> [-Type Basic Advanced]
    Get-Tech -Id <int> [-List] [-Type Basic Advanced]

  7. Jika nilai parameter dapat berisi beberapa nilai, seperti daftar nama dalam parameter Nama, tambahkan sepasang kurung siku langsung mengikuti nilai parameter.

    SYNTAX
    Get-Tech [-Name] <string[]> [-Type Basic Advanced]
    Get-Tech -Id <int[]> [-List] [-Type Basic Advanced]

  8. Jika pengguna dapat memilih dari parameter atau nilai parameter, seperti parameter Jenis, sertakan pilihan dalam tanda kurung kurawal dan pisahkan dengan simbol OR eksklusif (;).

    SYNTAX
    Get-Tech [-Name] <string[]> [-Type {Basic | Advanced}]
    Get-Tech -Id <int[]> [-List] [-Type {Basic | Advanced}]

  9. Jika nilai parameter harus menggunakan pemformatan tertentu, seperti tanda kutip atau tanda kurung, perlihatkan format dalam sintaks.

    SYNTAX
    Get-Tech [-Name] <"string[]"> [-Type {Basic | Advanced}]
    Get-Tech -Id <int[]> [-List] [-Type {Basic | Advanced}]

Mengkoding XML diagram sintaks

Simpul sintaks XML dimulai segera setelah simpul deskripsi, yang diakhir dengan tag </maml:description>. Untuk informasi tentang mengumpulkan data yang digunakan dalam diagram sintaks, lihat Mengumpulkan Informasi Sintaks.

Menambahkan simpul sintaks

Diagram sintaks yang ditampilkan dalam topik Bantuan cmdlet dihasilkan dari data dalam simpul sintaks XML. Simpul sintaks diapit dalam sepasang tag <command:syntax>. Dengan setiap set parameter cmdlet diapit dalam sepasang tag <command:syntaxitem>. Tidak ada batasan jumlah tag <command:syntaxitem> yang dapat Anda tambahkan.

Contoh berikut menunjukkan simpul sintaksis yang memiliki node item sintaks untuk dua set parameter.

<command:syntax>
  <command:syntaxItem>
    ...
    <!--Parameter Set 1 (default parameter set) parameters go here-->
    ...
  </command:syntaxItem>
  <command:syntaxItem>
    ...
    <!--Parameter Set 2 parameters go here-->
    ...
  </command:syntaxItem>
</command:syntax>

Menambahkan nama cmdlet ke data kumpulan parameter

Setiap set parameter cmdlet ditentukan dalam simpul item sintaksis. Setiap simpul item sintaks dimulai dengan sepasang tag <maml:name> yang menyertakan nama cmdlet.

Contoh berikut menyertakan simpul sintaksis yang memiliki node item sintaks untuk dua set parameter.

<command:syntax>
  <command:syntaxItem>
    <maml:name>Cmdlet-Name</maml:name>
  </command:syntaxItem>
  <command:syntaxItem>
    <maml:name>Cmdlet-Name</maml:name>
  </command:syntaxItem>
</command:syntax>

Menambahkan parameter

Setiap parameter yang ditambahkan ke simpul item sintaksis ditentukan dalam sepasang tag <command:parameter>. Anda memerlukan sepasang tag <command:parameter> untuk setiap parameter yang disertakan dalam kumpulan parameter, dengan pengecualian parameter umum yang disediakan oleh PowerShell.

Atribut tag <command:parameter> pembuka menentukan bagaimana parameter muncul dalam diagram sintaksis. Untuk informasi tentang atribut parameter, lihat Atribut Parameter .

Nota

Tag <command:parameter> mendukung elemen turunan <maml:description> yang kontennya tidak pernah ditampilkan. Deskripsi parameter ditentukan dalam simpul parameter XML. Untuk menghindari inkonsistensi antara informasi dalam bode item sintaksis dan simpul parameter, hilangkan (<maml:description> atau biarkan kosong.

Contoh berikut menyertakan simpul item sintaks untuk parameter yang ditetapkan dengan dua parameter.

<command:syntaxItem>
  <maml:name>Cmdlet-Name</maml:name>
  <command:parameter required="true" globbing="true"
    pipelineInput="true (ByValue)" position="1">
    <maml:name>ParameterName1</maml:name>
    <command:parameterValue required="true">
      string[]
    </command:parameterValue>
  </command:parameter>
  <command:parameter required="true" globbing="true"
    pipelineInput="true (ByPropertyName)">
    <maml:name>ParameterName2</maml:name>
    <command:parameterValue required="true">
      int32[]
    </command:parameterValue>
  </command:parameter>
</command:syntaxItem>
  • Last updated on