about_Comment_Based_Help

项目
05/09/2024

简短说明

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

长说明

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

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

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

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

Update-Help 和 Save-Help cmdlet 仅适用于 XML 文件。可更新的帮助不支持基于注释的帮助主题。

基于注释的帮助的语法

基于注释的帮助的语法如下：

# .<help keyword>
# <help content>

或

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

基于注释的帮助编写为一系列注释。可以在每行注释之前键入批注符号 # ，也可以使用 <# 和 #> 符号创建批注块。注释块中的所有行都解释为注释。

基于注释的帮助主题中的所有行都必须是连续的。如果基于注释的帮助主题后跟不属于帮助主题的注释，则最后一个非帮助注释行和基于注释的帮助的开头之间必须至少有一个空白行。

关键字定义基于注释的帮助的每个部分。每个基于注释的帮助关键字 (keyword) 前面都有一个点 .。关键字可以按任意顺序显示。关键字 (keyword) 名称不区分大小写。

例如，.Description关键字 (keyword) 先于函数或脚本的说明。

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

注释块必须至少包含一个关键字 (keyword) 。某些关键字（如 .EXAMPLE）可以多次出现在同一批注块中。每个关键字 (keyword) 的帮助内容从关键字 (keyword) 后的行开始，可以跨多行。

函数中基于注释的帮助的语法

函数的基于注释的帮助可以显示在以下三个位置之一：

在函数主体的开头。
在函数主体的末尾。
在function关键字 (keyword) 之前。函数帮助的最后一行和function关键字 (keyword) 之间不能有多个空行。

例如：

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 关键字 (keyword) 标识脚本模块中函数的基于 XML 的帮助文件，则必须为每个函数添加注释.ExternalHelp。

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

基于注释的帮助关键字

下面是基于注释的有效帮助关键字。它们按它们通常在帮助主题中的显示顺序及其预期用途列出。这些关键字可以按任何顺序显示在基于注释的帮助中，并且不区分大小写。

.SYNOPSIS

函数或脚本的简要说明。此关键字 (keyword) 在每个主题中只能使用一次。

.DESCRIPTION

函数或脚本的详细说明。此关键字 (keyword) 在每个主题中只能使用一次。

.PARAMETER

参数的说明。 .PARAMETER 为函数或脚本语法中的每个参数添加关键字 (keyword) 。

在关键字 (keyword) 所在的同一行中.PARAMETER键入参数名称。在关键字 (keyword) 后面的行中.PARAMETER键入参数说明。 Windows PowerShell将行与下一关键字 (keyword) 或注释块末尾之间的.PARAMETER所有文本解释为参数说明的一部分。说明可以包括段落分隔符。

.PARAMETER  <Parameter-Name>

Parameter 关键字可以按任何顺序出现在注释块中，但函数或脚本语法确定参数 (的顺序及其说明) 在帮助主题中的显示顺序。若要更改顺序，请更改语法。

还可以通过在函数或脚本语法中直接在参数变量名称前放置注释来指定参数说明。若要使此功能正常工作，还必须具有至少一个关键字 (keyword) 的批注块。

如果同时使用语法注释和.PARAMETER关键字 (keyword) ，则使用与.PARAMETER关键字 (keyword) 关联的说明，并忽略语法注释。

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

.EXAMPLE

使用函数或脚本的示例命令，后跟示例输出和说明（可选）。对每个示例重复此关键字 (keyword) 。

.INPUTS

可通过管道传递给函数或脚本的 .NET 类型的对象。还可以包含输入对象的说明。

.OUTPUTS

cmdlet 返回的对象的 .NET 类型。还可以包含返回对象的说明。

.NOTES

有关函数或脚本的其他信息。

.LINK

相关主题的名称。该值显示在“”.LINK关键字 (keyword) 下方的行上，并且必须前面有注释符号#或包含在注释块中。

.LINK 为每个相关主题重复关键字 (keyword) 。

此内容显示在帮助主题的“相关链接”部分中。

.Link 关键字 (keyword) 内容还可以包含统一资源标识符 (URI，) 同一帮助主题的联机版本。使用的 Online 参数Get-Help时，将打开联机版本。 URI 必须以“http”或“https”开头。

.COMPONENT

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

.ROLE

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

.FUNCTIONALITY

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

.FORWARDHELPTARGETNAME

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

# .FORWARDHELPTARGETNAME <Command-Name>

.FORWARDHELPCATEGORY

指定中 .ForwardHelpTargetName项的帮助类别。有效值为 Alias、、Cmdlet、HelpFile、Function、ProviderGeneral、FAQ、 ExternalScriptFilterGlossaryScriptCommand或。All 使用此关键字 (keyword) 可避免存在同名命令时发生冲突。

# .FORWARDHELPCATEGORY <Category>

.REMOTEHELPRUNSPACE

指定包含帮助主题的会话。输入包含 PSSession 对象的变量。 Export-PSSession cmdlet 使用此关键字 (keyword) 来查找导出命令的帮助主题。

# .REMOTEHELPRUNSPACE <PSSession-variable>

.EXTERNALHELP

为脚本或函数指定基于 XML 的帮助文件。

# .EXTERNALHELP <XML Help File>

在 .ExternalHelp XML 文件中记录函数或脚本时，需要关键字 (keyword) 。如果没有此关键字 (keyword) ，Get-Help则找不到函数或脚本的基于 XML 的帮助文件。

关键字 (keyword) .ExternalHelp 优先于其他基于注释的帮助关键字。如果 .ExternalHelp 存在，Get-Help则不显示基于注释的帮助，即使找不到与关键字 (keyword) 的值匹配的.ExternalHelp帮助主题也是如此。

如果函数由模块导出，请将关键字 (keyword) 的值.ExternalHelp设置为不带路径的文件名。 Get-Help 在模块目录的特定于语言的子目录中查找指定的文件名。函数的基于 XML 的帮助文件的名称没有要求，但最佳做法是使用以下格式：

<ScriptModule.psm1>-help.xml

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

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

自动生成的内容

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

名称

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

语法

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

参数列表

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

通用参数

将 Common 参数添加到帮助主题的语法和参数列表中，即使它们不起作用。有关通用参数的详细信息，请参阅 about_CommonParameters。

参数属性表

Get-Help 生成使用的 Full 或 Parameter 参数 Get-Help时显示的参数属性表。 Required、Position 和 Default 值属性的值取自函数或脚本语法。

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

注解

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

示例

函数的基于注释的帮助

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

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 关键字 (keyword) 为脚本指定基于 XML 的帮助主题的路径。

请注意，关键字 (keyword) 的值.ExternalHelp显示在关键字 (keyword) 所在的同一行上。任何其他放置都无效。

# .ExternalHelp C:\MyScripts\Update-Month-Help.xml

param ([string]$InputPath, [string]$OutPutPath)
function Get-Data { }
...

以下示例演示函数中关键字 (keyword) 的.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.
...

通过