about_Comment_Based_Help

發行項
03/20/2024

簡短描述

描述如何撰寫函式和腳本的批註型說明主題。

詳細描述

您可以使用特殊的說明批註關鍵詞，撰寫函式和腳本的批註型說明主題。

Get-Help Cmdlet 會以相同格式顯示批注型說明，其中會顯示從 XML 檔案產生的 Cmdlet 說明主題。使用者可以使用的所有參數 Get-Help，例如詳細、完整、範例和在線，來顯示以批注為基礎的說明內容。

您也可以為函式和文稿撰寫以 XML 為基礎的說明檔。若要讓 Get-Help Cmdlet 尋找函式或腳本的 XML 型說明檔，請使用 .ExternalHelp 關鍵詞。如果沒有這個關鍵詞， Get-Help 則找不到函式或腳本的 XML 型說明主題。

本主題說明如何撰寫函式和腳本的說明主題。如需如何顯示函式和腳本說明主題的詳細資訊，請參閱 Get-Help。

Update-Help 和 Save-Help Cmdlet 僅適用於 XML 檔案。可更新的說明不支援以批注為基礎的說明主題。

以批注為基礎的說明語法

批注型說明的語法如下：

# .<help keyword>
# <help content>

或

<#
.<help keyword>
<help content>
#>

以批注為基礎的說明會撰寫成一系列批注。您可以在每行批註之前輸入批注符號 # ，也可以使用 <# 和 #> 符號來建立批注區塊。批注區塊中的所有行都會解譯為批註。

以批注為基礎的說明主題中的所有行都必須是連續的。如果以批注為基礎的幫助主題遵循不屬於說明主題的批注，則最後一個非說明批注行與批注型說明開頭之間必須至少有一個空白行。

關鍵詞會定義以批注為基礎的說明的每個區段。每個以批註為基礎的說明關鍵字前面都會加上一個點 .。關鍵詞可以依任何順序顯示。關鍵詞名稱不區分大小寫。

例如， .Description 關鍵詞在函數或腳本的描述之前。

<#
.Description
Get-Function displays the name and syntax of all functions in the session.
#>

批注區塊至少必須包含一個關鍵詞。某些關鍵詞，例如 .EXAMPLE，可以在相同的批注區塊中出現多次。每個關鍵詞的說明內容都會在關鍵詞之後的行開始，而且可以跨越多行。

函式中以批注為基礎的說明語法

函式的批註型說明可以出現在三個位置的其中一個：

函式主體的開頭。
在函式主體的結尾。
在 function 關鍵詞之前。函數說明的最後一行與 function 關鍵詞之間不能有一個以上的空白行。

例如：

function Get-Function
{
<#
.<help keyword>
<help content>
#>

  # function logic
}

或

function Get-Function
{
   # function logic

<#
.<help keyword>
<help content>
#>
}

或

<#
.<help keyword>
<help content>
#>
function Get-Function { }

腳本中以批注為基礎的說明語法

腳本的批註型說明可以出現在腳本的下列兩個位置之一。

在腳本檔案的開頭。腳本說明只能在腳本前面加上批註和空白行。

如果腳本主體中的第一個專案（說明之後）是函式宣告，腳本說明結尾與函式宣告之間必須至少有兩個空白行。否則，說明會解譯為函式的說明，而不是腳本的說明。
在腳本檔案的結尾。不過，如果腳本已簽署，請將批註型說明放在腳本檔案的開頭。腳本的結尾是由簽章區塊所佔用。

例如：

<#
.<help keyword>
<help content>
#>


function Get-Function { }

或

function Get-Function { }

<#
.<help keyword>
<help content>
#>

腳本模組中以批註為基礎的說明語法

在腳本模組 .psm1中，以批註為基礎的說明會使用函式的語法，而不是腳本的語法。您無法使用文稿語法來提供文稿模組中定義之所有函式的說明。

例如，如果您使用 .ExternalHelp 關鍵詞來識別腳本模組中函式的 XML 說明檔，則必須將批註新增 .ExternalHelp 至每個函式。

# .ExternalHelp <XML-file-name>
function <function-name>
{
  ...
}

以批注為基礎的說明關鍵詞

以下是以批注為基礎的有效說明關鍵詞。它們會依其通常會出現在說明主題中以及其預定用途的順序列出。這些關鍵詞可以依批注型說明的任何順序顯示，而且不會區分大小寫。

.SYNOPSIS

函式或腳本的簡短描述。每個主題中只能使用此關鍵詞一次。

