關於註解

發行項
01/10/2025

簡短描述

描述如何使用PowerShell批注並列出特殊使用案例。

完整描述

您可以撰寫批註來標註或建構 PowerShell 程式代碼，以協助閱讀。執行程式代碼時，PowerShell 會忽略批註文字。

批註為程式代碼的讀取者提供重要的內容。您應該針對下列目的使用批註：

以更簡單的詞彙說明複雜的程序代碼
說明為何選擇特定方法
要注意的文件邊緣案例
提供支援參考數據的連結

某些批注在PowerShell中具有特殊意義。請參閱特殊批註。

PowerShell 批注樣式

PowerShell 支持兩種批注樣式：

單行批註 以哈希字元（#）開頭，並以換行符結尾。 # 前面可以加上不屬於批注一部分的文字，包括空格符。與未批注原始碼位於相同行的單行批注稱為行尾批注。
區塊註解 開頭為 <#，並以 #>結尾。區塊批注可以跨越任意數目的行，而且可以在未批注的原始程式碼之前、之後或中間包含。區塊中的所有文字都會被視為相同批注的一部分，包括空格符。

重要

您可以在區塊批註中包含單行批注。不過，您無法嵌套區塊註解。如果您嘗試巢狀區塊批注，外部區塊批注會在第一個遇到 #> 結束。

例子

範例 1：單行批注

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

範例 2：封鎖批注

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

範例 3：行尾批注

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

範例 4：內嵌區塊註解

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

範例 5：完整範例

<#
    .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
)

特殊批注

PowerShell 包含數個批注關鍵詞，可支援特定用途。

以批注為基礎的說明

您可以使用單行或區塊批註撰寫函式和腳本的批註型說明內容。用戶可以使用 Get-Help Cmdlet 來檢視函式或腳本的批註型說明。 PowerShell 定義 15 個批注關鍵詞，可用來提供資訊，例如描述和範例使用方式。

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

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

如需詳細資訊，請參閱：

`#Requires`

#Requires 語句會防止腳本執行，除非目前的PowerShell會話符合指定的必要條件。 #Requires 可以在腳本中的任何一行上顯示，但不論位置為何，都會以相同方式處理。

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

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

如需詳細資訊，請參閱 about_Requires。

簽章區塊

腳本可以簽署，使其符合PowerShell執行原則。簽署之後，簽章區塊就會新增至腳本的結尾。此區塊採用多個單行批注的形式，PowerShell 會在執行腳本之前讀取這些批注。

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

如需詳細資訊，請參閱 about_signing。

家當

在類 Unix 系統上，shebang （#!）是用於腳本開頭以指出執行該腳本所需 shell 的指示符。 Shebang 不是 PowerShell 語言的一部分。 PowerShell 會將它解譯為一般批註。 Shebang 由作業系統解釋。

在下列範例中，shebang 可確保從非 PowerShell 環境叫用腳本時，PowerShell 會執行腳本。

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

程式代碼編輯器區域標記

某些程式代碼編輯器支援區域標記，可讓您折疊和展開程式碼區段。針對 PowerShell，區域標記是以 #region 開頭，並以 #endregion結尾的批註。區域標記必須位於線條的開頭。 PowerShell ISE 和具有 PowerShell 延伸模組的 Visual Studio Code 支援區域標記。區域標記不是 PowerShell 語言的一部分。 PowerShell 會將它們解譯為一般批註。

如需詳細資訊，請參閱Visual StudioCode 檔中基本編輯折疊一節。

字串標記中的註解

# 和 <# #> 在可展開或逐字字串中沒有特殊意義。 PowerShell 會以字面方式解譯字元。

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.

不過，某些 PowerShell 功能的設計目的是使用包含批注的字串。批註的解譯取決於特定功能。

正則表達式註解

PowerShell 中的正則表達式（regex）會使用 .NET regex 引擎，其支援兩種批注樣式：

