Question

我目前正在编写PowerShell脚本，以审核AD结构中过时的计算机对象并对其采取行动。为了成为一名优秀的脚本编写者，我正在实现基于注释的帮助。它可以正常工作，但是我正在尝试使用语法来注释参数，这些参数会自动显示在帮助的.PARAMETERS部分下。

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

问题是我的一些参数使用了验证，并且我已经注释了验证代码中的一些内容。但是，基于注释的帮助包括所有这些杂项。注释，我希望它不会，因为它会使get-help输出混乱，并且不在那里添加任何值。

以下是代码的摘录：

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/

我可以在PowerShell中基于注释的帮助中隐藏某些注释吗？

1 个答案: