Bagikan melalui

tentang_Komentar

Deskripsi singkat

Menjelaskan cara menggunakan komentar PowerShell dan mencantumkan kasus penggunaan khusus.

Deskripsi panjang

Anda dapat menulis komentar untuk membuat anotasi atau menyusun kode PowerShell Anda untuk membantu keterbacaan. Saat kode Anda dijalankan, teks komentar diabaikan oleh PowerShell.

Komentar memberikan konteks penting kepada pembaca kode. Anda harus menggunakan komentar untuk tujuan berikut:

  • Menjelaskan kode kompleks dalam istilah yang lebih sederhana
  • Menjelaskan mengapa pendekatan tertentu dipilih
  • Kasus tepi dokumen yang perlu diperhatikan
  • Menyediakan tautan ke materi referensi pendukung

Beberapa komentar memiliki arti khusus dalam PowerShell. Lihat komentar khusus dan.

Gaya komentar PowerShell

PowerShell mendukung dua gaya komentar:

  • Komentar baris tunggal dimulai dengan karakter hash (#) dan diakhiri dengan baris baru. # dapat didahului oleh teks yang bukan bagian dari komentar, termasuk spasi kosong. Komentar baris tunggal yang ditempatkan pada baris yang sama dengan kode sumber yang tidak dikomentari dikenal sebagai komentar akhir baris.

  • Memblokir komentar dimulai dengan <# dan diakhir dengan #>. Komentar blok dapat mencakup sejumlah baris, dan dapat disertakan sebelum, setelah atau di tengah kode sumber yang tidak berkomentar. Semua teks dalam blok diperlakukan sebagai bagian dari komentar yang sama, termasuk spasi kosong.

    Penting

    Anda dapat menyertakan komentar baris tunggal dalam komentar blok. Namun, Anda tidak dapat menumpuk komentar blok. Jika Anda mencoba untuk menyisipkan komentar blok, komentar blok luar berakhir pada #> pertama yang ditemui.

Examples

Contoh 1: Komentar baris tunggal

# This is a single-line comment.
# This is also a single-line comment.

Contoh 2: Blokir komentar

<#
    This is a block comment.
    Text within the block is a part of the same comment.
Whitespace is unimportant in a block comment.
#>

Contoh 3: Komentar akhir baris

$var = 4 # This is an end-of-line comment

Contoh 4: Komentar blok dalam satu baris

'Foo'; <# This is an inline block comment #> 'Bar'

Contoh 5: Contoh lengkap

<#
    .DESCRIPTION
    Demonstrates PowerShell's different comment styles.
#>
param (
    [string] $Param1, # End-of-line comment
    <# Inline block comment #> $Param2
)

$var = 1, <# Inline block comment #> 2, 2

# Single-line comment.
# Another single-line comment.
$var.Where(
    <# Arg1 note #> { $_ -eq 2 },
    <# Arg2 note #> 'First',
    <# Arg3 note #> 1
)

Komentar khusus

PowerShell menyertakan beberapa kata kunci komentar untuk mendukung penggunaan tertentu.

Bantuan berbasis komentar

Anda dapat menulis konten bantuan berbasis komentar untuk fungsi dan skrip dengan menggunakan komentar baris tunggal atau komentar blok. Pengguna dapat menggunakan cmdlet Get-Help untuk melihat bantuan berbasis komentar untuk fungsi atau skrip. PowerShell mendefinisikan 15 kata kunci komentar yang dapat digunakan untuk memberikan informasi seperti deskripsi dan penggunaan contoh.

<#
    .DESCRIPTION
    Comment-based help using a block comment.
#>
function Get-Function { }

# .DESCRIPTION
# Comment-based help using multiple single-line comments.
function Get-Function { }

Untuk informasi selengkapnya, lihat:

#Requires

Pernyataan #Requires mencegah skrip berjalan kecuali sesi PowerShell saat ini memenuhi prasyarat yang ditentukan. #Requires dapat muncul di baris mana pun dalam skrip, tetapi diproses dengan cara yang sama terlepas dari posisinya.

#Requires -Modules AzureRM.Netcore
#Requires -Version 6.0

param (
    [Parameter(Mandatory)]
    [string[]] $Path
)

Untuk informasi selengkapnya, lihat about_Requires.

Blok tanda tangan

Skrip dapat ditandatangani sehingga mematuhi kebijakan eksekusi PowerShell. Setelah ditandatangani, blok tanda tangan ditambahkan ke akhir skrip. Blok ini mengambil bentuk beberapa komentar baris tunggal, yang dibaca oleh PowerShell sebelum skrip dijalankan.

# SIG # Begin signature block
# ...
# SIG # End signature block

Untuk informasi selengkapnya, lihat tentang_Penandatanganan.

Shebang

Pada sistem mirip Unix, shebang () adalah sebuah arahan yang digunakan di awal skrip untuk menunjukkan shell mana yang harus digunakan untuk menjalankan skrip. Shebang bukan bagian dari bahasa PowerShell. PowerShell menafsirkannya sebagai komentar biasa. Shebang ditafsirkan oleh sistem operasi.

Dalam contoh berikut, shebang memastikan PowerShell menjalankan skrip saat skrip dipanggil dari konteks non-PowerShell.

#!/usr/bin/env pwsh
Write-Host 'Begin script'

Penanda wilayah editor kode

Beberapa editor kode mendukung penanda wilayah yang memungkinkan Anda menciutkan dan memperluas bagian kode. Untuk PowerShell, penanda wilayah adalah komentar yang dimulai dengan #region dan diakhir dengan #endregion. Penanda wilayah harus berada di awal garis. Penanda wilayah didukung di PowerShell ISE dan di Visual Studio Code dengan ekstensi PowerShell. Penanda wilayah bukan bagian dari bahasa PowerShell. PowerShell menafsirkannya sebagai komentar biasa.

Untuk informasi selengkapnya, lihat bagian Lipat dari pengeditan Dasar di dokumentasi Visual Studio Code.

Komentar dalam token string

dan tidak bermakna khusus dalam string yang dapat diperluas atau yang verbatim. PowerShell menafsirkan karakter secara harfiah.

PS> '# This is not interpreted as a comment.'
# This is not interpreted as a comment.

PS> "This is <# also not interpreted #> as a comment."
This is <# also not interpreted #> as a comment.

Namun, fitur PowerShell tertentu dirancang untuk bekerja dengan string yang berisi komentar. Interpretasi komentar tergantung pada fitur tertentu.

Komentar ekspresi reguler

Ekspresi reguler (regex) di PowerShell menggunakan mesin regex .NET, yang mendukung dua gaya komentar.

  • Komentar sebaris ((?#))
  • Komentar akhir baris (#)

Komentar regex didukung oleh semua fitur berbasis regex di PowerShell. Misalnya:

PS> 'book' -match '(?# This is an inline comment)oo'
True

PS> 'book' -match '(?x)oo# This is an end-of-line comment'
True

PS> $regex = 'oo # This is an end-of-line comment'
PS> 'book' -split $regex, 0, 'IgnorePatternWhitespace'
b
k

Nota

Komentar regex akhir baris memerlukan konstruksi (?x) atau opsi IgnorePatternWhitespace.

Untuk informasi selengkapnya, lihat:

Komentar JSON

Dimulai di PowerShell 6.0, cmdlet ConvertFrom-Json mendukung gaya komentar JSON berikut:

  • Komentar baris tunggal (//)
  • Komentar blokir (/* */)

Nota

cmdlet Invoke-RestMethod secara otomatis menguraikan data JSON yang diterima. Di PowerShell 6.0 dan seterusnya, komentar diizinkan dalam data JSON.

Misalnya:

'{
    "Foo": "Bar" // This is a single-line comment
}' | ConvertFrom-Json

Foo
---
Bar

Peringatan

Dimulai di PowerShell 7.4, cmdlet Test-Json tidak lagi mendukung JSON dengan komentar. Kesalahan dikembalikan jika JSON menyertakan komentar. Dalam versi yang didukung sebelum 7.4, Test-Json berhasil mengurai JSON dengan komentar. Di PowerShell 7.5, Test-Json menyertakan opsi untuk mengabaikan komentar JSON.

Komentar CSV

Import-Csv dan ConvertFrom-Csv mendukung format W3C Extended Log. Baris yang dimulai dengan karakter hash (#) diperlakukan sebagai komentar dan diabaikan kecuali komentar dimulai dengan #Fields: dan berisi daftar nama kolom yang dibatasi. Dalam hal ini, cmdlet menggunakan nama kolom tersebut. Ini adalah format standar untuk Windows IIS dan log server web lainnya. Untuk informasi selengkapnya, lihat Format File Log yang Diperluas.

@'
# This is a CSV comment
Col1,Col2
Val1,Val2
'@ | ConvertFrom-Csv

Col1 Col2
---- ----
Val1 Val2

Di Windows PowerShell 5.1, perilaku default Export-Csv dan ConvertTo-Csv adalah untuk menyertakan informasi tipe dalam bentuk komentar #TYPE. Dimulai di PowerShell 6.0, defaultnya adalah tidak menyertakan komentar, tetapi ini dapat diganti dengan parameter IncludeTypeInformation.

[pscustomobject] @{ Foo = 'Bar' } | ConvertTo-Csv -IncludeTypeInformation

#TYPE System.Management.Automation.PSCustomObject
"Foo"
"Bar"

Saat komentar #TYPE disertakan dalam data CSV, Import-Csv dan ConvertFrom-Csv menggunakan informasi ini untuk mengatur properti pstypenames objek yang dideserialisasi.

class Test { $Foo = 'Bar' }
$test = [Test]::new()

$var = $test | ConvertTo-Csv -IncludeTypeInformation | ConvertFrom-Csv
$var.pstypenames

Test
CSV:Test

ConvertFrom-StringData komentar

Dalam data stringnya, cmdlet ConvertFrom-StringData memperlakukan baris yang dimulai dengan # sebagai komentar. Untuk informasi selengkapnya, lihat:

Catatan

  • Komentar blokir tidak dapat ditumpuk. Dalam contoh berikut, Baz bukan bagian dari komentar.

    <#
'Foo'
<# 'Bar' #>
'Baz'
#>

  • <# #> tidak memiliki arti khusus dalam komentar satu baris. # tidak memiliki arti khusus dalam komentar blok.

  • Untuk diperlakukan sebagai komentar, karakter komentar tidak boleh menjadi bagian dari token non-komentar. Dalam contoh berikut, #Bar dan <#Bar#> adalah bagian dari token Foo.... Oleh karena itu, mereka tidak diperlakukan sebagai komentar.

    PS> Foo#Bar
Foo#Bar: The term 'Foo#Bar' is not recognized as a name [...]

PS> Foo<#Bar#>
Foo<#Bar#>: The term 'Foo<#Bar#>' is not recognized as a name [...]
  • Last updated on