如何在 PowerShell 函数中添加帮助?


当我们写一个程序的时候,那些没有编程背景的人通常希望获得很多关于这个程序的帮助。当我们编写一个函数并声明参数时,那些不知道参数需要何种输入的人通常会先使用Get-Help命令来搜索帮助,然后他们只会找到参数,而没有找到其描述。例如,

function TestFunct{
   param(
      #16 Digit Application ID
      [parameter(Mandatory=$true)]
      [String]$AppID,
      #Date in the Unix Format - 2020-10-31T17:12:10+0530
      [String]$Date
   )
}

在上面的示例中,指定了两个参数,当用户获得此函数的帮助时,它不会指定提供参数描述的注释。例如,

PS C:\> help TestFunct -Parameter *
-AppID <string>

   Required?                   true
   Position?                   0
   Accept pipeline input?      false
   Parameter set name          (All)
   Aliases                     None
   Dynamic?                    false

-Date <string>

   Required?                   false
   Position?                   1
   Accept pipeline input?      false
   Parameter set name          (All)
   Aliases                     None
   Dynamic?                    false

要从注释中添加描述,我们需要添加基于注释的帮助,并需要使用基于注释的帮助中的SYNOPSIS

示例

function TestFunct{
   <#
      .SYNOPSIS
      This is test function for parameter based help
   #>
   param(
      #16 Digit Application ID
      [parameter(Mandatory=$true)]
      [String]$AppID,
      #Date in the Unix Format - 2020-10-31T17:12:10+0530
      [String]$Date
   )
}

现在我们检查参数时,会得到基于注释的描述。

PS C:\> help TestFunct -Parameter *
-AppID <String>
   16 Digit Application ID

   Required?                      true
   Position?                      1
   Default                        value
   Accept pipeline input?         false
   Accept wildcard characters?    false

-Date <String>
   Date in the Unix Format - 2020-10-31T17:12:10+0530

   Required?                      false
   Position?                      2
   Default                        value
   Accept pipeline input?         false
   Accept wildcard characters?    false

更新时间:2020 年 11 月 2 日

303 次浏览

职业生涯 起航

完成课程并获得认证

开始
广告