about_Comment_Based_Help

项目
10/07/2023

简短说明

介绍如何为函数和脚本编写基于注释的帮助主题。

长说明

可以使用特殊的帮助注释关键字为函数和脚本编写基于注释的帮助主题。

Get-Help cmdlet 显示基于注释的帮助，其格式与显示从 XML 文件生成的 cmdlet 帮助主题的格式相同。用户可以使用 Get-Help 的所有参数，如 Detailed、Full、Examples、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>
#>

脚本模块中基于注释的帮助的语法

在脚本模块 .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 关键字关联的说明，并忽略语法注释。

<#
.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-Help 的 Online 参数时，将打开联机版本。 URI 必须以“http”或“https”开头。

.COMPONENT

函数或脚本使用的或与之相关的技术或功能的名称。 Get-Help 的 Component 参数使用此值来筛选 Get-Help 返回的搜索结果。

.ROLE

帮助主题的用户角色的名称。 Get-Help 的 Role 参数使用此值来筛选 Get-Help 返回的搜索结果。

.FUNCTIONALITY

描述函数预期用途的关键字。 Get-Help 的 Functionality 参数使用此值来筛选 Get-Help 返回的搜索结果。

.FORWARDHELPTARGETNAME

重定向到指定命令的帮助主题。可以将用户重定向到任何帮助主题，包括函数、脚本、cmdlet 或提供程序的帮助主题。

# .FORWARDHELPTARGETNAME <Command-Name>

.FORWARDHELPCATEGORY

指定 .ForwardHelpTargetName 中的项的帮助类别。有效值为 Alias、Cmdlet、HelpFile、Function、Provider、General、FAQ、Glossary、ScriptCommand、ExternalScript、Filter 或 All。当存在同名的命令时，使用此关键字可避免冲突。

# .FORWARDHELPCATEGORY <Category>

.REMOTEHELPRUNSPACE

指定包含帮助主题的会话。输入包含 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 的帮助文件的名称没有要求，但最佳做法是使用以下格式：

<ScriptModule.psm1>-help.xml

如果该函数未包含在模块中，请包含基于 XML 的帮助文件的路径。如果该值包含路径并且该路径包含特定于 UI 区域性的子目录，则 Get-Help 会根据为 Windows 建立的语言后备标准递归搜索子目录以查找具有脚本或函数名称的 XML 文件，就像在模块目录中一样。

有关 cmdlet 帮助基于 XML 的帮助文件格式的详细信息，请参阅如何编写 Cmdlet 帮助。

自动生成的内容

名称、语法、参数列表、参数属性表、通用参数和注释由 Get-Help cmdlet 自动生成。

名称

函数帮助主题的名称部分取自函数语法中的函数名称。脚本帮助主题的名称取自脚本文件名。若要更改名称或其大写，请更改函数语法或脚本文件名。

语法

帮助主题的语法部分是从函数或脚本语法生成的。若要向帮助主题语法（如参数的 .NET 类型）添加详细信息，请将详细信息添加到语法。如果未指定参数类型，则对象类型将作为默认值插入。

参数列表

帮助主题中的参数列表是从函数或脚本语法以及使用 .Parameter 关键字添加的说明生成的。函数参数出现在帮助主题的参数部分中的顺序与它们在函数或脚本语法中出现的顺序相同。参数名称的拼写和大小写也取自语法。它不受 .Parameter 关键字指定的参数名称的影响。

通用参数

通用参数会被添加到帮助主题的语法和参数列表中，即使它们没有任何作用也不例外。有关通用参数的详细信息，请参阅 about_CommonParameters。

参数属性表

Get-Help 生成使用 Get-Help 的 Full 或 Parameter 参数时显示的参数属性表。必需、位置和默认值属性的值取自函数或脚本语法。

默认值和接受通配符的值不会出现在参数属性表中，即使它们是在函数或脚本中定义的也是如此。若要帮助用户，请在参数说明中提供此信息。

备注

帮助主题的注解部分是从函数或脚本名称自动生成的。无法更改或影响其内容。

示例

基于注释的函数帮助

以下示例函数包括基于注释的帮助：

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 中内置帮助函数的开头部分，该函数一次显示一屏帮助文本。由于 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},
...

以下命令使用此功能：

Get-Help -Name help

NAME

Get-Help

SYNOPSIS

Displays information about PowerShell cmdlets and concepts.
...