Register-ArgumentCompleter

Register-ArgumentCompleter
    -CommandName <String[]>
    -ScriptBlock <ScriptBlock>
    [-Native]
    [<CommonParameters>]

Register-ArgumentCompleter
    -ParameterName <String>
    -ScriptBlock <ScriptBlock>
    [-CommandName <String[]>]
    [<CommonParameters>]

Register-ArgumentCompleter cmdlet은 사용자 지정 인수 완료자를 등록합니다. 인수 완성기를 사용하면 지정한 명령에 대해 런타임에 동적 탭 완성을 제공할 수 있습니다.

CommandName 매개 변수를 사용하여 이 명령을 호출하고 ParameterName 또는 Native 매개 변수 없이 이 명령을 호출하면 Native 매개 변수를 지정한 것처럼 명령이 실행됩니다. 이렇게 하면 인수 완료자에서 PowerShell 명령 매개 변수가 작동하지 않습니다. PowerShell 명령에 대한 인수 완료자를 등록하려면 항상 ParameterName 매개 변수를 지정합니다.

다음 예제에서는 cmdlet의 Set-TimeZone 매개 변수에 대한 인수 완료자를 등록합니다.

$s = {
    param(
        $commandName,
        $parameterName,
        $wordToComplete,
        $commandAst,
        $fakeBoundParameters
    )

    (Get-TimeZone -ListAvailable).Id | Where-Object {
        $_ -like "$wordToComplete*"
    } | ForEach-Object {
        "'$_'"
    }
}

Register-ArgumentCompleter -CommandName Set-TimeZone -ParameterName Id -ScriptBlock $s

첫 번째 명령은 사용자가 tab 누를 때 전달되는 필수 매개 변수를 사용하는 스크립트 블록을 만듭니다. 자세한 내용은 ScriptBlock 매개 변수 설명을 참조하세요.

스크립트 블록 내에서 id 사용 가능한 값은 Get-TimeZone cmdlet을 사용하여 검색됩니다. 각 표준 시간대에 대한 ID 속성은 Where-Object cmdlet에 파이프됩니다. Where-Object cmdlet은 $wordToComplete제공된 값으로 시작되지 않는 ID를 필터링합니다. 이 ID는 사용자가 Tab누르기 전에 입력한 텍스트를 나타냅니다. 필터링된 ID는 각 값을 따옴표로 묶어 공백이 포함된 값을 처리하는 ForEach-Object cmdlet으로 파이프됩니다.

두 번째 명령은 scriptblock, ParameterNameID 및 CommandNameSet-TimeZone전달하여 인수 완료자를 등록합니다.

다음 예제에서는 cmdlet의 Stop-Service 매개 변수에 대한 탭 완성을 덮어쓰고 실행 중인 서비스만 반환합니다.

$s = {
    param(
        $commandName,
        $parameterName,
        $wordToComplete,
        $commandAst,
        $fakeBoundParameters
    )

    $services = Get-Service | Where-Object {
        $_.Status -eq 'Running' -and $_.Name -like "$wordToComplete*"
    }

    $services | ForEach-Object {
        New-Object -Type System.Management.Automation.CompletionResult -ArgumentList @(
            $_.Name          # completionText
            $_.Name          # listItemText
            'ParameterValue' # resultType
            $_.Name          # toolTip
        )
    }
}

Register-ArgumentCompleter -CommandName Stop-Service -ParameterName Name -ScriptBlock $s

첫 번째 명령은 사용자가 tab 누를 때 전달되는 필수 매개 변수를 사용하는 스크립트 블록을 만듭니다. 자세한 내용은 ScriptBlock 매개 변수 설명을 참조하세요.

스크립트 블록 내에서 첫 번째 명령은 Where-Object cmdlet을 사용하여 실행 중인 모든 서비스를 검색합니다. 서비스는 ForEach-Object cmdlet에 파이프됩니다. ForEach-Object cmdlet은 새 System.Management.Automation.CompletionResult 개체를 만들고 현재 서비스 이름($_.Name파이프라인 변수로 표시됨)으로 채웁니다.

CompletionResult 개체를 사용하면 반환된 각 값에 추가 세부 정보를 제공할 수 있습니다.

• completionText(String) - 자동 완성 결과로 사용할 텍스트입니다. 명령으로 전송되는 값입니다.
• listItemText(문자열) - 사용자가 Ctrl +누를 때와 같이 목록에 표시할 텍스트입니다. PowerShell은 표시에만 사용합니다. 이 명령은 선택할 때 명령에 전달되지 않습니다.
• resultType(CompletionResultType) - 완료 결과의 형식입니다.
• 도구 설명(문자열) - 개체에 대해 표시할 세부 정보가 포함된 도구 설명의 텍스트입니다. 사용자가 Ctrl +누른 후 항목을 선택하면 표시됩니다.

Native 매개 변수를 사용하여 네이티브 명령에 대한 탭 완성을 제공할 수 있습니다. 다음 예제에서는 dotnet CLI(명령줄 인터페이스)에 대한 탭 완성을 추가합니다.

$scriptblock = {
    param(
        $wordToComplete,
        $commandAst,
        $cursorPosition
    )

    dotnet complete --position $cursorPosition $commandAst.ToString() | ForEach-Object {
        [System.Management.Automation.CompletionResult]::new(
            $_,               # completionText
            $_,               # listItemText
            'ParameterValue', # resultType
            $_                # toolTip
        )
    }
}

Register-ArgumentCompleter -Native -CommandName dotnet -ScriptBlock $scriptblock

첫 번째 명령은 사용자가 tab 누를 때 전달되는 필수 매개 변수를 사용하는 스크립트 블록을 만듭니다. 자세한 내용은 ScriptBlock 매개 변수 설명을 참조하세요.

스크립트 블록 내에서 dotnet complete 명령은 탭 완성을 수행합니다. 결과는 ForEach-Object 클래스의 새 정적 메서드를 사용하여 각 값에 대한 CompletionResult 개체를 만드는 cmdlet으로 파이프됩니다.

이 cmdlet은 일반적인 매개 변수인 -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction 및 -WarningVariable 매개 변수를 지원합니다. 자세한 내용은 about_CommonParameters를 참조하세요.

개체를 이 cmdlet에 파이프로 연결할 수 없습니다.

이 cmdlet은 출력을 반환하지 않습니다.