主题
about_Comment_Based_Help
简短说明
描述如何为函数和脚本编写基于注释的帮助主题。
详细说明
可通过使用特殊帮助注释关键字为函数和脚本编写基于注释的帮助主题。
Get-Help cmdlet 显示基于注释的帮助的格式与它显示从 XML 文件生成的 cmdlet 帮助主题的格式相同。用
户可使用 Get-Help 的所有参数，如 Detailed、Full、Example 和 Online 来显示函数和脚本帮助。
也可通过使用帮助注释关键字为脚本和函数编写基于 XML 的帮助文件，并将用户重定向到另一个帮助文件。
此主题说明如何为函数和脚本编写帮助主题。有关如何显示函数和脚本帮助主题的信息，请参阅 Get-Help。
基于注释的帮助的语法
基于注释的帮助的语法如下：
# .< help keyword>
# <help content>
-或 -
<#
.< help keyword>
< help content>
#>
基于注释的帮助是以一系列注释的形式编写的。可在每行注释之前键入一个注释符号 (#)，或使用"<#"和"#>"
符号来创建一个注释块。注释块中的所有行都被解释为注释。
基于注释的帮助主题中的所有行必须是连续的。如果基于注释的帮助主题跟在不属于
该帮助主题的某个注释之后，则在最后一行非帮助注释主题与基于注释的帮助的起始行
之间必须至少有一个空行。
关键字定义了基于注释的帮助的每个部分。每个基于注释的帮助关键字前面都有一个
句点 (.)。关键字可以按任何顺序出现。关键字名不区分大小写。
例如，Description 关键字位于函数或脚本的说明之前。
<#
.Description
Get-Function 显示会话中所有函数的名称和语法。
#>
注释块必须包含至少一个关键字。一些关键字（如 EXAMPLE）在同一个注释块内
可能会出现多次。每个关键字的帮助内容都从该关键字后面一行开始，可以占多行。
函数中基于注释的帮助的语法
函数的基于注释的帮助可出现在以下三个位置之一：
-- 函数体的开头。
-- 函数体的末尾。
-- Function 关键字之前。在函数帮助的最后一行与 Function 关键字之间不能有一个以上空行。
例如：
function MyFunction
{
<#
.< help keyword>
< help content>
#>
<function commands>
}
-或 -
function MyFunction
{
<function commands>
<#
.< help keyword>
< help content>
#>
}
-或 -
<#
.< help keyword>
< help content>
#>
function MyFunction { }
脚本中基于注释的帮助的语法
脚本的基于注释的帮助可出现在脚本中以下两个位置之一。
-- 脚本文件的开头。脚本中脚本帮助的前面只能是注释和空行。
-- 如果脚本体中的第一项（帮助的后面）是函数声明，则在脚本帮助的末尾与函数
声明之间必须至少有两个空行。否则，该帮助将被解释为函数帮助，而非脚本帮助。
-- 脚本文件的末尾。
例如：
<#
.< help keyword>
< help content>
#>
function MyFunction { }
-或 -
function MyFunction { }
<#
.< help keyword>
< help content>
#>
基于注释的帮助关键字
以下是基于注释的帮助的有效关键字，列出的顺序是它们通常在帮助主题中
出现的顺序，并说明了这些关键字的预定用途。这些关键字可以按任何顺序
出现在基于注释的帮助中，并且不区分大小写。
.SYNOPSIS
对函数或脚本的简短说明。此关键字在每个主题中只能使用一次。
.DESCRIPTION
函数或脚本的详细说明。此关键字在每个主题中只能使用一次。
.PARAMETER <Parameter-Name>
参数说明。可在函数或脚本语法中为每个参数包括一个 Parameter 关键字。
Parameter 关键字可以按任意顺序出现在注释块中，但函数或脚本语法
将确定参数（及其说明）在帮助主题中出现的顺序。要更改顺序，请更改语法。
也可通过在函数或脚本语法中的参数变量名称前面放置注释来指定参数说明。
如果同时使用语法注释和 Parameter 关键字，则将使用与 Parameter 关键字
相关联的说明，而忽略语法注释。
.EXAMPLE
使用函数或脚本的示例命令，后面可跟有可选的示例输出和一段说明。针对每个示例重复此关键字。
.INPUTS
对象的可通过管道传送给函数或脚本的 Microsoft .NET Framework 类型。也可包括输入对象的说明。
.OUTPUTS
Cmdlet 所返回对象的 .NET Framework 类型。也可包括返回的对象的说明。
.NOTES
有关函数或脚本的其他信息。
.LINK
相关主题的名称。针对每个相关主题重复此关键字。
此内容出现在帮助主题的 Related Links 部分中。
Link 关键字内容也可包括指向相同帮助主题的联机版本的统一
资源标识符 (URI)。联机版本在使用 Get-Help 的 Online 参数
时打开。URI 必须以“http”或“https”开头。
.COMPONENT
函数或脚本使用的或与之相关的技术或功能。此内容在 Get-Help 命令中
包括 Get-Help 的 Component 参数时出现。
.ROLE
帮助主题的用户角色。此内容在 Get-Help 命令中包括 Get-Help 的 Role 参数时出现。
.FUNCTIONALITY
函数的预定用途。此内容在 Get-Help 命令中包括 Get-Help 的 Functionality 参数时出现。
.FORWARDHELPTARGETNAME <Command-Name>
重定向到指定命令的帮助主题。可将用户重定向到任何帮助主题，
包括函数、脚本、cmdlet 或提供程序的帮助主题。
.FORWARDHELPCATEGORY <Category>
在 ForwardHelpTargetName 中指定该项的帮助类别。
有效值为 Alias、Cmdlet、HelpFile、Function、Provider、General、FAQ、Glossary、
ScriptCommand、ExternalScript、Filter 或 All。使用此关键字可避免具有同名命令时发生冲突。
.REMOTEHELPRUNSPACE <PSSession-variable>
指定包括帮助主题的一个会话。输入包含 PSSession 的一个变量。此关键字由 Export-PSSession
cmdlet 使用，用于查找导出的命令的帮助主题。
.EXTERNALHELP <XML Help File Path>
指定基于 XML 的脚本或函数帮助文件的路径。
在 Windows Vista 以及更高版本的 Windows 上，如果 XML 文件的指定路径包括 UI 区域性特定子目
录，则 Get-Help 将递归搜索这些子目录，以按照为 Windows Vista 建立的语言回退标准查找具有相应脚
本或函数名的 XML 文件，就像它针对所有基于 XML 的帮助主题所执行的操作一样。
有关 cmdlet 帮助的基于 XML 的帮助文件格式的详细信息，请参阅 MSDN
(Microsoft Developer Network) 库中的“如何创建 Cmdlet 帮助”，
网址是：https://go.microsoft.com/fwlink/?LinkID=123415。
自动生成的内容
名称、语法、参数列表、参数属性表、通用参数和备注是由 Get-Help cmdlet 自动生成的。
名称：
函数帮助主题的名称部分从函数语法中的函数名称获取。脚本帮助主题的名称从
脚本文件名获取。要更改名称或其大小写，请更改函数语法或脚本文件名。
语法：
帮助主题的语法部分从函数或脚本语法生成。若要向帮助主题语法添加详细内容
（如某个参数的 .NET Framework 类型），请将详细内容添加到语法中。如果不
指定参数类型，则将“Object”类型作为默认值插入。
参数列表：
帮助主题中的参数列表是从函数或脚本语法以及使用 Parameters 关键字添加的
说明生成的。函数参数以它们出现在函数或脚本语法中的相同顺序出现在帮助主题的
“参数”部分。参数名的拼写和大小写也与语法中相同，不受 Parameter 关键字所指定的
参数名的影响。
通用参数：
通用参数被添加到帮助主题的语法和参数列表中，即使它们不起任何作用也如此。
有关通用参数的详细信息，请参阅 about_CommonParameters。
参数属性表：
Get-Help 将生成参数属性表，该表在使用 Get-Help 的 Full 或 Parameter 参数时出现。
Required、Position 和 Default value 属性的值从函数或脚本语法获取。
备注：
帮助主题的备注部分从函数或脚本名称自动生成。您不能更改或影响此部分的内容。
示例
示例 1：基于注释的函数帮助
以下示例函数包含了基于注释的帮助：
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
C:\PS> extension -name "File"
File.txt
.EXAMPLE
C:\PS> extension -name "File" -extension "doc"
File.doc
.EXAMPLE
C:\PS> extension "File" "doc"
File.doc
.LINK
联机版本：http://www.fabrikam.com/extension.html
.LINK
Set-Item
#>
}
结果如下：
C:\PS> get-help 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--------------------------
C:\PS> extension -name "File"
File.txt
-------------------------- EXAMPLE 2--------------------------
C:\PS> extension -name "File" -extension "doc"
File.doc
-------------------------- EXAMPLE 3--------------------------
C:\PS> extension "File" "doc"
File.doc
RELATED LINKS
联机版本：http://www.fabrikam.com/extension.html
Set-Item
示例 2：函数语法中的参数说明
此示例与前一个示例基本相同，只是将参数说明插入到函数语法中。说明比较简短时非常适合使用此格式。
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
C:\PS> extension -name "File"
File.txt
.EXAMPLE
C:\PS> extension -name "File" -extension "doc"
File.doc
.EXAMPLE
C:\PS> extension "File" "doc"
File.doc
.LINK
联机版本：http://www.fabrikam.com/extension.html
.LINK
Set-Item
#>
}
示例 3：基于注释的脚本帮助
以下示例脚本包含了基于注释的帮助。
请注意结束标记"#>"与 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
C:\PS> .\Update-Month.ps1
.EXAMPLE
C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv
.EXAMPLE
C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv -outputPath C:\Reports\2009\January.csv
#>
param ([string]$InputPath, [string]$OutPutPath)
function Get-Data { }
...
以下命令获取脚本帮助。由于脚本不在 Path 环境变量中列出的目录中，因此用于获取脚本帮助的
Get-Help 命令必须指定脚本路径。
PS C:\ps-test> get-help .\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--------------------------
C:\PS> .\Update-Month.ps1
-------------------------- EXAMPLE 2--------------------------
C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv
-------------------------- EXAMPLE 3--------------------------
C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv -outputPath
C:\Reports\2009\January.csv
RELATED LINKS
示例 4：重定向至 XML 文件
可为函数和脚本编写基于 XML 的帮助主题。虽然基于注释的帮助较易实现，但如果想要
更精确地控制帮助内容，或要将帮助主题翻译为多种语言，则需要使用基于 XML 的帮助。
以下示例显示了 Update-Month.ps1 脚本的前面几行。该脚本使用 ExternalHelp 关键字
来指定基于 XML 的脚本帮助主题的路径。
# .ExternalHelp C:\MyScripts\Update-Month-Help.xml
param ([string]$InputPath, [string]$OutPutPath)
function Get-Data { }
...
以下示例显示了 ExternalHelp 关键字在函数中的使用。
function Add-Extension
{
param ([string] $name, [string]$extension = "txt")
$name = $name + "." + $extension
$name
# .ExternalHelp C:\ps-test\Add-Extension.xml
}
示例 5：重定向至另一个帮助主题
以下代码摘自 Windows PowerShell 内置 Help 函数的开始部分，它一次显示一屏帮助文本。由于 Get-
Help cmdlet 的帮助主题描述 Help 函数，因此 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},
...
以下命令使用了此功能：
C:\PS> get-help help
NAME
Get-Help
SYNOPSIS
Displays information about Windows PowerShell cmdlets and concepts.
...
另请参阅
about_Functions
about_Functions_Advanced_Parameters
about_Scripts
“如何编写 Cmdlet 帮助”(https://go.microsoft.com/fwlink/?LinkID=123415)