about_Comment_Based_Help
適用於: Windows PowerShell 2.0, Windows PowerShell 3.0
在此插入簡介。
主題
about_Comment_Based_Help
簡短描述
說明如何撰寫函式和指令碼的以註解為基礎的說明主題。
詳細描述
您可以使用特殊說明註解關鍵字來撰寫函式和指令碼的以註解為基礎的說明主題。
Get-Help Cmdlet 會以顯示從 XML 檔案產生的 Cmdlet 說明主題的相同格式，顯示以註解為基礎的說明。使用者可以使用 Get-Help 的所有參數，例如 Detailed、Full、Example 和 Online，顯示以註解為基礎的說明內容。
您也可以撰寫函式和指令碼的以 XML 為基礎的說明檔。若要啟用 Get-Help Cmdlet 來尋找函式或指令碼的以 XML 為基礎的說明檔，請使用 ExternalHelp 關鍵字。沒有這個關鍵字，Get-Help 就找不到函式或指令碼的以 XML 為基礎的說明主題。
本主題說明如何撰寫函式和指令碼的說明主題。如需有關如何顯示函式和指令碼的說明主題的詳細資訊，請參閱 Get-Help。
注意：
Update-Help 和 Save-Help Cmdlet 只能在 XML 檔案上運作。可更新的說明不支援以註解為基礎的說明主題。
疑難排解附註：
即使已在函式或指令碼中定義，預設值和「接受萬用字元」值未出現在參數屬性表格。若要協助使用者，請在參數描述中提供這項資訊。
以註解為基礎之說明的語法
以註解為基礎之說明的語法如下所示：
# .< help keyword>
# <help content>
-or -
<#
.< help keyword>
< help content>
#>
以註解為基礎的說明會被撰寫為一連串的註解。您可以在每一行註解之前輸入註解符號 (#)，或者可以使用 "<#" 和 "#>" 符號來建立註解區塊。註解區塊內的所有行都會解譯成註解。
以註解為基礎的說明主題中的所有行必須是連續的。如果以註解為基礎的說明主題後面接續的註解不是說明主題的一部分，最後一個非說明註解行與以註解為基礎的說明的開頭之間必須有至少一列空白行。
關鍵字會定義以註解為基礎之說明的每個區段。每個以註解為基礎的說明關鍵字前面是點 (.)。關鍵字可以任何順序出現。關鍵字名稱不區分大小寫。
例如，Description 關鍵字會位於函式或指令碼的描述之前。
<#
.Description
Get-Function displays the name and syntax of all functions in the session.
#>
註解區塊必須包含至少一個關鍵字。某些關鍵字，例如 EXAMPLE，可以在相同的註解區塊中出現多次。每個關鍵字的說明內容會在關鍵字後面一行開始，並且可以跨越多行。
函式中以註解為基礎之說明的語法
函式的以註解為基礎的說明可以出現在三個位置其中之一：
-- At the beginning of the function body.
-- At the end of the function body.
-- Before the Function keyword. There cannot be more than one blank
line between the last line of the function help and the Function
keyword.
例如：
function Get-Function
{
<#
.< help keyword>
< help content>
#>
<function commands>
}
-or -
function Get-Function
{
<function commands>
<#
.< help keyword>
< help content>
#>
}
-or -
<#
.< help keyword>
< help content>
#>
function Get-Function { }
指令碼中以註解為基礎之說明的語法
指令碼的以註解為基礎的說明可以出現在指令碼中下列兩個位置其中之一。
-- At the beginning of the script file. Script help can be preceded in the
script only by comments and blank lines.
-- If the first item in the script body (after the help) is a function
declaration, there must be at least two blank lines between the end of the
script help and the function declaration. Otherwise, the help is
interpreted as being help for the function, not help for the script.
-- At the end of the script file. However, if the script is signed, place
Comment-based help at the beginning of the script file. The end of the
script is occupied by the signature block.
例如：
<#
.< help keyword>
< help content>
#>
function Get-Function { }
-or-
function Get-Function { }
<#
.< help keyword>
< help content>
#>
指令碼模組中以註解為基礎之說明的語法
在指令碼模組 (.psm1) 中，以註解為基礎的說明會使用函式的語法，而不是指令碼的語法。您無法使用指令碼語法以針對指令碼模組中定義的所有函式提供說明。
例如，如果您使用 ExternalHelp 關鍵字來識別指令碼模組中函式的以 XML 為基礎的說明檔，您必須將 ExternalHelp 註解新增至每個函式。
# .ExternalHelp <XML-file-name>
function <function-name>
{
...
}
以註解為基礎的說明關鍵字
以下是有效的以註解為基礎的說明關鍵字。它們是以通常在說明主題中出現的順序列出，同時列出其用途。這些關鍵字可以任何順序出現在以註解為基礎的說明中，並且不會區分大小寫。
.SYNOPSIS
函式或指令碼的簡短描述。這個關鍵字只能在每個主題中使用一次。
.DESCRIPTION
函式或指令碼的詳細描述。這個關鍵字只能在每個主題中使用一次。
.PARAMETER <Parameter-Name>
參數的描述。針對函式或指令碼語法中的每個參數新增 .PARAMETER 關鍵字。
在 .PARAMETER 關鍵字的同一行上輸入參數名稱。在 .PARAMETER 關鍵字後面的行上輸入參數描述。Windows PowerShell 會將 .PARAMETER 行和下一個關鍵字或註解區塊結尾之間的所有文字解譯為參數描述的一部分。描述可以包含分段。
Parameter 關鍵字可以任何順序出現在註解區塊，但是函式或指令碼語法會決定參數 (和它們的描述) 出現在說明主題中的順序。若要變更順序，請變更語法。
您也可以立即將註解放在函式或指令碼語法中的參數變數名稱前面，指定參數描述。如果您同時使用語法註解和 Parameter 關鍵字，則會使用與 Parameter 關鍵字相關聯的描述，且會略過語法註解。
.EXAMPLE
使用函式或指令碼的範例命令，並會選擇性地接續著範例輸出和描述。針對每個範例重複這個關鍵字。
.INPUTS
可以輸送到函式或指令碼的 Microsoft .NET Framework 類型物件。您也可以包含輸入物件的描述。
.OUTPUTS
Cmdlet 傳回的 .NET Framework 類型物件。您也可以包含傳回物件的描述。
.NOTES
函式或指令碼的其他資訊。
.LINK
相關主題的名稱。此值會顯示在 .LINE 關鍵字底下的行上，前面必須有註解符號 (#) 或包含在註解區塊。
對每個相關主題重複 .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 中項目的說明類別。有效值為別名、Cmdlet、說明檔案、函式、提供者、一般、常見問題集、詞彙、ScriptCommand、ExternalScript、篩選或所有。使用此關鍵字來避免當命令具有相同名稱時的衝突。
.REMOTEHELPRUNSPACE <PSSession-variable>
指定包含說明主題的工作階段。輸入包含 PSSession 的變數。此關鍵字是 Export-PSSession Cmdlet 用來尋找匯出之命令的說明主題。
.EXTERNALHELP <XML Help File>
指定指令碼或函式的以 XML 為基礎的說明檔。
當函式或指令碼記載於 XML 檔案中時需要 ExternalHelp 關鍵字。沒有這個關鍵字，Get-Help 就找不到函式或指令碼的以 XML 為基礎的說明檔。
ExternalHelp 關鍵字的優先順序高於其他以註解為基礎的說明關鍵字。如果有 ExternalHelp，Get-help 就不會顯示以註解為基礎的說明，即使它找不到符合 ExternalHelp 關鍵字值的說明主題。
如果函式是由模組匯出，則將 ExternalHelp 關鍵字的值設為不包含路徑的檔案名稱。Get-Help 會在模組目錄的特定語言子目錄中尋找指定的檔案名稱。函式的以 XML 為基礎的說明檔名稱並沒有特別要求，但是最佳做法是使用下列格式：
<ScriptModule.psm1>-help.xml
如果函式未包含在模組中，則將路徑包含至以 XML 為基礎的說明檔。如果值包含路徑且路徑包含 UI 文化特性特有的子目錄，則 Get-Help 會遞迴地在子目錄中搜尋具有指令碼或函式之名稱的 XML 檔案，該名稱符合針對 Windows 建立的語言後援標準，就像它在模組目錄中所做的一樣。
如需 Cmdlet 說明以 XML 為基礎的說明檔案格式的詳細資訊，請參閱 MSDN (Microsoft Developer Network) 文件庫中的＜如何建立 Cmdlet 說明＞，網址為 https://go.microsoft.com/fwlink/?LinkID=123415。
自動產生的內容
Get-Help Cmdlet 會自動產生名稱、語法、參數清單、參數屬性表格、一般參數和備註。
名稱：
函式說明主題的 [名稱] 區段是取自函式語法中的函式名稱。指令碼說明主題的 [名稱] 是取自指令碼檔案名稱。若要變更名稱或其大小寫，請變更函式語法或指令碼檔案名稱。
語法：
說明主題的 [語法] 區段是從函式或指令碼語法產生。若要將詳細資料新增至說明主題語法，例如參數的 .NET Framework 類型，請將詳細資料新增至語法。如果您未指定參數類型，「物件」類型會插入作為預設值。
參數清單：
說明主題中的 [參數] 清單是從函式或指令碼語法和您使用 Parameters 關鍵字新增的描述所產生。函式參數會出現在說明主題的 [參數] 區段中，顯示順序與它們出現在函式或指令碼語法的順序相同。參數名稱的拼字和大小寫也是取自語法。不會受到 Parameter 關鍵字所指定的參數名稱影響。
一般參數：
即使一般參數沒有任何作用，仍會將它們新增至說明主題的語法和參數清單。如需一般參數的詳細資訊，請參閱 about_CommonParameters。
參數屬性表格：
Get-Help 會產生參數屬性的表格，該表格會在您使用 Get-help 的 Full 或 Parameter 參數時顯示。Required、Position 和 Default 值屬性的值是取自函式或指令碼語法。
疑難排解附註：
Default 值不會出現在參數屬性表格中，即使它們已在函式或指令碼中定義也是如此。若要協助使用者，請在參數描述中列出預設值。
備註：
說明主題的 [備註] 區段是從函式或指令碼名稱自動產生。您無法變更或影響其內容。
停用以註解為基礎的說明
[這項技術是由紐約州紐約市的 Windows 工程師 Rich Prescott 所建議]。
您可以停用以註解為基礎的說明。這樣會讓以註解為基礎的說明無效而不用刪除它。
若要停用以註解為基礎的說明，在 here-string 中括住註解。若要隱藏 here-string，將它指派給變數或將它輸送到 Out-Null Cmdlet。
當它停用時，以註解為基礎的說明就沒有任何作用。
例如，下列函式具有以註解為基礎的說明。
<#
.SYNOPSIS
Adds a file name extension to a supplied name.
#>
function Add-Extension
{
param ([string]$Name,[string]$Extension = "txt")
...
}
若要停用以註解為基礎的說明，請以 here-string 將它括起來，如下列範例所示。
@"
<#
.SYNOPSIS
Adds a file name extension to a supplied name.
#>
"@
function Add-Extension
{
param ([string]$Name,[string]$Extension = "txt")
...
}
若要隱藏已停用的以註解為基礎的說明，請將 here-string 指派給不在函式中使用的本機變數，如下列範例所示。您也可以將它輸送到 Out-Null Cmdlet。
$x = @"
<#
.SYNOPSIS
Adds a file name extension to a supplied name.
#>
"@
function Add-Extension
{
param ([string]$Name,[string]$Extension = "txt")
...
}
如需 here-string 的詳細資訊，請參閱 about_Quoting_Rules (https://go.microsoft.com/fwlink/?LinkID=113253)。
範例
範例 1：函式的以註解為基礎的說明
下列範例函式包含以註解為基礎的說明：
function Add-Extension
{
param ([string]$Name,[string]$Extension = "txt")
$name = $name + "." + $extension
$name
<#
.SYNOPSIS
Adds a file name extension to a supplied name.
.DESCRIPTION
Adds a file name extension to a supplied name.
Takes any strings for the file name or extension.
.PARAMETER Name
Specifies the file name.
.PARAMETER Extension
Specifies the extension. "Txt" is the default.
.INPUTS
None. You cannot pipe objects to Add-Extension.
.OUTPUTS
System.String. Add-Extension returns a string with the extension or file name.
.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
NAME
Add-Extension
SYNOPSIS
Adds a file name extension to a supplied name.
SYNTAX
Add-Extension [[-Name] <String>] [[-Extension] <String>] [<CommonParameters>]
DESCRIPTION
Adds a file name extension to a supplied name. Takes any strings for the file name or extension.
PARAMETERS
-Name
Specifies the file name.
Required? false
Position? 0
Default value
Accept pipeline input? false
Accept wildcard characters?
-Extension
Specifies the extension. "Txt" is the default.
Required? false
Position? 1
Default value
Accept pipeline input? false
Accept wildcard characters?
<CommonParameters>
This cmdlet supports the common parameters: -Verbose, -Debug,
-ErrorAction, -ErrorVariable, -WarningAction, -WarningVariable,
-OutBuffer and -OutVariable. For more information, type
"get-help about_commonparameters".
INPUTs
None. You cannot pipe objects to Add-Extension.
OUTPUTS
System.String. Add-Extension returns a string with the extension or file name.
-------------------------- EXAMPLE 1 --------------------------
C:\PS> extension -name "File"
File.txt
-------------------------- EXAMPLE 2 --------------------------
C:\PS> extension -name "File" -extension "doc"
File.doc
-------------------------- EXAMPLE 3 --------------------------
C:\PS> extension "File" "doc"
File.doc
RELATED LINKS
http://www.fabrikam.com/extension.html
Set-Item
範例 2：函式語法中的參數描述
這個範例與上一個範例相同，不同之處在於函式語法中插入參數描述。此格式在描述簡短時十分實用。
function Add-Extension
{
param
(
[string]
# Specifies the file name.
$name,
[string]
# Specifies the file name extension. \"Txt\" is the default.
$extension = "txt"
)
$name = $name + "." + $extension
$name
<#
.SYNOPSIS
Adds a file name extension to a supplied name.
.DESCRIPTION
Adds a file name extension to a supplied name. Takes any strings for the file name or extension.
.INPUTS
None. You cannot pipe objects to Add-Extension.
.OUTPUTS
System.String. Add-Extension returns a string with the extension or file name.
.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
Performs monthly data updates.
.DESCRIPTION
The Update-Month.ps1 script updates the registry with new data generated
during the past month and generates a report.
.PARAMETER InputPath
Specifies the path to the CSV-based input file.
.PARAMETER OutputPath
Specifies the name and path for the CSV-based output file. By default,
MonthlyUpdates.ps1 generates a name from the date and time it runs, and
saves the output in the local directory.
.INPUTS
None. You cannot pipe objects to Update-Month.ps1.
.OUTPUTS
None. Update-Month.ps1 does not generate any output.
.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
Performs monthly data updates.
SYNTAX
C:\ps-test\Update-Month.ps1 [-InputPath] <String> [[-OutputPath]
<String>] [<CommonParameters>]
DESCRIPTION
The Update-Month.ps1 script updates the registry with new data
generated during the past month and generates a report.
PARAMETERS
-InputPath
Specifies the path to the CSV-based input file.
Required? true
Position? 0
Default value
Accept pipeline input? false
Accept wildcard characters?
-OutputPath
Specifies the name and path for the CSV-based output file. By
default, MonthlyUpdates.ps1 generates a name from the date
and time it runs, and saves the output in the local directory.
Required? false
Position? 1
Default value
Accept pipeline input? false
Accept wildcard characters?
<CommonParameters>
This cmdlet supports the common parameters: -Verbose, -Debug,
-ErrorAction, -ErrorVariable, -WarningAction, -WarningVariable,
-OutBuffer and -OutVariable. For more information, type,
"get-help about_commonparameters".
INPUTS
None. You cannot pipe objects to Update-Month.ps1.
OUTPUTS
None. Update-Month.ps1 does not generate any output.
-------------------------- EXAMPLE 1 --------------------------
C:\PS> .\Update-Month.ps1
-------------------------- EXAMPLE 2 --------------------------
C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv
-------------------------- EXAMPLE 3 --------------------------
C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv -outputPath
C:\Reports\2009\January.csv
RELATED LINKS
範例 4：重新導向至 XML 檔案
您可以撰寫函式和指令碼的以 XML 為基礎的說明主題。雖然以註解為基礎的說明比較容易實作，但若要提供可更新的說明以及多種語言的說明主題，就必須使用以 XML 為基礎的說明。
下列範例顯示 Update-Month.ps1 指令碼的前幾行。指令碼會使用 ExternalHelp 關鍵字來指定指令碼以 XML 為基礎的說明主題的路徑。
請注意，ExternalHelp 關鍵字的值會出現在關鍵字的同一行。任何其他位置無效。
# .ExternalHelp C:\MyScripts\Update-Month-Help.xml
param ([string]$InputPath, [string]$OutPutPath)
function Get-Data { }
...
下列範例顯示 ExternalHelp 關鍵字在函式中的三個有效位置。
function Add-Extension
{
# .ExternalHelp C:\ps-test\Add-Extension.xml
param ([string] $name, [string]$extension = "txt")
$name = $name + "." + $extension
$name
}
function Add-Extension
{
param ([string] $name, [string]$extension = "txt")
$name = $name + "." + $extension
$name
# .ExternalHelp C:\ps-test\Add-Extension.xml
}
# .ExternalHelp C:\ps-test\Add-Extension.xml
function Add-Extension
{
param ([string] $name, [string]$extension = "txt")
$name = $name + "." + $extension
$name
}
範例 5：重新導向至不同的說明主題
下列程式碼是摘錄自 Windows PowerShell 內建說明函式的開頭，一次顯示一個說明文字的畫面。因為 Get-Help Cmdlet 的說明主題會描述說明函式，說明函式使用 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
Displays information about Windows PowerShell cmdlets and concepts.
...
關鍵字
about_Comment-Based_Help
另請參閱
about_Functions
about_Functions_Advanced_Parameters
about_Scripts
＜如何撰寫 Cmdlet 說明＞(https://go.microsoft.com/fwlink/?LinkID=123415)