编辑说明
重要
Windows PowerShell 语言规范 3.0 于 2012 年 12 月发布，基于 Windows PowerShell 3.0。 此规范不反映 PowerShell 的当前状态。 没有计划更新本文档以反映当前状态。 此处提供了本文档供历史参考。
该规范文档可作为Microsoft Word文档从Microsoft下载中心获取：https://www.microsoft.com/download/details.aspx?id=36389。该Word文档已在此Microsoft Learn上转换为展示格式。 转换期间，进行了一些编辑更改，以适应 Docs 平台的格式设置。 已更正某些拼写错误和次要错误。
PowerShell 为程序员提供了一种使用特殊注释指令来记录其脚本的机制。 使用此类语法的注释称为帮助注释。 Get-Help cmdlet 通过这些指令生成文档。
A.1 简介
帮助注释包含形式为 .name 的帮助指令，其后面有一行或多行帮助内容文本。 帮助注释可以由一系列 single-line-comment 或 delimited-comment (§2.2.3) 组成。 由单个实体的文档组成的注释集称为帮助主题。
例如，
# <help-directive-1>
# <help-content-1>
...
# <help-directive-n>
# <help-content-n>
或
<#
<help-directive-1>
<help-content-1>
...
<help-directive-n>
<help-content-n>
#>
帮助主题中的所有行都必须是连续行。 如果帮助主题遵循不属于该主题的注释，则两者之间必须至少有一个空白行。
指令可以按任意顺序显示，某些指令可能会多次出现。
指令名称不区分大小写。
记录函数时，帮助主题可能出现在以下三个位置之一：
- 紧靠在函数定义之前，并且函数帮助的最后一行与包含函数语句的行之间最多只有一个空白行。
- 函数体内部紧跟在左大括号后面。
- 函数体内部紧靠在右大括号之前。
记录脚本文件时，帮助主题可能出现在以下两个位置之一：
- 在脚本文件的开头，（可选）前面只有注释和空白行。 如果帮助后脚本中的第一项是函数定义，则脚本帮助末尾和该函数声明之间必须至少有两个空行。 否则，帮助将被解释为应用于函数而不是脚本文件。
- 在脚本文件的末尾。
A.2 帮助指令
A.2.1 .描述
语法：
.DESCRIPTION
描述：
此指令允许对函数或脚本进行详细说明。 （.SYNOPSIS 指令（§A.2.11）旨在简要说明。 此指令在每个主题中只能使用一次。
例子：
<#
.DESCRIPTION
Computes Base to the power Exponent. Supports non-negative integer
powers only.
#>
A.2.2 .EXAMPLE
语法：
.EXAMPLE
描述：
此指令允许显示命令用法的示例。
如果此指令多次出现，则每个关联的帮助内容块都显示为单独的示例。
例子：
<#
.EXAMPLE
Get-Power 3 4
81
.EXAMPLE
Get-Power -Base 3 -Exponent 4
81
#>
A.2.3 .EXTERNALHELP
语法：
.EXTERNALHELP <XMLHelpFilePath>
描述：
此指令指定脚本或函数的基于 XML 的帮助文件的路径。
尽管基于注释的帮助更易于实现，但如果需要对帮助内容进行更精确的控制，或者需要将帮助主题翻译成多种语言，则需要基于 XML 的帮助。 此规范未定义基于 XML 的帮助的详细信息。
例子：
<#
.EXTERNALHELP C:\MyScripts\Update-Month-Help.xml
#>
A.2.4 .FORWARDHELPCATEGORY
语法：
.FORWARDHELPCATEGORY <Category>
描述：
指定 ForwardHelpTargetName（§A.2.5）中项的帮助类别。 有效值为 Alias、All、Cmdlet、ExternalScript、FAQ、Filter、Function、General、Glossary、HelpFile、Provider 和 ScriptCommand。 使用此指令可避免在具有相同名称的命令时发生冲突。
例子：
请参阅 §A.2.5。
A.2.5 .FORWARDHELPTARGETNAME
语法：
.FORWARDHELPTARGETNAME <Command-Name>
描述：
重定向到由 <Command-Name>指定的帮助主题。
例子：
function Help {
<#
.FORWARDHELPTARGETNAME Get-Help
.FORWARDHELPCATEGORY Cmdlet
#>
...
}
命令 Get-Help help 被视为 Get-Help Get-Help。
A.2.6 .INPUTS
语法：
.INPUTS
描述：
管道可用于通过管道将一个或多个对象传递给脚本或函数。 此指令用于描述此类对象及其类型。
如果此指令多次出现，每个关联的帮助内容块将按照指令的词法顺序被收集到一个文档条目中。
例子：
<#
.INPUTS
None. You cannot pipe objects to Get-Power.
.INPUTS
For the Value parameter, one or more objects of any kind can be written
to the pipeline. However, the object is converted to a string before it
is added to the item.
#>
function Process-Thing {
param ( ...
[Parameter(ValueFromPipeline=$true)]
[Object[]]$Value,
...
)
...
}
A.2.7 .LINK
语法：
.LINK
描述：
此指令指定相关主题的名称。
如果该指令出现多次，则按照指令的词法顺序在一个文档条目中收集每个相关的帮助内容块。
Link 指令内容还可以包含指向相同帮助主题联机版本的 URI。 在线版本将在使用 Online 参数调用 Get-Help 时打开。 URI 必须以“http”或“https”开头。
例子：
<#
.LINK
Online version: http://www.acmecorp.com/widget.html
.LINK
Set-ProcedureName
#>
A.2.8 注释
语法：
.NOTES
描述：
此指令允许提供有关函数或脚本的其他信息。 此指令在每个主题中只能使用一次。
例子：
<#
.NOTES
*arbitrary text goes here*
#>
A.2.9 .OUTPUTS
语法：
.OUTPUTS
描述：
此指令用于描述命令输出的对象。
如果该指令出现多次，每个相关的帮助内容块按照指令的词法顺序被收集到一个文档条目中。
例子：
<#
.OUTPUTS
double - Get-Power returns Base to the power Exponent.
.OUTPUTS
None unless the -PassThru switch parameter is used.
#>
A.2.10 .PARAMETER
语法：
.PARAMETER <Parameter-Name>
描述：
此指令允许对给定参数进行详细说明。 此指令可用于每个参数一次。 参数指令可以按注释块中的任意顺序显示;但是，在源中实际定义其相应参数的顺序决定了参数及其说明在生成的文档中显示的顺序。
另一种格式涉及将参数描述注释紧挨着相应的参数变量名称声明之前。 如果源同时包含参数说明注释和 Parameter 指令，则使用与 Parameter 指令关联的说明。
例子：
<#
.PARAMETER Base
The integer value to be raised to the Exponent-th power.
.PARAMETER Exponent
The integer exponent to which Base is to be raised.
#>
function Get-Power {
param ([long]$Base, [int]$Exponent)
...
}
function Get-Power {
param ([long]
# The integer value to be raised to the Exponent-th power.
$Base,
[int]
# The integer exponent to which Base is to be raised.
$Exponent
)
...
}
A.2.11 .概要
语法：
.SYNOPSIS
描述：
此指令允许简要说明函数或脚本。 （.DESCRIPTION 指令（§A.2.1）适用于详细说明。 此指令在每个主题中只能使用一次。
例子：
<#
.SYNOPSIS
Computes Base to the power Exponent.
#>