.DESCRIPTION

函式或腳本的詳細描述。每個主題中只能使用此關鍵詞一次。

.PARAMETER

參數的描述。 .PARAMETER在函式或腳本語法中新增每個參數的關鍵詞。

在與關鍵詞相同的行 .PARAMETER 上輸入參數名稱。在關鍵詞後面的 .PARAMETER 幾行上輸入參數描述。 Windows PowerShell 會將行與下一個關鍵詞或批注區塊結尾之間的 .PARAMETER 所有文字解譯為參數描述的一部分。描述可以包含段落分隔符。

.PARAMETER  <Parameter-Name>

Parameter 關鍵詞可以依批注區塊中的任何順序顯示，但函式或腳本語法會決定參數出現在說明主題中的順序。若要變更順序，請變更語法。

您也可以在參數變數名稱之前，將批註放在函式或腳本語法中，以指定參數描述。若要這樣做，您也必須有至少一個關鍵詞的批注區塊。

如果您使用語法批注和 .PARAMETER 關鍵詞，則會使用與 .PARAMETER 關鍵詞相關聯的描述，並忽略語法批註。

<#
.SYNOPSIS
    Short description here
#>
function Verb-Noun {
    [CmdletBinding()]
    param (
        # This is the same as .Parameter
        [string]$Computername
    )
    # Verb the Noun on the computer
}

.EXAMPLE

使用函式或腳本的範例命令，選擇性地後面接著範例輸出和描述。針對每個範例重複這個關鍵詞。

.INPUTS

可傳送至函式或腳本之物件的 .NET 類型。您也可以包含輸入物件的描述。

.OUTPUTS

Cmdlet 傳回之物件的 .NET 類型。您也可以包含傳回物件的描述。

.NOTES

函式或腳本的其他資訊。

.LINK

相關主題的名稱。值會出現在「.LINK關鍵詞下方的行上，且前面必須加上批注符號 # 或包含在批注區塊中。

.LINK針對每個相關主題重複關鍵詞。

此內容會出現在幫助主題的 [相關連結] 區段中。

關鍵詞 .Link 內容也可以包含相同説明主題的在線版本統一資源識別碼（URI）。當您使用的 Get-HelpOnline 參數時，會開啟在線版本。 URI 的開頭必須是「HTTP」或「HTTPs」。

.COMPONENT

函式或腳本所使用的技術或功能名稱，或其相關。的 Component 參數 Get-Help 會使用此值來篩選所 Get-Help傳回的搜尋結果。

.ROLE

說明主題的使用者角色名稱。的 Role 參數 Get-Help 會使用此值來篩選所 Get-Help傳回的搜尋結果。

.FUNCTIONALITY

描述函式用途的關鍵詞。的功能參數Get-Help會使用這個值來篩選所Get-Help傳回的搜尋結果。

.FORWARDHELPTARGETNAME

重新導向至指定命令的說明主題。您可以將使用者重新導向至任何說明主題，包括函式、腳本、Cmdlet 或提供者的說明主題。

# .FORWARDHELPTARGETNAME <Command-Name>

.FORWARDHELPCATEGORY

指定中的 .ForwardHelpTargetName項目說明類別。有效值為 Alias、、、HelpFile、Function、FAQGeneralProviderScriptCommandGlossary、ExternalScript、 Filter或。AllCmdlet 使用這個關鍵詞，以避免有具有相同名稱的命令時發生衝突。

# .FORWARDHELPCATEGORY <Category>

.REMOTEHELPRUNSPACE

指定包含說明主題的工作階段。輸入包含 PSSession 物件的變數。 Export-PSSession Cmdlet 會使用此關鍵詞來尋找導出命令的說明主題。

# .REMOTEHELPRUNSPACE <PSSession-variable>

.EXTERNALHELP

指定文稿或函式的 XML 型說明檔。

# .EXTERNALHELP <XML Help File>

當 .ExternalHelp 函式或腳本記載在 XML 檔案中時，需要關鍵詞。如果沒有這個關鍵詞， Get-Help 則找不到函式或腳本的 XML 型說明檔。

關鍵詞 .ExternalHelp 優先於其他以批注為基礎的說明關鍵詞。如果 .ExternalHelp 存在， Get-Help 則不會顯示以批注為基礎的說明，即使找不到符合關鍵詞值的 .ExternalHelp 幫助主題也一樣。

如果函式是由模組匯出，請將關鍵詞的值 .ExternalHelp 設定為沒有路徑的檔名。 Get-Help 會在模組目錄的語言特定子目錄中尋找指定的檔名。函式的 XML 型說明檔名稱沒有需求，但最佳做法是使用下列格式：

