Bagikan melalui

panduan gaya PowerShell-Docs

Artikel ini menyediakan panduan gaya khusus untuk konten PowerShell-Docs. Ini dibangun berdasarkan informasi yang diuraikan dalam Gambaran Umum.

Memformat elemen sintaks perintah

Gunakan aturan berikut untuk memformat elemen bahasa PowerShell saat elemen digunakan dalam kalimat.

  • Selalu gunakan nama lengkap untuk cmdlet dan parameter dalam kasus Pascal yang tepat

  • Hanya gunakan alias saat Anda secara khusus menunjukkan alias

  • Kata kunci dan operator PowerShell harus semua huruf kecil

  • Item berikut harus diformat menggunakan teks tebal :

    • Nama jenis

    • Nama kelas

    • Nama properti

    • Nama parameter

      • Secara default, gunakan parameter tanpa awalan tanda hubung.
      • Gunakan nama parameter dengan tanda hubung jika Anda mengilustrasikan sintaks. Bungkus parameter dalam backtick.

      Contohnya:

      The parameter's name is **Name**, but it's typed as `-Name` when used on the command
line as a parameter.

  • Item-item berikut harus diformat menggunakan backtick (`):

    • Nilai properti dan parameter

    • Ketik nama yang menggunakan gaya kurung siku - Misalnya: [System.Io.FileInfo]

    • Menyebut karakter berdasarkan namanya. Misalnya: Gunakan karakter tanda bintang (*) sebagai pengganti.

    • Kata kunci dan operator bahasa

    • Cmdlet, nama fungsi, dan skrip

    • Alias perintah dan parameter

    • Nama metode - Misalnya: Metode ToString() mengembalikan representasi string objek

    • Variabel

    • Perintah bawaan

    • Jalur file dan direktori

    • Contoh sintaks perintah sebaris - Lihat Markdown untuk sampel kode

      Contoh ini menunjukkan beberapa contoh backtick:

      The following code uses `Get-ChildItem` to list the contents of `C:\Windows` and assigns
the output to the `$files` variable.

```powershell
$files = Get-ChildItem C:\Windows
```

      Contoh ini menunjukkan sintaks perintah sebaris:

      To start the spooler service on a remote computer named DC01, you type:
`sc.exe \\DC01 start spooler`.

      Menyertakan ekstensi file memastikan bahwa perintah yang benar dijalankan sesuai dengan prioritas perintah PowerShell.

Markdown untuk sampel kode

Markdown mendukung dua gaya kode yang berbeda:

  • Rentang kode (sebaris) - ditandai oleh satu karakter backtick (`). Digunakan dalam paragraf, bukan sebagai blok mandiri.
  • Blok kode - blok multibaris yang dikelilingi oleh string triple-backtick (```). Blok kode juga dapat memiliki label bahasa setelah backtick. Label bahasa memungkinkan penyorotan sintaks untuk konten blok kode.

Semua blok kode harus terkandung dalam pagar kode. Jangan pernah menggunakan indentasi untuk blok kode. Markdown memungkinkan pola ini tetapi bisa bermasalah dan harus dihindari.

Blok kode adalah satu atau beberapa baris kode yang dikelilingi oleh pagar kode triple-backtick (```). Penanda pagar kode harus berada di baris tersendiri sebelum dan sesudah contoh kode. Penanda pembuka dapat memiliki label bahasa opsional. Label bahasa memungkinkan penyorotan sintaks pada halaman web yang dirender.

Untuk daftar lengkap tag bahasa yang didukung, lihat Blok kode pagar di panduan kontributor terpusat.

Penerbitan juga menambahkan tombol Salin yang dapat menyalin konten blok kode ke clipboard. Ini memungkinkan Anda menempelkan kode ke dalam skrip untuk menguji sampel kode. Namun, tidak semua contoh dimaksudkan untuk dijalankan seperti yang ditulis. Beberapa blok kode adalah ilustrasi dasar konsep PowerShell.

Ada tiga jenis blok kode yang digunakan dalam dokumentasi kami:

  1. Blok sintaksis
  2. Contoh ilustratif
  3. Contoh yang dapat dieksekusi

Blok sintaks kode

Blok kode sintaks digunakan untuk menggambarkan struktur sintaktik perintah. Jangan gunakan tag bahasa pada pagar kode. Contoh ini mengilustrasikan semua kemungkinan parameter dari cmdlet Get-Command.

