編輯附註
重要
Windows PowerShell 語言規格 3.0 於 2012 年 12 月發行，並以 Windows PowerShell 3.0 為基礎。 此規格不會反映 PowerShell 的目前狀態。 沒有計劃更新此檔以反映目前的狀態。 此文件在此提供作為歷史參考。
規格文件可作為 Microsoft Word 文件從 Microsoft 下載中心取得：https://www.microsoft.com/download/details.aspx?id=36389 此 Word 文件已被轉換，以便在 Microsoft Learn 上呈現。 在轉換期間，已進行一些編輯變更，以配合 Docs 平臺的格式設定。 已修正某些錯字和次要錯誤。
PowerShell 提供一種機制，讓程式設計人員使用特殊批註指示詞來記錄其腳本。 使用這類語法的批註稱為 幫助註釋。 Cmdlet Get-Help 會從這些指令中產生文件。
A.1 簡介
說明批註以 說明指示詞 為形式，名稱 後面接著一或多行的說明內容文字。 幫助註釋可以由一系列 單行註釋或 分隔註釋（§2.2.3）組成。 由單一實體的文件批注組成的集合稱為 說明主題。
例如
# <help-directive-1>
# <help-content-1>
...
# <help-directive-n>
# <help-content-n>
或
<#
<help-directive-1>
<help-content-1>
...
<help-directive-n>
<help-content-n>
#>
說明主題中的所有行都必須是連續的。 如果幫助主題出現在不屬於該主題的註解之後，則兩者之間必須至少有一個空白行。
指示詞可以依任何順序顯示，而某些指示詞可能會多次出現。
指示詞名稱不區分大小寫。
記錄函式時，說明主題可能會出現在三個位置之一：
- 緊接在函式定義之前，函數說明的最後一行與包含函式定義的行之間最多只有一個空白行。
- 在函式主體內，緊接在左花括號之後。
- 在函式的主體內部，緊接在右大括弧之前。
在記錄腳本檔案時，說明主題可能會出現在兩個位置之一：
- 在腳本檔案的開頭，選擇性地前面只加上批註和空白行。 如果腳本說明之後的第一個元素是函式定義，那麼腳本說明結尾與該函式宣告之間必須至少有兩個空白行。 否則，幫助將會被解釋為是套用到函式上的，而不是應用在腳本檔案上。
- 在腳本檔案的結尾。
A.2 協助指令
A.2.1 。描述
語法：
.DESCRIPTION
描述：
此指令允許函數或腳本的詳細描述。 （「.SYNOPSIS 指令」（§A.2.11）適用於簡短描述。） 每個主題中只能使用此指令一次。
例子：
<#
.DESCRIPTION
Computes Base to the power Exponent. Supports non-negative integer
powers only.
#>
A.2.2 。例
語法：
.EXAMPLE
描述：
這個指令允許顯示命令使用範例。
如果這個指令出現多次，每個相關的說明內容區塊將作為獨立的範例顯示。
例子：
<#
.EXAMPLE
Get-Power 3 4
81
.EXAMPLE
Get-Power -Base 3 -Exponent 4
81
#>
A.2.3 。EXTERNALHELP
語法：
.EXTERNALHELP <XMLHelpFilePath>
描述：
這個指令會指定腳本或函式之基於XML的說明檔的路徑。
雖然以批注為基礎的說明更容易實作，但如果需要更精確的說明內容控制，或說明主題要翻譯成多種語言，則需要以 XML 為基礎的說明。 此規格並未定義 XML 型說明的詳細資料。
例子：
<#
.EXTERNALHELP C:\MyScripts\Update-Month-Help.xml
#>
A.2.4 。FORWARDHELPCATEGORY
語法：
.FORWARDHELPCATEGORY <Category>
描述：
指定項目的說明類別於 ForwardHelpTargetName （§A.2.5）。 有效值為 Alias、All、Cmdlet、ExternalScript、FAQ、Filter、函式、一般、詞彙、HelpFile、Provider和 ScriptCommand。 使用這個指令，以避免當命令具有相同名稱時發生衝突。
例子：
請參閱 A.2.5。
A.2.5 。FORWARDHELPTARGETNAME
語法：
.FORWARDHELPTARGETNAME <Command-Name>
描述：
重新導向至 <Command-Name>所指定的幫助主題。
例子：
function Help {
<#
.FORWARDHELPTARGETNAME Get-Help
.FORWARDHELPCATEGORY Cmdlet
#>
...
}
命令 Get-Help help 會被當作 Get-Help Get-Help 處理。
A.2.6 輸入
語法：
.INPUTS
描述：
管線可用來將一或多個物件傳送至腳本或函式。 這項指令是用來描述這類物件及其類型。
如果這個指令多次出現，則會依照指令的字典順序，將每個相關的說明內容區塊收集在一個文件條目中。
例子：
<#
.INPUTS
None. You cannot pipe objects to Get-Power.
.INPUTS
For the Value parameter, one or more objects of any kind can be written
to the pipeline. However, the object is converted to a string before it
is added to the item.
#>
function Process-Thing {
param ( ...
[Parameter(ValueFromPipeline=$true)]
[Object[]]$Value,
...
)
...
}
A.2.7 .連結
語法：
.LINK
描述：
這個指令指定相關主題的名稱。
如果這個指令多次出現，則會依照指令的字典順序，將每個相關的說明內容區塊收集在一個文件條目中。
Link 指示詞內容也可以包含相同說明主題在線版本的 URI。 使用 Online 參數叫用 Get-Help 時，會開啟在線版本。 URI 的開頭必須是 http 或 https。
例子：
<#
.LINK
Online version: http://www.acmecorp.com/widget.html
.LINK
Set-ProcedureName
#>
A.2.8 。筆記
語法：
.NOTES
描述：
這個指令允許提供有關函式或腳本的更多資訊。 每個主題中只能使用此指令一次。
例子：
<#
.NOTES
*arbitrary text goes here*
#>
A.2.9. 輸出
語法：
.OUTPUTS
描述：
這個指令是用來描述命令輸出的對象。
如果這個指令多次出現，則會依照指令的字典順序，將每個相關的說明內容區塊收集在一個文件條目中。
例子：
<#
.OUTPUTS
double - Get-Power returns Base to the power Exponent.
.OUTPUTS
None unless the -PassThru switch parameter is used.
#>
A.2.10。參數
語法：
.PARAMETER <Parameter-Name>
描述：
這個指令允許對指定參數進行詳細描述。 每個參數都可以使用這個指令一次。 參數指示詞可以在批注區塊中以任何順序顯示;不過，來源中實際定義其對應參數的順序會決定參數及其描述出現在結果檔中的順序。
替代格式牽涉到將參數描述批註放在對應參數變數名稱的宣告之前。 如果來源同時包含參數描述批注和 Parameter 指示詞，則會使用與 Parameter 指示詞相關聯的描述。
例子：
<#
.PARAMETER Base
The integer value to be raised to the Exponent-th power.
.PARAMETER Exponent
The integer exponent to which Base is to be raised.
#>
function Get-Power {
param ([long]$Base, [int]$Exponent)
...
}
function Get-Power {
param ([long]
# The integer value to be raised to the Exponent-th power.
$Base,
[int]
# The integer exponent to which Base is to be raised.
$Exponent
)
...
}
A.2.11 。概要
語法：
.SYNOPSIS
描述：
這個指令允許有簡短描述函式或腳本。 （.DESCRIPTION 指令（§A.2.1）是用於詳細說明。） 每個主題中只能使用此指令一次。
例子：
<#
.SYNOPSIS
Computes Base to the power Exponent.
#>