<ScriptModule.psm1>-help.xml

如果函式未包含在模組中，請包含 XML 型說明檔的路徑。如果值包含路徑，且路徑包含UI文化特性特定的子目錄， Get-Help 請根據針對Windows建立的語言後援標準，以遞歸方式搜尋具有腳本或函式名稱的 XML 檔案，就像在模組目錄中一樣。

如需 Cmdlet 說明 XML 說明檔格式的詳細資訊，請參閱如何撰寫 Cmdlet 說明。

自動產生的內容

Cmdlet 會自動產生 Get-Help 名稱、語法、參數清單、參數屬性數據表、通用參數和備註。

名稱

函 式幫助主題的 Name 區段取自函式語法中的函式名稱。文稿說明主題的名稱取自腳本檔名。若要變更名稱或其大小寫，請變更函式語法或腳本檔名。

語法

說明 主題的 [語法 ] 區段是從函式或腳本語法產生。若要將詳細數據新增至說明主題語法，例如參數的 .NET 類型，請將詳細數據新增至語法。如果您未指定參數類型，則會 將 Object 類型插入為預設值。

參數清單

說明主題中的參數清單會從函式或腳本語法，以及使用 .Parameter 關鍵詞新增的描述產生。函式參數會以與函式或腳本語法中出現的順序相同，出現在說明主題的Parameters區段中。參數名稱的拼字和大小寫也取自語法。它不受關鍵詞所指定的 .Parameter 參數名稱影響。

一般參數

一般參數會新增至說明主題的語法和參數清單，即使它們沒有任何作用。如需常見參數的詳細資訊，請參閱 about_CommonParameters。

參數屬性數據表

Get-Help 會產生當您使用 的 Full 或 Parameter 參數 Get-Help時所出現的參數屬性數據表。 Required、Position 和 Default value 屬性值取自函式或腳本語法。

默認值和接受通配符的值不會出現在參數屬性數據表中，即使它們是在函式或腳本中定義也一樣。若要協助使用者，請在參數描述中提供這項資訊。

備註

說明 主題的「備註」區 段會自動從函式或腳本名稱產生。您無法變更或影響其內容。

範例

函式的批註型說明

下列範例函式包含以批注為基礎的說明：

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

PS> extension -name "File"
File.txt

.EXAMPLE

PS> extension -name "File" -extension "doc"
File.doc

.EXAMPLE

PS> extension "File" "doc"
File.doc

.LINK

http://www.fabrikam.com/extension.html

.LINK

Set-Item
#>
}

結果如下所示：

Get-Help -Name "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

PS> extension -name "File"
File.txt

Example 2

PS> extension -name "File" -extension "doc"
File.doc

Example 3

PS> extension "File" "doc"
File.doc

RELATED LINKS

http://www.fabrikam.com/extension.html
Set-Item

函式語法中的參數描述

這個範例與前一個範例相同，不同之處在於參數描述會插入函式語法中。當描述簡短時，此格式最有用。

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

PS> extension -name "File"
File.txt

.EXAMPLE

PS> extension -name "File" -extension "doc"
File.doc

.EXAMPLE

PS> extension "File" "doc"
File.doc

.LINK

http://www.fabrikam.com/extension.html

.LINK

Set-Item
#>
}

腳本的批註型說明

下列範例腳本包含以批註為基礎的說明。請注意結尾 #> 與 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

PS> .\Update-Month.ps1

.EXAMPLE

PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv

.EXAMPLE

PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv -outputPath `
C:\Reports\2009\January.csv
#>

param ([string]$InputPath, [string]$OutPutPath)

function Get-Data { }
...

下列命令會取得腳本說明。因為腳本不在環境變數中 $env:Path 所列的目錄中， Get-Help 因此取得腳本說明的命令必須指定腳本路徑。

Get-Help -Name .\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

PS> .\Update-Month.ps1

Example 2

PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv

Example 3

PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv -outputPath
C:\Reports\2009\January.csv

# RELATED LINKS

重新導向至 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
}

重新導向至不同的說明主題

下列程式代碼是PowerShell中內建說明函式開頭的摘錄，一次顯示一個說明文字畫面。由於 Cmdlet 的說明主題 Get-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},
...

下列命令會使用這項功能：

Get-Help -Name help

NAME

Get-Help

SYNOPSIS

Displays information about PowerShell cmdlets and concepts.
...