Могу ли я скрыть некоторые комментарии из справки на основе комментариев в PowerShell? - PullRequest
Новая
       26

Могу ли я скрыть некоторые комментарии из справки на основе комментариев в PowerShell?

3 голосов
/ 03 июля 2019

В настоящее время я пишу сценарий 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 синтаксиса справки на основе комментариев в верхней части скрипта?

1 Ответ

3 голосов
/ 03 июля 2019

Ваши комментарии над атрибутами параметров и внутри них интерпретируются как комментарии к параметрам, поскольку вы используете другие разделы справки на основе комментариев, но не .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/

...