```
Get-Command [-Verb <String[]>] [-Noun <String[]>] [-Module <String[]>]
  [-FullyQualifiedModule <ModuleSpecification[]>] [-TotalCount <Int32>] [-Syntax]
  [-ShowCommandInfo] [[-ArgumentList] <Object[]>] [-All] [-ListImported]
  [-ParameterName <String[]>] [-ParameterType <PSTypeName[]>] [<CommonParameters>]
```

Contoh ini menjelaskan for pernyataan dalam istilah umum:

```
for (<init>; <condition>; <repeat>)
{<statement list>}
```

Contoh ilustratif

Contoh ilustrasi digunakan untuk menjelaskan konsep PowerShell. Yo'u harus Menghindari penggunaan perintah PowerShell dalam contoh jika memungkinkan. Namun, contoh ilustrasi tidak dimaksudkan untuk disalin dan ditempelkan untuk eksekusi. Mereka paling umum digunakan untuk contoh sederhana yang mudah dipahami. Anda dapat menyertakan perintah PowerShell dan contoh output.

Berikut adalah contoh sederhana yang mengilustrasikan operator perbandingan PowerShell. Dalam hal ini, kami tidak berniat pembaca untuk menyalin dan menjalankan contoh ini. Perhatikan bahwa contoh ini menggunakan sebagai string prompt yang disederhanakan PS> .

```powershell
PS> 2 -eq 2
True

PS> 2 -eq 3
False

PS> 1,2,3 -eq 2
2

PS> "abc" -eq "abc"
True

PS> "abc" -eq "abc", "def"
False

PS> "abc", "def" -eq "abc"
abc
```

Contoh yang dapat dieksekusi

Contoh kompleks, atau contoh yang dimaksudkan untuk disalin dan dijalankan, harus menggunakan markup gaya blok berikut:

```powershell
<Your PowerShell code goes here>
```

Output yang ditampilkan oleh perintah PowerShell harus diapit dalam blok kode Output untuk mencegah penyorotan sintaks. Contohnya:

```powershell
Get-Command -Module Microsoft.PowerShell.Security
```

```Output
CommandType  Name                        Version    Source
-----------  ----                        -------    ------
Cmdlet       ConvertFrom-SecureString    3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       ConvertTo-SecureString      3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Get-Acl                     3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Get-AuthenticodeSignature   3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Get-CmsMessage              3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Get-Credential              3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Get-ExecutionPolicy         3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Get-PfxCertificate          3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       New-FileCatalog             3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Protect-CmsMessage          3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Set-Acl                     3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Set-AuthenticodeSignature   3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Set-ExecutionPolicy         3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Test-FileCatalog            3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Unprotect-CmsMessage        3.0.0.0    Microsoft.PowerShell.Security
```

Output Label kode bukan bahasa resmi yang didukung oleh sistem penyorotan sintaks. Namun, label ini berguna karena sistem penerbitan kami menambahkan label Output ke bingkai kotak kode di halaman web. Kotak Kode output tidak memiliki penyorotan sintaksis.

Aturan gaya pengkodian

Hindari kelanjutan baris dalam sampel kode