內嵌註釋（(?#)）
行末註解（#）

PowerShell 中所有以 regex 為基礎的功能都支援 Regex 批注。例如：

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

注意

行尾的正則表達式注釋需要 (?x) 建構或 IgnorePatternWhitespace 選項。

如需詳細資訊，請參閱：

關於正則表達式
正則表達式中的各種構造

JSON 注釋

從 PowerShell 6.0 開始，ConvertFrom-Json Cmdlet 支援下列 JSON 批注樣式：

單行註解（//）
封鎖批註（/* */）

注意

Invoke-RestMethod Cmdlet 會自動解析收到的 JSON 數據。在 PowerShell 6.0 之後，JSON 數據中允許批注。

例如：

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

Foo
---
Bar

警告

從 PowerShell 7.4 開始，Test-Json Cmdlet 不再支援具有批注的 JSON。如果 JSON 包含批注，則會傳回錯誤。在支援的 7.4 之前版本中，Test-Json 成功剖析含有註解的 JSON。在 PowerShell 7.5 中，Test-Json 包含忽略 JSON 批注的選項。

CSV 批注

Import-Csv 和 ConvertFrom-Csv 支援 W3C 擴充記錄格式。以井字號（#）開頭的行會被視為註解並會被忽略，除非註解以 #Fields: 開頭且包含用分隔符分隔的欄位名稱清單。在此情況下，Cmdlet 會使用這些數據行名稱。這是 Windows IIS 和其他網頁伺服器記錄的標準格式。如需詳細資訊，請參閱擴充記錄檔格式。

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

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

在 Windows PowerShell 5.1 中，預設 Export-Csv 和 ConvertTo-Csv 行為是以 #TYPE 批注的形式包含類型資訊。從 PowerShell 6.0 開始，預設不包含註解，但可以使用 IncludeTypeInformation 參數來覆寫。

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

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

當 CSV 資料中包含 #TYPE 批注時，Import-Csv 和 ConvertFrom-Csv 使用此資訊來設定還原串行化物件的 pstypenames 屬性。

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

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

Test
CSV:Test

`ConvertFrom-StringData` 批注

在其字串數據中，ConvertFrom-StringData Cmdlet 會將以 # 開頭的行視為批注。如需詳細資訊，請參閱：

範例 3：轉換包含註解的 here-string

筆記

區塊註解無法嵌套。在下列範例中，Baz 不是批注的一部分。
```
<#
'Foo'
<# 'Bar' #>
'Baz'
#>
```
<# #> 在單行批注內沒有特殊意義。 # 區塊批注內沒有特殊意義。
若要被視為註解，註解字元不可成為非註解標記的一部分。在下列範例中，#Bar 和 <#Bar#> 是 Foo... 令牌的一部分。因此，它們不會被視為批注。
```
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 [...]
```

共用方式為

關於註解

簡短描述

完整描述

PowerShell 批注樣式

例子

範例 1：單行批注

範例 2：封鎖批注

範例 3：行尾批注

範例 4：內嵌區塊註解

範例 5：完整範例

特殊批注

以批注為基礎的說明

`#Requires`

簽章區塊

家當

程式代碼編輯器區域標記

字串標記中的註解

正則表達式註解

JSON 注釋

CSV 批注

`ConvertFrom-StringData` 批注

筆記

其他資源

共用方式為

關於註解

簡短描述

完整描述

PowerShell 批注樣式

例子

範例 1：單行批注

範例 2：封鎖批注

範例 3：行尾批注

範例 4：內嵌區塊註解

範例 5：完整範例

特殊批注

以批注為基礎的說明

#Requires

簽章區塊

家當

程式代碼編輯器區域標記

字串標記中的註解

正則表達式註解

JSON 注釋

CSV 批注

ConvertFrom-StringData 批注

筆記

其他資源

`#Requires`

`ConvertFrom-StringData` 批注