主題
about_Comment_Based_Help
簡短描述
描述如何撰寫函數和指令碼的註解架構說明主題。
完整描述
您可以藉由使用特殊的說明註解關鍵字，撰寫函數和指令碼的註解架構說明主題。
Get-Help cmdlet 顯示註解架構說明的格式，就跟顯示 XML 檔案所產生的 cmdlet
說明主題格式是相同的。使用者可以使用 Get-Help 的所有參數顯示函數和指令碼說
明，例如 Detailed、Full、Example 和 Online 等參數。
您也可以藉由使用說明註解關鍵字，撰寫指令碼和函數的 XML 架構說明檔，並將使用
者重新導向至其他說明檔。
本主題說明如何撰寫函數和指令碼的說明主題。如需如何顯示函數和指令碼說明主題
的詳細資訊，請參閱 Get-Help。
註解架構說明的語法
註解架構說明的語法如下：
# .< help keyword>
# <help content>
-或-
<#
.< help keyword>
< help content>
#>
註解架構的說明是以一系列的註解撰寫而成的。您可以在每行註解前輸入註解符號
(#)，或是使用 "<#" 和 "#>" 符號建立註解區塊。註解區塊內的所有行都會解譯成
註解。
註解架構說明主題中的所有行都必須是連續的。如果註解架構說明主題跟隨的註解並
不屬於該說明主題，則最後一個非說明註解行和註解架構說明的開頭之間，必須至少
有一行空白。
關鍵字會定義每一節的註解架構說明。每個註解架構說明關鍵字前會加上點號 (.)。
關鍵字可以任何順序出現。而關鍵字的名稱是不區分大小寫的。
例如，Description 關鍵字會出現在函數或指令碼描述的前方。
<#
.Description
Get-Function 會顯示工作階段中所有函數的名稱和語法。
#>
註解區塊必須至少包含一個關鍵字。有些如 EXAMPLE 這類的關鍵字可以在相同註解
區塊中出現許多次。每個關鍵字的說明內容是從關鍵字後的下一行開始，並且可以
跨越多行。
函數中註解架構說明的語法
函數的註解架構說明可以出現在三個位置之中：
-- 函數主體的開頭。
-- 函數主體的結尾。
-- Function 關鍵字之前。在函數說明最後一行和 Function 關鍵字之間，不能
有超過一行以上的空白。
例如：
function MyFunction
{
<#
.< help keyword>
< help content>
#>
<function commands>
}
-或-
function MyFunction
{
<function commands>
<#
.< help keyword>
< help content>
#>
}
-或-
<#
.< help keyword>
< help content>
#>
function MyFunction { }
指令碼中註解架構說明的語法
指令碼的註解架構說明可以出現在指令碼的下列兩個位置之中：
-- 指令檔的開頭。指令碼中的指令碼說明前方只能有註解和空白行。
-- 如果指令碼主體 (位於說明後方) 中的第一個項目是函數宣告，則指令碼說明的
結尾和函數宣告之間，必須至少要有兩行空白。否則就會將說明解譯為函數的說
明，而非指令碼的說明。
-- 指令檔的結尾。
例如：
<#
.< help keyword>
< help content>
#>
function MyFunction { }
-或-
function MyFunction { }
<#
.< help keyword>
< help content>
#>
註解架構說明關鍵字
下列為有效的註解架構說明的關鍵字。排列的順序是依據其通常會出現在說明主題中
的順序，並列出其用途。
這些關鍵字在註解架構說明中可以任何順序出現，並且不區分大小寫。
.SYNOPSIS
函數或指令碼的簡短描述。這個關鍵字在每個主題中僅能使用一次。
.DESCRIPTION
函數或指令碼的詳細描述。這個關鍵字在每個主題中僅能使用一次。
.PARAMETER <參數-名稱>
參數的描述。函數或指令碼語法中的每個參數可以包含一個 Parameter 關鍵字。
Parameter 關鍵字在註解區塊中可以任何順序出現，但函數或指令碼語法會決定
參數 (和其描述) 在說明主題中出現的順序。若要變更順序，則請變更語法。
您也可以藉由將函數或指令碼語法中的註解緊接著放置在參數變數名稱之前，
即可指定參數描述。如果您同時使用語法註解和 Parameter 關鍵字，則會
使用與 Parameter 關鍵字相關聯的描述，而忽略語法註解。
.EXAMPLE
會使用函數或指令碼的範例命令，後面可選擇性跟隨著範例輸出和描述。
請針對每個範例重複這個關鍵字。
.INPUTS
可經由管道輸出至函數或指令碼之物件的 Microsoft .NET Framework 型別。您
也可以加入輸入物件的描述。
.OUTPUTS
Cmdlet 傳回之物件的 .NET Framework 型別。您也可以加入所傳回物件的描述。
.NOTES
函數或指令碼的其他相關資訊。
.LINK
相關主題的名稱。請針對每個相關主題重複這個關鍵字。
這些內容會出現在說明主題的＜相關連結＞一節中。
Link 關鍵字內容也可包含同一說明主題線上版本的統一資源識別項 (URI)。線
上版本會在您使用 Get-Help 的 Online 參數時開啟。
URI 必須以 "http" 或 "https" 做為開頭。
.COMPONENT
函數或指令碼所使用的技術或功能，或者是相關的技術或功能。這些內容會
在 Get-Help 命令包含 Get-Help 的 Component 參數時開啟。
.ROLE
說明主題的使用者角色。這些內容會在 Get-Help 命令包含 Get-Help 的 Role
參數時開啟。
.FUNCTIONALITY
函數的設計用途。這些內容會在 Get-Help 命令包含 Get-Help 的 Functionality
參數時開啟。
.FORWARDHELPTARGETNAME <Command-Name>
重新導向至指定命令的說明主題。您可以將使用者重新導向至任何說明主題，
包含函數、指令碼、cmdlet 或提供者的說明主題。
.FORWARDHELPCATEGORY <Category>
指定 ForwardHelpTargetName 中項目的說明分類。
有效值為 Alias、Cmdlet、HelpFile、Function、Provider、General、FAQ、
Glossary、ScriptCommand、ExternalScript、Filter 或 All。
使用這個關鍵字可以在多個命令具有相同名稱時避免發生衝突。
.REMOTEHELPRUNSPACE <PSSession-variable>
指定包含說明主題的工作階段。請輸入包含 PSSession 的變數。這個關鍵字是由
Export-PSSession cmdlet 用來找出所匯出命令的說明主題。
.EXTERNALHELP <XML Help File Path>
指定指令碼或函數的 XML 架構說明檔的路徑。
在 Windows Vista 和較新版本的 Windows 中，如果 XML 檔案的指定路徑包含
UI-culture-specific 子目錄，則 Get-Help 會使用指令碼或函數名稱，在子目
錄中遞迴搜尋 XML 檔案，並按照針對 Windows Vista 建立的語言後援標準進
行，就如同針對所有 XML 架構說明主題所進行的方式。
如需 Cmdlet 說明之 XML 架構說明檔案格式的詳細資訊，請參閱
MSDN (Microsoft Developer Network) 文件庫中的＜如何建立 Cmdlet
說明＞(英文)，網址為：https://go.microsoft.com/fwlink/?LinkId=123415。
自動產生的內容
名稱、語法、參數清單、參數屬性表格、一般參數和註解，是由 Get-Help cmdlet
自動產生的。
名稱：
函數說明主題的 Name 區段是取自於函數語法中的函數名稱。指令碼說明主
題的 Name 是取自於指令檔名稱。若要變更名稱或其大小寫，請變更函數語
法或指令檔名稱。
語法：
說明主題的 Syntax 區段是從函數或指令碼語法所產生的。若要對說明主題
語法新增詳細資料，例如參數的 .NET Framework 型別，請將詳細資料新增
至語法。如果沒有指定參數型別，就會插入 "Object" 型別做為預設值。
參數清單：
說明主題的參數清單產生來源，是函數或指令碼語法以及您使用 Parameters
關鍵字而新增的描述。說明主題 “Parameters” 區段中的函數參數出現順
序，跟在函數或指令碼語法中的順序相同。參數名稱的拼字和大小寫也是從
語法取得的，並不會受到 Parameter 關鍵字所指定參數名稱的影響。
一般參數：
在說明主題的語法和參數清單中會加入一般參數，即使這些參數沒有任何作
用也一樣。如需一般參數的詳細資訊，請參閱 about_CommonParameters。
參數屬性表格：
Get-Help 所產生的參數屬性表格，會在您使用 Get-Help 的 Full 或
Parameter 參數時出現。Required、Position 和 Default 屬性的值，
是從函數或指令碼語法取得的。
註解：
說明主題的 Remarks 區段是從函數或指令碼名稱自動產生的。您無法變更
或影響其內容。
範例
範例 1：函數的註解架構說明
下列範例函數包含註解架構的說明：
function Add-Extension
{
param ([string]$Name,[string]$Extension = "txt")
$name = $name + "."+ $extension
$name
<#
.SYNOPSIS
對提供的名稱加上副檔名。
.DESCRIPTION
對提供的名稱加上副檔名。針對檔名或副檔名採用任何字串。
.PARAMETER Name
指定檔名。
.PARAMETER Extension
指定副檔名。預設為 "Txt"。
.INPUTS
無。您無法經由管道將物件輸出至 Add-Extension。
.OUTPUTS
System.String：Add-Extension 會傳回具有副檔名或檔名的字串。
.EXAMPLE
C:\PS> extension -name "File"
File.txt
.EXAMPLE
C:\PS> extension -name "File" -extension "doc"
File.doc
.EXAMPLE
C:\PS> extension "File" "doc"
File.doc
.LINK
線上版本：http://www.fabrikam.com/extension.html
.LINK
Set-Item
#>
}
結果如下：
C:\PS> get-help add-extension -full
名稱
Add-Extension
概要
對提供的名稱加上副檔名。
語法
Add-Extension [[-Name] <String>] [[-Extension] <String>]
[<CommonParameters>]
描述
對提供的名稱加上副檔名。針對檔名或副檔名採用任何字串。
參數
-Name
指定檔名。
必要? false
位置? 0
預設值
接受管線輸入? false
接受萬用字元?
-Extension
指定副檔名。預設為 "Txt"。
必要? false
位置? 1
預設值
接受管線輸入? false
接受萬用字元?
<CommonParameters>
這個 Cmdlet 支援一般參數：-Verbose、-Debug、ErrorAction、
-ErrorVariable、-WarningAction、-WarningVariable、
OutBuffer 和 -OutVariable。
如需詳細資訊，請輸入 "get-help about_commonparameters"。
輸入
無。您無法經由管道將物件輸出至 Add-Extension。
輸出
System.String：Add-Extension 會傳回具有副檔名或檔名的字串。
-------------------------- 範例 1 --------------------------
C:\PS> extension -name "File"
File.txt
-------------------------- 範例 2 --------------------------
C:\PS> extension -name "File" -extension "doc"
File.doc
-------------------------- 範例 3 --------------------------
C:\PS> extension "File" "doc"
File.doc
相關連結
線上版本：http://www.fabrikam.com/extension.html Set-Item
範例 2：函數語法中的參數描述
除了在函數語法中插入參數描述之外，這個範例與前一個範例是相同的。
在描述很簡短的情況下，這個格式最為好用。
function Add-Extension
{
param
(
[string]
# 指定檔名。
$name,
[string]
# 指定副檔名。預設為 "Txt"。
$extension = "txt"
)
$name = $name + "."+ $extension
$name
<#
.SYNOPSIS
對提供的名稱加上副檔名。
.DESCRIPTION
對提供的名稱加上副檔名。針對檔名或副檔名採用任何字串。
.INPUTS
無。您無法經由管道將物件輸出至 Add-Extension。
.OUTPUTS
System.String：Add-Extension 會傳回具有副檔名或檔名的字串。
.EXAMPLE
C:\PS> extension -name "File"
File.txt
.EXAMPLE
C:\PS> extension -name "File" -extension "doc"
File.doc
.EXAMPLE
C:\PS> extension "File" "doc"
File.doc
.LINK
線上版本：http://www.fabrikam.com/extension.html
.LINK
Set-Item
#>
}
範例 3：指令碼的註解架構說明
下列範例指令碼包含註解架構的說明。
請注意，在結尾 "#>" 和 Param 陳述式之間的空白行。如果指令碼沒有 Param
陳述式，則在說明主題最後一個註解和第一個函數宣告之間，必須至少要有兩
行空白行。沒有這些空白行的話，Get-Help 會將說明主題與函數建立關聯，
而非指令碼。
<#
.SYNOPSIS
執行每月資料更新。
.DESCRIPTION
Update-Month.ps1 指令碼會使用上個月間產生的新資料更新登錄，並產生
報告。
.PARAMETER InputPath
指定 CSV 架構輸入檔的路徑。
.PARAMETER OutputPath
指定 CSV 架構輸出檔的名稱和路徑。根據預設，MonthlyUpdates.ps1 會依
據執行的日期和時間產生名稱，並將輸出儲存在本機目錄中。
.INPUTS
無。您無法經由管道將物件輸出至 Update-Month.ps1。
.OUTPUTS
無。Update-Month.ps1 不會產生任何輸出。
.EXAMPLE
C:\PS> .\Update-Month.ps1
.EXAMPLE
C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv
.EXAMPLE
C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv -outputPath C:\Reports\2009\January.csv
#>
param ([string]$InputPath, [string]$OutPutPath)
function Get-Data { }
...
下列命令會取得指令碼說明。因為指令碼所在的目錄沒有列在 Path 環境變數
中，所以要取得該指令碼說明的 Get-Help 命令必須指定指令碼路徑。
PS C:\ps-test> get-help .\update-month.ps1 -full
NAME
C:\ps-test\Update-Month.ps1
SYNOPSIS
執行每月資料更新。
語法
C:\ps-test\Update-Month.ps1 [-InputPath] <String>
[[-OutputPath] ]<String>] [<CommonParameters>]
DESCRIPTION
Update-Month.ps1 指令碼會使用上個月間產生的新資料更新登錄，並
產生報告。
PARAMETERS
-InputPath
指定 CSV 架構輸入檔的路徑。
必要? true
位置? 0
預設值
接受管線輸入? false
接受萬用字元?
-OutputPath
指定 CSV 架構輸出檔的名稱和路徑。根據預設，
MonthlyUpdates.ps1 會依據執行的日期和時間產生名稱，
並將輸出儲存在本機目錄中。
必要? false
位置? 1
預設值
接受管線輸入? false
接受萬用字元?
<CommonParameters>
這個 Cmdlet 支援一般參數：-Verbose、-Debug、ErrorAction、
-ErrorVariable、-WarningAction、-WarningVariable、
OutBuffer 和 -OutVariable。
如需詳細資訊，請輸入 "get-help about_commonparameters"。
INPUTS
無。您無法經由管道將物件輸出至 Update-Month.ps1。
OUTPUTS
無。Update-Month.ps1 不會產生任何輸出。
-------------------------- 範例 1 --------------------------
C:\PS> .\Update-Month.ps1
-------------------------- 範例 2 --------------------------
C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv
-------------------------- 範例 3 --------------------------
C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv -outputPath
C:\Reports\2009\January.csv
相關連結
範例 4：重新導向至 XML 檔案
您可以為函數和指令碼撰寫 XML 架構的說明主題。雖然註解架構的說明比較容
易實作，但是在您想要對說明內容進行更精準的控制，或是在您要將說明主題
翻譯成多種語言時，就需要 XML 架構的說明。
下列範例顯示 Update-Month.ps1 指令碼的前幾行。該指令碼使用
ExternalHelp 關鍵字指定指令碼的 XML 架構說明主題路徑。
# .ExternalHelp C:\MyScripts\Update-Month-Help.xml
param ([string]$InputPath, [string]$OutPutPath)
function Get-Data { }
...
下列範例示範函數中的 ExternalHelp 關鍵字使用。
function Add-Extension
{
param ([string] $name, [string]$extension = "txt")
$name = $name + "."+ $extension
$name
# .ExternalHelp C:\ps-test\Add-Extension.xml
}
範例 5：重新導向至其他說明主題
下列程式碼摘錄自 Windows PowerShell 內建的 Help 函數的開頭，其每次會
顯示一個畫面的說明文字。因為 Get-Help cmdlet 的說明主題會描述 Help
函數，所以Help 函數使用 ForwardHelpTargetName 和 ForwardHelpCategory
關鍵字，將使用者重新導向至 Get-Help cmdlet 說明主題。
function help
{
<#
.FORWARDHELPTARGETNAME Get-Help
.FORWARDHELPCATEGORY Cmdlet
#>
[CmdletBinding(DefaultParameterSetName='AllUsersView')]
param(
[Parameter(Position=0, ValueFromPipelineByPropertyName=$true)]
[System.String]
${Name},
...
下列命令使用這個功能：
C:\PS> get-help help
NAME
Get-Help
SYNOPSIS
顯示 Windows PowerShell Cmdlet 和概念的相關資訊。
...
請參閱
about_Functions
about_Functions_Advanced_Parameters
about_Scripts
如何撰寫 Cmdlet 說明 (https://go.microsoft.com/fwlink/?LinkID=123415)