时间戳

首页 > 解决方案 > 如何定义自定义命令的文档（使用 Get-Command 或 Get-Help）

powershell - 如何定义自定义命令的文档（使用 Get-Command 或 Get-Help）

问题描述

假设我有一个自定义命令：

function Search-ForStringInFile($string)
{
        ls -Recurse | Select-String -Pattern "$string" -List | Select Path
}

而且我希望能够运行Get-Help Search-ForStringInFile或Get-Command Search-ForStringInFile获得命令功能的描述。

描述：在当前目录/下的所有文件中搜索关键字

我可以在function添加此文档时使用特殊的注释语法吗？

标签： powershelldocumentation-generationpowershell-5.0powershell-v5.1

解决方案

这称为基于注释的帮助。事实上，PowerShell ISE 有一个非常棒的代码片段，可以准确地完成您想做的事情。只需点击 Control+J 并选择“Cmdlet - 高级功能”来加载我将在下面提供的代码片段：

<#
.Synopsis
   Short description
.DESCRIPTION
   Long description
.EXAMPLE
   Example of how to use this cmdlet
.EXAMPLE
   Another example of how to use this cmdlet
#>
function Verb-Noun
{
}

一旦您填写了上述每一项的值（请参阅此处的文档以了解所有可用字段）并按 F5，帮助将出现在您的函数中。

PS>Get-Help Verb-Noun
NAME
    Verb-Noun

SYNOPSIS
    Short description


SYNTAX
    Verb-Noun [-Param1] <Object> [-Param2 <Int32>] [-WhatIf] [-Confirm] [<CommonParameters>]

    Verb-Noun [-Param3 <String>] [-WhatIf] [-Confirm] [<CommonParameters>]


DESCRIPTION
    Long description


PARAMETERS
    -Param1 <Object>
        Param1 help description

        Required?                    true
        Position?                    1
        Default value                
        Accept pipeline input?       true (ByValue, ByPropertyName)
        Accept wildcard characters?  false

    -Param2 <Int32>
        Param2 help description

        Required?                    false
        Position?                    named
        Default value                0
        Accept pipeline input?       false
        Accept wildcard characters?  false

    -Param3 <String>
        Param3 help description

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

    -WhatIf [<SwitchParameter>]

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

    -Confirm [<SwitchParameter>]

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

    <CommonParameters>
        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer, PipelineVariable, and OutVariable. For more information, see 
        about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216). 

INPUTS
    Inputs to this cmdlet (if any)


OUTPUTS
    Output from this cmdlet (if any)


NOTES


        General notes

    -------------------------- EXAMPLE 1 --------------------------

    PS C:\>Example of how to use this cmdlet






    -------------------------- EXAMPLE 2 --------------------------

    PS C:\>Another example of how to use this cmdlet







RELATED LINKS

因此，要向您自己的 cmdlet 添加帮助，您只需在函数中粘贴相同的注释块即可。您可以将其放置在以下三个位置之一：

  • 在函数声明之前
  • 函数声明后(ewww)
  • 在你的功能结束时（不要被认为是，但选择这个选项在道德上是错误的）。

文档也在这里提供了每个已批准位置的示例。

推荐阅读