powershell - 我可以在 PowerShell 的基于评论的帮助中隐藏某些评论吗？

Question

我目前正在编写一个 PowerShell 脚本来审核我们的 AD 结构中的陈旧计算机对象并对其采取措施。为了成为一名优秀的脚本编写者，我正在实现基于评论的帮助。它正在工作，但我正在尝试使用您注释参数的语法，它们会自动显示在帮助的 .PARAMETERS 部分下。

如果可以避免的话，我不想在适当的基于注释的帮助注释代码中使用单独的 .PARAMETERS 部分，以便注释在物理上与参数保持一致。但如果没有办法避免我的问题，那么我想我将不得不这样做。

问题是我的一些参数使用了验证，我已经注释了一些验证代码。但是，基于评论的帮助包括所有这些杂项。评论，我宁愿它没有，因为它使 get-help 输出变得困惑并且不会在那里增加任何值(value)。

这是代码的摘录:

function audit-StaleADComputersInOU {
<#
.SYNOPSIS
Exports a list of AD Computer objects to the screen, and optionally to a CSV formatted file.
Optionally take other actions on returned objects.
Results are from one or more given OU DNs, and filtered by LastLogonTimeStamp.

.OTHER COMMENT-BASED HELP SECTIONS
etc. etc., not including .PARAMETERS
#>


    [CmdletBinding(SupportsShouldProcess=$true)]

    param(
        # Specify the full filepath to a file.
        # Results will be exported in CSV format to that file.
        # Parent directory must exist.
        # Omit to export nothing and create no file.
        [ValidateScript({
            # Parent directory
            $path = Split-Path -Path $_

            # Check parent directory exists
            if(!(Test-Path $path)) {
                throw "$path directory doesn't exist!"
            }
            # Check parent directory is actually a directory
            if(!(Test-Path $path -PathType Container)) {
                throw "$path is not a directory!"
            }
            # Check file doesn't already exist
            if(Test-Path $_){
                throw "$_ already exists!"
            }
            return $true
        })]
        [System.IO.FileInfo]
        $ExportToCSV,

        # Other params, etc.
    )

    # Doing stuff
}

下面是 Get-Help audit-StaleADComputersInOU -full 的相关输出:

NAME
    audit-StaleADComputersInOU

SYNOPSIS
    Exports a list of AD Computer objects to the screen, and optionally to a CSV formatted file.
    Optionally take other actions on returned objects.
    Results are from one or more given OU DNs, and filtered by LastLogonTimeStamp.


.OTHER COMMENT-BASED HELP SECTIONS
    etc. etc., not including .PARAMETERS


PARAMETERS
    -ExportToCSV <FileInfo>
        Specify the full filepath to a file.
        Results will be exported in CSV format to that file.
        Parent directory must exist.
        Omit to export nothing and create no file.
        Parent directory
        Check parent directory exists
        Check parent directory is actually a directory
        Check file doesn't already exist

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

    -OtherParams [<SwitchParameter>]
        etc.

有什么办法可以避免这种情况吗？我可以使用任何评论语法使特定评论对基于评论的帮助不可见吗？还是我唯一的选择是将我希望看到的注释提取到脚本顶部基于注释的帮助语法的 .PARAMETERS 部分？

Answer 1

您在参数属性上方和内部的注释被解释为参数注释，因为您使用了其他基于注释的帮助部分而不是 .PARAMETER对于那个参数。什么Get-Help在这种情况下所做的是假设参数上面的注释应该是描述。

要阻止这种情况发生，您必须有一个 .PARAMETER <param name>在每个参数的基于主要评论的帮助中。除了从参数中删除注释之外别无他法。您不需要参数的描述，但我建议添加一个。

<#
.SYNOPSIS
Exports a list of AD Computer objects to the screen, and optionally to a CSV formatted file.
Optionally take other actions on returned objects.
Results are from one or more given OU DNs, and filtered by LastLogonTimeStamp.

.OTHER COMMENT-BASED HELP SECTIONS
etc. etc., not including .PARAMETERS

.PARAMETER ExportToCSV
#>

以上内容将确保对参数的注释不会包含在帮助中。如果您需要说明，请将其放在下面，就像任何其他基于评论的帮助部分一样。

引用:https://www.sapien.com/blog/2015/02/18/troubleshooting-comment-based-help/