關於_基於評論的說明

簡短描述

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

完整描述

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

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

您也可以為函式和文稿撰寫以 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>
#>

以註釋為基礎的說明關鍵詞

以下是以批注為基礎的有效說明關鍵詞。這些關鍵詞在批註型說明中可以以任何順序出現，而且不區分大小寫。關鍵詞會依通常出現在說明主題中的順序列於本文中。

.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 關鍵詞內容也可以包含相同幫助主題的在線版本統一資源標識碼（URI）。當您使用的 Get-Help 參數時，會開啟在線版本。 URI 的開頭 http 必須是或 https。

`.COMPONENT`

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

`.ROLE`

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

`.FUNCTIONALITY`

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

`.FORWARDHELPTARGETNAME <Command-Name>`

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

# .FORWARDHELPTARGETNAME <Command-Name>

`.FORWARDHELPCATEGORY`

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

# .FORWARDHELPCATEGORY <Category>

`.REMOTEHELPRUNSPACE <PSSession-variable>`

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

# .REMOTEHELPRUNSPACE <PSSession-variable>

`.EXTERNALHELP`

指定用於文稿或函式的 XML 格式說明文件。

# .EXTERNALHELP <XML Help File>

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

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

如果函式是由模組匯出，請將 .EXTERNALHELP 關鍵詞的值設定為沒有路徑的檔名。 Get-Help 在模組目錄的語言特定子目錄中尋找指定的檔名。函數的 XML 型說明檔名稱沒有需求。從 PowerShell 5.0 開始，模組匯出的函式可以記錄在以模組命名的說明檔案中。您不需要使用 .EXTERNALHELP 註解關鍵字。例如，如果函式是由模組匯Test-Function出的，您可以MyModule將說明檔案MyModule-help.xml命名為。 Cmdlet 會在Get-Help模組目錄的檔案中Test-Function尋找函式的MyModule-help.xml說明。

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

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

自動產生的內容

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

名字

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

語法

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

參數清單

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

一般參數

Common 參數 已新增至說明主題的語法和參數清單，即便它們沒有作用。如需常見參數的詳細資訊，請參閱 about_CommonParameters。

參數屬性數據表

Get-Help 會創建參數屬性的數據表，該表會在您使用的 Full 或 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 can't pipe objects to Add-Extension.

.OUTPUTS

System.String. Add-Extension returns a string with the extension
or file name.

.EXAMPLE

PS> Add-Extension -Name "File"
File.txt

.EXAMPLE

PS> Add-Extension -Name "File" -Extension "doc"
File.doc

.EXAMPLE

PS> Add-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 can't pipe objects to Add-Extension.

OUTPUTS

System.String. Add-Extension returns a string with the extension or
file name.

Example 1

PS> Add-Extension -Name "File"
File.txt

Example 2

PS> Add-Extension -Name "File" -Extension "doc"
File.doc

Example 3

PS> Add-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 can't pipe objects to Add-Extension.

.OUTPUTS

System.String. Add-Extension returns a string with the extension or
file name.

.EXAMPLE

PS> Add-Extension -Name "File"
File.txt

.EXAMPLE

PS> Add-Extension -Name "File" -Extension "doc"
File.doc

.EXAMPLE

PS> Add-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 can't pipe objects to Update-Month.ps1.

.OUTPUTS

None. Update-Month.ps1 doesn't 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 can't pipe objects to Update-Month.ps1.

# OUTPUTS

None. Update-Month.ps1 doesn't 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中內建說明函式開頭的摘錄，一次顯示一個說明文字畫面。由於 Get-Help Cmdlet 的說明主題描述說明函式，因此 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.
...

另請參閱

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-09-24