How to write comment in PowerShell Script

今天我们要说的是如何在PowerShell脚本中添加帮助文档，在平时大家写完脚本后通常会写一些该脚本如何使用的帮助文档，以供脚本使用者初次使用。有些人会选择将帮助文档写进一个方法里，然后用变量来触发这个方法。有的人会选择在自己所写的脚本运行之初就显示帮助文档，方法很多，但是弊端也有很多。

从编写一个规范的脚本标准角度来说不统一的帮助文档不易于规范性操作管理，再者在我们学习PowerShell的cmdlet使用时都习惯性的使用get-help来查看帮助，那么为何不用get-help来查看我们自己写的方法或者脚本呢？能做到吗，答案是肯定的，这就是开题所说的在PowerShell脚本中添加帮助文档。下面就让我们开始吧~

在PS脚本中添加帮助文档分为两大区域：

1、基于脚本的帮助注释

2、基于方法的帮助注释

 

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

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

-- 函数体的开头。

-- 函数体的末尾。

-- Function 关键字之前。

在函数帮助的最后一行与 Function 关键字之间不能有一个以上空行。

 

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

脚本的基于注释的帮助可出现在脚本中以下两个位置之一。

-- 脚本文件的开头。脚本中脚本帮助的前面只能是注释和空行。

-- 如果脚本体中的第一项（帮助的后面）是函数声明，则在脚本帮助的末尾与函数
声明之间必须至少有两个空行。否则，该帮助将被解释为函数帮助，而非脚本帮助。

-- 脚本文件的末尾。

在帮助中必须添加相对应的注释关键字，用法具体如下：

 .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 帮助”，        网址是：http://go.microsoft.com/fwlink/?LinkID=123415。

 

下面来看一个实例：

如下是一个基于脚本的帮助文档注释，按照基于脚本的帮助文档语法要求，可以将 注释放在脚本的开头或者末尾前后要有一定空行保持间隔。

<#   .SYNOPSIS    ping 127.0.0.1信息    .DESCRIPTION    ping 127.0.0.1信息    .PARAMETER <Parameter-Name>无需加入参数    .EXAMPLE    C:\ping-test.ps1    .INPUTS    无需输入对象    .OUTPUTS    返回string类信息    .NOTES    ping 127.0.0.1    .LINK地址：http://blog.csdn.net/itanders#>param([switch]$loop)function ping-test{do{ping 127.0.0.1}while($loop)}ping-test

 

将脚本保存为ping-test.ps1，用我们最熟悉的get-help命令查看脚本帮助看看，是不是就像操作系统自带的cmdlet帮助一样的格式一样展现了出来

 

 

二、基于方法的帮助文档注释，按照方法帮助文档注释的语法规则将注释语句写于方法开头或者末尾

param([switch]$loop)function global:ping-test{<#   .SYNOPSIS    ping 127.0.0.1信息    .DESCRIPTION    ping 127.0.0.1信息    .PARAMETER <Parameter-Name>无需加入参数    .EXAMPLE    C:\ping-test.ps1ping-test    .INPUTS    无需输入对象    .OUTPUTS    返回string类信息    .NOTES    ping 127.0.0.1    .LINK地址：http://blog.csdn.net/itanders#>do{ping 127.0.0.1}while($loop)}

因为是基于方法的帮助文档，所以我们必须运行脚本，再用get-help来查看脚本中包含的方法的帮助文档。