about_Comment_Based_Help

简短说明

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

长说明

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

Get-Help cmdlet 以相同的格式显示基于注释的帮助,其中显示从 XML 文件生成的 cmdlet 帮助主题。 用户可以使用“详细”、“完整”、“示例”和“联机”等所有参数Get-Help来显示基于注释的帮助的内容。

还可以为函数和脚本编写基于 XML 的帮助文件。 若要使 Get-Help cmdlet 能够查找函数或脚本的基于 XML 的帮助文件,请使用 .ExternalHelp 关键字。 如果没有此关键字, Get-Help 则找不到函数或脚本的基于 XML 的帮助主题。

本主题介绍如何编写函数和脚本的帮助主题。 有关如何显示函数和脚本的帮助主题的信息,请参阅 Get-Help

Update-HelpSave-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 内容还可以包括统一资源标识符 (URI) 到同一帮助主题的联机版本。 使用 Online 参数的 Get-HelpOnline 参数时,将打开联机版本。 URI 必须以“http”或“https”开头。

.COMPONENT

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

.ROLE

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

.FUNCTIONALITY

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

.FORWARDHELPTARGETNAME

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

# .FORWARDHELPTARGETNAME <Command-Name>

.FORWARDHELPCATEGORY

指定项的 .ForwardHelpTargetName帮助类别。 有效值为、、、HelpFileGeneralGlossaryFunctionProviderFAQExternalScriptScriptCommand或。AllFilterCmdletAlias 使用此关键字可避免在具有相同名称的命令时发生冲突。

# .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 类型)添加详细信息,请将详细信息添加到语法中。 如果未指定参数类型,则 对象 类型将插入为默认值。

参数列表

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

通用参数

公共参数将添加到帮助主题的语法和参数列表,即使它们不起作用。 有关常见参数的详细信息,请参阅 about_CommonParameters

参数属性表

Get-Help生成使用 FullParameter 参数Get-Help时出现的参数属性表。 必需位置和默认值属性的值取自函数或脚本语法。

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

注解

帮助主题的 “备注 ”部分是从函数或脚本名称自动生成的。 不能更改或影响其内容。

示例

基于注释的函数帮助

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

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.
...

另请参阅