Hindari menggunakan karakter kelanjutan baris (`) dalam contoh kode PowerShell. Karakter backtick sulit dilihat dan dapat menyebabkan masalah jika ada spasi tambahan di akhir baris.

  • Gunakan splatting PowerShell untuk mengurangi panjang garis untuk cmdlet yang memiliki beberapa parameter.
  • Manfaatkan peluang pemutusan garis alami PowerShell, seperti setelah karakter pipa (|), kurung kurung ({),( dan tanda kurung ([).

Hindari menggunakan perintah PowerShell dalam contoh

Penggunaan string prompt tidak disarankan dan harus terbatas pada skenario yang dimaksudkan untuk mengilustrasikan penggunaan baris perintah. Untuk sebagian besar contoh ini, string prompt harus PS>. Perintah ini tidak bergantung pada indikator khusus OS.

Perintah diperlukan dalam contoh untuk mengilustrasikan perintah yang mengubah perintah atau ketika jalur yang ditampilkan signifikan terhadap skenario. Contoh berikut mengilustrasikan bagaimana permintaan berubah saat menggunakan penyedia Registri.

PS C:\> cd HKCU:\System\
PS HKCU:\System\> dir

    Hive: HKEY_CURRENT_USER\System

Name                   Property
----                   --------
CurrentControlSet
GameConfigStore        GameDVR_Enabled                       : 1
                       GameDVR_FSEBehaviorMode               : 2
                       Win32_AutoGameModeDefaultProfile      : {2, 0, 1, 0...}
                       Win32_GameModeRelatedProcesses        : {1, 0, 1, 0...}
                       GameDVR_HonorUserFSEBehaviorMode      : 0
                       GameDVR_DXGIHonorFSEWindowsCompatible : 0

Jangan gunakan alias dalam contoh

Gunakan nama lengkap semua cmdlet dan parameter kecuali Anda secara khusus mendokumentasikan alias. Nama cmdlet dan parameter harus menggunakan nama dengan gaya penamaan Pascal yang tepat.

Menggunakan parameter dalam contoh

Hindari menggunakan parameter posisi. Untuk mengurangi kemungkinan kebingungan, Anda harus menyertakan nama parameter dalam contoh, bahkan jika parameter berposisi.

Memformat artikel referensi cmdlet

Artikel referensi cmdlet memiliki struktur tertentu. PlatyPS mendefinisikan struktur ini. PlatyPS menghasilkan bantuan cmdlet untuk modul PowerShell di Markdown. Setelah Anda mengedit file Markdown, PlatyPS dapat membuat file bantuan MAML yang digunakan oleh cmdlet Get-Help.

PlatyPS memiliki skema yang mengharapkan struktur tertentu untuk referensi cmdlet. Dokumen skema PlatyPS menjelaskan struktur ini. Pelanggaran skema menyebabkan kesalahan build yang harus diperbaiki sebelum kami dapat menerima kontribusi Anda.

  • Jangan hapus salah satu struktur header ATX. PlatyPS mengharapkan sekumpulan header tertentu dalam urutan tertentu.
  • Header INPUTS dan OUTPUTS H2 harus memiliki jenis H3. Jika cmdlet tidak mengambil input atau mengembalikan nilai, gunakan nilai None untuk H3.
  • Rentang kode sebaris dapat digunakan dalam paragraf apa pun.
  • Blok kode berpagar hanya diizinkan di bagian CONTOH .

Dalam skema PlatyPS, EXAMPLES adalah header H2. Setiap contoh adalah header H3. Dalam contoh, skema tidak mengizinkan blok kode dipisahkan oleh paragraf. Skema hanya memungkinkan struktur berikut:

### Example X - Title sentence

0 or more paragraphs
1 or more code blocks
0 or more paragraphs.

Beri nomor setiap contoh dan tambahkan judul singkat.

Contohnya:

### Example 1: Get cmdlets, functions, and aliases

This command gets the PowerShell cmdlets, functions, and aliases that are installed on the
computer.

```powershell
Get-Command
```

### Example 2: Get commands in the current session

```powershell
Get-Command -ListImported
```

Pemformatan file About_

About_* file ditulis dalam Markdown tetapi dikirim sebagai file teks biasa. Kami menggunakan Pandoc untuk mengonversi Markdown menjadi teks biasa. About_* file diformat untuk kompatibilitas terbaik di semua versi PowerShell dan dengan alat penerbitan.

Panduan pemformatan dasar:

  • Batasi baris paragraf hingga 80 karakter

  • Membatasi blok kode hingga 76 karakter

  • Batasi kutipan blok dan pemberitahuan hingga 78 karakter

  • Saat menggunakan meta-karakter khusus \, $, dan <:

    • Dalam header, karakter ini harus diloloskan menggunakan karakter awal \ atau diapit dalam rentang kode menggunakan backtick (`)

    • Di dalam paragraf, karakter-karakter ini harus dimasukkan ke dalam spasi kode. Contohnya:

      ### The purpose of the \$foo variable

The `$foo` variable is used to store ...

  • Tabel dalam format Markdown

    • Untuk About_* artikel, tabel harus pas dalam 76 karakter
      • Jika konten tidak pas dalam batas 76 karakter, gunakan daftar poin sebagai gantinya
    • Menggunakan karakter pembuka dan penutupan | pada setiap baris

Langkah berikutnya

Daftar periksa editorial

  • Last updated on